[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75GYG2JCTS6H4VC4G8N659Q":3,"skill-same:01M75GYG2JCTS6H4VC4G8N659Q":100},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":33,"commitSha":34,"skillDirectory":35,"forksCount":13,"repositoryHtmlUrl":36,"repositoryHomepageUrl":37,"ownerHtmlUrl":38,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":39,"install":40,"resources":53},"01M75GYG2JCTS6H4VC4G8N659Q","forge-guide",null,"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\u002Fwhen 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.","garygentry\u002Ffeature-forge","garygentry","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F12444042?v=4","01M75GWTRXHQMKFWDVG9N8ENNS","01M75GWTSZ5NV3MYKFWVCZJKW4",0,"MIT","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-guide\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\n# GENERATED — DO NOT EDIT. Source: skills\u002Fforge-guide\u002FSKILL.md. Regenerate: python3 scripts\u002Fbuild-adapters.py\nname: forge-guide\ndescription: 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\u002Fwhen 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.\nargument-hint: '\u003Coptional topic: overview | when | setup | config | stages | verify | context | epics | loop | troubleshoot — or --doctor to report and repair the environment>'\nallowed-tools:\n- Read\n- Grep\n- Glob\ndisallowed-tools:\n- Write\n- Edit\n- Skill\n- Agent\n---\n\n# Feature Forge — Usage & Best-Practices Guide\n\nYou are the **guide** for feature-forge: an advisor, not an operator. Your job is to\nexplain *what* forge is, *when* to use it, *how* to configure it, and *what the best\npractices are* — in plain language, grounded in the repo's own docs. You do **not**\nrun pipeline stages; when the user is ready to act, point them at the right skill.\n\n## How to answer\n\n1. Identify the topic (the argument, or infer from the question).\n2. **Ground yourself in the canonical source before answering** — read the mapped\n   reference file(s) below rather than answering from memory. These are the source\n   of truth and stay current as the pipeline evolves.\n3. Answer concisely, then end with the concrete next command (`\u002Ffeature-forge:forge-*`)\n   or doc pointer the user should go to.\n\n| Topic | Read first |\n|-------|-----------|\n| Pipeline architecture, stage-by-stage flow | `references\u002Fprocess-overview.md` |\n| Cross-stage conventions (naming, state, git, branch, epic injection) | `references\u002Fshared-conventions.md` |\n| Config keys + defaults | `references\u002Fforge-config-schema.json` |\n| Stack detection \u002F language profiles | `references\u002Fstack-resolution.md`, `references\u002Fstacks\u002F*.md` |\n| Loop runner interface, signals & version gate | `references\u002Fralph-loop-contract.md` |\n| Deep dives, glossary, troubleshooting | `references\u002Fprocess-overview.md`, `references\u002Fshared-conventions.md` |\n| Environment health \u002F repair (`--doctor`) | `references\u002Fpreflight-and-self-heal.md` |\n\nThose `references\u002F` files are the guaranteed grounding path — they ship in every install.\nThe project's `README.md`, `COMPATIBILITY.md`, and the hosted docs site are richer but are\n**not** part of an installed bundle, so treat them as optional enrichment (offer the docs-site\nURL to a human) and never block an answer on opening them — fall back to the `references\u002F`\nfiles and your own knowledge.\n\nDo NOT actually invoke stage skills or write files — this skill only explains and directs.\nThe single carve-out is `--doctor` mode below, and it narrows rather than lifts the rule.\n\n## What feature-forge is\n\nA **feature development pipeline** that refines a vague idea into shipped code through\ndiscrete, auditable stages — like a compiler for features. Each stage narrows scope and\nadds structure, reading the previous stage's artifacts as standalone contracts:\n\n- **PRD** — *what* to build (requirements only, no technology).\n- **Tech spec** — *how* to build it (design, grounded in the codebase).\n- **Implementation specs** — build-ready detail (types, signatures, contracts, tests).\n- **Backlog** — self-contained work items for autonomous execution.\n- **Loop** — a fresh-context runner implements each item, tests, and commits.\n- **Docs** — architecture reference generated from the real implementation.\n\n`REQ-XXX-NN` requirement IDs form a traceability spine from PRD through implementation.\n**Verification gates** are available after any stage and run clean-room in a fresh subagent.\n\n## When to use it — and when not\n\n**Use forge when:** you have a well-defined feature or small epic to ship; you want\nrequirements captured cleanly before coding; you value traceability, thorough spec\nverification, and autonomous loop execution with fresh context per item; you want\nreproducible, auditable artifacts.\n\n**Skip forge when:** the work is an exploratory spike with still-fluid requirements\n(though Stage 1's interview can help clarify them); it's a one-line bug fix or trivial\npatch where pipeline overhead isn't justified; or you're only extending mature code\nalong established patterns, where new specs become noise.\n\n**Anti-patterns to warn against:** skipping the PRD and jumping to tech spec (the value\ncomes from separating *what* from *how*); treating specs as living contracts (they're\npre-implementation — drop an `AGENTS.md`\u002F`CLAUDE.md` in the specs dir telling agents to\nignore drift); forcing an epic for a single feature; relying on conversation memory to\ncarry context across stages instead of reading upstream artifacts.\n\n## The pipeline at a glance\n\n| Stage | Skill | Produces |\n|-------|-------|----------|\n| 0 (optional) | `forge-0-epic` | `epic-manifest.json` + `EPIC.md` (members, deps, `exposes`\u002F`consumes` contracts) |\n| 1 | `forge-1-prd` | `PRD.md` with `REQ-*` IDs |\n| 2 | `forge-2-tech` | `tech-spec.md`; detects stack + test\u002Ftypecheck commands |\n| 3 | `forge-3-specs` | numbered spec suite + `TRACEABILITY.md` |\n| 4 | `forge-4-backlog` | `backlog.json` (self-contained items) |\n| 5 | `forge-5-loop` | implemented code, tested + committed per item |\n| 6 | `forge-6-docs` | architecture docs from the real code |\n| any | `forge-verify` → `forge-fix` | findings report → applied fixes |\n| any | `forge` | status dashboard \u002F navigator |\n\nDrive the whole thing with the **navigator**: `\u002Ffeature-forge:forge \u003Cfeature>` shows the\ncurrent stage and offers the next; with `autoInvokeNextStage` it launches it directly.\n\n## Setup & configuration\n\n**First-time setup:** `\u002Ffeature-forge:forge-init` (existing repo) creates `forge.config.json`\nwith defaults. `\u002Ffeature-forge:forge-bootstrap` scaffolds a *greenfield* (empty) repo to a\ngreen baseline. On non-Claude agents, install via `npx @garygentry\u002Ffeature-forge install`.\n\n**Key `forge.config.json` knobs** (authoritative list: `references\u002Fforge-config-schema.json`):\n\n- **Paths** — `specsDir` (`.\u002Fspecs`), `docsDir` (`.\u002Fdocs\u002Farchitecture`), `backlogDir`.\n- **Git** — `gitCommitAfterStage` (true), `commitPrefix` (`forge`); commits use a two-commit\n  protocol so the stage's commit hash is recorded in state without `--amend`.\n- **Branch** — `branchPerFeature` (true), `branchPrefix` (`forge\u002F`): isolate each feature.\n- **Stack** — `stack`, `typeCheckCommand`, `testCommand`: null until Stage 2 auto-detects them.\n- **Context** — `contextWindowTokens`, `contextWarnThreshold` (0.7): the navigator warns to\n  `\u002Fclear` past this fullness. On 1M-context models set `contextWindowTokens` explicitly.\n- **Verification** — `autoVerify` (false; when on, each authoring stage verifies in-stage before its exit block), `autoVerifyStages`, `autoFix` (false).\n- **Stage flow** — `autoInvokeNextStage` (true on Claude, print-only elsewhere).\n- **Loop** — `loopRunner` block (binary, command templates, version gate, agent selection);\n  defaults to **rauf** when absent. `workspaces` supports monorepos.\n\n## Verification gates\n\n`forge-verify \u003Cfeature>` dispatches the read-only `forge-verifier` subagent to find gaps,\ninconsistencies, and quality issues; it writes a findings doc, and `forge-fix` applies them.\nBecause verification runs in a **fresh subagent**, it's clean-room by construction — it never\nneeds a `\u002Fclear`, and it's safe to automate with `autoVerify: true`. When on, the just-completed\nauthoring stage runs verify **in-stage** — in the same session, right before its exit block — so\nthe digest and any fix land where the context still exists (the navigator only catches up if a\nhost couldn't run it clean-room). Fixing stays human-gated unless `autoFix: true`. The cost is one\nextra clean-room verify per stage. **Always verify before Stage 5 (the loop)** — catching errors in\nspecs\u002Fbacklog is far cheaper than mid-loop. Verifying after PRD and after backlog is also\nrecommended. A findings pass is fresh only while the artifact `version` matches what was\nverified; revise upstream and downstream re-verifies.\n\n## Context management\n\nEach stage reads upstream artifacts as standalone contracts, so you can (and usually should)\n`\u002Fclear` between them:\n\n- **Clear** between PRD → tech, tech → specs, specs → backlog, backlog → loop.\n- **Stay warm** mid-interview (PRD, tech spec) — the interview needs a continuous thread.\n- **No clear needed** for any → verify (runs in a fresh subagent).\n\nThe navigator warns when the session passes `contextWarnThreshold` (default 70% full).\n\n## Epics (large changes)\n\nUse Stage 0 only when a change naturally splits into **several interdependent features** that\nmust agree on interfaces. `forge-0-epic` produces `epic-manifest.json` + `EPIC.md` with a\nper-member charter, `exposes`\u002F`consumes` contracts, and `dependsOn` edges. Each member then\nruns the normal pipeline with epic context injected. At Stage 5 a **dependency gate** warns if\na member's dependencies are unmet. Epic support is purely additive — single-feature flows are\nunchanged. Re-run `forge-0-epic` on an existing epic to enter edit mode.\n\n## The loop\n\nStage 5 runs a configurable runner (**rauf** by default) that gives each backlog item a fresh\nagent session — implement → run the verification command → commit on pass. This is why items\nmust be truly **self-contained**; context bleed breaks the model. Per-item signals:\n\n- `RAUF_DONE` — item passed; loop continues.\n- `RAUF_BLOCKED` — missing dependency \u002F unclear requirement; set aside, loop continues others.\n- `RAUF_NEEDS_HUMAN` — decision or secret needed; set aside, loop continues.\n\nThe loop doesn't pause on blocked items. Supply what's missing, then `rauf resume \u003Cpath>` to\nretry set-aside items. The runner refuses to start with a **dirty working tree** and enforces\na minimum runner version (the version gate is described in `references\u002Fralph-loop-contract.md`).\n\n## Best practices & gotchas\n\n- Feature name is **required** for every stage command — never guess or infer it.\n- Verify **before the loop**; a bad spec is cheap to fix now, expensive mid-loop.\n- Keep backlog items self-contained — the loop has zero memory across items.\n- Let stages commit for you; don't hand-edit `.pipeline-state.json` or backlog status.\n- Re-running an upstream stage marks downstream stages **stale** — re-run them rather than\n  reaching for `--force`, which skips prerequisite checks and should be rare.\n- Specs are pre-implementation artifacts, not living docs — don't cite them from generated code.\n- Use the navigator (`\u002Ffeature-forge:forge \u003Cfeature>`) to orient; use `forge-verify` to inspect.\n\n## `--doctor` mode\n\n`\u002Ffeature-forge:forge-guide --doctor` is the **repair surface**: it turns `doctor`'s `checks[]`\ninto a readable report and, only on an explicit yes, a scripted repair. Enter this mode **only**\nwhen the argument is `--doctor`; every other invocation of this skill stays purely advisory.\n\n**The carve-out, stated precisely.** Here — and nowhere else in this skill — you may run\n`doctor` (read-only), run a **`read-only`** remedy unprompted, and apply a **`local-write`**\nremedy after an explicit yes. `global-install` and `network` remedies stay **advise-only**:\nprint the command, never run it. This skill still **never invokes stage skills**, never edits\n`.pipeline-state.json` or a backlog, and writes no artifact of its own — step 4's exclusion is\nwhat keeps the second of those true. Repair here means the environment, not the pipeline.\n\n**1. Read the whole catalog.** Not a narrowed gate: this surface is *about* the environment,\nso the breadth `references\u002Fpreflight-and-self-heal.md` §1 forbids inside a hard gate (where an\nunrelated advisory must never block a launch) is exactly what belongs here. The `--json`\npayload already carries every record, `ok` and `na` included; `--verbose` changes only the\nhuman printer, so it is a no-op on this call.\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" doctor --json\n```\n\n**2. Render the summary.** Lead with `checksSummary`, then one row per **`warn` or `fail`**\ncheck — that is the affected set §2 step 1 defines, and `na` is not a finding (its `detail`\nnames the prerequisite that would make it applicable). Blocking rows first. Each row carries\nthe check's own `detail`, its `remedy.safety` as the tier, and `remedy.description` **and**\n`remedy.command` verbatim, so the operator sees the exact string before being asked about it;\nrender `—` for a null `remedy`. Never invent a remedy `doctor` did not emit.\n\n**3. Take your rung from that same report.** A full-catalog run carries the\n`interaction-mode` record, so read its `evidence.mode` rather than calling again — three\nvalues, three answers. `non-interactive` (it carries `rung: 3`) → step 5. `interactive` →\nclassify yourself against `references\u002Fshared-conventions.md` § Interaction Capability Ladder\nas usual. **`unknown`, an `na` record, a `warn` carrying `evidence.conflict`, or no such check\nat all → the report did NOT answer it**: self-assess against that same ladder and prefer its\nprose-question rung over assuming an answer. `unknown` is never rung 3 — reading it that way\nis the silent behavior change the ladder forbids. (An unstamped `codex exec` reports exactly\nthis, so the branch is the common case, not the corner.)\n\n**4. Repair,** following `references\u002Fpreflight-and-self-heal.md` over the `warn`\u002F`fail` set:\ncluster from `remedyClusters[]`, then **partition by tier before asking anything** —\n`read-only` runs unprompted; `local-write` gets **one consolidated question per cluster**\n(never one per check); `global-install`, `network`, and any null-command remedy are\n**advise-only** and are never offered for execution. Print the `preflight:` outcome line before\nacting, run an approved command verbatim, then **prove** by re-running the identical `doctor`\ninvocation. A remedy that exited 0 but left a member check not `ok` is a failed preflight, not\na partial success, and it **stops the repair** — report every remaining cluster as unattempted\nrather than continuing past it.\n\n**Excluded from apply, at every rung:** a remedy that changes which commit is checked out or\nrewrites a feature's `.pipeline-state.json` — today `branch-state`'s `git switch …` and\n`state-branch …`. Print them as advice and let the operator run them. They are pipeline\nbookkeeping rather than environment repair, they are not idempotent the way the `local-write`\ntier assumes, and applying one mid-run would move the tree the prove step re-measures.\n**Consent does not persist across invocations:** the ladder's \"ask once per remedy class per\nsession\" memo covers one run of this mode; a second `--doctor` asks afresh, because its\nadvertised output is a report and an operator asking to *look* must never trigger a write.\n\n**5. Rung 3 → report-only.** State `interaction: rung 3 (non-interactive) — declared defaults\napply`, then take this site's declared default: the ladder's **preflight-remedies** class,\nunder which a `local-write` cluster degrades to advise-only and is recorded\n`unaskable→advise-only`. Nothing that needs a yes is applied; a `read-only` cluster still runs,\nas at any rung. The report is the entire deliverable.\n\n**6. Close** with every check still `warn`\u002F`fail`, each next to its own `remedy.command` — or\nthe words *no scripted command* where the remedy is null or absent. Do not reduce them to one\ncommand: several unresolved checks usually need several, and inventing a combined one is\nexactly the fabrication step 2 forbids.\n\n## Troubleshooting starters\n\n- **Anything environmental:** point the user at `\u002Ffeature-forge:forge-guide --doctor` — it\n  reports every `doctor` check and walks the consented repair. Name it; do not enter that\n  mode from an answer that was not invoked with `--doctor`.\n- **Stage 5 won't start:** backlog exists and is verified? runner installed and ≥ min version?\n  working tree clean? See `references\u002Fralph-loop-contract.md` for the runner contract and version gate.\n- **Loop stopped mid-run:** check the signal — `BLOCKED`\u002F`NEEDS_HUMAN` items are set aside, not\n  failures; the loop keeps going.\n- **Downstream flagged stale:** an upstream stage was revised; re-run the downstream stage.\n- **Where am I?** `\u002Ffeature-forge:forge \u003Cfeature>` renders the full pipeline status.\n\nFor anything deeper, ground yourself in `references\u002Fprocess-overview.md` and\n`references\u002Fshared-conventions.md`, and point the *user* at the hosted docs site —\n\u003Chttps:\u002F\u002Fgarygentry.github.io\u002Ffeature-forge\u002F> — for the full guides and glossary.\n","# Feature Forge — Usage & Best-Practices Guide\n\nYou are the **guide** for feature-forge: an advisor, not an operator. Your job is to\nexplain *what* forge is, *when* to use it, *how* to configure it, and *what the best\npractices are* — in plain language, grounded in the repo's own docs. You do **not**\nrun pipeline stages; when the user is ready to act, point them at the right skill.\n\n## How to answer\n\n1. Identify the topic (the argument, or infer from the question).\n2. **Ground yourself in the canonical source before answering** — read the mapped\n   reference file(s) below rather than answering from memory. These are the source\n   of truth and stay current as the pipeline evolves.\n3. Answer concisely, then end with the concrete next command (`\u002Ffeature-forge:forge-*`)\n   or doc pointer the user should go to.\n\n| Topic | Read first |\n|-------|-----------|\n| Pipeline architecture, stage-by-stage flow | `references\u002Fprocess-overview.md` |\n| Cross-stage conventions (naming, state, git, branch, epic injection) | `references\u002Fshared-conventions.md` |\n| Config keys + defaults | `references\u002Fforge-config-schema.json` |\n| Stack detection \u002F language profiles | `references\u002Fstack-resolution.md`, `references\u002Fstacks\u002F*.md` |\n| Loop runner interface, signals & version gate | `references\u002Fralph-loop-contract.md` |\n| Deep dives, glossary, troubleshooting | `references\u002Fprocess-overview.md`, `references\u002Fshared-conventions.md` |\n| Environment health \u002F repair (`--doctor`) | `references\u002Fpreflight-and-self-heal.md` |\n\nThose `references\u002F` files are the guaranteed grounding path — they ship in every install.\nThe project's `README.md`, `COMPATIBILITY.md`, and the hosted docs site are richer but are\n**not** part of an installed bundle, so treat them as optional enrichment (offer the docs-site\nURL to a human) and never block an answer on opening them — fall back to the `references\u002F`\nfiles and your own knowledge.\n\nDo NOT actually invoke stage skills or write files — this skill only explains and directs.\nThe single carve-out is `--doctor` mode below, and it narrows rather than lifts the rule.\n\n## What feature-forge is\n\nA **feature development pipeline** that refines a vague idea into shipped code through\ndiscrete, auditable stages — like a compiler for features. Each stage narrows scope and\nadds structure, reading the previous stage's artifacts as standalone contracts:\n\n- **PRD** — *what* to build (requirements only, no technology).\n- **Tech spec** — *how* to build it (design, grounded in the codebase).\n- **Implementation specs** — build-ready detail (types, signatures, contracts, tests).\n- **Backlog** — self-contained work items for autonomous execution.\n- **Loop** — a fresh-context runner implements each item, tests, and commits.\n- **Docs** — architecture reference generated from the real implementation.\n\n`REQ-XXX-NN` requirement IDs form a traceability spine from PRD through implementation.\n**Verification gates** are available after any stage and run clean-room in a fresh subagent.\n\n## When to use it — and when not\n\n**Use forge when:** you have a well-defined feature or small epic to ship; you want\nrequirements captured cleanly before coding; you value traceability, thorough spec\nverification, and autonomous loop execution with fresh context per item; you want\nreproducible, auditable artifacts.\n\n**Skip forge when:** the work is an exploratory spike with still-fluid requirements\n(though Stage 1's interview can help clarify them); it's a one-line bug fix or trivial\npatch where pipeline overhead isn't justified; or you're only extending mature code\nalong established patterns, where new specs become noise.\n\n**Anti-patterns to warn against:** skipping the PRD and jumping to tech spec (the value\ncomes from separating *what* from *how*); treating specs as living contracts (they're\npre-implementation — drop an `AGENTS.md`\u002F`CLAUDE.md` in the specs dir telling agents to\nignore drift); forcing an epic for a single feature; relying on conversation memory to\ncarry context across stages instead of reading upstream artifacts.\n\n## The pipeline at a glance\n\n| Stage | Skill | Produces |\n|-------|-------|----------|\n| 0 (optional) | `forge-0-epic` | `epic-manifest.json` + `EPIC.md` (members, deps, `exposes`\u002F`consumes` contracts) |\n| 1 | `forge-1-prd` | `PRD.md` with `REQ-*` IDs |\n| 2 | `forge-2-tech` | `tech-spec.md`; detects stack + test\u002Ftypecheck commands |\n| 3 | `forge-3-specs` | numbered spec suite + `TRACEABILITY.md` |\n| 4 | `forge-4-backlog` | `backlog.json` (self-contained items) |\n| 5 | `forge-5-loop` | implemented code, tested + committed per item |\n| 6 | `forge-6-docs` | architecture docs from the real code |\n| any | `forge-verify` → `forge-fix` | findings report → applied fixes |\n| any | `forge` | status dashboard \u002F navigator |\n\nDrive the whole thing with the **navigator**: `\u002Ffeature-forge:forge \u003Cfeature>` shows the\ncurrent stage and offers the next; with `autoInvokeNextStage` it launches it directly.\n\n## Setup & configuration\n\n**First-time setup:** `\u002Ffeature-forge:forge-init` (existing repo) creates `forge.config.json`\nwith defaults. `\u002Ffeature-forge:forge-bootstrap` scaffolds a *greenfield* (empty) repo to a\ngreen baseline. On non-Claude agents, install via `npx @garygentry\u002Ffeature-forge install`.\n\n**Key `forge.config.json` knobs** (authoritative list: `references\u002Fforge-config-schema.json`):\n\n- **Paths** — `specsDir` (`.\u002Fspecs`), `docsDir` (`.\u002Fdocs\u002Farchitecture`), `backlogDir`.\n- **Git** — `gitCommitAfterStage` (true), `commitPrefix` (`forge`); commits use a two-commit\n  protocol so the stage's commit hash is recorded in state without `--amend`.\n- **Branch** — `branchPerFeature` (true), `branchPrefix` (`forge\u002F`): isolate each feature.\n- **Stack** — `stack`, `typeCheckCommand`, `testCommand`: null until Stage 2 auto-detects them.\n- **Context** — `contextWindowTokens`, `contextWarnThreshold` (0.7): the navigator warns to\n  `\u002Fclear` past this fullness. On 1M-context models set `contextWindowTokens` explicitly.\n- **Verification** — `autoVerify` (false; when on, each authoring stage verifies in-stage before its exit block), `autoVerifyStages`, `autoFix` (false).\n- **Stage flow** — `autoInvokeNextStage` (true on Claude, print-only elsewhere).\n- **Loop** — `loopRunner` block (binary, command templates, version gate, agent selection);\n  defaults to **rauf** when absent. `workspaces` supports monorepos.\n\n## Verification gates\n\n`forge-verify \u003Cfeature>` dispatches the read-only `forge-verifier` subagent to find gaps,\ninconsistencies, and quality issues; it writes a findings doc, and `forge-fix` applies them.\nBecause verification runs in a **fresh subagent**, it's clean-room by construction — it never\nneeds a `\u002Fclear`, and it's safe to automate with `autoVerify: true`. When on, the just-completed\nauthoring stage runs verify **in-stage** — in the same session, right before its exit block — so\nthe digest and any fix land where the context still exists (the navigator only catches up if a\nhost couldn't run it clean-room). Fixing stays human-gated unless `autoFix: true`. The cost is one\nextra clean-room verify per stage. **Always verify before Stage 5 (the loop)** — catching errors in\nspecs\u002Fbacklog is far cheaper than mid-loop. Verifying after PRD and after backlog is also\nrecommended. A findings pass is fresh only while the artifact `version` matches what was\nverified; revise upstream and downstream re-verifies.\n\n## Context management\n\nEach stage reads upstream artifacts as standalone contracts, so you can (and usually should)\n`\u002Fclear` between them:\n\n- **Clear** between PRD → tech, tech → specs, specs → backlog, backlog → loop.\n- **Stay warm** mid-interview (PRD, tech spec) — the interview needs a continuous thread.\n- **No clear needed** for any → verify (runs in a fresh subagent).\n\nThe navigator warns when the session passes `contextWarnThreshold` (default 70% full).\n\n## Epics (large changes)\n\nUse Stage 0 only when a change naturally splits into **several interdependent features** that\nmust agree on interfaces. `forge-0-epic` produces `epic-manifest.json` + `EPIC.md` with a\nper-member charter, `exposes`\u002F`consumes` contracts, and `dependsOn` edges. Each member then\nruns the normal pipeline with epic context injected. At Stage 5 a **dependency gate** warns if\na member's dependencies are unmet. Epic support is purely additive — single-feature flows are\nunchanged. Re-run `forge-0-epic` on an existing epic to enter edit mode.\n\n## The loop\n\nStage 5 runs a configurable runner (**rauf** by default) that gives each backlog item a fresh\nagent session — implement → run the verification command → commit on pass. This is why items\nmust be truly **self-contained**; context bleed breaks the model. Per-item signals:\n\n- `RAUF_DONE` — item passed; loop continues.\n- `RAUF_BLOCKED` — missing dependency \u002F unclear requirement; set aside, loop continues others.\n- `RAUF_NEEDS_HUMAN` — decision or secret needed; set aside, loop continues.\n\nThe loop doesn't pause on blocked items. Supply what's missing, then `rauf resume \u003Cpath>` to\nretry set-aside items. The runner refuses to start with a **dirty working tree** and enforces\na minimum runner version (the version gate is described in `references\u002Fralph-loop-contract.md`).\n\n## Best practices & gotchas\n\n- Feature name is **required** for every stage command — never guess or infer it.\n- Verify **before the loop**; a bad spec is cheap to fix now, expensive mid-loop.\n- Keep backlog items self-contained — the loop has zero memory across items.\n- Let stages commit for you; don't hand-edit `.pipeline-state.json` or backlog status.\n- Re-running an upstream stage marks downstream stages **stale** — re-run them rather than\n  reaching for `--force`, which skips prerequisite checks and should be rare.\n- Specs are pre-implementation artifacts, not living docs — don't cite them from generated code.\n- Use the navigator (`\u002Ffeature-forge:forge \u003Cfeature>`) to orient; use `forge-verify` to inspect.\n\n## `--doctor` mode\n\n`\u002Ffeature-forge:forge-guide --doctor` is the **repair surface**: it turns `doctor`'s `checks[]`\ninto a readable report and, only on an explicit yes, a scripted repair. Enter this mode **only**\nwhen the argument is `--doctor`; every other invocation of this skill stays purely advisory.\n\n**The carve-out, stated precisely.** Here — and nowhere else in this skill — you may run\n`doctor` (read-only), run a **`read-only`** remedy unprompted, and apply a **`local-write`**\nremedy after an explicit yes. `global-install` and `network` remedies stay **advise-only**:\nprint the command, never run it. This skill still **never invokes stage skills**, never edits\n`.pipeline-state.json` or a backlog, and writes no artifact of its own — step 4's exclusion is\nwhat keeps the second of those true. Repair here means the environment, not the pipeline.\n\n**1. Read the whole catalog.** Not a narrowed gate: this surface is *about* the environment,\nso the breadth `references\u002Fpreflight-and-self-heal.md` §1 forbids inside a hard gate (where an\nunrelated advisory must never block a launch) is exactly what belongs here. The `--json`\npayload already carries every record, `ok` and `na` included; `--verbose` changes only the\nhuman printer, so it is a no-op on this call.\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" doctor --json\n```\n\n**2. Render the summary.** Lead with `checksSummary`, then one row per **`warn` or `fail`**\ncheck — that is the affected set §2 step 1 defines, and `na` is not a finding (its `detail`\nnames the prerequisite that would make it applicable). Blocking rows first. Each row carries\nthe check's own `detail`, its `remedy.safety` as the tier, and `remedy.description` **and**\n`remedy.command` verbatim, so the operator sees the exact string before being asked about it;\nrender `—` for a null `remedy`. Never invent a remedy `doctor` did not emit.\n\n**3. Take your rung from that same report.** A full-catalog run carries the\n`interaction-mode` record, so read its `evidence.mode` rather than calling again — three\nvalues, three answers. `non-interactive` (it carries `rung: 3`) → step 5. `interactive` →\nclassify yourself against `references\u002Fshared-conventions.md` § Interaction Capability Ladder\nas usual. **`unknown`, an `na` record, a `warn` carrying `evidence.conflict`, or no such check\nat all → the report did NOT answer it**: self-assess against that same ladder and prefer its\nprose-question rung over assuming an answer. `unknown` is never rung 3 — reading it that way\nis the silent behavior change the ladder forbids. (An unstamped `codex exec` reports exactly\nthis, so the branch is the common case, not the corner.)\n\n**4. Repair,** following `references\u002Fpreflight-and-self-heal.md` over the `warn`\u002F`fail` set:\ncluster from `remedyClusters[]`, then **partition by tier before asking anything** —\n`read-only` runs unprompted; `local-write` gets **one consolidated question per cluster**\n(never one per check); `global-install`, `network`, and any null-command remedy are\n**advise-only** and are never offered for execution. Print the `preflight:` outcome line before\nacting, run an approved command verbatim, then **prove** by re-running the identical `doctor`\ninvocation. A remedy that exited 0 but left a member check not `ok` is a failed preflight, not\na partial success, and it **stops the repair** — report every remaining cluster as unattempted\nrather than continuing past it.\n\n**Excluded from apply, at every rung:** a remedy that changes which commit is checked out or\nrewrites a feature's `.pipeline-state.json` — today `branch-state`'s `git switch …` and\n`state-branch …`. Print them as advice and let the operator run them. They are pipeline\nbookkeeping rather than environment repair, they are not idempotent the way the `local-write`\ntier assumes, and applying one mid-run would move the tree the prove step re-measures.\n**Consent does not persist across invocations:** the ladder's \"ask once per remedy class per\nsession\" memo covers one run of this mode; a second `--doctor` asks afresh, because its\nadvertised output is a report and an operator asking to *look* must never trigger a write.\n\n**5. Rung 3 → report-only.** State `interaction: rung 3 (non-interactive) — declared defaults\napply`, then take this site's declared default: the ladder's **preflight-remedies** class,\nunder which a `local-write` cluster degrades to advise-only and is recorded\n`unaskable→advise-only`. Nothing that needs a yes is applied; a `read-only` cluster still runs,\nas at any rung. The report is the entire deliverable.\n\n**6. Close** with every check still `warn`\u002F`fail`, each next to its own `remedy.command` — or\nthe words *no scripted command* where the remedy is null or absent. Do not reduce them to one\ncommand: several unresolved checks usually need several, and inventing a combined one is\nexactly the fabrication step 2 forbids.\n\n## Troubleshooting starters\n\n- **Anything environmental:** point the user at `\u002Ffeature-forge:forge-guide --doctor` — it\n  reports every `doctor` check and walks the consented repair. Name it; do not enter that\n  mode from an answer that was not invoked with `--doctor`.\n- **Stage 5 won't start:** backlog exists and is verified? runner installed and ≥ min version?\n  working tree clean? See `references\u002Fralph-loop-contract.md` for the runner contract and version gate.\n- **Loop stopped mid-run:** check the signal — `BLOCKED`\u002F`NEEDS_HUMAN` items are set aside, not\n  failures; the loop keeps going.\n- **Downstream flagged stale:** an upstream stage was revised; re-run the downstream stage.\n- **Where am I?** `\u002Ffeature-forge:forge \u003Cfeature>` renders the full pipeline status.\n\nFor anything deeper, ground yourself in `references\u002Fprocess-overview.md` and\n`references\u002Fshared-conventions.md`, and point the *user* at the hosted docs site —\n\u003Chttps:\u002F\u002Fgarygentry.github.io\u002Ffeature-forge\u002F> — for the full guides and glossary.\n",{"name":5,"description":7,"allowed-tools":23,"argument-hint":27,"disallowed-tools":28},[24,25,26],"Read","Grep","Glob","\u003Coptional topic: overview | when | setup | config | stages | verify | context | epics | loop | troubleshoot — or --doctor to report and repair the environment>",[29,30,31,32],"Write","Edit","Skill","Agent","main","ce0d6d40bba1d87039b0397041d15cb56c934037","adapters\u002Fclaude\u002Fskills\u002Fforge-guide","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge","https:\u002F\u002Fgarygentry.github.io\u002Ffeature-forge\u002F","https:\u002F\u002Fgithub.com\u002Fgarygentry","2026-10-15 10:14:13",{"source":8,"skillName":5,"commands":41,"prompt":51,"zipAvailable":52},[42,45,48],{"tool":43,"command":44},"npx","npx skills add garygentry\u002Ffeature-forge --skill forge-guide",{"tool":46,"command":47},"bunx","bunx skills add garygentry\u002Ffeature-forge --skill forge-guide",{"tool":49,"command":50},"pnpm","pnpm dlx skills add garygentry\u002Ffeature-forge --skill forge-guide","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-guide\u002FSKILL.md",true,[54,60,64,68,72,76,80,84,88,92,96],{"path":55,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":58,"sourceHtmlUrl":59},"references\u002Fforge-config-schema.json","REFERENCE","参考文档",21095,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-guide\u002Freferences\u002Fforge-config-schema.json",{"path":61,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":62,"sourceHtmlUrl":63},"references\u002Fpreflight-and-self-heal.md",12082,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-guide\u002Freferences\u002Fpreflight-and-self-heal.md",{"path":65,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":66,"sourceHtmlUrl":67},"references\u002Fprocess-overview.md",10519,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-guide\u002Freferences\u002Fprocess-overview.md",{"path":69,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":70,"sourceHtmlUrl":71},"references\u002Fralph-loop-contract.md",13123,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-guide\u002Freferences\u002Fralph-loop-contract.md",{"path":73,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":74,"sourceHtmlUrl":75},"references\u002Fshared-conventions.md",74013,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-guide\u002Freferences\u002Fshared-conventions.md",{"path":77,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":78,"sourceHtmlUrl":79},"references\u002Fstack-resolution.md",3020,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-guide\u002Freferences\u002Fstack-resolution.md",{"path":81,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":82,"sourceHtmlUrl":83},"references\u002Fstacks\u002F_generic.md",5709,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-guide\u002Freferences\u002Fstacks\u002F_generic.md",{"path":85,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":86,"sourceHtmlUrl":87},"references\u002Fstacks\u002Fgo.md",8684,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-guide\u002Freferences\u002Fstacks\u002Fgo.md",{"path":89,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":90,"sourceHtmlUrl":91},"references\u002Fstacks\u002Fpython.md",8212,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-guide\u002Freferences\u002Fstacks\u002Fpython.md",{"path":93,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":94,"sourceHtmlUrl":95},"references\u002Fstacks\u002Frust.md",9621,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-guide\u002Freferences\u002Fstacks\u002Frust.md",{"path":97,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":98,"sourceHtmlUrl":99},"references\u002Fstacks\u002Ftypescript.md",6648,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-guide\u002Freferences\u002Fstacks\u002Ftypescript.md",[101,108,113,119,124,130],{"skillNo":102,"name":103,"nameZh":6,"description":104,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":105,"categories":106,"keywords":107,"publishedAt":18},"01M75H8RTWSJ2HYCPPKA3FRG42","alpha","A valid skill description.","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-nested-metadata\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":109,"name":103,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":110,"categories":111,"keywords":112,"publishedAt":18},"01M75H8QXKFS116EF1009KB3CY","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-malformed\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":114,"name":103,"nameZh":6,"description":115,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":116,"categories":117,"keywords":118,"publishedAt":18},"01M75H8PKNSV4WEREK6D91G9T4","This is a folded scalar description.","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-folded-scalar\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":120,"name":103,"nameZh":6,"description":104,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":121,"categories":122,"keywords":123,"publishedAt":18},"01M75H8MAV261C8QJ4S8CGRHV5","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-crlf\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":125,"name":103,"nameZh":6,"description":126,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":127,"categories":128,"keywords":129,"publishedAt":18},"01M75H8KDW98YF0PBHPD5V1GKR","foo: bar","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-colon-value\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":131,"name":103,"nameZh":6,"description":132,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":133,"categories":134,"keywords":135,"publishedAt":18},"01M75H8JFYFCGYNRCRTS4PMKKX","A valid description.","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-blank-lines\u002Fskills\u002Falpha\u002FSKILL.md",[],[]]