/craft-story-implement

name: story-implement
description: "Implement a story through the Implement Phase. Stories must be fully designed with chunks before implementation."
argument-hint: "[story-name]"

Story Implement

⛔ **CRITICAL: YOU ARE THE ORCHESTRATOR, NOT THE IMPLEMENTER**

You must NOT write implementation code directly. For EVERY chunk, you MUST use the Task tool to invoke the implementer agent:

Task tool:
  subagent_type: "craft:implementer"
  description: "Implement chunk N of [story]"
  prompt: [chunk details, story context, TDD requirement]

If you find yourself about to write code → STOP → use Task tool instead.

---

⛔ **CRITICAL: VALIDATION CHAIN IS INLINE**

Do NOT invoke the validate-chunk skill (`craft:validate-chunk`) during the implementation loop. The validate-chunk skill exists for manual user invocation only. story-implement owns the validation chain directly:

• Invoke chunk-validator agent via Task tool
• Route PASSED/PARTIAL inline
• Route FAILED via Read `${CLAUDE_PLUGIN_ROOT}/commands/references/validate-fix-loop.md`

---

⛔ **CRITICAL: ALL VALIDATION RUNS SYNCHRONOUSLY**

**NEVER** use `run_in_background: true` for test, typecheck, lint, or build commands. All validation must complete synchronously — results confirmed before marking any chunk or story done. This applies to:

• Per-chunk validation (Step 4)
• Quality gates (Step 5)
• Any "verify nothing broke" test runs

Background test runs cause orphaned failure notifications that appear after stories are already marked complete. If a command is slow, wait for it.

---

Implement a story that's already been designed. This is pure Implement Phase — chunks exist, decisions are locked, just execute.

Project Root

All `.craft/` paths in this command are relative to `$CRAFT_PROJECT_ROOT` (set at session start). Use `${CRAFT_PROJECT_ROOT:-.}` as prefix when constructing paths. Pass the project root to all subagents.

Prerequisites & Status Guards

Before implementation, **validate story location and status**:

**Location check:**

• If story is in `.craft/backlog/` → BLOCK:

Use **AskUserQuestion**:

question: "This story is in the backlog. Assign it to a cycle first?"
header: "Assign"
options:
  - label: "Assign to [active cycle] (Recommended)"
    description: "Add to current cycle and implement"
  - label: "Create new cycle for it"
    description: "Start a new cycle with this story"
  - label: "Cancel"
    description: "Go back"

If no `ACTIVE_CYCLE` exists: omit the "Assign to [active cycle]" option. Only show "Create new cycle" and "Cancel".

**If user selects "Assign to [active cycle]":** → invoke `craft:craft-cycle-assign` with the story path. After assignment completes, return to story-implement for the same story.

**If user selects "Create new cycle for it":** → invoke `craft:craft-cycle-design` with the story as context. After cycle creation completes, invoke `craft:craft-cycle-start` to activate the new cycle, then return to story-implement for the same story.

**If user selects "Cancel":** → end, do not proceed

**Cycle check:**

• Extract the cycle name from the story path (e.g., `.craft/cycles/[cycle-name]/stories/[story].md` → `[cycle-name]`)
• Read `ACTIVE_CYCLE` from `.global-state`
• If story is in a cycle AND that cycle is NOT the current `ACTIVE_CYCLE`:

→ BLOCK: Do NOT proceed. Do NOT attempt to manually activate the cycle by editing state files. → Route to `craft:cycle-start` to properly activate the cycle first.

Use **AskUserQuestion**:

question: "This story is in cycle '[cycle-name]' which isn't the active cycle. Activate it first?"
header: "Cycle"
options:
  - label: "Activate [cycle-name] (Recommended)"
    description: "Use craft:cycle-start to properly activate this cycle"
  - label: "Pick a story from the active cycle"
    description: "Choose a story from [ACTIVE_CYCLE] instead"
  - label: "Cancel"
    description: "Go back"

⛔ **NEVER manually edit `.global-state` or `.state` files to activate a cycle.** Always use `craft:cycle-start` which runs the proper transition scripts (`start-cycle.sh`), updates cycle.yaml status, and handles the active cycle switch cleanly.

If user selects "Activate": invoke `craft:cycle-start` with the cycle name. After activation completes, return to story-implement for the original story.

If user selects "Pick a story from the active cycle": → invoke `craft:craft-story-implement` with no args (triggers Step 1 story picker filtered to active cycle)

If user selects "Cancel": → end, do not proceed

**Go re-check:**

• For a story in a cycle, run `bash "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/cycle-stage.sh" "${CRAFT_PROJECT_ROOT:-.}/.craft/cycles/[cycle-name]"`. On a non-empty `source_issue=`, Read `${CLAUDE_PLUGIN_ROOT}/commands/references/tracker-refresh.md` and run its `## At story start`: one comments read, then the delta copy and the stage re-record. Backlog stories and cycles with no `source_issue` skip this silently.

**Stage check:**

• For a story in a cycle, run `bash "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/cycle-stage.sh" "${CRAFT_PROJECT_ROOT:-.}/.craft/cycles/[cycle-name]"`. Backlog stories skip this check.
• If it prints `implement=no`: print the `say=` value as your own first line and end. No AskUserQuestion, no `start-story.sh`, no state change, and no in-session override: the only way to lift the stop is a newer Go on the issue.
• If it prints `implement=yes`: continue silently.

**Status check:**

| Status | Action | |--------|--------| | `ready` | OK: Proceed to implementation | | `active` | OK: Resume from current chunk | | `complete` | BLOCK: "Story already complete. Pick another?" |

**Also check story has:**

• Chunks defined (from plan-chunks)
• Acceptance criteria

**If story is missing chunks:** Use **AskUserQuestion**:

question: "This story doesn't have chunks planned. How do you want to proceed?"
header: "Plan"
options:
  - label: "Design it now (Creative Phase)"
    description: "Explore options, then plan chun