@garygentry/feature-forge 0.1.5 → 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:

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) |

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/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

@@ -98,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
 
@@ -58,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>")
@@ -88,7 +105,7 @@ Whenever a stage creates the specs tree for the first time (the first PRD or epi
 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; 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; }
 mkdir -p "<specsDir>"
 [ -f "<specsDir>/AGENTS.md" ] || cp "$R/references/templates/specs-hygiene/AGENTS.md" "<specsDir>/AGENTS.md"
@@ -115,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
@@ -133,6 +150,8 @@ 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.
@@ -185,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