@garygentry/feature-forge 0.1.5 → 0.2.0

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

@@ -176,7 +176,12 @@ When building the Fix Execution Plan:
 **If not in plan mode:** Output the following as text:
 "Findings and fix plan written to `{findings-file}`."
 
-Then use `AskUserQuestion` to ask: "Would you like to: (a) Review the findings first, (b) Run `/feature-forge:forge-fix {feature}` to apply fixes now, or (c) Enter plan mode and re-run `/feature-forge:forge-verify {feature}` for plan-mode workflow?" Do NOT embed this question in your text output.
+Then use `AskUserQuestion` to ask how to proceed. Follow the **Decision Support** protocol in `references/shared-conventions.md`: recommend a path based on the findings and give each option a one-line trade-off. Let the severity and volume of findings drive the recommendation — e.g. recommend (b) **Apply fixes now** when findings are clear-cut and mechanical; recommend (a) **Review first** when findings involve design judgment or you flagged low-confidence items; recommend (c) **plan-mode workflow** when the fixes are large or interdependent enough to warrant a reviewed plan. Present:
+- **(a) Review the findings first** — read `{findings-file}` and decide per-finding; safest, but you act on nothing until you return.
+- **(b) Run `/feature-forge:forge-fix {feature}` now** — applies the fix plan immediately; fastest, best when findings are unambiguous.
+- **(c) Enter plan mode and re-run `/feature-forge:forge-verify {feature}`** — produces a reviewable plan before any edits; best for large or risky fix sets.
+
+Do NOT embed this question in your text output.
 
 ## Step 6: Update Pipeline State
 
@@ -213,7 +218,7 @@ Do NOT mark as `findings-applied` — that happens after the fix pass.
 - For specs verification, also run the deterministic traceability validator to supplement agent-driven traceability checks. Include any uncovered requirements or orphaned references as findings:
 
 ```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/validate-traceability.py" {specsDir}/{feature}/PRD.md {specsDir}/{feature}/ --json
 ```

package/adapters/claude/skills/forge-verify/references/verification-checklists.md

@@ -192,7 +192,7 @@ findings to E01/E02/E03/E08. Then perform the judgment checks E04–E07 by readi
 manifest, EPIC.md, and completed members' specs.
 
 ```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" validate "{epic}" --specs-dir "{specsDir}" --json
 ```

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

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

package/adapters/codex/agents/{forge-researcher.md → forge-researcher.toml}

@@ -1,8 +1,7 @@
----
 # GENERATED — DO NOT EDIT. Source: agents/forge-researcher.md. Regenerate: python3 scripts/build-adapters.py
-name: forge-researcher
-description: Explores the codebase to understand package structure, integration points, existing patterns, and conventions. Use during feature planning, especially when running /feature-forge:forge-2-tech. Returns a distilled integration report without polluting the main conversation's context window.
----
+name = "forge-researcher"
+description = "Explores the codebase to understand package structure, integration points, existing patterns, and conventions. Use during feature planning, especially when running /feature-forge:forge-2-tech. Returns a distilled integration report without polluting the main conversation's context window."
+developer_instructions = """
 
 You are a codebase research agent for the feature-forge pipeline. Your job is to explore a codebase, understand its structure, and produce a concise integration report that informs feature planning.
 
@@ -131,3 +130,4 @@ ALL commands not listed above are forbidden. Specifically:
 - Write/append redirects (`>`, `>>`)
 - Package managers with install/add (`pip install`, `npm install`, `bun install`)
 - Any command that creates, modifies, or deletes files
+"""

package/adapters/codex/agents/{forge-spec-writer.md → forge-spec-writer.toml}

@@ -1,8 +1,7 @@
----
 # GENERATED — DO NOT EDIT. Source: agents/forge-spec-writer.md. Regenerate: python3 scripts/build-adapters.py
-name: forge-spec-writer
-description: Authors exactly one numbered implementation spec document for a forge feature, to the quality bar in forge-3-specs. Dispatched by forge-3-specs as one of several parallel writers, after the shared foundation docs (00-core-definitions, 01-architecture-layout) are already written. Writes only its single assigned file and returns a requirement-coverage manifest.
----
+name = "forge-spec-writer"
+description = "Authors exactly one numbered implementation spec document for a forge feature, to the quality bar in forge-3-specs. Dispatched by forge-3-specs as one of several parallel writers, after the shared foundation docs (00-core-definitions, 01-architecture-layout) are already written. Writes only its single assigned file and returns a requirement-coverage manifest."
+developer_instructions = """
 
 You are a specification author for the feature-forge pipeline. You write **exactly one**
 numbered implementation spec document to a high quality bar, then return a short manifest
@@ -110,3 +109,4 @@ ALL commands not listed above are forbidden. Specifically:
 - Write/append redirects (`>`, `>>`) — use the Write tool for your one file
 - Package managers with install/add
 - Any command that creates, modifies, or deletes files other than your single Write
+"""

package/adapters/codex/agents/{forge-verifier.md → forge-verifier.toml}

@@ -1,8 +1,7 @@
----
 # GENERATED — DO NOT EDIT. Source: agents/forge-verifier.md. Regenerate: python3 scripts/build-adapters.py
-name: forge-verifier
-description: Verifies feature forge pipeline artifacts for completeness, consistency, and quality. Delegates to this agent when running /feature-forge:forge-verify or when the user asks to check specs, backlog, or implementation for gaps. This agent has read-only tools and persistent memory — it cannot modify files, only analyze and report findings.
----
+name = "forge-verifier"
+description = "Verifies feature forge pipeline artifacts for completeness, consistency, and quality. Delegates to this agent when running /feature-forge:forge-verify or when the user asks to check specs, backlog, or implementation for gaps. This agent has read-only tools and persistent memory — it cannot modify files, only analyze and report findings."
+developer_instructions = """
 
 You are a meticulous verification agent for the feature-forge development pipeline. Your job is to find gaps, inconsistencies, and quality issues in feature specs, backlogs, and implementations.
 
@@ -113,3 +112,4 @@ ALL commands not listed above are forbidden. Specifically:
 - Write/append redirects (`>`, `>>`)
 - Package managers (`pip install`, `npm install`, `bun install`, `cargo install`)
 - Any command that creates, modifies, or deletes files
+"""

package/adapters/codex/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/codex/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/codex/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/codex/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/codex/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/codex/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/codex/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/codex/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