@garygentry/feature-forge 0.1.4 → 0.2.0

package/adapters/claude/skills/forge-5-loop/SKILL.md

@@ -52,7 +52,7 @@ Read `{resolvedFeatureDir}/.pipeline-state.json`. If not in force mode, `stages.
 
 Check if `stages.forge-verify-backlog` exists and has status `passed` or `findings-applied`. If not, use `AskUserQuestion` to warn:
 
-"Backlog hasn't been verified yet. It's recommended to run `/feature-forge:forge-verify {feature}` first to catch issues before implementation. Continue anyway?"
+"Backlog hasn't been verified yet. Recommended: run `/feature-forge:forge-verify {feature}` first — the loop implements items autonomously and commits as it goes, so a bad item (wrong scope, missing dependency, untestable acceptance criteria) is far cheaper to catch now than after several commits build on it. Continue anyway?" Offer **Verify first (recommended)** · **Continue without verifying**.
 
 ### 1b-epic. Epic Dependency Gate
 
@@ -61,7 +61,7 @@ Read the resolved feature's `.pipeline-state.json`. **If it has no `epic` key, s
 1. Run `render-status "{epic}" --specs-dir "{specsDir}" --json` via the helper:
 
    ```bash
-R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+R="$(for d in "$HOME"/.claude/skills/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/epic-manifest.py" \
   render-status "{epic}" --specs-dir "{specsDir}" --json
@@ -101,13 +101,8 @@ For the version-too-old case, phrase it concretely, e.g.: "Your rauf is {reporte
 
 Check that `loopRunner.preconditionFile` (default `.rauf.json`) exists in the project root. If not:
 
-- **If `loopRunner.name == "rauf"` and a legacy `.ralph.json` (or `.ralph/` directory) exists**, this is an un-migrated Ralph project. STOP and tell the user:
-
-  "This project is still on the legacy **Ralph** layout. Run `rauf migrate .` first (the loop runner only understands `.rauf/` and `RAUF_*` signals), then re-run `/feature-forge:forge-5-loop {feature}`."
-
-- **Otherwise**, STOP and show `loopRunner.setupHint` (default: "Run `rauf install .` …"), e.g.:
-
-  "The loop runner isn't set up in this project ({preconditionFile} is missing). {setupHint}"
+- **If `loopRunner.name == "rauf"` and a legacy `.ralph.json` (or `.ralph/` directory) exists**, this is an un-migrated Ralph project. STOP: "This project is still on the legacy **Ralph** layout. Run `rauf migrate .` first (the loop runner only understands `.rauf/` and `RAUF_*` signals), then re-run `/feature-forge:forge-5-loop {feature}`."
+- **Otherwise**, STOP and show `loopRunner.setupHint` (default: "Run `rauf install .` …"), e.g. "The loop runner isn't set up in this project ({preconditionFile} is missing). {setupHint}"
 
 ### 1e. Backlog File Check
 
