jupes/agent-forge-harness / .agents/skills/forge-plan
forge-plan
VerifiedTurn Forge research into a validated implementation plan and Beads dependency graph. Use for /forge-plan or the pipeline's planning phase.
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.
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.
--smith <name>: when the run was started with it, add --smith <name> to every
forge:phase-gate call in this skill. The phase gate refuses a name that is not configured and
records the smith on the run as its executor. It does not change the model of the session doing the
work (.claude/workflows/forge.md, --smith).
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.
Each checkpoint becomes one Beads task, so give each one two more things:
- A complexity label:
complexity:low,complexity:mediumorcomplexity:high. It names the bench of smiths a task is routed to when its value is handed toforge:exec --complexity(.claude/protocols/model-tier-policy.md). Nothing reads the label from Beads yet. - A file map: the globs the task may touch, one per line under a
Filesheading, relative to the repository root. The implement phase holds the worker to it, and the scheduler reserves it: a queued task whose map overlaps a reservation, or the map of a task ahead of it (tasks in progress and tasks holding a reservation come first, then bundle order), waits (bun run forge:eligibleshows which and why). Keep it as narrow as the work allows. The scheduler reads the map from the task's description, else from its acceptance criteria. A task whose map is missing, empty or malformed reserves the whole repository (**), so it runs alone. An entry whose last segment has no wildcard (scripts/scheduler) also reserves everything under it.
The file map has one format, read by parseFileMap in scripts/scheduler/filemap.ts:
- A glob is a relative path with forward slashes.
*stands for any run of characters inside one path segment,?for one character, and a segment that is exactly**for any number of segments (src/**/a.ts, notsrc/**a.ts); every other character stands for itself.{a,b}alternation is not part of the format: write one glob per line. - Nothing but globs under the heading. A line with a space in it, an absolute path, a
..segment, a backslash, a<placeholder>or a# noteis refused, and one refused line refuses the whole map. - Blank lines are skipped, and so is a one-line
<!-- … -->comment (a comment that wraps onto a second line is refused); a list bullet and backticks around a glob are dropped;dir/means everything underdir. - The section ends at the next heading (
##or deeper) or horizontal rule, so put theFilesblock last in the checkpoint. - The template starts every map at
**, the whole repository: the map of a task that could touch anything, which overlaps every other task. Replace it with the paths the task really touches. A map that has to stay at**says why in a one-line<!-- … -->comment above it.
A worked example is in references/example-plan.md. Step 4 ends with the command that checks every
checkpoint's map once the plan is written.
4. Write the plan document
Write to plans/drafts/<slug>.md (matches the existing /plan convention):
Read the artifact template at this step and fill each applicable section with verified evidence.
Then check the maps, before any task is created from them. The parser reads only the first Files
section of a text, so a plan is checked checkpoint by checkpoint, and a refusal names the line of the
plan:
bun run scripts/scheduler/filemap-cli.ts plans/drafts/<slug>.md --plan # exit 0: every checkpoint has a usable map
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 <id> "review: plan <VERDICT> — <#B>/<#H>/<#M>/<#L>"
(<id>: the issue the run was started from; if there is none yet, keep the lines and log them
on the feature once step 6 has created it)
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 <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, unless the run was started from an issue (see below)
bd create --json --type feature --title "[<repo>] <feature title>" --priority <p> \
--description "<summary>" --acceptance "<top-level acceptance criteria>"
# One task per checkpoint (or per behavior for fine-grained TDD), with its label and its file map
bd create --json --type task --title "[<repo>] <checkpoint/behavior>" --priority <p> \
--labels "complexity:<low|medium|high>" \
--acceptance "<the test(s) that prove this done>" \
--body-file .tmp/work/<slug>-task-<letter>.md
# Sequential dependencies between checkpoints: the later one depends on the earlier one
bd dep add <later-id> <earlier-id>
A run that was started from an existing issue does not get a second one to group it. That issue
is the run's tracking issue (.claude/commands/forgemaster.md, Step 0): skip the feature, and create
each checkpoint's task under it by adding --parent <id> to the task line, also when the plan has
one checkpoint, so that every checkpoint has a task that carries its label and its file map. What
the run's writes then name depends on what the starting issue is (step 7 and
.claude/workflows/forge.md, Which bead a phase names):
- a task, a bug or a chore: the run names it with
--beadon its plan and implement writes, and closes it at the ship step; - a feature or an epic: it is the
--epicof those writes, which name the checkpoint tasks, and it is named with--beadonly by the ship write.
A child inherits its parent's labels, a complexity:* label included. If the starting issue carries
one, add --no-inherit-labels to the task line so the child has only its own.
The task's description is read from a file so that the file map keeps its lines. Write one per task
from its checkpoint: what the task delivers, then the checkpoint's map under ## Files (the heading
is ## in a description). Check each file before the task is created:
bun run scripts/scheduler/filemap-cli.ts .tmp/work/<slug>-task-<letter>.md # exit 0: the map is usable
<what this task delivers, in a sentence or two>
## Files
<!-- This task's file map: one glob per line, relative to the repository root. Replace ** with the paths this task touches. -->
**
A map the parser refuses is not a map: fix it in the plan before the task is created.
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. The run's state learns them from the
write in step 7: --bead for the task it names, --epic for the issue that groups them.
If Beads/Dolt is unavailable (bd errors), note it in the plan under a ## Beads heading,
record the missing issue graph and continue drafting. Restore tracking before marking
this phase complete or handing tasks to implementation; a draft is not an executable issue graph.
7. Approve & hand off
Present the plan summary (scope, checkpoints, Beads created). For an attended run,
obtain the configured plan approval; for an explicitly unattended run, use the review
gate in .claude/workflows/forge-auto.md. Advance only when that gate is satisfied:
bun run forge:phase-gate plan --slug <slug> --write --bead <task-id> --epic <feature-or-epic-id>
<task-id> is the issue the run was started from (a task, a bug or a chore), else the first task
the plan created: the one the implement phase claims first. --epic names the feature or epic that
groups the tasks; leave it out when there is none, and never pass that issue as --bead here. The
command prints the run's correlation as data.correlation: from this write on, a quality gate can be
tied to the task being built (.claude/workflows/forge.md, Which bead a phase names).
Then point to the next phase: /forge-implement <slug> (or /forgemaster continues).
Exit Criteria
-
plans/drafts/<slug>.mdexists with TDD Strategy and Checkpoints filled. - Each checkpoint names a demo command or is explicitly
(no live demo). - Each checkpoint has a complexity label and a file map, and
bun run scripts/scheduler/filemap-cli.ts plans/drafts/<slug>.md --planexits 0; a map still at**says why in a comment. - 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 exist and are mapped in the plan; a tracker outage leaves the phase incomplete.
- The attended approval or authorized unattended review gate is satisfied; forge state advanced to
plancomplete.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |