Forge: robust-development workflow

Forge is a 10-step pipeline that produces robust, code-grounded feature implementations. The value comes from the gates: parallel domain experts surface cross-domain conflicts; the adversarial critic ground-truths the plan against the actual code; the user-approval step gives the human the chance to redirect before any edit happens; parallel implementers in isolated worktrees finish the work without stepping on each other.

The workflow is heavy by design. Dispatching parallel agents (instead of doing all the analysis in the main session) is also the token-cost lever — the main session never reads the full expert or implementer transcripts, only their structured reports.

When to enter the workflow

Enter forge when ANY hold:

• The feature crosses ≥ 2 architectural areas (UI + persistence; service + worker; etc.).
• The feature touches a hot path or trust boundary (UI render loop, request handler, auth, parser).
• The user says "review this design", "use forge for this", or similar.

For trivial localized changes (typo, single-method bug fix, copy edit), do NOT use forge — direct edit is appropriate.

The 10 steps

Steps 1, 2, 2.3, 2.5, 7 run in the main session with no skill — they are orchestrator actions. Steps 9 and 10 are produced by a single skill (/forge:build-and-report) in one pass. Step 8 runs /forge:dispatch-implementation when the plan has ≥ 2 disjoint steps; otherwise the orchestrator implements directly in-session.

Model rationale: the research-shaped subagents (experts, critic) pin fable in their frontmatter — investigation depth is their purpose, and the pin holds even when the session runs a cheaper model. The synthesis steps (4, 6) inherit the session model so they never age into a downgrade when newer models ship. Implementers stay sonnet as a deliberate cost choice — they execute a plan the experts and critic already verified.

Deep mode — user opt-in upgrade for Steps 3 and 5

Deep mode upgrades the two research dispatches from Agent calls to Workflow orchestration. Enter it ONLY when BOTH hold:

• The user explicitly asked for a deep / thorough / exhaustive run ("deep forge", "be thorough", "ultracode"). Depth is a user opt-in, never an orchestrator inference — multi-agent fan-out at this scale is the user's call.
• The Workflow tool is available in the session (requires Claude Code ≥ 2.1.154).

If either fails, run the standard pipeline; deep mode is an upgrade, not a prerequisite. What changes:

