forge-plan

name

forge-plan

description

Phase 2 of the Forge pipeline. Turn a research document into an implementation plan that is built around Beads issues and TDD. Reads plans/research/<slug>.md, designs the build, sets up red-green-refactor test strategy using the tdd skill, materializes a Beads epic/feature/tasks with dependencies and priorities, and defines demo/test checkpoints. Use when starting /forge-plan or the plan step of /forgemaster.

forge-plan

Phase 2 of 4 in the Forge pipeline (research → plan → implement → ship). Input is the research document from [[forge-research]]; output is plans/drafts/<slug>.md plus a Beads issue graph.

The plan is not just a file — it is a Beads-tracked, TDD-shaped build sequence with explicit points where the user can see the work running.

When to Use

• The user runs /forge-plan <slug> or /forgemaster enters its plan phase.
• A plans/research/<slug>.md exists (or the user wants to plan a researched feature).

Prerequisites

bun run forge:phase-gate plan --slug <slug>     # verifies research artifact exists
cat plans/research/<slug>.md                    # the source of truth for this plan

If no research document exists, stop and tell the user to run /forge-research <slug> first. Do not invent research.

Process

1. Absorb the research

Read plans/research/<slug>.md end to end. The plan must be consistent with its decisions, constraints, and non-goals. If you find a contradiction, surface it instead of silently diverging.

2. Set up TDD for the feature

Read and follow the TDD skill at .claude/skills/tdd/SKILL.md (see also its tests.md, interface-design.md, deep-modules.md). Apply its discipline to this feature:

• List behaviors to test, not implementation steps — phrase each as a specification ("user can save settings and they survive a refresh").
• Design the public interface for testability (small interface, deep implementation).
• Plan vertical slices: one failing test → minimal code → repeat. Reject horizontal slicing (all tests first, then all code).
• Mark the tracer-bullet behavior: the first end-to-end test that proves the path works.
• Name the test files that will hold these behaviors, adjacent to source (*.test.ts).

Capture this as the plan's Test Strategy section (below).

3. Design the build sequence with demo checkpoints

Break the work into ordered steps. Group steps into checkpoints — points where something is runnable and observable. Each checkpoint must name a concrete command or action the user can run to see progress (a test, a dev server route, a CLI invocation). Mark a checkpoint (no live demo) only when the work genuinely has no observable surface yet.

4. Write the plan document

Write to plans/drafts/<slug>.md (matches the existing /plan convention):

# Plan: <slug> — <feature title>
Generated: <date>
Repo: <repo>
Phase: plan (2/4) — from plans/research/<slug>.md

## Summary
<~100 tokens: what is being built, why, the approach>

## Existing Code to Reuse
- `path` — <how it is reused> (from research)

## TDD Strategy (red-green-refactor)
Following .claude/skills/tdd. Behaviors are tested through public interfaces, vertically.

| # | Behavior (as a spec) | Test file | Tracer? |
|---|----------------------|-----------|---------|
| 1 | <observable behavior> | `x.test.ts` | yes |
| 2 | <observable behavior> | `x.test.ts` | no |

Refactor watch-list (after green): <duplication / deep-module opportunities>.

## Build Sequence & Checkpoints
### Checkpoint A — <name>
Steps:
1. <step> — `path` — <change>
2. <step> — `path` — <change>
Demo: `bun test path/x.test.ts` (or `bun run dev` → /route) — user sees <observable result>.

### Checkpoint B — <name>
...
Demo: `(no live demo)` — internal refactor, verified by tests only.

## Files to Create / Modify
| File | Create/Modify | Purpose |
|------|---------------|---------|

## Validation Commands
\`\`\`bash
bun run typecheck
bun test <paths>
\`\`\`

## Beads Issue Map
| Beads ID | Type | Title | Depends on | Priority |
|----------|------|-------|-----------|----------|

## Estimated Scope
- Files: <n new / n modified>; Complexity: Low|Medium|High; Checkpoints: <n>

5. Plan review loop

Before creating Beads issues, run a review-plan feedback loop to catch false premises early. Spawn a review-plan sub-agent (Agent tool, subagent_type: "Explore", prompt: "Review plans/drafts/<slug>.md using the review-plan skill"). Loop up to 2 turns; stop early when the verdict is SOUND (zero Blocker + High + Medium findings).

turn = 0
loop:
  1. Spawn Agent (review-plan skill) → returns verdict + findings by severity
  2. Log: bd comments add <feature-id> "review: plan <VERDICT> — <#B>/<#H>/<#M>/<#L>"
  3. If SOUND (no Blocker/High/Medium):  break — plan is clean
  4. turn += 1
  5. If turn >= 2:  break — maximum turns reached
  6. Address every Blocker, High, and Medium finding by editing plans/drafts/<slug>.md
     Log: bd comments add <feature-id> "worklog: plan revised after review turn <turn> — <summary>"
  7. Continue loop

After the loop, tell the user the final verdict and turn count (e.g. "SOUND after 1 review" or "NEEDS REVISION — 2 review turns exhausted"). If Medium+ findings remain after 2 turns, surface them explicitly so the user can decide whether to address them before implementing.

6. Materialize Beads

Create the issue graph that the implement phase will execute. Set --priority on every issue using .claude/skills/beads-priority-assignment/SKILL.md (see [[beads-priority-assignment]]).

# One feature (or epic) to group the work
bd create --json --repo <repo> --type feature --title "<feature title>" --priority <p> \
  --description "<summary>" --acceptance "<top-level acceptance criteria>"

# One task per checkpoint (or per behavior for fine-grained TDD)
bd create --json --repo <repo> --type task --title "<checkpoint/behavior>" --priority <p> \
  --acceptance "<the test(s) that prove this done>"

# Sequential dependencies between checkpoints
bd dep add <later-id> --requires <earlier-id>

Prefer one task per checkpoint so each closed task maps to something the user saw run. Record every created id back into the plan's Beads Issue Map and the forge state.

If Beads/Dolt is unavailable (bd errors), note it in the plan under a ## Beads heading, list the issues that should exist, and continue — do not block planning.

7. Approve & hand off

Present the plan summary (scope, checkpoints, Beads created) and ask the user to approve. On approval, advance the forge state:

bun run forge:phase-gate plan --slug <slug> --write

Then point to the next phase: /forge-implement <slug> (or /forgemaster continues).

Exit Criteria

• plans/drafts/<slug>.md exists with TDD Strategy and Checkpoints filled.
• Each checkpoint names a demo command or is explicitly (no live demo).
• Plan review loop ran: SOUND verdict reached, or 2 turns completed; outcome logged to Beads.
• Any remaining Medium+ findings (after 2 turns) surfaced to user before proceeding.
• Beads issues created (or their absence noted with reason) and mapped in the plan.
• User approved the plan; forge state advanced to plan complete.