forgemaster
Route a task by complexity and run the gated Forge pipeline (research → plan → implement → ship). Use when the user runs /forgemaster or wants the full guided feature pipeline.
SKILL.md.agents/skills/forgemaster/SKILL.md
GitHub/forgemaster — Route by complexity, then run the Forge pipeline gated phase by phase
Judge the complexity of the request, route to the right-sized Forge path, then run it gated —
pausing at each boundary for your approval. Medium-or-higher work runs the full four-phase pipeline
(research → plan → implement → ship); low-complexity work is handed to the trimmed
forge-mini path to save turns and cost. You stay in control at every step.
See .claude/workflows/forge.md (full) and .claude/workflows/forge-mini.md (mini) for details.
Usage
Accepts a JIRA ticket, a Beads issue id, or a free-text description — or nothing, to resume the active run.
/forgemaster <description> # free text → judge complexity, route, run
/forgemaster <BEADS-ID> # e.g. agent-forge-harness-f25 → load that issue as the work
/forgemaster <JIRA-KEY> # e.g. PROJ-1234 → mirror into Beads, then run
/forgemaster # resume the run in flight (see: bun run forge:runs)
/forgemaster --full <input> # force the full pipeline (skip the complexity check)
/forgemaster --mini <input> # force the mini path (skip the complexity check)
/forgemaster <input> --smith <name> # record the run as built by a configured smith (see Notes)
Step 0 — Preflight (mandatory)
Beads is required for this pipeline. Confirm it is reachable before anything else:
bd ready >/dev/null # if this errors, the Dolt server is down
If bd errors: run bd dolt start, then retry. Do not proceed without Beads. (The SessionStart
hook normally starts the server automatically; this is the manual recovery.)
Resolve the input → a Beads-tracked work item + <slug>
Detect what was passed and normalize it to one Beads issue plus a kebab-case <slug>. Check in this
order (the first match wins):
- Strip flags (
--full/--mini/--smith <name>) and trim whitespace. - Empty → resume: run
bun run forge:runs --active. With exactly one run in flight, resume it at its first incomplete phase (always a full run; skip the triage in Step 0.5, go to Step 1). With several, ask which one — runs are concurrent, so "the active run" is not a thing to guess. - Existing Beads id —
bd show <arg>succeeds (e.g.agent-forge-harness-f25): use that issue as the work definition (title, description, AC). Do not create a duplicate — it is the tracking issue; the plan phase may add child tasks under it. Derive<slug>from its title. Claim it when implementation starts. - JIRA key — matches
^[A-Z][A-Z0-9]+-\d+$(e.g.PROJ-1234) and is not an existing bead:- Fetch the ticket if a JIRA integration is available (a JIRA MCP server or a
jiraCLI on PATH). If none is configured, ask the user to paste the ticket summary + description + acceptance criteria — do not invent them. - Mirror it into Beads (Beads stays the source of truth), linking back to JIRA:
Priority viabd create --type <feature|bug|task> --title "[<repo>] <summary>" \ --priority <p> --external-ref "jira-<KEY>" --acceptance "<AC>" --description "<body + JIRA link>".claude/skills/beads-priority-assignment/SKILL.md. Derive<slug>from the summary (e.g.proj-1234-<short-title>).
- Fetch the ticket if a JIRA integration is available (a JIRA MCP server or a
- Free text → derive a kebab-case
<slug>; the Beads issue is created later (full: in the plan phase; mini: in the scope step).
Confirm the resolved <slug> and a one-line work summary with the user before continuing.
Step 0.5 — Complexity triage & route
Pick the right-sized path before doing real work — running the full pipeline on a one-file change wastes turns and money (cost is the whole point of this step).
--full/--miniflag present → honor it, skip the judgment.- Resuming an existing full run → stay full.
- Otherwise judge complexity from cheap signals (a quick look, not a research project): aligns with
the tiers in
.claude/commands/go.mdand the model-tier rubric in.claude/protocols/model-tier-policy.md.
| Signal | → Mini | → Full |
|---|---|---|
| Files touched | ≤ ~3 | > 3 |
| New architecture / component / system | no | yes |
| Genuine unknowns or design decisions | ≤ 1 | several |
| Scope clarity | clear from the ask + code | ambiguous, needs investigation |
| Cross-cutting / shared interfaces | no | yes |
Default when uncertain: ask, don't assume. Use AskUserQuestion to state your read and the
recommended route, letting the user confirm or override:
- Mini → follow
.claude/workflows/forge-mini.md(scope → build → wrap). Do not use theforge:phase-gate/ run state files or writeplans//reports/docs; track in Beads only. (A mini run keeps no run state unless it was given--smith: then its wrap step records one run, as that workflow says.) Then go straight to that workflow — the phase-walk below is for the full path. - Full → continue to Step 1 with the
<slug>resolved in Step 0.
If a mini run outgrows its size mid-flight, escalate to full (/forge-research <slug>) as described
in forge-mini.md.
Step 1 — Walk the phases (full path)
For each phase in order — research, plan, implement, ship — do this loop:
Gate entry. Run
bun run forge:phase-gate <phase> --slug <slug>. If it exits non-zero, read itserror: usually the prerequisite artifact is missing — stop and tell the user which earlier phase to run. (With--smith, it can also be a name that is not configured.)Announce. Tell the user which phase is starting and where its output will land (see the table in
.claude/workflows/forge.md).Run the phase by following its skill end to end:
- research →
.claude/skills/forge-research/SKILL.md - plan →
.claude/skills/forge-plan/SKILL.md - implement →
.claude/skills/forge-implement/SKILL.md - ship →
.claude/skills/forge-ship/SKILL.mdThe phase records its own completion (forge:phase-gate <phase> --slug <slug> --write --bead <id>). Which issue each phase names, and when research names none, is in.claude/workflows/forge.md, Which bead a phase names: a task until the close, the feature or epic only on the ship write.
- research →
Show the exit artifact. Surface what the phase produced (the research/plan/ship doc, the demoed checkpoints, the PR) so the user can inspect it.
Gate the transition. Use
AskUserQuestionto ask whether to proceed to the next phase:- Proceed → continue to the next phase.
- Revise this phase → re-run the current phase skill with the user's feedback.
- Stop here → end the run; the state file preserves progress for later resumption.
Never auto-advance across a phase boundary. The pause is the point.
Step 2 — Finish
After the ship phase records complete:
- Confirm
reports/<slug>-ship.mdand the PR exist. - The Stop exit hook goes quiet automatically once ship is complete.
- Summarize the whole run: the slug, the four artifacts, the Beads epic/feature closed, and the PR.
Notes
- Within a phase, the implement phase still pauses at its own demo/test checkpoints — those are finer-grained stops than the phase boundaries this command gates.
- Resuming:
/forgemaster <slug>(or bare/forgemaster, when exactly one run is in flight) picks up at the first incomplete phase recorded in.tmp/work/forge-runs/<slug>.json. - Concurrent runs: each run owns its own state file, so several can be in flight at once.
bun run forge:runslists them. Give each code-touching run its own worktree (bun run worktree create <branch>, then--checkout <path>on the phase-gate write) so two runs do not build on top of each other. --smith <name>: records the run as built by that configured smith (a provider, a model and an effort:bun run forge:config show). Add it to everyforge:phase-gatecall of the run, the entry check of Step 1 and each phase's write: a name that is not configured is refused, and the write stores the smith on the run. It does not change the model of the session reading this command. Everything else about it is in.claude/workflows/forge.md,--smith.- Unattended:
/forgemaster-autoruns the same four phases with a subagent review at each boundary instead of asking you — see.claude/workflows/forge-auto.md. - Standalone phases: you can always run a single phase directly (
/forge-plan <slug>) instead of the full orchestration; the same gates apply.