@@ -117,6 +112,10 @@ Resolve the backlog file path (matching forge-4-backlog's composition rule, item
 
 Verify the file exists on disk. If not, STOP and tell the user: "No backlog.json found at {path}. Run `/feature-forge:forge-4-backlog {feature}` to generate it."
 
+### 1f. Branch Pre-flight (if using git)
+
+The runner commits each completed item straight onto the current branch, so guard against committing onto the default branch. Skip if not a git repo or `branchPerFeature` is false. Read the current branch (`git rev-parse --abbrev-ref HEAD`) and default branch (`git symbolic-ref --quiet refs/remotes/origin/HEAD`, else `main`/`master`). If `.pipeline-state.json` records a `branch` that differs from the current one, warn via `AskUserQuestion` (offer **switch back** or **proceed here**). Otherwise, if the current branch **is** the default, strongly recommend via `AskUserQuestion` creating/switching to `{branchPrefix}{feature}` (`git switch -c`, then record it to the state `branch` field) before the loop commits — still allowing **proceed on `{defaultBranch}`**. Never hard-stop.
+
 ## Step 2: Construct the Loop Command
 
 ### 2a. Analyze Backlog
@@ -180,6 +179,7 @@ For the full loop-runner contract — event-stream vs. log-fallback launch, the
 - **(b) Agent question.** Add an **"agent"** question to the same `AskUserQuestion` surface: **one option per advertised row** labelled `"{displayName} ({id}) — available/not found"`, **plus an explicit `"default (claude-cli)"` choice mapping to `run_selection = None`**. Resolve the pick (run > project, empty/whitespace unset, an explicit runner-default pick collapses to the default path) into `{resolved.agent, resolved.source}`. Precedence: `item.provider > --agent > project defaultAgent > runner default` (forge never reads a backlog item's provider).
 - **(c) Availability listing.** From the **same** parsed `agents[]` (no second probe), list `id` / `displayName` / available (`yes`/`no`, `detail` on unavailable rows).
 - **(d) Verdict** — only for a **non-default** resolved agent (default path `None`/`claude-cli` → no probe, byte-identical to today). Classify by **membership** then `available` (never by exit code): **UNKNOWN** (`∉` set) → **hard-reject BEFORE any loop side-effect**, error lists the **sorted** valid ids, **NO proceed-anyway**; **UNAVAILABLE** (member, `available False`) → warn with `detail`, `AskUserQuestion` offering **proceed-anyway OR choose-another** (re-presents the same `agents[]`), never silent; **AVAILABLE** → proceed, the validated id fills `{agent}`; **probe failure** (non-zero exit / unparseable / missing or empty `agents[]` / row lacking `id`) → surface it, offer **choose-another OR abort**, **never launch the non-default agent unvalidated** and never silently fall back to the default.
+- **(d-model) Claude-only model-alias guard.** Runs **only** when the resolved agent is **non-default** (not the default / `claude-cli` path). Read the backlog.json (Step 1e path); collect items whose `model` is a **Claude-specific alias** (tier `opus`/`sonnet`/`haiku` or a `claude-*` id). **If none, skip silently.** Otherwise warn before launch via `AskUserQuestion` (NOT prose): `item.model` outranks `--agent`, so the alias is forwarded verbatim to `{agent}`, which will likely reject it (e.g. codex 400 *"The 'sonnet' model is not supported…"*) — every spawn exits 1 and rauf circuit-breaks (*"3 consecutive infra failures — halting"*) with no hint of the cause. Offer: **(1) Strip `model` for this run (recommended)** — rewrite backlog.json removing the `model` key from each affected item (persistent edit; re-run forge-4-backlog to restore), then proceed; **(2) Proceed as-is** — only safe if `{agent}` understands the pinned ids. forge touches only `model`, never `provider`. Full rationale: `references/runner-contract.md`.
 - **(e) Optional-flags line.** Replace the confirmation's optional-flags line with one that lists `--agent <id>` first plus the agent precedence pointer (`item.provider > --agent > project defaultAgent > runner default`) alongside the model precedence.
 - **(f) Resolved-agent line.** Add to the confirmation block: `Agent: {resolved.agent or claude-cli} (source: {sourceLabel})` — `sourceLabel`: `RUN` → `"per-run selection"`, `PROJECT` → `"project default (loopRunner.defaultAgent)"`, `DEFAULT` → `"runner default — claude-cli"`.
 
@@ -193,11 +193,11 @@ Before launching, update `{resolvedFeatureDir}/.pipeline-state.json`:
 - Set `currentStage` to `forge-5-loop`
 - Update `updatedAt`
 
-### 3b. Launch Background Process
+Then commit this state write before launching (mandatory). The runner refuses to run with uncommitted changes (*"…pass --force"*), and this marker is itself one — so an otherwise-clean repo fails its first launch unless committed. Commit it via the shared-conventions **Git Commit Protocol** (epic members: stage `{specsDir}/{epic}/`): `{commitPrefix}({feature}): forge-5-loop in-progress` — a launch precondition, required regardless of `gitCommitAfterStage`. Unrelated leftover changes still trip the refusal; surface it, never auto-pass `--force`. See `references/runner-contract.md`.
 
-Launch the loop **backgrounded** (`run_in_background: true`) so it survives session end and does not block the session, and prefer the machine-readable event stream (`loopRunner.eventStreamCommand`, default for rauf) redirected to a stable `events.ndjson` so the session can supervise it live; fall back to the plain `runCommand` (tailing the human log) when no `eventStreamCommand` is configured. The background task's exit notification is the single authoritative terminal signal (Step 4). For the exact launch commands (incl. the `mkdir -p` state-dir guard) and the event-stream vs. log-fallback detail, read `references/runner-contract.md`.
+### 3b. Launch Background Process
 
-Loop runs can take significant time (minutes to hours depending on backlog size).
+Launch the loop **backgrounded** (`run_in_background: true`) so it survives session end and does not block the session, and prefer the machine-readable event stream (`loopRunner.eventStreamCommand`, default for rauf) redirected to a stable `events.ndjson` so the session can supervise it live; fall back to the plain `runCommand` (tailing the human log) when no `eventStreamCommand` is configured. The background task's exit notification is the single authoritative terminal signal (Step 4). Loop runs can take significant time (minutes to hours depending on backlog size). For the exact launch commands (incl. the `mkdir -p` state-dir guard) and the event-stream vs. log-fallback detail, read `references/runner-contract.md`.
 
 ### 3c. Inform User
 
@@ -246,7 +246,7 @@ Run the **status-json command** (`loopRunner.statusJsonCommand`) and read
 `backlogSummary` for the authoritative counts — it separates the three non-done
 outcomes: genuine `blocked`, `needsHuman`, and runner-`deferred` ("false blocks").
 Fall back to the **list command** (`loopRunner.listCommand`) if `statusJsonCommand`
-is not configured. You will already have most of this from the live tally in 3e.
+is not configured. You will already have most of this from the live tally in 3e. If the run used a review flag (e.g. rauf's `--review`), also read any `review_completed` event (event stream, or `{loopRunner.stateDir}/events.ndjson`) for its `itemsCreated`/`summary` to surface in 4b — see `references/result-reporting.md`.
 
 ### 4b. Report Results
 
@@ -267,13 +267,15 @@ Update `{resolvedFeatureDir}/.pipeline-state.json`:
 2. If all items complete: set `currentStage` to `"forge-6-docs"`
 3. Update `updatedAt`
 
-**No git commit is needed** — the loop runner commits atomically per completed item during the run. The implementation code is already committed.
+**No git commit is needed** — the loop runner commits implementation code atomically per completed item during the run. (Step 6's commit, epic members only, is of pipeline state / manifest — a distinct artifact.)
+
+## Step 5b: Offer Impl-Verify (standalone path)
 
-> **Note:** Step 5's "no git commit needed" remark refers to *implementation code*, which the runner commits per-item. The epic handoff's commit in Step 6 below is of *pipeline state / manifest* — a distinct artifact — and applies only to epic members.
+**Gate:** run only if (a) the feature's `.pipeline-state.json` has **no** `epic` key **and** (b) Step 5 set `stages.forge-5-loop.status` to `complete`. Otherwise **skip** — partial runs end as today, and epic members get the equivalent offer in Step 6.1 (do **not** prompt twice). This standalone counterpart to Step 6.1 nudges verification interactively rather than via the easily-missed "Next steps" text. Use `AskUserQuestion` (NOT inline prose) to offer: *"{feature}'s loop is complete. Recommended: run `/feature-forge:forge-verify {feature} impl` to audit the implementation before generating docs. Run it now, or skip to forge-6-docs?"* On **run**, hand off to `/feature-forge:forge-verify {feature} impl`. On **skip**, record `stages.forge-verify-impl.status` as `"skipped"` (mirrors `forge-4-backlog`'s skip handling) and point the user at `/feature-forge:forge-6-docs {feature}` — the forge-6-docs backstop re-surfaces the skip.
 
 ## Step 6: Epic Handoff
 
-**Gate:** only run this step if (a) the resolved feature's `.pipeline-state.json` has an `epic` key **and** (b) Step 5 set `stages.forge-5-loop.status` to `complete` (all backlog items done). If either is false, **skip** — standalone features and partial runs end exactly as today (REQ-COMPAT-01).
+**Gate:** only run this step if (a) the resolved feature's `.pipeline-state.json` has an `epic` key **and** (b) Step 5 set `stages.forge-5-loop.status` to `complete` (all backlog items done). If either is false, **skip** — standalone completed features are handled by Step 5b, and partial runs end as today (REQ-COMPAT-01).
 
 1. **Offer impl-verify first (recommended, skippable).** Per the completion rule (`00-core-definitions.md §7`), a feature whose `forge-verify-impl.status == findings-reported` does **not** unblock dependents. Use `AskUserQuestion` (NOT inline prose) to offer:
 
@@ -297,7 +299,7 @@ Update `{resolvedFeatureDir}/.pipeline-state.json`:
 - rauf resolves `RAUF.md` with fallback: checks `{backlogDir}/.rauf/RAUF.md` first, then the project's `.rauf/RAUF.md`. As long as the runner is installed in the project, the prompt template will be found.
 - State files (state.json, {loopRunner.logFile}, etc.) are created at `{backlogDir}/{loopRunner.stateDir}/` — this is within the feature's spec directory and is expected. State is isolated per backlog dir, so concurrent features don't collide.
 - If the session disconnects during a long-running loop, the runner process continues independently. The user can check results later with the status / list commands.
-- Never run the run command in the foreground (without `run_in_background`) — it blocks and will hit the Bash tool timeout for any non-trivial backlog. "Don't block the foreground" is NOT "stay silent": supervise via the `Monitor` tool (3d), which is harness-driven, not a sleep loop. Never `sleep`/poll in the foreground to wait for the loop.
-- The `Monitor` must use `persistent: true` (not a bounded `timeout_ms`), watch the **structured** surface (`events.ndjson`), and never filter on raw `RAUF_*` tokens — they appear in agent prose and false-match. A `needs_human`/`blocked`/`review` signal does **not** pause the loop — the runner sets the item aside and keeps going; surface it live but don't tell the user the loop is waiting. See `references/runner-contract.md` for the full monitoring rules.
+- Never run the run command in the foreground (without `run_in_background`) — it blocks and will hit the Bash tool timeout for any non-trivial backlog. "Don't block the foreground" is NOT "stay silent": supervise via the `Monitor` tool (3d), never `sleep`/poll in the foreground. The `Monitor` must use `persistent: true` (not a bounded `timeout_ms`), watch the **structured** surface (`events.ndjson`), and never filter on raw `RAUF_*` tokens — they appear in agent prose and false-match. A `needs_human`/`blocked`/`review` signal does **not** pause the loop — the runner sets the item aside and keeps going; surface it live but don't tell the user the loop is waiting. See `references/runner-contract.md` for the full monitoring rules.
 - If a previous loop run left a stale lock, the user may need to pass `--force` to clear it. rauf will report this error clearly.
 - The version gate (1c) uses the `--json` form on purpose; never parse `rauf version`'s human output.
+- **Implementation artifacts must not cite specs.** The loop should **read** the specs and `backlog.json` freely — they are the source of truth for what to build, and the backlog rightly references specs for provenance. But the artifacts the loop **writes into the target repo** (source code, generated `SKILL.md`/agent files, configs, code comments) must be **self-contained**: they must NOT reference feature-forge spec files (no `See specs/{feature}/NN-*.md`, no "source spec" provenance notes in shipped output). Specs are pre-implementation inputs that may be archived or deleted once the feature ships; the implementation must stand on its own. This applies only to shipped implementation output — never to the backlog or spec documents, which should keep citing specs.

package/adapters/claude/skills/forge-5-loop/references/result-reporting.md

@@ -13,6 +13,19 @@ Next steps:
   - /feature-forge:forge-6-docs {feature}         Generate architecture docs
 ```
 
+**Runner review pass.** A review flag (e.g. rauf's `--review`) makes the runner run
+a post-loop review that **auto-creates and implements fix items** rather than handing
+findings to the user — distinct from `forge-verify impl` (a clean-context audit that
+writes a findings doc). When Step 4a captured a `review_completed` event, add a line
+**above** "Next steps" so the pass's effect is visible and not mistaken for "nothing
+happened":
+```
+Runner review pass: {itemsCreated} fix item(s) created and implemented.
+  {summary}
+```
+Omit this line when no `review_completed` event was emitted (no review flag passed).
+The created items are already counted in the totals above.
+
 **Some items need a human:**
 ```
 Loop completed for {feature}.

package/adapters/claude/skills/forge-5-loop/references/runner-contract.md

@@ -70,6 +70,38 @@ The default / `claude-cli` path runs **no** probe (zero extra cost). See
 `04-availability-precheck.md` for the full pre-check, classification, and allow-list,
 and `02-config-schema-and-gating.md` for the capability gate.
 
+> **Probe false-negative for Claude Code installs (advisory).** `rauf agents` may
+> report `claude-cli` **unavailable** (e.g. *"credentials file not found:
+> ~/.config/claude-code/credentials.json"*) even when a working `claude` CLI
+> authenticates elsewhere — the probe's credential heuristic doesn't cover every
+> install. This is a rauf probe concern, not something forge-5-loop fixes. The
+> **default-agent path skips the probe entirely**, so an ordinary default run is
+> unaffected; only an **explicit** `--agent claude-cli` would be flagged UNAVAILABLE,
+> and the existing **proceed-anyway** path (above) covers it. Do not attempt to
+> patch rauf's probe from here.
+
+### Claude-only model-alias guard (Step 2d, sub-step d-model)
+
+When the resolved agent is **non-default** (not the default / `claude-cli` path),
+forge must guard against a backlog whose items pin **Claude-specific** model aliases.
+forge-4-backlog (via the rauf author-backlog skill) writes Claude tier aliases
+(`opus` / `sonnet`) into each item's `model`. Because rauf's precedence puts
+`item.model` **above** `--agent`, the alias is forwarded verbatim to the selected
+agent; a non-Claude agent (e.g. codex) then 400s — *"The 'sonnet' model is not
+supported when using Codex with a ChatGPT account."* — so **every** spawn exits 1 and
+rauf reports *"Circuit breaker: 3 consecutive infra failures — halting"* with no hint
+of the real cause. forge-5-loop therefore detects Claude-specific `model` aliases in
+the backlog (tier aliases `opus`/`sonnet`/`haiku` or `claude-*` ids) and, before
+launch, **warns** and offers (via `AskUserQuestion`) to **strip `model` for this run**
+(remove the key from each affected item so each spawn uses the agent's own default) or
+**proceed as-is**. forge only ever touches the `model` field — never `provider`. The
+default / `claude-cli` path skips this guard (the aliases are valid there).
+
+> **Follow-up (out of scope here — rauf repo).** The durable fix would be for the
+> rauf `author-backlog` skill to keep `model` **provider-neutral** by default (or to
+> document that writing a tier alias binds the backlog to Claude agents). That lives
+> in the separate rauf plugin/repo, not feature-forge; tracked as a follow-up.
+
 ## Optional flags catalog (Step 2d, rauf)
 
 These are the optional flags the user may add to the rendered run command. If the
@@ -92,6 +124,14 @@ Launch the loop **backgrounded** so it survives session end and does not block t
 session, and prefer the machine-readable event stream so the session can supervise
 it live.
 
+> **Clean-tree precondition.** rauf refuses to run with uncommitted changes
+> (*"Refusing to run the loop with uncommitted changes… pass --force"*). Step 3a's
+> in-progress `.pipeline-state.json` write is itself an uncommitted change, so it
+> **must be committed before launch** (Step 3a) — otherwise the first launch on an
+> otherwise-clean repo always fails. If the tree still has unrelated uncommitted
+> changes after that commit, surface it and let the user commit/stash or pass
+> `--force`; never auto-pass `--force`.
+
 - **If `loopRunner.eventStreamCommand` is configured (default for rauf):** render it
   (it appends `--ndjson` to the run) and launch via the Bash tool with
   `run_in_background: true`, redirecting stdout to a stable events file:

package/adapters/claude/skills/forge-6-docs/SKILL.md

@@ -35,12 +35,16 @@ Check `{resolvedFeatureDir}/backlog.json` (or `{backlogDir}/{feature}/backlog.js
 
 Also check `.pipeline-state.json` for `stages.forge-5-loop`. If it exists and has status `in-progress` (some items incomplete), include this in the warning: "The rauf loop has not fully completed — {done}/{total} items done. Documentation may need updates after remaining items are implemented."
 
+### Impl-Verify Backstop
+
+Check `.pipeline-state.json` for `stages.forge-verify-impl`. If it is **absent** or has status `"skipped"`, use `AskUserQuestion` to warn with the cost of skipping: "Implementation hasn't been verified yet. Recommended: run `/feature-forge:forge-verify {feature} impl` first to audit the loop's output — docs generated over unverified code can document bugs or gaps as if they were intended behavior, and readers will trust them. Generate docs anyway?" Offer **Verify first (recommended)** · **Generate docs anyway**. This mirrors `forge-4-backlog`'s pre-stage verification check and backstops a skipped impl-verify regardless of how the loop ended. If `stages.forge-verify-impl` shows it already ran (`findings-applied`, `findings-reported`, or `passed`), proceed with no warning.
+
 ### Epic-Level Documentation (epic members only)
 
 If the resolved feature has an `epic` back-pointer in its `.pipeline-state.json`, run:
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+R="$(for d in "$HOME"/.claude/skills/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/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
 ```
@@ -110,6 +114,11 @@ Present the plan and use `AskUserQuestion` to get the user's confirmation.
 - Specs are the source of truth for design intent; code is the source of truth for behavior
 - Read the actual source code to verify your documentation is correct
 
+**Don't cite or link spec files in the generated docs.**
+- Read the specs freely for context, but the docs you write are shipped implementation artifacts — they must be self-contained
+- Never link or reference `PRD.md`, `tech-spec.md`, or the numbered implementation specs (`specs/{feature}/NN-*.md`); these are pre-implementation artifacts that may be archived or deleted
+- Reference only the code, runtime contracts/configuration, and other generated docs. If you need to convey design intent, write it directly into the doc rather than pointing at a spec
+
 **Match existing conventions.**
 - If other features' docs use a specific heading structure, follow it
 - If they include diagrams, include diagrams
@@ -173,6 +182,7 @@ Write pipeline state conforming to `references/pipeline-state-schema.json`.
 ## Gotchas
 
 - Don't just rephrase the specs. Documentation should explain the implemented system, not the planned system. Read the actual code.
+- Don't cite spec files (PRD.md, tech-spec.md, numbered specs) as sources or "further reading" in the generated docs — specs are pre-implementation artifacts that may not survive. Keep the docs self-contained; link only to code, configuration, and other docs.
 - If the implementation doesn't exist yet (backlog hasn't been run), document based on specs but note prominently that docs are pre-implementation and may need updating.
 - API reference should include actual function signatures from the code, not from the spec (they may differ).
 - Don't generate docs that will immediately be stale. Focus on concepts, architecture, and patterns rather than line-by-line code walkthroughs.

package/adapters/claude/skills/forge-bootstrap/SKILL.md

@@ -0,0 +1,240 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-bootstrap/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-bootstrap
+description: Scaffold a brand-new empty repository to a pipeline-ready, green baseline (structure, toolchain, passing lint+test, forge.config.json), then optionally chain into the pipeline. Use when the user runs /feature-forge:forge-bootstrap or asks to bootstrap/scaffold a new empty project for forge. Do NOT trigger on a non-empty repo (that is forge-init), or for general project setup outside the forge pipeline.
+argument-hint: '[--mode-b] [--here|<target-dir>]'
+---
+
+# Bootstrap a Greenfield Repo
+
+Take a **brand-new, empty** repository to a pipeline-ready, **green** baseline — a
+scaffolded stack, a valid `forge.config.json`, and a passing lint+test — then optionally
+chain into the pipeline (Mode B). You own the **conversation and decisions only**; every
+mechanic (the greenfield gate, `git init`, scaffolding, the config write, the toolchain
+probe, the commit) is delegated to the helper `scripts/forge-bootstrap.py`. Never inline
+file generation, template contents, the config field list, or the greenfield allow-list —
+they live in the helper and templates, referenced here, never duplicated.
+
+`<target-dir>` below is the project being bootstrapped (default `.`, or the argument) — it is
+**distinct from `$R`**, the plugin root. Drive control flow off the helper's exit codes and
+JSON: **0** = ok, **1** = actionable findings, **2** = usage/IO **or** verify
+toolchain-missing.
+
+## Host adaptation (conversational fallback)
+
+If the `AskUserQuestion` tool is available, ask the interview questions through it. If it is
+**not** available (a non-Claude host such as Codex), emit the same questions as a single
+**numbered text list** — each line one question with its options in brackets and the default
+marked — then **stop and wait for a single text reply**. Parse the reply positionally
+(answer N → question N); re-prompt only the unparseable items. The question content (text,
+options, defaults) and the conditional gating (Q4 skipped for go/rust/generic; Q6a only for
+monorepo; Q8 only after a verified-green baseline) are **identical** across both paths — only
+the rendering changes. Never assume answers; always wait for the reply.
+
+Emit any context as plain text, then route **all** questions through `AskUserQuestion` (or the
+fallback) — never as inline prose questions, which stall the session.
+
+## Flow (Mode A — default)
+
+```
+1. Portable-root prelude            → locate $R
+2. check                            → gate + recovery detection
+     ├─ eligible:false   (exit 1)   → Greenfield refusal — STOP
+     └─ resumeMarker != null        → Resume / restart / cancel
+3. Interview                        → assemble the Answers payload
+4. scaffold --answers <json>        → git init if absent; compose templates; write config;
+                                       track artifacts into the sentinel
+5. verify                          → toolchain probe + lint/test per member
+     ├─ toolchainPresent:false (2)  → Missing toolchain: scaffold-anyway-unverified vs abort
+     ├─ green:false      (exit 1)   → Not-green: surface failures, offer fix/abort
+     └─ green:true       (exit 0)   → proceed
+6. commit  [--stage-only per Q9]    → stage exact tracked list; single baseline commit;
+                                       remove the sentinel before staging
+7. Completion summary / Mode B hand-off
+```
+
+### Step 1 — locate the helper
+
+Every bash invocation begins with the byte-identical portable-root prelude, then calls the
+helper. Pass `--specs-dir ./specs` (the default) so the gate allow-lists the specs directory.
+
+```bash
+R="$(for d in "$HOME"/.claude/skills/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-bootstrap.py" check "<target-dir>" --json --specs-dir ./specs
+```
+
+Never hardcode a plugin path or a `~/.claude/...` path — always go through `$R`.
+
+### Step 2 — gate (`check`)
+
+Read `CheckResult{eligible, disqualifying[], resumeMarker}`.
+
+- **`eligible:false` (exit 1) → Greenfield refusal.** Name **every** path in `disqualifying[]`
+  verbatim, then direct the user to the right tool — run `forge-init`, then `forge-1-prd`.
+  **Touch no files** and STOP (the gate is read-only).
+
+  ```
+  This repo is not empty — forge-bootstrap only scaffolds a brand-new project.
+  Disqualifying files found:
+    - package.json
+    - src/index.ts
+  To set forge up on an existing project, run:  /feature-forge:forge-init
+  Then start the pipeline with:                 /feature-forge:forge-1-prd <feature>
+  ```
+
+- **`resumeMarker != null` → Partial-state detected.** A `.forge-bootstrap.json` sentinel
+  from this tool's own prior run exists — do **not** treat it as a refusal. Surface the prior
+  run's `startedAt` and `artifactsWritten[]`, then ask **resume / restart / cancel**:
+  - **Resume** — reuse the sentinel's mirrored `answers` (no re-interview), re-run `scaffold`
+    (idempotent — the helper skips already-recorded files), continue from step 5.
+  - **Restart** — discard the partial: delete the recorded `artifactsWritten[]` tree + the `.forge-bootstrap.json` sentinel (a skill-orchestration step — the helper has no clean subcommand), then run the interview and `scaffold` fresh.
+  - **Cancel** — stop without changes.
+
+  You perform no cleanup yourself; you only render the choice and dispatch the subcommand.
+
+### Step 3 — interview
+
+Ask exactly these, in order. Resolved answers become the `Answers` payload handed to
+`scaffold --answers`.
+
+| # | Question | Default / seed rule | Options |
+|---|----------|---------------------|---------|
+| Q1 | Project name? | default = target directory basename (confirm) | free-text, pre-filled |
+| Q2 | One-line purpose? | no default; seeds README + config | free-text |
+| Q3 | Language / stack? | required | `typescript` / `python` / `go` / `rust` / `generic` |
+| Q4 | Package manager? | **only when the stack has a choice** — TS: `npm`/`pnpm`/`yarn`, Python: `uv`/`poetry`/`pip`; **skipped** for go/rust/generic | the stack's options |
+| Q5 | License? | **detect & pre-select** from a pre-existing `LICENSE` (see gating); else default `MIT`. The helper keeps an existing `LICENSE` (REQ-SCAF-09) | `MIT` / `Apache-2.0` / `none` |
+| Q6 | Single package or monorepo? | default `single` | `single` / `monorepo` |
+| Q6a | (monorepo only) member count, then per-member name + stack | no default; one member each (mixed-language allowed) | loop |
+| Q7 | Chain into the pipeline now (Mode B)? | default `no` | `no, scaffold only` / `yes, chain in` |
+| Q8 | (Mode B only) First build: feature or epic? | asked **only after a verified-green baseline** | `feature` / `epic` |
+| Q9 | Commit the baseline, or leave it staged? | default `commit` | `commit` / `stage only` |
+
+Gating: Q4 is asked only when the chosen stack has a package-manager choice; Q6a only when
+Q6 = `monorepo` (each member gets a `path` like `packages/<name>`; a single package is one
+member with `path = "."`); Q7 may be asked up-front, but Q8 / Mode B launch are gated on a
+verified-green, committed baseline (see below). You may also offer an optional
+"generate a CI workflow (lint+test)?" question, setting `Answers.ci`.
+
+License detect-and-seed (Q5, REQ-SCAF-09): when a `LICENSE` already exists in the target
+(an allowed-meta file the gate let through), **read its first lines** and pre-select the
+matching Q5 default — "MIT License" → `MIT`, "Apache License" → `Apache-2.0`, otherwise
+keep the default and note the unrecognized license. The helper never overwrites the existing
+`LICENSE`; this only seeds the interview default. Also set `Answers.author` from
+`git config user.name` (fallback: the project name) and `Answers.host` to `claude` when
+running on a Claude host (so the helper emits `CLAUDE.md` alongside `AGENTS.md`), else leave
+it null.
+
+**Assemble the payload.** Build one `Answers` JSON object — `projectName`, `purpose`,
+`layout`, `license`, `members[]`, `modeB`, `modeBTarget`, `ci`, `commitStyle`, `author`,
+`host` — and pass it verbatim to `scaffold --answers '<json>'`. Invent no fields beyond that
+schema. Two fields come from your runtime, not the interview: `author` from `git config
+user.name` (else the project name; it is the LICENSE copyright holder), and `host` — `"claude"`
+when running under a Claude host (e.g. `AskUserQuestion` is available), else `"codex"`/`"other"`.
+`host` drives the host-conditional agent file: the helper always emits `AGENTS.md` and adds
+`CLAUDE.md` only when `host == "claude"`.
+
+```bash
+R="$(for d in "$HOME"/.claude/skills/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-bootstrap.py" scaffold "<target-dir>" --json --answers '<Answers JSON>'
+```
+
+### Step 5 — verify
+
+```bash
+R="$(for d in "$HOME"/.claude/skills/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-bootstrap.py" verify "<target-dir>" --json --answers '<Answers JSON>'
+```
+
+Read `VerifyResult{green, toolchainPresent, lint[], test[]}`.
+
+- **`toolchainPresent:false` (exit 2) → Missing toolchain.** Warn, naming which stack's
+  toolchain is missing. Ask **scaffold-anyway (unverified) vs abort**. If scaffold-anyway,
+  proceed to commit and mark the baseline **unverified** in the summary — never claim green
+  you could not verify. If abort, stop; the sentinel stays in-progress for a later resume. An
+  unverified baseline **disqualifies Mode B** (no override).
+- **`green:false` with `toolchainPresent:true` (exit 1) → Not-green.** Surface the failing
+  `CommandOutcome` entries (command + member) verbatim; offer abort or retry-after-investigation.
+  Do not silently proceed to a "green" summary.
+- **`green:true` (exit 0)** → proceed to commit.
+
+### Step 6 — commit
+
+Invoke `commit` (or `commit --stage-only`, per Q9). Helper-owned: it stages the **exact
+tracked list** (never `git add -A`/`--force`/`--no-verify`), makes a single baseline commit,
+and removes the sentinel before staging so it never enters history. Read
+`CommitResult{committed, commitHash, staged[]}`. On commit failure, surface the error and
+leave the sentinel in-progress (resumable) — do **not** declare success.
+
+```bash
+R="$(for d in "$HOME"/.claude/skills/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-bootstrap.py" commit "<target-dir>" --json --answers '<Answers JSON>' [--stage-only]
+```
+
+## Completion summary
+
+Render the human-facing summary from the helper's JSON (`VerifyResult` + `CommitResult`). State:
+created artifacts (from `CommitResult.staged[]`, including any kept pre-existing meta file);
+resolved stack(s) (single, or each monorepo member's name + stack); the **verification
+verdict** — `green` or `unverified` (never "green" for an unverified baseline); the commit
+state (with `commitHash`, or staged-only); and the exact next command. In Mode B, **launch**
+the next stage instead of printing the command.
+
+```
+Bootstrap complete — pipeline-ready baseline.
+  Stack:        python (uv)
+  Created:      pyproject.toml, src/acme_svc/..., tests/test_smoke.py, .gitignore,
+                README.md, LICENSE, AGENTS.md, CLAUDE.md, forge.config.json
+  Kept:         (none — README/LICENSE generated fresh)
+  Verification: green  (mypy ✓   pytest ✓)
+  Commit:       baseline committed (a1b2c3d)
+  Next step:    /feature-forge:forge-1-prd <feature>
+```
+
+Unverified variant:
+
+```
+  Verification: UNVERIFIED — toolchain not found on this machine; lint+test were not run.
+                Install the toolchain and re-run verify before relying on the baseline.
+```
+
+## Mode B hand-off (opt-in)
+
+Mode B is **opt-in** (Q7; default Mode A) and **agent-driven** — it hands skill-to-skill to
+the next pipeline stage, not through the helper.
+
+**Gate:** launch the next stage **only after both** a verified-green baseline
+(`VerifyResult.green == true`) **and** a successful commit (`CommitResult.committed == true`).
+If the baseline is unverified or not-green, you MUST NOT launch the next stage and MUST NOT
+even ask Q8 — fall back to the Mode A summary with the next command printed. There is no
+"launch anyway on red" path.
+
+When the gate passes:
+
+1. Ask Q8 — feature vs epic — if not already resolved.
+2. **Feature:** invoke `forge-1-prd <feature>` skill-to-skill, seeding `<feature>` from a
+   confirmed, kebab-cased name.
+3. **Epic:** invoke `forge-0-epic <epic>` skill-to-skill. Seed the epic name and initial
+   decomposition from the project name + purpose (Q1/Q2), **propose it, let the user
+   edit/approve**, then launch.
+4. **Launch** that stage instead of printing its command.
+
+Mode B auto-launches **only the immediate next stage**; every subsequent pipeline stage stays
+a normal, user-driven step. The hand-off is always skill-to-skill, never via the helper.
+
+## The four terminal outcomes
+
+Every run ends in exactly one explicit, actionable outcome — make it explicit in your output;
+no run ends silently:
+
+- **Success** — `commit` exit 0 + green (or unverified-but-proceeded) → completion summary, or
+  Mode B launch.
+- **Greenfield refusal** — `check` `eligible:false` → name `disqualifying[]`, point to
+  `forge-init` + `forge-1-prd`, touch nothing.
+- **Missing toolchain** — `verify` `toolchainPresent:false` (exit 2) → scaffold-anyway-unverified
+  vs abort; mark **unverified**.
+- **Partial-state detected** — `check` `resumeMarker != null` → resume / restart / cancel.

package/adapters/claude/skills/forge-bootstrap/references/templates/ci/github-actions.yml

@@ -0,0 +1,12 @@
+name: ci
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # <<MEMBER_STEPS>>

package/adapters/claude/skills/forge-bootstrap/references/templates/generic/run.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Entrypoint for the scaffolded baseline.
+echo "Hello from {{PROJECT_NAME}}"

package/adapters/claude/skills/forge-bootstrap/references/templates/generic/test.sh

@@ -0,0 +1,13 @@
+#!/bin/sh
+# Behavioral test: run the entrypoint and assert its output.
+set -eu
+
+actual="$(./run.sh)"
+expected="Hello from {{PROJECT_NAME}}"
+
+if [ "$actual" != "$expected" ]; then
+  printf 'FAIL: expected %s but got %s\n' "$expected" "$actual" >&2
+  exit 1
+fi
+
+printf 'PASS: run.sh produced the expected greeting\n'

package/adapters/claude/skills/forge-bootstrap/references/templates/go/go.mod

@@ -0,0 +1,3 @@
+module {{PKG}}
+
+go 1.21

package/adapters/claude/skills/forge-bootstrap/references/templates/go/main.go

@@ -0,0 +1,12 @@
+package main
+
+import "fmt"
+
+// greet returns the project greeting for name.
+func greet(name string) string {
+	return "Hello from " + name
+}
+
+func main() {
+	fmt.Println(greet("{{PROJECT_NAME}}"))
+}

package/adapters/claude/skills/forge-bootstrap/references/templates/go/main_test.go

@@ -0,0 +1,11 @@
+package main
+
+import "testing"
+
+func TestGreet(t *testing.T) {
+	got := greet("world")
+	want := "Hello from world"
+	if got != want {
+		t.Errorf("greet(\"world\") = %q, want %q", got, want)
+	}
+}

package/adapters/claude/skills/forge-bootstrap/references/templates/hygiene/AGENTS.md

@@ -0,0 +1,24 @@
+# Agent Instructions — {{PROJECT_NAME}}
+
+## Project Purpose
+
+{{PURPOSE}}
+
+## Getting Started
+
+This project was scaffolded by forge-bootstrap. To continue development:
+
+1. Review `forge.config.json` for the project configuration.
+2. Run the forge pipeline (forge-1-prd → forge-0-epic → forge-3-specs → forge-4-backlog) to plan and implement features.
+3. Use `forge-5-loop` to drive autonomous implementation.
+
+## Conventions
+
+- Follow the patterns established in the existing codebase.
+- Keep `forge.config.json` up to date with any changes to stack or commands.
+
+## Specs are pre-implementation
+
+- Documents under `specs/` (PRDs, tech specs, numbered implementation specs) establish the backlog. They are **not** kept in sync with the code as it evolves.
+- Do not flag or "fix" divergence between a finalized spec and the implementation — code is the source of truth for behavior.
+- It's fine for `specs/` artifacts and `backlog.json` to reference specs for provenance, but implementation artifacts (source code, generated skills/agents, configs, docs) must not reference spec files, which may be archived or deleted after a feature ships.

package/adapters/claude/skills/forge-bootstrap/references/templates/hygiene/CLAUDE.md

@@ -0,0 +1,25 @@
+# Claude Instructions — {{PROJECT_NAME}}
+
+## Project Purpose
+
+{{PURPOSE}}
+
+## Getting Started
+
+This project was scaffolded by forge-bootstrap. To continue development:
+
+1. Review `forge.config.json` for the project configuration.
+2. Run the forge pipeline (forge-1-prd → forge-0-epic → forge-3-specs → forge-4-backlog) to plan and implement features.
+3. Use `forge-5-loop` to drive autonomous implementation.
+
+## Working with Claude
+
+- Use `/feature-forge:forge` to enter the forge pipeline for new features.
+- The `forge.config.json` at the project root defines the stack, commands, and pipeline settings.
+- Follow the patterns established in the existing codebase.
+
+## Specs are pre-implementation
+
+- Documents under `specs/` (PRDs, tech specs, numbered implementation specs) establish the backlog. They are **not** kept in sync with the code as it evolves.
+- Don't flag or "fix" divergence between a finalized spec and the implementation — code is the source of truth for behavior.
+- It's fine for `specs/` artifacts and `backlog.json` to reference specs for provenance, but implementation artifacts (source code, generated skills/agents, configs, docs) must not reference spec files, which may be archived or deleted after a feature ships.

package/adapters/claude/skills/forge-bootstrap/references/templates/hygiene/README.md

@@ -0,0 +1,11 @@
+# {{PROJECT_NAME}}
+
+{{PURPOSE}}
+
+## License
+
+This project is licensed under {{LICENSE}}.
+
+---
+
+_Scaffolded by [forge-bootstrap](https://github.com/feature-forge/feature-forge)._