--- name: story-lifecycle description: Run one user story end to end in its own worktree, from claim to merge. Use when you are responsible for delivering a single story. --- # Story lifecycle One story, one worktree, one branch, one set of ports. You own it from claim to merge. Everything you need is in the artifacts: the story file and the blueprint. Nothing is handed to you in conversation. ## 1. Claim ``` node .Codex/scripts/story.mjs claim --feature --base ``` Returns the worktree path, the branch, the assigned ports, the specs path and the start command, and marks the story `in-progress` in the shared registry so no other session takes it or its ports. Then work only inside that worktree. Every command you run starts by sourcing its environment: ``` set -a; . ./.Codex-story.env; set +a ``` Skip that and you run against the developer's own state, not the story's. ## 2. Read The story file, then the blueprint, then the code the blueprint names. In that order. If the blueprint has a gap, it goes back to whoever wrote it: do not fill it yourself. ## 3. Freeze the interface Before any code, every contact point between backend and frontend work is fixed and written down. See `interface-contracts`. Parallel work on an unfrozen interface is the one failure mode that costs a full rewrite. ## 4. Implement Dispatch the blueprint's tasks: backend work to the backend engineer, interface work to the frontend engineer, in parallel when the blueprint says they are independent, sequentially when it does not. Both work in this worktree. Neither invents a contract. When they disagree, you arbitrate; when the disagreement is about the plan or the story, it goes up. ## 5. Validate Mark the story `validating`, then hand the validator the story, the blueprint and the diff. It runs the app on this worktree's ports and verifies every criterion against reality. It cannot change code, by design. - **PASS**, no blockers → continue. - **BLOCKED** → run `remediation-loop`. Three iterations, then escalate. ## 6. Test and document Only on validated code with zero blockers, and both at once: they read the same shipped code and neither blocks the other. - **qa-engineer**: one test per acceptance criterion, one regression test per blocking finding that was raised. Writes tests, never source. - **docs-writer**: every surface the change ships on, written against the code rather than the blueprint. Writes documentation, never source. ## 7. Hand back Report: the branch, what shipped, the validation verdict with its evidence, the tests added, the non-blocking findings, and anything left unverified. Integration is not yours. The session that owns the feature merges the story branch into the integration branch, in dependency order, and only then: ``` node .Codex/scripts/story.mjs state done node .Codex/scripts/story.mjs release ``` `release` refuses to discard a worktree that still holds unmerged work. That refusal is a correct answer: merge first. ## States `planned` → `in-progress` → `validating` → `done`, with `blocked` as the exit when the loop caps out. Move the state as it changes, not at the end: the registry is how a parallel session knows what is happening. ## Rules - Never touch a file outside your worktree. The specs directory is a symlink into the main checkout and is shared: write only your own story's artifacts there. - Never take a port that is not yours. They are assigned for a reason. - A story is done when the criteria pass with evidence, not when the code looks right.