Build Plan

Build Plan

Decompose a PRD into an implementation plan. PLAN ONLY — no implementation code is written.

Arguments

Slug matching an existing PRD. Example: build-plan clybor-skill-discovery-research.

If no argument, prompt for the slug or list candidates from .claude/PRPs/*/prd.md.

Phase 1: PARSE + PARALLEL LOAD

Batch in one message — these reads have no dependencies:

• Read .claude/PRPs/{slug}/prd.md (verify status drafting/approved; all sections filled; anchor case concrete; mirror named-or-flagged)
• Read .claude/PRPs/_profiles/{type}.md (profile from PRD frontmatter)
• Read mirror target verbatim (path from PRD)
• Profile's mandatory-reading paths — Read each in the same batch (not sequentially)

If any PRD check fails: stop, surface the gap, instruct user to revise via build-prd or direct edit.

Phase 2: ADVERSARIAL RE-READ OF PRD

The PRD is the source document for this plan. First-pass extraction misses 15-25% per the adversarial-re-read skill. Invoke it before planning:

Skill(skill="adversarial-re-read", args="source=.claude/PRPs/{slug}/prd.md target=plan-for-{slug}")

The re-read returns a synthesis-vs-source diff identifying everything the first read missed. Treat each finding as a planning constraint.

Phase 3: GROUND THE MIRROR (parallel Explore)

The mirror target's sibling files often matter as much as the file itself (shared scripts, profile, templates, related skills in the same plugin). Spawn Explore — independent search, no need for the main context window to hold all the file content:

Agent(
  subagent_type="Explore",
  description="Map mirror target and its environment",
  prompt="Read the mirror target at {path from PRD} and identify: (1) which sections to copy verbatim, (2) which sections need adaptation for this build, (3) which sibling files in the same folder/plugin are referenced. Return a section-by-section copy/adapt/skip recommendation plus a list of sibling files worth reading. Search breadth: medium."
)

Phase 4: DECIDE THE SHAPE

Use mcp__sequential-thinking__sequentialthinking to choose ONE shape:

The shape determines what build-execute does: single-shot = one pass; iterative-bounded = calibration loop with hard caps; pipeline = sequential per-stage execute; wrapper = compose existing pieces.

Pipeline shape → scaffold numbered stage folders

When the shape is Pipeline, the plan MUST scaffold the execution structure (mirror docs/templates/stage-pipeline/):

• Create .claude/PRPs/{slug}/stages/NN-{stage-name}/ per stage — zero-padded prefixes encode execution order; reordering = renaming folders.
• Each stage folder gets a CONTEXT.md contract — Inputs (source / where / why), Process (numbered steps), Outputs (artifact / location / format) — under 80 lines, plus an output/ folder for the handoff artifact.
• A stage reads ONLY its declared Inputs (previous stage's output/ + named references). Everything else is do-not-load.
• build-execute walks stages in folder order with a human review gate at every boundary: Shawn inspects output/ before the next stage runs; the next stage picks up whatever he left.
• Plan tasks map 1:1 to stages; each stage's DONE check = its Outputs exist and satisfy the contract.

Phase 5: WRITE THE PLAN (delegate step-decomposition to Plan agent)

The step-by-step decomposition is exactly what the Plan subagent exists for. Spawn it AFTER the shape is locked but BEFORE you write the plan file:

Agent(
  subagent_type="Plan",
  description="Decompose {slug} into step-by-step tasks",
  prompt="Design a step-by-step implementation plan. Shape: {shape}. PRD: <paste>. Mirror recommendation: <paste from Phase 3 Explore output>. Adversarial re-read findings: <paste from Phase 2>. Return: numbered tasks, each with a binary DONE check. No 'polish' or 'finalize' steps. Identify which files get touched in which order."
)

Copy .claude/PRPs/_templates/plan-template.md to .claude/PRPs/{slug}/plan.md. Fill every section using the Plan agent's output as the basis for "Step-by-step tasks":

• Mandatory reading: exact file paths + line ranges. Vague references ("the relevant skill") are not allowed.
• Mirror target: path + which sections to copy verbatim vs adapt.
• Step-by-step tasks: numbered, one line each, no hard-wrapping (wrapped text breaks later find-and-replace edits and makes file:line citations drift). Each task has a DONE check that can come back red — binary is not enough. A grep for a phrase the task itself wrote is binary and unfalsifiable; check behaviour the task changed instead. No "polish" or "finalize" tasks.
• Acceptance checklist: reference each PRD criterion by number and label. Never restate a criterion's condition — that creates a second copy which drifts from the PRD.
• Test authorship map: every artifact the acceptance test names, and the one task that creates it. Build-execute ticks tasks, not checklist lines, so an unauthored artifact ships unbuilt.
• Dependency order: the real edges, not the task numbering. Flag any DONE that cannot be evaluated until a later task lands.
• Acceptance test: how build-evaluate will measure success. Reference the PRD's anchor case explicitly.
• Anti-patterns to avoid: from the profile, plus anything specific to this build.
• Estimated effort: produced by the build-estimate skill, not typed. Write the spec (.claude/PRPs/{slug}/estimate/estimate-<date>.json: tasks by kind and status, fixed gates, process profile, calendar), run estimate.py project, paste the output. The section must carry the tool's rate per task unit … [MEASURED|ASSUMED] line so a reader can see what the number rests on. Helps execute pick the right caps.

Phase 6: SAFETY CHECK

6a — mechanical gate. Run it; do not eyeball it.

python3 .claude/hooks/check-plan-soundness.py .claude/PRPs/{slug}/plan.md --prd .claude/PRPs/{slug}/prd.md

Non-zero exit means the plan has a defect that a reviewer panel would otherwise spend an hour finding. Fix and re-run until it passes — do not proceed to Phase 7 on a failing plan. It checks six things no amount of careful reading reliably catches:

• a DONE check that greps a string its own task body wrote (can never go red)
• an artifact the acceptance test uses that no task authors (ships unbuilt)
• a DONE that depends on a later task's output (unevaluable when it runs)
• a criterion whose wording disagrees across the PRD table, PRD checklist and plan checklist
• a dependency cycle, or an edge naming a task that does not exist
• a duplicate task number

If it reports zero tasks parsed, the task lines are malformed — fix the format rather than ignoring the run.

6b — profile patterns. If the profile defines forbidden patterns (e.g., "skill description > 1024 chars," "plugin.json missing version bump"), grep the plan for them. If any appear, flag and refuse to exit — the plan as written will fail validate.

Phase 7: LINK BACK

Edit the PRD frontmatter: set status: planning and add plan_ref: .claude/PRPs/{slug}/plan.md.

Output

## Plan Generated: {PRD title}

**Plan:** .claude/PRPs/{slug}/plan.md
**PRD:** .claude/PRPs/{slug}/prd.md (status → planning)
**Shape:** {single-shot / iterative-bounded / pipeline / wrapper}
**Mirror:** {path to mirror target, or "none — adversarial review will be heavier"}
**Estimated effort:** {minutes / hours / days}

### Next step
Size it: `build-estimate {slug}` (optional, never a gate), then `build-execute {slug}`.
Sequence: **prd → probe → validate → plan → estimate → build → evaluate**.
⚠ Re-run `bash .claude/PRPs/{slug}/probes/run.sh` first — it costs seconds and catches a cited source moving underneath the plan.

Guidelines

• This skill writes ONLY the plan markdown. No implementation files.
• Mirror existing artifacts aggressively. New structure invites bugs.
• The acceptance test must reference the PRD's anchor case. If it doesn't, you wrote the wrong test.
• "Step-by-step tasks" must each have a DONE check that can come back red. Binary is necessary but not sufficient: grep -q "never drops" schema.md, on a file the same task wrote, is binary and cannot fail. Tasks that say "improve X" are a smell.
• Phase 6a is a gate, not advice. A plan that fails check-plan-soundness.py will fail build-validate for the same reasons, an hour later and at the cost of a five-agent panel.