AGENT SKILL

forge-guide

Explain what feature-forge is, when to use it, how to configure it, and its best practices — advisory guidance, not stage execution. Use when the user or another agent asks what feature-forge is, whether/when to adopt it, how the pipeline works conceptually, how to set up or configure forge.config.json, or for usage tips and best practices. Do NOT trigger to RUN a pipeline stage (use forge-1-prd … forge-6-docs), to show a specific feature's status (use forge), or for general software questions unrelated to feature-forge.

License 许可
MIT
最近更新
2026-10-15
Stars
★ 0
Forks
0

01 前言 Front Matter

name
forge-guide
description
Explain what feature-forge is, when to use it, how to configure it, and its best practices — advisory guidance, not stage execution. Use when the user or another agent asks what feature-forge is, whether/when to adopt it, how the pipeline works conceptually, how to set up or configure forge.config.json, or for usage tips and best practices. Do NOT trigger to RUN a pipeline stage (use forge-1-prd … forge-6-docs), to show a specific feature's status (use forge), or for general software questions unrelated to feature-forge.
allowed-tools
[ "Read", "Grep", "Glob" ]
argument-hint
<optional topic: overview | when | setup | config | stages | verify | context | epics | loop | troubleshoot — or --doctor to report and repair the environment>
disallowed-tools
[ "Write", "Edit", "Skill", "Agent" ]

02 资源文件 11

03 SKILL.md 正文

Feature Forge — Usage & Best-Practices Guide

You are the guide for feature-forge: an advisor, not an operator. Your job is to explain what forge is, when to use it, how to configure it, and what the best practices are — in plain language, grounded in the repo's own docs. You do not run pipeline stages; when the user is ready to act, point them at the right skill.

How to answer

  1. Identify the topic (the argument, or infer from the question).
  2. Ground yourself in the canonical source before answering — read the mapped reference file(s) below rather than answering from memory. These are the source of truth and stay current as the pipeline evolves.
  3. Answer concisely, then end with the concrete next command (/feature-forge:forge-*) or doc pointer the user should go to.
