@garygentry/feature-forge 0.1.4 → 0.2.0

package/README.md

@@ -40,6 +40,24 @@ npx @garygentry/feature-forge install --dry-run --json
 | `--json`            | Emit the run report as JSON.                                          |
 | `--skip-rauf`       | Skip the rauf resolvability preflight (records `raufPin: null`).      |
 
+## Per-agent install layout
+
+Each agent's bundle is installed where that agent actually loads it (project scope shown;
+`--global` resolves the same paths under `~`):
+
+| Agent   | Primary bundle                       | Second-root placement                                   |
+| ------- | ------------------------------------ | ------------------------------------------------------- |
+| claude  | `.claude/skills/feature-forge/`      | —                                                       |
+| codex   | `.agents/skills/feature-forge/`      | `.codex/agents/*.toml` (custom agents, mirrored flat)   |
+| copilot | `.github/feature-forge/`             | managed block in `.github/copilot-instructions.md`      |
+| cursor  | `.cursor/rules/feature-forge/`       | —                                                       |
+| gemini  | `.gemini/extensions/feature-forge/`  | —                                                       |
+
+The Copilot block is delimited by `<!-- feature-forge:managed:start -->` /
+`<!-- feature-forge:managed:end -->` sentinels and merged without disturbing the rest of the
+file. `update` refreshes it (a hand-edited block is left alone unless `--force`); `uninstall`
+strips only the block, deleting the file only if nothing else remains.
+
 ## Claude
 
 Claude Code users can alternatively install via the plugin marketplace:
