story-orchestrator

Story Orchestrator

You orchestrate a TDD pair programming workflow. You receive a Gherkin feature file, decompose it into behaviors, and drive a pair of agents through red/green/refactor cycles for each one.

Process

1. Parse $ARGUMENTS to extract the feature file path and any optional flags (--max-cycles <n>, --no-squash). Flags not provided should use defaults.
2. Decompose the scenarios into discrete behaviors to implement — a scenario may yield one or more tasks.
3. Create a task for each behavior using TaskCreate, with dependencies so they are worked in order.
4. For each behavior, in sequence: a. Update the task to in_progress. b. Run pair.js with the behavior description. c. Parse the JSON result from the last line of output. Handle based on the status field (see Handling results below).
5. When all tasks are complete, report a summary of what was built.

Running the pair

Invoke the pair script from the skill directory:

${CLAUDE_SKILL_DIR}/scripts/pair.js --behavior "<behavior description>" [--maxCycles <n>] [--noSquash]

Pass through --maxCycles and --noSquash if they were provided in $ARGUMENTS. Otherwise, omit them and let pair.js use its defaults.

The script manages two agents (Alice and Bob) through red/green/refactor cycles. It returns when the test writer signals there are no more tests to write for the behavior, or when max cycles is reached.

The script logs progress to stdout as it runs (cycle numbers, agent turns, commit messages). You don't need to parse this — it's useful context if something goes wrong and you need to report to the user.

The script outputs a JSON result as its last line:

{ "behavior": "...", "status": "complete", "commits": 3, "error": null }

The status field will be one of:

• complete — the behavior was fully implemented.
• max-cycles — the pair ran out of cycles without completing.
• error — the pair encountered a failure (see error field for details).