Topic Read first
Pipeline architecture, stage-by-stage flow references/process-overview.md
Cross-stage conventions (naming, state, git, branch, epic injection) references/shared-conventions.md
Config keys + defaults references/forge-config-schema.json
Stack detection / language profiles references/stack-resolution.md, references/stacks/*.md
Loop runner interface, signals & version gate references/ralph-loop-contract.md
Deep dives, glossary, troubleshooting references/process-overview.md, references/shared-conventions.md
Environment health / repair (--doctor) references/preflight-and-self-heal.md

Those references/ files are the guaranteed grounding path — they ship in every install. The project's README.md, COMPATIBILITY.md, and the hosted docs site are richer but are not part of an installed bundle, so treat them as optional enrichment (offer the docs-site URL to a human) and never block an answer on opening them — fall back to the references/ files and your own knowledge.

Do NOT actually invoke stage skills or write files — this skill only explains and directs. The single carve-out is --doctor mode below, and it narrows rather than lifts the rule.

What feature-forge is

A feature development pipeline that refines a vague idea into shipped code through discrete, auditable stages — like a compiler for features. Each stage narrows scope and adds structure, reading the previous stage's artifacts as standalone contracts:

  • PRD — what to build (requirements only, no technology).
  • Tech spec — how to build it (design, grounded in the codebase).
  • Implementation specs — build-ready detail (types, signatures, contracts, tests).
  • Backlog — self-contained work items for autonomous execution.
  • Loop — a fresh-context runner implements each item, tests, and commits.
  • Docs — architecture reference generated from the real implementation.

REQ-XXX-NN requirement IDs form a traceability spine from PRD through implementation. Verification gates are available after any stage and run clean-room in a fresh subagent.

When to use it — and when not

Use forge when: you have a well-defined feature or small epic to ship; you want requirements captured cleanly before coding; you value traceability, thorough spec verification, and autonomous loop execution with fresh context per item; you want reproducible, auditable artifacts.

Skip forge when: the work is an exploratory spike with still-fluid requirements (though Stage 1's interview can help clarify them); it's a one-line bug fix or trivial patch where pipeline overhead isn't justified; or you're only extending mature code along established patterns, where new specs become noise.

Anti-patterns to warn against: skipping the PRD and jumping to tech spec (the value comes from separating what from how); treating specs as living contracts (they're pre-implementation — drop an AGENTS.md/CLAUDE.md in the specs dir telling agents to ignore drift); forcing an epic for a single feature; relying on conversation memory to carry context across stages instead of reading upstream artifacts.

The pipeline at a glance

Stage Skill Produces
0 (optional) forge-0-epic epic-manifest.json + EPIC.md (members, deps, exposes/consumes contracts)
1 forge-1-prd PRD.md with REQ-* IDs
2 forge-2-tech tech-spec.md; detects stack + test/typecheck commands
3 forge-3-specs numbered spec suite + TRACEABILITY.md
4 forge-4-backlog backlog.json (self-contained items)
5 forge-5-loop implemented code, tested + committed per item
6 forge-6-docs architecture docs from the real code
any forge-verify → forge-fix findings report → applied fixes
any forge status dashboard / navigator

Drive the whole thing with the navigator: /feature-forge:forge <feature> shows the current stage and offers the next; with autoInvokeNextStage it launches it directly.

Setup & configuration

First-time setup: /feature-forge:forge-init (existing repo) creates forge.config.json with defaults. /feature-forge:forge-bootstrap scaffolds a greenfield (empty) repo to a green baseline. On non-Claude agents, install via npx @garygentry/feature-forge install.

Key forge.config.json knobs (authoritative list: references/forge-config-schema.json):

  • Paths — specsDir (./specs), docsDir (./docs/architecture), backlogDir.
  • Git — gitCommitAfterStage (true), commitPrefix (forge); commits use a two-commit protocol so the stage's commit hash is recorded in state without --amend.
  • Branch — branchPerFeature (true), branchPrefix (forge/): isolate each feature.
  • Stack — stack, typeCheckCommand, testCommand: null until Stage 2 auto-detects them.
  • Context — contextWindowTokens, contextWarnThreshold (0.7): the navigator warns to /clear past this fullness. On 1M-context models set contextWindowTokens explicitly.
  • Verification — autoVerify (false; when on, each authoring stage verifies in-stage before its exit block), autoVerifyStages, autoFix (false).
  • Stage flow — autoInvokeNextStage (true on Claude, print-only elsewhere).
  • Loop — loopRunner block (binary, command templates, version gate, agent selection); defaults to rauf when absent. workspaces supports monorepos.

Verification gates

forge-verify <feature> dispatches the read-only forge-verifier subagent to find gaps, inconsistencies, and quality issues; it writes a findings doc, and forge-fix applies them. Because verification runs in a fresh subagent, it's clean-room by construction — it never needs a /clear, and it's safe to automate with autoVerify: true. When on, the just-completed authoring stage runs verify in-stage — in the same session, right before its exit block — so the digest and any fix land where the context still exists (the navigator only catches up if a host couldn't run it clean-room). Fixing stays human-gated unless autoFix: true. The cost is one extra clean-room verify per stage. Always verify before Stage 5 (the loop) — catching errors in specs/backlog is far cheaper than mid-loop. Verifying after PRD and after backlog is also recommended. A findings pass is fresh only while the artifact version matches what was verified; revise upstream and downstream re-verifies.

Context management

Each stage reads upstream artifacts as standalone contracts, so you can (and usually should) /clear between them:

  • Clear between PRD → tech, tech → specs, specs → backlog, backlog → loop.
  • Stay warm mid-interview (PRD, tech spec) — the interview needs a continuous thread.
  • No clear needed for any → verify (runs in a fresh subagent).

The navigator warns when the session passes contextWarnThreshold (default 70% full).

Epics (large changes)

Use Stage 0 only when a change naturally splits into several interdependent features that must agree on interfaces. forge-0-epic produces epic-manifest.json + EPIC.md with a per-member charter, exposes/consumes contracts, and dependsOn edges. Each member then runs the normal pipeline with epic context injected. At Stage 5 a dependency gate warns if a member's dependencies are unmet. Epic support is purely additive — single-feature flows are unchanged. Re-run forge-0-epic on an existing epic to enter edit mode.

The loop

Stage 5 runs a configurable runner (rauf by default) that gives each backlog item a fresh agent session — implement → run the verification command → commit on pass. This is why items must be truly self-contained; context bleed breaks the model. Per-item signals:

  • RAUF_DONE — item passed; loop continues.
  • RAUF_BLOCKED — missing dependency / unclear requirement; set aside, loop continues others.
  • RAUF_NEEDS_HUMAN — decision or secret needed; set aside, loop continues.

The loop doesn't pause on blocked items. Supply what's missing, then rauf resume <path> to retry set-aside items. The runner refuses to start with a dirty working tree and enforces a minimum runner version (the version gate is described in references/ralph-loop-contract.md).

Best practices & gotchas

  • Feature name is required for every stage command — never guess or infer it.
  • Verify before the loop; a bad spec is cheap to fix now, expensive mid-loop.
  • Keep backlog items self-contained — the loop has zero memory across items.
  • Let stages commit for you; don't hand-edit .pipeline-state.json or backlog status.
  • Re-running an upstream stage marks downstream stages stale — re-run them rather than reaching for --force, which skips prerequisite checks and should be rare.
  • Specs are pre-implementation artifacts, not living docs — don't cite them from generated code.
  • Use the navigator (/feature-forge:forge <feature>) to orient; use forge-verify to inspect.

--doctor mode

/feature-forge:forge-guide --doctor is the repair surface: it turns doctor's checks[] into a readable report and, only on an explicit yes, a scripted repair. Enter this mode only when the argument is --doctor; every other invocation of this skill stays purely advisory.

The carve-out, stated precisely. Here — and nowhere else in this skill — you may run doctor (read-only), run a read-only remedy unprompted, and apply a local-write remedy after an explicit yes. global-install and network remedies stay advise-only: print the command, never run it. This skill still never invokes stage skills, never edits .pipeline-state.json or a backlog, and writes no artifact of its own — step 4's exclusion is what keeps the second of those true. Repair here means the environment, not the pipeline.

1. Read the whole catalog. Not a narrowed gate: this surface is about the environment, so the breadth references/preflight-and-self-heal.md §1 forbids inside a hard gate (where an unrelated advisory must never block a launch) is exactly what belongs here. The --json payload already carries every record, ok and na included; --verbose changes only the human printer, so it is a no-op on this call.

R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
python3 "$R/scripts/forge-session.py" doctor --json

2. Render the summary. Lead with checksSummary, then one row per warn or fail check — that is the affected set §2 step 1 defines, and na is not a finding (its detail names the prerequisite that would make it applicable). Blocking rows first. Each row carries the check's own detail, its remedy.safety as the tier, and remedy.description and remedy.command verbatim, so the operator sees the exact string before being asked about it; render — for a null remedy. Never invent a remedy doctor did not emit.

3. Take your rung from that same report. A full-catalog run carries the interaction-mode record, so read its evidence.mode rather than calling again — three values, three answers. non-interactive (it carries rung: 3) → step 5. interactive → classify yourself against references/shared-conventions.md § Interaction Capability Ladder as usual. unknown, an na record, a warn carrying evidence.conflict, or no such check at all → the report did NOT answer it: self-assess against that same ladder and prefer its prose-question rung over assuming an answer. unknown is never rung 3 — reading it that way is the silent behavior change the ladder forbids. (An unstamped codex exec reports exactly this, so the branch is the common case, not the corner.)

4. Repair, following references/preflight-and-self-heal.md over the warn/fail set: cluster from remedyClusters[], then partition by tier before asking anything — read-only runs unprompted; local-write gets one consolidated question per cluster (never one per check); global-install, network, and any null-command remedy are advise-only and are never offered for execution. Print the preflight: outcome line before acting, run an approved command verbatim, then prove by re-running the identical doctor invocation. A remedy that exited 0 but left a member check not ok is a failed preflight, not a partial success, and it stops the repair — report every remaining cluster as unattempted rather than continuing past it.

Excluded from apply, at every rung: a remedy that changes which commit is checked out or rewrites a feature's .pipeline-state.json — today branch-state's git switch … and state-branch …. Print them as advice and let the operator run them. They are pipeline bookkeeping rather than environment repair, they are not idempotent the way the local-write tier assumes, and applying one mid-run would move the tree the prove step re-measures. Consent does not persist across invocations: the ladder's "ask once per remedy class per session" memo covers one run of this mode; a second --doctor asks afresh, because its advertised output is a report and an operator asking to look must never trigger a write.

5. Rung 3 → report-only. State interaction: rung 3 (non-interactive) — declared defaults apply, then take this site's declared default: the ladder's preflight-remedies class, under which a local-write cluster degrades to advise-only and is recorded unaskable→advise-only. Nothing that needs a yes is applied; a read-only cluster still runs, as at any rung. The report is the entire deliverable.

6. Close with every check still warn/fail, each next to its own remedy.command — or the words no scripted command where the remedy is null or absent. Do not reduce them to one command: several unresolved checks usually need several, and inventing a combined one is exactly the fabrication step 2 forbids.

Troubleshooting starters

  • Anything environmental: point the user at /feature-forge:forge-guide --doctor — it reports every doctor check and walks the consented repair. Name it; do not enter that mode from an answer that was not invoked with --doctor.
  • Stage 5 won't start: backlog exists and is verified? runner installed and ≥ min version? working tree clean? See references/ralph-loop-contract.md for the runner contract and version gate.
  • Loop stopped mid-run: check the signal — BLOCKED/NEEDS_HUMAN items are set aside, not failures; the loop keeps going.
  • Downstream flagged stale: an upstream stage was revised; re-run the downstream stage.
  • Where am I? /feature-forge:forge <feature> renders the full pipeline status.

For anything deeper, ground yourself in references/process-overview.md and references/shared-conventions.md, and point the user at the hosted docs site — https://garygentry.github.io/feature-forge/ — for the full guides and glossary.

04 同仓库更多 Skills