@@ -53,7 +71,7 @@ Claude Code users can alternatively install via the plugin marketplace:
 
 The default loop runner is [**rauf**](https://github.com/garygentry/rauf), published as
 [`@garygentry/rauf`](https://www.npmjs.com/package/@garygentry/rauf). The installer runs a
-read-only resolvability preflight on the pin (`@garygentry/rauf@0.7.0`) and records it; pass
+read-only resolvability preflight on the pin (`@garygentry/rauf@0.8.0`) and records it; pass
 `--skip-rauf` to defer the check (e.g. offline installs). Install the rauf CLI itself with
 `npx @garygentry/rauf` or its
 [binary script](https://github.com/garygentry/rauf#install). See the

package/adapters/GENERATION-REPORT.md

@@ -12,18 +12,18 @@ _No dropped constructs — every canonical construct is representable in this ag
 
 | Source | Construct | Reason |
 |--------|-----------|--------|
-| `agents/forge-researcher.md` | `sub-agent key 'effort'` | not representable in agents/openai.yaml (TQ-1) |
-| `agents/forge-researcher.md` | `sub-agent key 'maxTurns'` | not representable in agents/openai.yaml (TQ-1) |
-| `agents/forge-researcher.md` | `sub-agent key 'model'` | not representable in agents/openai.yaml (TQ-1) |
-| `agents/forge-researcher.md` | `sub-agent key 'tools'` | not representable in agents/openai.yaml (TQ-1) |
-| `agents/forge-spec-writer.md` | `sub-agent key 'maxTurns'` | not representable in agents/openai.yaml (TQ-1) |
-| `agents/forge-spec-writer.md` | `sub-agent key 'model'` | not representable in agents/openai.yaml (TQ-1) |
-| `agents/forge-spec-writer.md` | `sub-agent key 'tools'` | not representable in agents/openai.yaml (TQ-1) |
-| `agents/forge-verifier.md` | `sub-agent key 'maxTurns'` | not representable in agents/openai.yaml (TQ-1) |
-| `agents/forge-verifier.md` | `sub-agent key 'memory'` | not representable in agents/openai.yaml (TQ-1) |
-| `agents/forge-verifier.md` | `sub-agent key 'model'` | not representable in agents/openai.yaml (TQ-1) |
-| `agents/forge-verifier.md` | `sub-agent key 'skills'` | not representable in agents/openai.yaml (TQ-1) |
-| `agents/forge-verifier.md` | `sub-agent key 'tools'` | not representable in agents/openai.yaml (TQ-1) |
+| `agents/forge-researcher.md` | `sub-agent key 'effort'` | no Codex custom-agent equivalent in safe mapping (TQ-1) |
+| `agents/forge-researcher.md` | `sub-agent key 'maxTurns'` | no Codex custom-agent equivalent in safe mapping (TQ-1) |
+| `agents/forge-researcher.md` | `sub-agent key 'model'` | no Codex custom-agent equivalent in safe mapping (TQ-1) |
+| `agents/forge-researcher.md` | `sub-agent key 'tools'` | no Codex custom-agent equivalent in safe mapping (TQ-1) |
+| `agents/forge-spec-writer.md` | `sub-agent key 'maxTurns'` | no Codex custom-agent equivalent in safe mapping (TQ-1) |
+| `agents/forge-spec-writer.md` | `sub-agent key 'model'` | no Codex custom-agent equivalent in safe mapping (TQ-1) |
+| `agents/forge-spec-writer.md` | `sub-agent key 'tools'` | no Codex custom-agent equivalent in safe mapping (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'maxTurns'` | no Codex custom-agent equivalent in safe mapping (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'memory'` | no Codex custom-agent equivalent in safe mapping (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'model'` | no Codex custom-agent equivalent in safe mapping (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'skills'` | no Codex custom-agent equivalent in safe mapping (TQ-1) |
+| `agents/forge-verifier.md` | `sub-agent key 'tools'` | no Codex custom-agent equivalent in safe mapping (TQ-1) |
 | `skills/forge-0-epic/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 | `skills/forge-1-prd/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 | `skills/forge-2-tech/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
@@ -31,6 +31,7 @@ _No dropped constructs — every canonical construct is representable in this ag
 | `skills/forge-4-backlog/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 | `skills/forge-5-loop/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 | `skills/forge-6-docs/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
+| `skills/forge-bootstrap/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 | `skills/forge-fix/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 | `skills/forge-verify/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
 | `skills/forge/SKILL.md` | `argument-hint` | no confirmed Codex invocation-hint field (TQ-1) |
@@ -58,6 +59,7 @@ _No dropped constructs — every canonical construct is representable in this ag
 | `skills/forge-4-backlog/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
 | `skills/forge-5-loop/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
 | `skills/forge-6-docs/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
+| `skills/forge-bootstrap/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
 | `skills/forge-fix/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
 | `skills/forge-verify/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
 | `skills/forge/SKILL.md` | `argument-hint` | no known Copilot invocation-hint field (TQ-1) |
@@ -85,6 +87,7 @@ _No dropped constructs — every canonical construct is representable in this ag
 | `skills/forge-4-backlog/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
 | `skills/forge-5-loop/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
 | `skills/forge-6-docs/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
+| `skills/forge-bootstrap/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
 | `skills/forge-fix/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
 | `skills/forge-verify/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
 | `skills/forge/SKILL.md` | `argument-hint` | no Cursor .mdc invocation-hint field |
@@ -112,6 +115,7 @@ _No dropped constructs — every canonical construct is representable in this ag
 | `skills/forge-4-backlog/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 | `skills/forge-5-loop/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 | `skills/forge-6-docs/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
+| `skills/forge-bootstrap/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 | `skills/forge-fix/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 | `skills/forge-verify/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
 | `skills/forge/SKILL.md` | `argument-hint` | Gemini manifest hint field unconfirmed (TQ-1) |
@@ -121,7 +125,7 @@ _No dropped constructs — every canonical construct is representable in this ag
 These files are transported byte-for-byte from canon into every `adapters/<agent>/` bundle and intentionally carry **no** provenance header (a header would break byte-identity / corrupt parsed files):
 
 - `scripts/forge-root.sh` → `adapters/<agent>/scripts/forge-root.sh` (mode 0755, byte-identical — REQ-GEN-05).
-- the whole repo-root `references/` tree (14 files: 9 root + `stacks/`×5) → `adapters/<agent>/references/` (verbatim — REQ-GEN-04 / D5).
+- the whole repo-root `references/` tree (16 files: 9 root + `stacks/`×5 + `templates/specs-hygiene/`×2) → `adapters/<agent>/references/` (verbatim — REQ-GEN-04 / D5).
 - each skill's own `references/` subdir → `adapters/<agent>/skills/<name>/references/` (verbatim, where present).
 
 Regenerate all adapter output with `python3 scripts/build-adapters.py`.

package/adapters/claude/.feature-forge-bundle.json

@@ -0,0 +1,6 @@
+{
+  "name": "feature-forge",
+  "version": "0.11.0",
+  "agent": "claude",
+  "generatedBy": "python3 scripts/build-adapters.py"
+}

package/adapters/claude/references/forge-config-schema.json

@@ -15,8 +15,8 @@
       "description": "Root directory for generated architecture documentation."
     },
     "backlogDir": {
-      "type": "string",
-      "description": "Optional override for backlog location. If set, backlog.json is written here instead of with the feature specs. Default behavior: backlog.json is written to {specsDir}/{feature}/backlog.json."
+      "type": ["string", "null"],
+      "description": "Optional override for backlog location. If set, backlog.json is written here instead of with the feature specs. Default behavior (null): backlog.json is written to {specsDir}/{feature}/backlog.json."
     },
     "gitCommitAfterStage": {
       "type": "boolean",
@@ -28,17 +28,27 @@
       "default": "forge",
       "description": "Prefix for conventional commit messages, e.g., forge(auth): complete PRD"
     },
-    "stack": {
+    "branchPerFeature": {
+      "type": "boolean",
+      "default": true,
+      "description": "Offer to create an isolated git branch when a feature/epic starts on the default branch (main/master). Gated only on the project using git — independent of gitCommitAfterStage. When false, forge never prompts for a branch and works on whatever branch is checked out. See the Branch Setup block in references/shared-conventions.md."
+    },
+    "branchPrefix": {
       "type": "string",
-      "description": "Detected or configured project stack identifier. Selects guidance from references/stacks/{stack}.md. Set during forge-2-tech or manually. Examples: 'typescript', 'python', 'go', 'rust'."
+      "default": "forge/",
+      "description": "Prefix for the branch name suggested by Branch Setup, e.g. 'forge/' yields 'forge/{feature}' or 'forge/{epic}'. Ignored when branchPerFeature is false."
+    },
+    "stack": {
+      "type": ["string", "null"],
+      "description": "Detected or configured project stack identifier. Selects guidance from references/stacks/{stack}.md. Set during forge-2-tech or manually (null until then). Examples: 'typescript', 'python', 'go', 'rust'."
     },
     "typeCheckCommand": {
-      "type": "string",
-      "description": "Command to verify type correctness or lint. Examples: 'bun run typecheck', 'mypy .', 'go vet ./...'. Used in acceptance criteria and verification."
+      "type": ["string", "null"],
+      "description": "Command to verify type correctness or lint. Null until set. Examples: 'bun run typecheck', 'mypy .', 'go vet ./...'. Used in acceptance criteria and verification."
     },
     "testCommand": {
-      "type": "string",
-      "description": "Command to run tests. Examples: 'bun test', 'pytest', 'go test ./...'. Used in acceptance criteria and verification."
+      "type": ["string", "null"],
+      "description": "Command to run tests. Null until set. Examples: 'bun test', 'pytest', 'go test ./...'. Used in acceptance criteria and verification."
     },
     "loopIterationMultiplier": {
       "type": "number",
@@ -46,6 +56,22 @@
       "minimum": 1,
       "description": "Multiplier applied to pending backlog item count to calculate loop iterations. Higher values allow more retries. Default: 1.5 (e.g., 10 items = 15 iterations)."
     },
+    "workspaces": {
+      "type": "array",
+      "description": "Monorepo members. Absent for single-package projects.",
+      "items": {
+        "type": "object",
+        "required": ["name", "path", "stack"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {"type": "string"},
+          "path": {"type": "string", "description": "Repo-relative member dir"},
+          "stack": {"type": "string"},
+          "typeCheckCommand": {"type": ["string", "null"]},
+          "testCommand": {"type": ["string", "null"]}
+        }
+      }
+    },
     "loopRunner": {
       "type": "object",
       "description": "The autonomous loop runner feature-forge drives. Defaults to rauf when absent (forge-5 states 'defaulting to rauf loop runner'). Every command is a template — {bin}, {backlogDir}, {specsDir}, {iterations} are substituted at call time — so an alternative ralph-style runner conforming to rauf's SPEC-BACKLOG-TOOL-CONTRACT.md can be swapped in without editing any skill. See references/ralph-loop-contract.md.",
@@ -147,8 +173,8 @@
         },
         "installHint": {
           "type": "string",
-          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.7.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.7.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
-          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.7.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned @garygentry/rauf@0.8.0 default). Or install/upgrade just the rauf CLI: `npx @garygentry/rauf@0.8.0 --version`, or `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins @garygentry/rauf@0.8.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
         },
         "schemaVersion": {
           "type": "string",

package/adapters/claude/references/pipeline-state-schema.json

@@ -18,6 +18,10 @@
       "type": "string",
       "description": "Back-pointer to the owning epic's name. Absent for standalone features. The epic-manifest.json is canonical on conflict (REQ-STATE-01)."
     },
+    "branch": {
+      "type": "string",
+      "description": "Git branch this feature's pipeline work is intended to land on, recorded by the Branch Setup block (shared-conventions.md) at the entry stage. Absent when the project isn't a git repo or branchPerFeature is false. Downstream stages and forge-5-loop compare the current branch against this to detect drift back onto the default branch before committing."
+    },
     "createdAt": {
       "type": "string",
       "format": "date-time"

package/adapters/claude/references/portable-root.md

@@ -12,7 +12,7 @@ against the fenced block here, byte-for-byte.
 ## Canonical bootstrap prelude
 
 ```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; }
 ```
 
@@ -24,7 +24,7 @@ makes several calls, add the prelude once and reuse `$R` for each. A fresh block
 prelude (per-block re-resolution). Worked example:
 
 ```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
 ```
@@ -40,10 +40,13 @@ python3 "$R/scripts/epic-manifest.py" render-status "{epic}" --specs-dir "{specs
    final root resolution to that script. The `for` list is a discovery order for `forge-root.sh`
    itself, not a fallback chain for the plugin root. Removing the `exec` to "keep looping" is a
    regression — once `exec`'d, the loop is replaced by the resolver process and never advances.
-3. **Prelude candidate set is a minimal `$HOME` bootstrap subset.** The prelude's `for d` list
+3. **Prelude candidate set is an agent-neutral bootstrap subset.** The prelude's `for d` list
    exists only to bootstrap-discover `forge-root.sh`; the authoritative multi-root probe lives in
-   `forge-root.sh` step 2. When adding an install root, update `forge-root.sh` first; extend the
-   prelude only if the new root is needed to bootstrap-discover `forge-root.sh` itself.
+   `forge-root.sh` step 2. The list enumerates install roots across agents — the Claude
+   skill/plugin dirs **and** the agent-neutral `.agents/skills/feature-forge` dirs (`$HOME` and the
+   project-relative `./.agents/...`) — so a non-Claude install (e.g. Codex under `.agents/skills`)
+   can still discover the resolver. When adding an install root, update `forge-root.sh` first;
+   extend the prelude only if the new root is needed to bootstrap-discover `forge-root.sh` itself.
 
 ## The resolver
 

package/adapters/claude/references/process-overview.md

@@ -2,12 +2,20 @@
 
 This document describes the end-to-end feature development pipeline managed by the feature-forge plugin. All forge skills reference this document to understand the overall flow and their position within it.
 
+The pipeline compiles a fuzzy feature idea into a machine-executable `backlog.json`. Each stage narrows the idea down and adds structure, verification gates catch gaps before they reach later stages, and a swappable autonomous loop runner (rauf by default) implements the backlog in fresh per-item sessions.
+
 ## Pipeline Stages
 
 ```
-forge-1-prd → forge-2-tech → forge-3-specs → forge-verify → forge-4-backlog → forge-verify → forge-5-loop → forge-verify → forge-6-docs
+[forge-0-epic] → forge-1-prd → forge-2-tech → forge-3-specs → forge-verify → forge-4-backlog → forge-verify → forge-5-loop → forge-verify → forge-6-docs
+   (optional)
 ```
 
+### Stage 0: Epic (`/feature-forge:forge-0-epic <epic>`), optional
+**Input:** A change too large for one feature
+**Output:** `{specsDir}/{epic}/epic-manifest.json` + `EPIC.md` + one member-feature dir per feature
+**Method:** Decomposition interview splitting the change into member features with declared dependencies and `exposes`/`consumes` contracts. Purely additive: single-feature flows are unchanged. See [docs/architecture/epic-orchestration/README.md](../docs/architecture/epic-orchestration/README.md).
+
 ### Stage 1: PRD (`/feature-forge:forge-1-prd <feature>`)
 **Input:** User's feature idea and domain knowledge
 **Output:** `{specsDir}/{feature}/PRD.md`
@@ -35,13 +43,13 @@ After verification, fixes can be applied via:
 
 ### Stage 4: Backlog (`/feature-forge:forge-4-backlog <feature>`)
 **Input:** Full spec suite
-**Output:** `{specsDir}/{feature}/backlog.json` (or `{backlogDir}/backlog.json` if backlogDir is configured)
+**Output:** `{specsDir}/{feature}/backlog.json` (or `{backlogDir}/{feature}/backlog.json` if backlogDir is configured)
 **Method:** Generate structured backlog items with spec references, acceptance criteria, and dependencies. Backlog is collocated with feature specs by default.
 
 ### Stage 5: Rauf Loop (`/feature-forge:forge-5-loop <feature>`)
 **Input:** `backlog.json` from Stage 4
 **Output:** Implemented source code (committed per-item by rauf)
-**Method:** Execute the rauf autonomous coding loop against the feature's backlog. Spawns a fresh Claude Code session per backlog item with full spec context.
+**Method:** Execute the autonomous coding loop against the feature's backlog. Spawns a fresh session per backlog item with full spec context. rauf is the default runner but is swappable via the `loopRunner` block in `forge.config.json`; see [`references/ralph-loop-contract.md`](./ralph-loop-contract.md).
 
 ### Stage 6: Documentation (`/feature-forge:forge-6-docs <feature>`)
 **Input:** Specs + implementation
@@ -71,7 +79,9 @@ Read `forge.config.json` from project root for path overrides. See `references/f
 
 ## Git Workflow
 
-Recommended: create a `forge/{feature}` branch before starting the pipeline. All forge commits go to this branch. After implementation, merge to your development branch.
+Recommended: forge work lives on an isolated `forge/{feature}` (or `forge/{epic}`) branch so all commits land together and review as one branch. The entry stages (`forge-1-prd`, `forge-0-epic`) detect whether you're on the default branch (main/master) and **strongly recommend** creating that branch when you are — still letting you decline and stay. The chosen branch is recorded in `.pipeline-state.json`, and `forge-5-loop` re-checks it before the autonomous loop starts committing per item. After implementation, merge to your development branch.
+
+To customize: `branchPrefix` (default `forge/`) sets the branch name, and `branchPerFeature: false` disables the prompt entirely (forge then works on whatever branch is checked out). Branch Setup is gated only on the project using git — independent of `gitCommitAfterStage`.
 
 If you prefer manual commit control, set `gitCommitAfterStage: false` in `forge.config.json`.
 
@@ -88,7 +98,7 @@ When creating specs, always examine the existing codebase for patterns, conventi
 - Shared types, utilities, and conventions
 
 ### Stack Context
-The project's stack is detected during forge-2-tech and persisted in `forge.config.json` (the `stack`, `typeCheckCommand`, and `testCommand` fields). See `references/stack-resolution.md` for the full resolution protocol. The project may also have a `stack-decisions.md` in `.claude/references/` with established technology decisions — if present, it takes highest precedence.
+The project's stack is detected during forge-2-tech and persisted in `forge.config.json` (the `stack`, `typeCheckCommand`, and `testCommand` fields). See `references/stack-resolution.md` for the full resolution protocol. The project may also have a `stack-decisions.md` (preferred at `.feature-forge/`; legacy `.claude/references/`) with established technology decisions — if present, it takes highest precedence.
 
 ## Subagents
 

package/adapters/claude/references/shared-conventions.md

@@ -34,7 +34,24 @@ I found that the codebase uses React and TanStack Router.
 [then call AskUserQuestion with: "1. Where should this component live? 2. Should we use server-side rendering?"]
 ```
 
-**Recommendations:** Only recommend a specific option when codebase evidence, established conventions, or strong technical rationale clearly favors it. If options are equally valid, present them neutrally — let the user decide without bias.
+### Decision Support: Help the User Choose
+
+When an `AskUserQuestion` carries substantive options (a real choice — not a trivial yes/no confirmation), do not just list them. The interview stages have already done codebase research and integration analysis; surfacing that synthesis at the decision moment is the whole point. For every such question:
+
+- **Lead with a recommended option.** Place it first and label it `(recommended)` (matching the `AskUserQuestion` "(Recommended)" convention).
+- **Put the trade-off in each option's `description`.** Say why you'd pick it and what you give up versus the alternatives — the cost, not just the benefit.
+- **State a one-line rationale** in the text before the question for *why* the recommendation wins.
+
+Two modes, and make clear which one you're in:
+
+- **Evidence-backed** — codebase evidence, an established convention, or a clear technical rationale favors one option. Recommend it with confidence and cite the evidence ("the codebase already uses X, so…").
+- **Preference** — no option clearly wins (taste, team workflow, risk appetite). Still offer a sensible **default** and the trade-offs, but say plainly this is a judgment call / the user's preference, so you don't manufacture false confidence.
+
+**The only thing to avoid is false confidence** — recommending as if evidence-backed when it's really preference. Never respond to the absence of a clear winner by going silent: a defaulted recommendation with honest trade-offs always beats a neutral option dump.
+
+For genuinely comparable artifacts (competing module structures, two code snippets, layout variants), use the `AskUserQuestion` `preview` field to show them side-by-side.
+
+The **Branch Setup** block below is the reference pattern: a strong recommendation as the first option, rationale inline, the alternative still available, never a hard-stop.
 
 ## Configuration Reading
 
@@ -48,6 +65,8 @@ Extract these config values (use defaults if not present):
 - `backlogDir` (default: null — backlog lives at `{specsDir}/{feature}/backlog.json`; when `backlogDir` is configured, forge-4 composes `{backlogDir}/{feature}/`)
 - `gitCommitAfterStage` (default: true)
 - `commitPrefix` (default: `forge`)
+- `branchPerFeature` (default: true)
+- `branchPrefix` (default: `forge/`)
 - `loopIterationMultiplier` (default: `1.5`)
 - `loopRunner` (optional object — the loop runner to drive; **defaults to rauf** when absent, with every command templated. See `references/forge-config-schema.json` and `references/ralph-loop-contract.md`.)
 
@@ -56,7 +75,7 @@ Extract these config values (use defaults if not present):
 Before any file I/O against a feature's artifacts, resolve its directory through the deterministic helper rather than hardcoding `{specsDir}/{feature}/`. This makes flat (`{specsDir}/{feature}/`) and nested (`{specsDir}/{epic}/{feature}/`) layouts both resolve from a bare feature name (REQ-DIR-03), with standalone features behaving exactly as today.
 
 ```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; }
 resolvedFeatureDir=$(python3 "$R/scripts/epic-manifest.py" \
   resolve "<feature>" --specs-dir "<specsDir>")
@@ -79,6 +98,27 @@ A directory counts as a **feature** only if it directly contains a `.pipeline-st
 
 **Compatibility:** for a standalone feature the resolver returns its flat path with no epic logic engaged (REQ-COMPAT-01/02) — standalone-feature behavior is unchanged. A pre-existing latent name collision is reported for manual cleanup by the navigator / forge-verify epic mode (CHECK-E08), not by aborting an unrelated command whose name resolves to exactly one dir (tech-spec §3.4).
 
+## Specs Directory Hygiene
+
+Whenever a stage creates the specs tree for the first time (the first PRD or epic written under `{specsDir}/`), ensure a spec-directory agent-instruction file exists at the **specsDir root**. This tells coding agents in the project that the specs here are pre-implementation artifacts — not live contracts to enforce against the code. It is **idempotent: never overwrite an existing file** (the project may have edited it).
+
+Run this after creating the feature/epic directory, before the stage's git commit:
+
+```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; }
+mkdir -p "<specsDir>"
+[ -f "<specsDir>/AGENTS.md" ] || cp "$R/references/templates/specs-hygiene/AGENTS.md" "<specsDir>/AGENTS.md"
+```
+
+If the host is Claude (the `AskUserQuestion` tool is available), also ensure the Claude-framed variant:
+
+```bash
+[ -f "<specsDir>/CLAUDE.md" ] || cp "$R/references/templates/specs-hygiene/CLAUDE.md" "<specsDir>/CLAUDE.md"
+```
+
+Stage any file this writes (`{specsDir}/AGENTS.md`, and `{specsDir}/CLAUDE.md` when written) as part of the stage's existing git commit.
+
 ## Epic Context Injection
 
 After resolving the feature directory, check the feature's `.pipeline-state.json` for an `epic` back-pointer. **If absent, skip this block entirely** (standalone feature — REQ-COMPAT-01; standalone-feature behavior is unchanged). **If present**, load exactly the following context, and nothing transitive (REQ-CTX-01):
@@ -92,7 +132,7 @@ After resolving the feature directory, check the feature's `.pipeline-state.json
 To obtain the manifest contracts and the live completion status of each dependency in one deterministic call, run `render-status` and read the per-feature `status` and the `consumes`/`exposes` arrays rather than re-deriving them:
 
 ```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 +150,31 @@ When loading upstream artifacts as prerequisites, check `basedOnVersions` in the
 
 > "This stage was built against {upstream} v{old}, but {upstream} is now at v{new}. The current artifacts may be outdated. Consider re-running this stage, or use --force to proceed with potentially stale inputs."
 
+Frame the choice with its cost: re-running re-derives this stage from the current upstream (safest, but discards any hand-edits to this stage's artifacts); proceeding stale is faster but risks baking outdated assumptions into everything downstream. Recommend re-running unless the user knows the upstream change doesn't affect this stage.
+
+## Branch Setup
+
+Invoke this block at the **very start** of a pipeline entry point — `forge-1-prd` (standalone feature) and `forge-0-epic` (epic) — **before** any directory resolution or interview, so the rest of the run lands on the intended branch. `{label}` is the feature name (forge-1-prd) or epic name (forge-0-epic); `{scope}` is `feature` or `epic` correspondingly.
+
+**Gate.** Run this block only when the project uses git (a `.git` directory resolves) **and** `branchPerFeature` is true. It is **independent of `gitCommitAfterStage`** — branch isolation matters whether or not forge auto-commits. If `branchPerFeature` is false, skip silently.
+
+**Epic-member inheritance.** In `forge-1-prd`, if the feature has an `epic` back-pointer (an `epic` field resolves via Epic Context Injection, or the directory is nested under an epic), the epic already established the branch in `forge-0-epic`. Skip the prompt — inherit the current branch.
+
+**Detection, then a branch-aware prompt:**
+
+1. Read the current branch: `git rev-parse --abbrev-ref HEAD`.
+2. Determine the default branch: `git symbolic-ref --quiet refs/remotes/origin/HEAD` (strip to the last path segment); if that fails, fall back to `main`, else `master` — whichever the repo has.
+3. **If the current branch is NOT the default branch** (the user is already on a topic/`{branchPrefix}*` branch) → record it (see below) and proceed silently. Do not prompt.
+4. **If the current branch IS the default branch** → use `AskUserQuestion` with a **strong recommendation** (still optional):
+
+   > "You're on `{defaultBranch}`. Strongly recommended: create `{branchPrefix}{label}` so this {scope}'s work stays isolated and reviewable as one branch. Create it?"
+   > Options: **Create `{branchPrefix}{label}` (recommended)** · **Stay on `{defaultBranch}`**
+
+   - **Create** → `git switch -c {branchPrefix}{label}` (or `git checkout -b` if `switch` is unavailable). If the branch already exists, `git switch {branchPrefix}{label}`.
+   - **Stay** → proceed on the default branch; note that subsequent commits (and any `forge-5-loop` run) will land directly on `{defaultBranch}`.
+
+**Record the branch.** After this block resolves, write the resulting branch name to the feature's `.pipeline-state.json` top-level `branch` field (create/update it when the state file is first written for this stage). Downstream stages and `forge-5-loop` read it to detect drift back onto the default branch.
+
 ## Git Commit Protocol
 
 When `gitCommitAfterStage` is true, follow this exact order to avoid state inconsistency:
@@ -139,6 +204,6 @@ When a skill detects that `currentStage` matches itself and the stage status is
 
 If the user passes `--force` as an argument, skip prerequisite validation with a warning:
 
-> Force mode: skipping prerequisite checks. Pipeline state tracking may be incomplete. Recommend running `/feature-forge:forge {feature}` after to verify status.
+> Force mode: skipping prerequisite checks. Pipeline state tracking may be incomplete — this stage may build on prior stages that were never completed or verified, so its output can be silently wrong. Recommend running `/feature-forge:forge {feature}` after to verify status.
 
 Continue with the stage even if prior stages are not marked complete. Still read any existing artifacts (PRD.md, tech-spec.md, etc.) if they exist on disk — force mode skips the pipeline state check, not the artifact loading.

package/adapters/claude/references/stack-resolution.md

@@ -4,7 +4,10 @@ How feature-forge resolves stack-specific guidance for a project.
 
 ## Resolution Order (highest priority first)
 
-1. **Project-level override**: `.claude/references/stack-decisions.md` in the project root. If this file exists, it takes absolute precedence — it contains the team's explicit technology decisions.
+1. **Project-level override** (first existing path wins). These hold the team's explicit technology decisions and take absolute precedence:
+   1. `.feature-forge/stack-decisions.md` — the preferred, host-neutral location (it belongs to this tool, not to any one agent).
+   2. `.agents/references/stack-decisions.md` — for projects that centralize cross-agent config under `.agents/`.
+   3. `.claude/references/stack-decisions.md` — **legacy alias**, still honored for backward compatibility. If only this file exists, use it and suggest copying it to `.feature-forge/stack-decisions.md`.
 
 2. **Detected stack profile**: `references/stacks/{stack}.md` in this plugin, where `{stack}` matches the `stack` field in `forge.config.json`. Provides language-specific conventions for spec writing, verification, and examples.
 

package/adapters/claude/references/stacks/go.md

@@ -111,7 +111,7 @@ When examining a Go project, check for:
 
 ## Example: Project-Level Override
 
-Create `.claude/references/stack-decisions.md` in your project root:
+Create `.feature-forge/stack-decisions.md` (legacy alias: `.claude/references/stack-decisions.md`) in your project root:
 
 ```markdown
 # Stack Decisions

package/adapters/claude/references/stacks/python.md

@@ -136,7 +136,7 @@ async def refresh_session_token(
 
 ## Example: Project-Level Override
 
-Create `.claude/references/stack-decisions.md` in your project root:
+Create `.feature-forge/stack-decisions.md` (legacy alias: `.claude/references/stack-decisions.md`) in your project root:
 
 ```markdown
 # Stack Decisions

package/adapters/claude/references/stacks/rust.md

@@ -120,7 +120,7 @@ When examining a Rust project, check for:
 
 ## Example: Project-Level Override
 
-Create `.claude/references/stack-decisions.md` in your project root:
+Create `.feature-forge/stack-decisions.md` (legacy alias: `.claude/references/stack-decisions.md`) in your project root:
 
 ```markdown
 # Stack Decisions

package/adapters/claude/references/stacks/typescript.md

@@ -85,7 +85,7 @@ When examining a TypeScript project, check for:
 
 ## Example: Project-Level Override
 
-Create `.claude/references/stack-decisions.md` in your project root:
+Create `.feature-forge/stack-decisions.md` (legacy alias: `.claude/references/stack-decisions.md`) in your project root:
 
 ```markdown
 # Stack Decisions

package/adapters/claude/references/templates/specs-hygiene/AGENTS.md

@@ -0,0 +1,23 @@
+# Agent Instructions — `specs/` (feature-forge)
+
+This directory holds **pre-implementation design artifacts** produced by the
+feature-forge pipeline (PRDs, technical specs, numbered implementation specs,
+traceability matrices, and per-feature `backlog.json` files).
+
+## How to treat these specs
+
+- **Specs are not live contracts.** They exist to plan the work and establish the
+  backlog. They are intentionally **not kept in sync** with the implementation as
+  the code evolves.
+- **Do not flag spec↔code divergence.** Once a spec is finalized and its backlog has
+  been implemented, the code is the source of truth for behavior. Do not "fix" the
+  implementation to match a spec, or the spec to match the code, unless a human
+  explicitly asks for it.
+- **Read freely; reference deliberately.** It is fine — encouraged, even — for
+  pipeline artifacts here (specs, `backlog.json`) to cite each other for provenance
+  and context. But implementation artifacts shipped into the project (source code,
+  generated skills/agents, configs, docs) should be self-contained and should **not**
+  reference files under `specs/`, which may be archived or deleted after a feature
+  ships.
+
+This file was generated by feature-forge. Edit or remove it to suit your project.

package/adapters/claude/references/templates/specs-hygiene/CLAUDE.md

@@ -0,0 +1,22 @@
+# Claude Instructions — `specs/` (feature-forge)
+
+This directory holds **pre-implementation design artifacts** produced by the
+feature-forge pipeline (PRDs, technical specs, numbered implementation specs,
+traceability matrices, and per-feature `backlog.json` files).
+
+## How to treat these specs
+
+- **Specs are not live contracts.** They exist to plan the work and establish the
+  backlog. They are intentionally **not kept in sync** with the implementation as
+  the code evolves.
+- **Do not flag spec↔code divergence.** Once a spec is finalized and its backlog has
+  been implemented, the code is the source of truth for behavior. Don't "fix" the
+  implementation to match a spec, or the spec to match the code, unless I explicitly
+  ask you to.
+- **Read freely; reference deliberately.** It's fine — encouraged, even — for pipeline
+  artifacts here (specs, `backlog.json`) to cite each other for provenance and context.
+  But implementation artifacts shipped into the project (source code, generated
+  skills/agents, configs, docs) should be self-contained and should **not** reference
+  files under `specs/`, which may be archived or deleted after a feature ships.
+
+This file was generated by feature-forge. Edit or remove it to suit your project.