PRD Stepper — Execute One Story End-to-End

prd-creation defines the work; prd-stepper does the work. Given a PRD tracker JSON (or the active one referenced in scratchpad.md), this skill executes one story to completion — including dependency checks, agent spawning, gate enforcement, and tracker updates.

When to invoke

• User says: "continue with AUTH-002", "next story", "next PRD story", "execute the next story", "step through the PRD", "what's next on the PRD", "let's do the next one".
• User says: "go ahead with <story-id>" — interpret as: execute that specific story.
• Proactively after closing a story: ask "shall I continue with the next one?" if the next story's dependencies are met.

What it does

Step 1 — Locate the PRD tracker

If the user didn't name a PRD file:

1. Read scratchpad.md for an "Active Plan" or "Current PRD" reference.
2. If multiple PRDs exist in docs/plans/, ask which one (use AskUserQuestion).
3. If no PRD exists, route the user to prd-creation instead.

The tracker is the .json file (e.g. docs/plans/auth-rework-prd.json); the .md is the narrative and may be useful context but is not the source of truth for status.

Step 2 — Pick the story

• If the user named one (AUTH-001, PDF-002, etc.), use that.
• Otherwise pick the first story in declared order where:
  • status ∈ {pending, in_progress} (resume in-progress before starting new)
  • all depends_on stories are implemented
  • blocked_by is null
• If nothing qualifies, report: "No story ready to execute. PRD is either complete or all remaining stories are blocked."

Step 3 — Read the spec

Pull from the story:

• complexity: low / medium / high → drives spawn-vs-inline
• primary_agent: which agent type to spawn if needed
• key_files: read these before deciding
• acceptance_criteria: the gate for "done"
• triggers: multi_file, external_reference, quality_sensitive
• required_gates: roles that must run before marking implemented (auditor, reviewer, verifier)
• delegation (if present): explicit spawn instructions

Step 4 — Check dependencies + announce

Print one line to the user: "Starting story {id} ({title}). Complexity: {complexity}. Strategy: {inline | spawn {agent}}."

If the strategy needs user confirmation (e.g., spawning a long multi-persona debate that will run an hour), pause for OK.

Step 5 — Mark in_progress

Update your task list (find or create a task matching the story ID; set status to in_progress). Update the PRD JSON: story.status = "in_progress". Use a Node/Python helper for the JSON mutation — NEVER pipe a jq mutation through a shell redirect and mv over the canonical file in one chain; that pattern has wiped a PRD JSON in production use. See references/json-mutation-safety.md.

Step 6 — Execute

Inline (low complexity)

Do the work directly. Read key_files, make the edits, run smoke tests / npm test, verify acceptance criteria.

Spawn (medium or high complexity)

Use your agent-spawning tool with the story's primary_agent type. Run it in the background if expected duration is more than a few minutes. Include in the brief:

• The full story spec verbatim (so the agent has the acceptance criteria)
• The key_files to read
• The triggers and what they mean
• Any PRD-level goal statement or scoring rubric your tracker carries (optional — not part of the base schema)
• Where to write the deliverable

If your setup has a heartbeat/pulse mechanism for monitoring long background spawns, use it here. Per references/background-agent-completion.md: after the agent returns, verify the deliverable file actually exists at the expected path. If absent, complete inline.

High-complexity + needs persona isolation

If the story's delegation.implementation calls for genuinely separate multi-persona reasoning (e.g., independent perspectives debated before an implementation decision), consider running that as isolated sub-agent processes per persona/phase rather than a single general-purpose agent — whichever mechanism your own setup uses for that.

Step 7 — Run required gates

verifier, auditor, and reviewer below are role names, not agent identifiers — spawn whatever subagent type your own setup provides for each role, or run the gate's check inline yourself if it doesn't have one. A gate that can't be run for real is not passed; don't let a missing agent type turn into a silently-skipped gate.

After execution, for each gate in story.required_gates:

• verifier: run the current project's own test/validation commands (e.g. npm test, smoke-generate the artifact, schema/lint validation) — the exact commands are project-specific; look them up in that project's CLAUDE.md or package.json rather than assuming a fixed set.
• auditor: spawn an auditor role with a brief that includes the story's acceptance criteria + the artifact path. PRD acceptance gates are concrete spot-checks, not open-ended review.
• reviewer: spawn a reviewer role to read the deliverable against whatever review process, style guide, or compliance rule applies in this project, and sign off.

Note: the specific example commands in this skill (npm test, a schema-validation step, an example tracker filename) are illustrative stand-ins only — substitute your own project's actual test/validation commands and gate scripts.

Each gate produces a deliverable file under docs/research/ or similar, with verdict: PASS | FAIL. If FAIL, do not mark implemented; surface the findings to the user and either reopen the story or escalate.

Step 8 — Update the tracker

When all acceptance criteria + gates pass:

• story.status = "implemented"
• story.completed_date = today (YYYY-MM-DD)
• story.implementation_notes = 2-3 sentence summary: what was done, what the metrics were, where the deliverable lives.
• Update your task list: mark the task completed.
• Update scratchpad.md if the entry references the active story.

If this was the last story:

• Set prd.status = "completed" and prd.completed_date = today.
• Write a SHIPPED entry in scratchpad.md with the deliverable index (file paths).
• Suggest a final commit.

Step 9 — Report

≤ 6-line confirmation:

✅ {story-id} ({title}) implemented.
   Deliverable: {path}
   Acceptance criteria: {N}/{N} met.
   Gates: {gate names + PASS/FAIL}
   Next story ready: {next-id} ({title}) — proceed? (or "done")

Hard rules

1. Apply decisions only within their declared scope. If the PRD carries a list of prior decisions tagged by scope (global vs. per-story), apply only those tagged for the current story — never silently apply the rest.
2. Verify deliverable files exist at expected paths after spawned agents return. Do not trust the verbal summary alone.
3. Honor gate failures. A FAIL gate reopens the story; do not paper over.
4. Mutate the PRD JSON safely. Use Node/Python helpers. Never jq ... > /tmp/x && mv /tmp/x <canonical> in one chain — that pattern has burned a PRD file in production use.
5. The PRD JSON is the source of truth. The .md narrative may drift; trust the JSON when they disagree.
6. One story at a time unless the user explicitly says "do the next 3 in parallel". PRD stories often have dependencies; chaining them inline is safer.
7. Kill and respawn, don't message mid-flight, for scope changes on a running background agent. Mid-flight redirection is unreliable — see references/mid-flight-agent-redirection.md.

Defaults table

Same role-names-not-identifiers caveat as Step 7 applies to researcher/auditor/reviewer below.

Examples

Note: the file path, story IDs, and gate commands below are illustrative stand-ins to show the shape of a full pass — substitute your own project's actual PRD path, story IDs, and test/validation commands.

Example 1 — User says "continue with AUTH-002"

1. Read docs/plans/auth-rework-prd.json.
2. Find AUTH-002. Status pending. depends_on AUTH-001 — confirm AUTH-001.status === "implemented".
3. complexity medium, primary_agent implementer, multi_file true.
4. Announce: "Starting AUTH-002 (Add password-reset flow). Complexity: medium. Strategy: inline (two files + a migration)."
5. Mark in_progress in tracker.
6. Make the edits described in the story's acceptance criteria.
7. Run npm test. Manually verify each acceptance criterion against the running app.
8. Mark implemented. Write implementation_notes summarizing what changed.
9. Report.

Example 2 — User says "next story" with nothing in progress

1. Read PRD JSON.
2. Find first pending story with met dependencies.
3. Confirm with user before spawning (especially if it's a long-running background task).
4. Execute as above.

Example 3 — Story has a reviewer gate and a verifier gate

After primary execution:

1. Spawn verifier agent with brief = "run npm test + validate the output schema against {path}". Wait. PASS required.
2. Spawn reviewer agent with brief = "read {deliverable} against {acceptance criteria}, plus any scoring rubric your tracker carries". Wait. PASS required.
3. Only then mark implemented.

Related

• prd-creation — defines what this skill executes.

If your own setup has a pulse/heartbeat skill for background spawns, or a separate multi-persona reasoning skill for debate-shaped stories, wire those in where this skill calls for them — neither is required for prd-stepper to work.