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
- 参考文档references/forge-config-schema.json20.6 KB
- 参考文档references/preflight-and-self-heal.md11.8 KB
- 参考文档references/process-overview.md10.3 KB
- 参考文档references/ralph-loop-contract.md12.8 KB
- 参考文档references/shared-conventions.md72.3 KB
- 参考文档references/stack-resolution.md2.9 KB
- 参考文档references/stacks/_generic.md5.6 KB
- 参考文档references/stacks/go.md8.5 KB
- 参考文档references/stacks/python.md8.0 KB
- 参考文档references/stacks/rust.md9.4 KB
- 参考文档references/stacks/typescript.md6.5 KB
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
- Identify the topic (the argument, or infer from the question).
- 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.
- 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/clearpast this fullness. On 1M-context models setcontextWindowTokensexplicitly. - 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 —
loopRunnerblock (binary, command templates, version gate, agent selection); defaults to rauf when absent.workspacessupports 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.jsonor 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; useforge-verifyto 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 everydoctorcheck 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.mdfor the runner contract and version gate. - Loop stopped mid-run: check the signal —
BLOCKED/NEEDS_HUMANitems 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
alpha
A valid skill description.
alpha
暂无简介
alpha
This is a folded scalar description.
alpha
A valid skill description.
alpha
foo: bar
alpha
A valid description.