oxygen: Command for Claude Code

Add a case to an existing flow

Use when the dev wants a new test case that's a near-sibling of an existing flow's cases — same target:, same backend_mode:, same setup:, same surface — rather than authoring a whole new file. Sharing settings + setup across cases is cheaper to maintain and keeps related coverage in one place.

$ARGUMENTS is parsed as <flow-file> <description>. The flow file is either a path (web-app/tests/agentic/flows/chat-ask.flow.test.yml) or a stem (chat-ask).

This command must be run from the root of an oxy-hq/oxygen-internal checkout.

Steps

1. Resolve the flow file

# If the dev gave a stem, find the file.
if [ ! -f "$FLOW_PATH" ]; then
  FLOW_PATH=$(find web-app/tests/agentic/flows -name "${FLOW_STEM}.flow.test.yml" | head -1)
fi

If the file doesn't exist, tell the dev: "I can't find a flow at <path>. Either give me the full path or use /test-feature to author a new flow." Exit.

2. Re-read source of truth

Always re-read these — they evolve:

• web-app/tests/agentic/README.md — confirm the schema hasn't drifted.
• json-schemas/flow-test.json.
• web-app/tests/agentic/canonical-prompts.md — for cache_scope: shared step text the new case might want to reuse.
• The full contents of the target flow file (Read) so you preserve its target:, backend_mode:, settings:, and setup: and add a case that's shape-compatible with the existing ones.

3. Check the existing flow's contract

Before adding a case, verify the new case fits:

• Same target:? If not, the dev probably wants a new flow, not a new case here. Use AskUserQuestion to confirm.
• Same backend_mode:? Cases inside one flow share the backend boot. Mixing modes inside one flow doesn't work — local-mode and cloud-mode flows are spawned differently by the runner.
• Same setup state? If the new case needs different setup (a clean test.sql vs a dirty one, a different starting URL, a different demo file to revert via restore_demo_file:), it can't share this flow's setup: block. Tell the dev and route them to /test-feature instead.
• No name collision? The new case's name: must be unique within the flow.