# Prd Stepper > Execute the NEXT (or a named) story in a PRD tracker file end-to-end — read the story spec from the JSON, mark in_progress, decide spawn-vs-inline based on complexity, run required gates, update the tracker with completed_date and implementation_notes. Companion to `prd-creation`. Use when the user says "continue with ", "next PRD story", "execute ", "step through the PRD", "what's next on the PRD", or "let's do the next one". This skill governs execution once a PRD tracker JSON exists, however it originated — whether created directly by `prd-creation` or handed off from some other planning process. Batching multiple PRD stories in one session, when the user opts in, is a legitimate variant of this same mechanism, not a different one. - Skill: `cobuchan/prd-stepper` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add cobuchan/prd-stepper` - Raw SKILL.md: https://api.skillmd.com/api/skills/cobuchan/prd-stepper/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: cobuchan (https://skillmd.com/u/cobuchan) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/cobuchan/prd-stepper --- # 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 " — 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](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](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 ` 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](references/mid-flight-agent-redirection.md). ## Defaults table Same role-names-not-identifiers caveat as Step 7 applies to `researcher`/`auditor`/`reviewer` below. | Trigger | Action | |---|---| | `triggers.external_reference: true` | Add a `researcher` role before `primary_agent`; supply primary-source URLs | | `triggers.multi_file: true` | Add `auditor` to required_gates if not present; run scope check | | `triggers.quality_sensitive: true` | Add `reviewer` to required_gates if not present | | `complexity: high` + no `delegation` block | Spawn a planning role first to design the change | | Story already `in_progress` from prior session | Resume (don't reset) — read the agent's last output or partial artifact | ## 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.