• Step 3 — /forge:expert-analysis dispatches the experts through a Workflow script with schema-validated reports (see that skill's "Deep mode" section). Malformed reports are retried at the tool layer instead of hand-parsed by heading.
• Step 5 — /forge:critic-review runs the critic plus a two-refuter panel per Blocking finding (see that skill's "Deep mode" section). Panel verdicts arrive pre-flagged for /forge:plan-revise, which verifies the likeliest misfires first.
• Everything else is unchanged: same gates, same Step 7 approval, same implementation routing.

Step 2.3 — Domain-skill scan

After the structural search, check whether the consuming project has skills in .claude/skills/ that claim domain authority over any area the feature touches. A skill is a domain-authority candidate when its description uses words like "authoritative", "schema", "reference", or names the domain by type (e.g. "rAthena YAML database schemas", "rathena scripting API").

For each matching skill, invoke it with the Skill tool immediately — before Step 2.5 and before expert dispatch. Its output becomes supplemental domain authority for this forge run: pass it inline in the relevant expert dispatch prompt (see /forge:expert-analysis Dispatch Template — the optional ## Domain authority section) so the expert starts from pre-baked knowledge rather than file searches.

Why this step exists: experts and the reality-check spike read files to answer schema questions. A project skill that already encodes the authoritative answer is faster, more reliable, and prevents experts from disagreeing on field names that the skill has already settled.

Skip Step 2.3 only when the project has no .claude/skills/ directory or no skill description matches the feature's domain.

Step 2.5 — Reality-check spike

Before dispatching experts, run a ≤ 30-line spike against the single riskiest assumption — whichever claim, if false, would invalidate the whole design. Examples: "does this metric actually separate the cases in real data?", "does this API return the shape we assumed?", "does the existing parser already emit the event we want to subscribe to?".

If the spike refutes the assumption, STOP — surface the refutation to the user with file:line evidence and ask for a corrected scope before continuing. Do NOT silently re-scope.

Skip Step 2.5 only when the feature has no risky assumption (pure refactor, well-trodden CRUD, well-covered by existing patterns).

Step 7 — Approval gate

The master plan is built to direct Claude — W-IDs, file:line citations, done-when criteria, contract clauses. Presented raw, it trains users to approve without reading. So present in two layers: a short plan digest first, then the full plan beneath it for anyone who wants the detail.

Write the digest for a developer who has NOT followed the pipeline: technical terms are fine (this reader is a dev), plan machinery is not — no W-IDs, no file:line lists, no contract-clause numbering. Shape:

## What this plan does

<2–3 sentences: the intention — what gets built, and why it answers what the user asked for.>

**The change:** <1–2 sentences naming the areas touched in dev terms — "a new handler in the request pipeline plus a settings toggle", not file paths.>

**Worth knowing before you approve:**
- <the 1–2 real risks, stated as what the user would observe if they bite>
- <what the critic changed, if anything: "the critic caught X; the plan now does Y">
- <decisions still open — the same questions the plan's Open questions section escalates>

**How we'll know it works:** <one sentence: the test command, build, or smoke test that verifies it.>

Cap the digest at ~12 lines and skip any bullet with nothing real to say. The digest is presentation only — the full plan below it remains the single canonical artifact the critic verified and the implementers receive. Never let the digest drift into a second plan, and never edit the plan via the digest.

Immediately after the digest + plan, MUST invoke AskUserQuestion:

AskUserQuestion(questions: [{
  question: "The revised plan is ready. Do you approve implementation?",
  header: "Approval",
  multiSelect: false,
  options: [
    { label: "Approve",   description: "Proceed to implementation. Parallel implementers if the plan has ≥ 2 disjoint steps; in-session otherwise." },
    { label: "Revise",    description: "Tell me what to change; I'll update the plan before implementing." },
    { label: "Cancel",    description: "Abort the forge run at this point." }
  ]
}])

No risk tiers. No diff preview. The user reads the digest for intention and the plan for detail, then approves, asks for a revision, or cancels.

After approval (Step 8)

Default mode is parallel-first: invoke /forge:dispatch-implementation whenever the plan has ≥ 2 steps marked Parallel-friendly: yes (the annotation guarantees disjoint Files-touched sets and no ordering dependency). One forge-implementer subagent per qualifying step, each in isolation: "worktree", all dispatched in a single tool-use block.

Fall back to in-session implementation when the plan has < 2 disjoint parallel-friendly steps. In that case the orchestrator writes the code directly; the coordination overhead of parallel dispatch does not pay for itself on a single coherent edit.

Build and report (Steps 9 and 10)

After implementation lands, invoke /forge:build-and-report. The skill bumps the version per the consuming project's convention (read from the project's CLAUDE.md), runs the project's build / verification commands, and emits the final report with the two mandatory sections "How to test this feature" and "How is this feature useful?".

The forge plugin is stack-agnostic; the actual version-bump file (plugin.xml, package.json, Cargo.toml, pyproject.toml, etc.) and build command (./gradlew buildPlugin, npm run build, cargo build, pytest) are the consuming project's responsibility to declare in its own CLAUDE.md.

Workflow principles

• Citations required. Experts, critic, plan — every claim cites file:line (or a doc URL for claims an expert verified against external documentation). Summaries without citations break verification chains.
• Single canonical plan in conversation. /forge:plan-revise rewrites in place; the conversation never holds v1 + v2 + v3 simultaneously.
• Foreground subagents. Every Agent dispatch in this workflow is run_in_background: false. The next step needs the prior step's output. (Deep-mode Workflow runs return via task notification — wait for the result; never start the next step on a pending workflow.)
• Resume when context is an asset; re-dispatch when it misleads. Decision-only blockers and contested critic findings continue the original subagent via SendMessage (its read context and worktree are intact). Fresh dispatch is for changed assignments — re-sliced work units, re-scoped expert coverage — where stale context is a liability. Fall back to fresh dispatch when SendMessage is unavailable.
• No persistent state files. The plan, critique, and expert reports live in conversation context. The workflow does not write .claude/plans/*.md or similar.
• User approval is non-negotiable. Step 7 is the gate. The orchestrator never silently proceeds to writing code.
• `TaskCreate` per work unit before dispatch. When /forge:dispatch-implementation runs, MUST invoke TaskCreate for each work unit (paired content + activeForm) before the parallel Agent calls — the dispatch skill's body specifies the exact wording.

Re-running a single phase

The action skills are independently invocable for re-runs:

• Bad expert coverage → re-run /forge:expert-analysis with a different role list (fresh dispatch — the original experts' context reflects the wrong scope).
• Plan needs revision after the user pushed back → re-run /forge:plan-revise. Re-dispatch the critic only if the change is structural.
• One dispatched implementer blocked on a decision, work unit unchanged → resume it via SendMessage with the ruling. Blocked because the step itself was wrong → re-run /forge:dispatch-implementation 2 (just unit W2) after revising the plan.
• Build broke after a tangential change → re-run /forge:build-and-report.

Each action skill is user-invocable: false — only the orchestrator (Claude) invokes them, at the right step in the pipeline. They are deliberately hidden from the slash-command menu so the workflow runs as a single coherent pipeline driven by this reference. Do not auto-fire skills out of sequence: the workflow's value comes from the gates between steps, and skipping ahead defeats them.