@garygentry/feature-forge 0.1.5 → 0.2.0

package/adapters/claude/scripts/forge-init.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Initialize feature-forge configuration in the current project.
+# Creates forge.config.json with sensible defaults.
+
+set -euo pipefail
+
+CONFIG_FILE="forge.config.json"
+
+if [ -f "$CONFIG_FILE" ]; then
+  echo "⚠️  $CONFIG_FILE already exists. Skipping."
+  exit 0
+fi
+
+cat > "$CONFIG_FILE" << 'EOF'
+{
+  "specsDir": "./specs",
+  "docsDir": "./docs/architecture",
+  "backlogDir": null,
+  "gitCommitAfterStage": true,
+  "commitPrefix": "forge",
+  "stack": null,
+  "typeCheckCommand": null,
+  "testCommand": null,
+  "loopIterationMultiplier": 1.5
+}
+EOF
+
+echo "✅ Created $CONFIG_FILE with defaults."
+echo ""
+echo "Defaults:"
+echo "  specsDir:            ./specs"
+echo "  docsDir:             ./docs/architecture"
+echo "  backlogDir:          null (defaults to {specsDir}/{feature}/backlog.json)"
+echo "  gitCommitAfterStage: true"
+echo "  commitPrefix:        forge"
+echo "  stack:               null (auto-detected during forge-2-tech)"
+echo "  typeCheckCommand:    null (auto-detected during forge-2-tech)"
+echo "  testCommand:         null (auto-detected during forge-2-tech)"
+echo "  loopIterationMultiplier: 1.5 (multiplier for loop iterations)"
+echo ""
+echo "The loop runner defaults to rauf. To target a different ralph-style runner,"
+echo "add a \"loopRunner\" block (see references/forge-config-schema.json)."
+echo ""
+echo "Edit $CONFIG_FILE to customize paths and stack settings for your project."

package/adapters/claude/scripts/forge-root.sh

@@ -13,13 +13,17 @@
 set -euo pipefail
 
 # Sentinel predicate (00-core-definitions.md §2 / SENTINEL_FILES). A directory is a valid
-# plugin root iff BOTH sentinel files exist. Content-based, so it identifies a feature-forge
-# install under ANY agent's directory layout.
+# feature-forge root iff it carries the neutral bundle sentinel `.feature-forge-bundle.json`
+# (emitted into EVERY per-agent adapter bundle) OR the legacy Claude plugin manifest
+# `.claude-plugin/plugin.json` (the canon repo root + the Claude bundle). Content-based, so it
+# identifies a feature-forge install under ANY agent's directory layout — not just Claude's.
 is_root() {  # $1 = candidate dir
-  [ -f "$1/scripts/epic-manifest.py" ] && [ -f "$1/.claude-plugin/plugin.json" ]
+  [ -f "$1/.feature-forge-bundle.json" ] || [ -f "$1/.claude-plugin/plugin.json" ]
 }
 
-# ── Step 1: self-location — parent of this script's dir is the plugin root. ──────────────
+# ── Step 1: self-location — parent of this script's dir is the install root. ─────────────
+# This is the PRIMARY path: a bundle ships its own scripts/forge-root.sh, so the parent of
+# this script's dir is that bundle's root under any agent's layout.
 self_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
 root="$(cd -- "$self_dir/.." && pwd -P)"
 if is_root "$root"; then
@@ -27,11 +31,23 @@ if is_root "$root"; then
   exit 0
 fi
 
-# ── Step 2: candidate-root probe (authoritative multi-root list; extend here first). ─────
-# Globs that match nothing expand to themselves; the is_root test rejects such literals.
+# ── Step 2: candidate-root probe (authoritative multi-agent root list; extend here first). ─
+# Globs that match nothing expand to themselves; the is_root test rejects such literals. Covers
+# every supported agent's install destination under BOTH global ($HOME) and project ($PWD) scope,
+# matching the installer's per-agent layout: claude .claude/skills, codex .agents/skills, copilot
+# .github/feature-forge, cursor .cursor/rules, gemini .gemini/extensions.
 for candidate in \
   "$HOME/.claude/skills/feature-forge" \
+  "$PWD/.claude/skills/feature-forge" \
   "$HOME"/.claude/plugins/*/feature-forge \
+  "$HOME/.agents/skills/feature-forge" \
+  "$PWD/.agents/skills/feature-forge" \
+  "$HOME/.github/feature-forge" \
+  "$PWD/.github/feature-forge" \
+  "$HOME/.cursor/rules/feature-forge" \
+  "$PWD/.cursor/rules/feature-forge" \
+  "$HOME/.gemini/extensions/feature-forge" \
+  "$PWD/.gemini/extensions/feature-forge" \
 ; do
   if is_root "$candidate"; then
     printf '%s\n' "$candidate"
@@ -39,12 +55,18 @@ for candidate in \
   fi
 done
 
-# ── Step 3: env fallback — the SINGLE sanctioned residual ${CLAUDE_PLUGIN_ROOT} (C-4). ───
+# ── Step 3: env fallback — neutral FEATURE_FORGE_ROOT, then the legacy CLAUDE_PLUGIN_ROOT. ─
+# The neutral override works for every agent; CLAUDE_PLUGIN_ROOT is kept only for backwards
+# compatibility with existing Claude installs (C-4).
+if [ -n "${FEATURE_FORGE_ROOT:-}" ] && is_root "$FEATURE_FORGE_ROOT"; then
+  printf '%s\n' "$FEATURE_FORGE_ROOT"
+  exit 0
+fi
 if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && is_root "$CLAUDE_PLUGIN_ROOT"; then
   printf '%s\n' "$CLAUDE_PLUGIN_ROOT"
   exit 0
 fi
 
 # ── Step 4: failure — actionable message to stderr, exit 1 (REQ-RES-04). ─────────────────
-echo "feature-forge: cannot locate plugin root. Set CLAUDE_PLUGIN_ROOT or run from an installed skill dir." >&2
+echo "feature-forge: cannot locate install root. Set FEATURE_FORGE_ROOT to the bundle dir, or run from an installed skill dir." >&2
 exit 1

package/adapters/claude/scripts/validate-traceability.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Validate requirement traceability between PRD and implementation specs.
+
+Extracts REQ-XXX-NN identifiers from a PRD file and checks that every
+requirement is referenced in at least one implementation spec document.
+Also reports orphaned references (IDs found in specs but not in PRD).
+
+Usage:
+    python validate-traceability.py <prd-path> <specs-dir> [--json]
+
+Exit codes:
+    0 = all requirements covered, no orphans
+    1 = gaps or orphans found
+    2 = file not found or read error
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+REQ_PATTERN = re.compile(r"REQ-[A-Z]+-\d+")
+
+
+def extract_req_ids(text: str) -> set[str]:
+    """Extract all unique REQ-XXX-NN identifiers from text."""
+    return set(REQ_PATTERN.findall(text))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate requirement traceability between PRD and specs"
+    )
+    parser.add_argument("prd_path", help="Path to PRD.md file")
+    parser.add_argument("specs_dir", help="Directory containing ##-*.md spec files")
+    parser.add_argument(
+        "--json", action="store_true", dest="json_output", help="Output as JSON"
+    )
+    args = parser.parse_args()
+
+    prd_path = Path(args.prd_path)
+    specs_dir = Path(args.specs_dir)
+
+    # Read PRD
+    if not prd_path.exists():
+        print(f"Error: PRD file not found: {prd_path}", file=sys.stderr)
+        return 2
+
+    try:
+        prd_text = prd_path.read_text()
+    except OSError as e:
+        print(f"Error reading PRD: {e}", file=sys.stderr)
+        return 2
+
+    prd_reqs = extract_req_ids(prd_text)
+
+    if not prd_reqs:
+        print(f"Warning: No REQ-XXX-NN identifiers found in {prd_path}", file=sys.stderr)
+
+    # Read spec files (##-*.md pattern)
+    if not specs_dir.exists():
+        print(f"Error: Specs directory not found: {specs_dir}", file=sys.stderr)
+        return 2
+
+    spec_files = sorted(specs_dir.glob("[0-9][0-9]-*.md"))
+    if not spec_files:
+        print(f"Warning: No spec files matching ##-*.md found in {specs_dir}", file=sys.stderr)
+
+    # Track which specs cover which requirements
+    spec_reqs: dict[str, set[str]] = {}
+    all_spec_reqs: set[str] = set()
+
+    for spec_file in spec_files:
+        try:
+            text = spec_file.read_text()
+            reqs = extract_req_ids(text)
+            spec_reqs[spec_file.name] = reqs
+            all_spec_reqs |= reqs
+        except OSError as e:
+            print(f"Warning: Could not read {spec_file}: {e}", file=sys.stderr)
+
+    # Also check TRACEABILITY.md if it exists
+    traceability_file = specs_dir / "TRACEABILITY.md"
+    if traceability_file.exists():
+        try:
+            text = traceability_file.read_text()
+            trace_reqs = extract_req_ids(text)
+            spec_reqs["TRACEABILITY.md"] = trace_reqs
+            all_spec_reqs |= trace_reqs
+        except OSError:
+            pass
+
+    # Analysis
+    uncovered = sorted(prd_reqs - all_spec_reqs)
+    orphaned = sorted(all_spec_reqs - prd_reqs)
+
+    # Per-requirement coverage map
+    coverage: dict[str, list[str]] = {}
+    for req_id in sorted(prd_reqs):
+        covering_specs = [
+            name for name, reqs in spec_reqs.items() if req_id in reqs
+        ]
+        coverage[req_id] = covering_specs
+
+    has_issues = bool(uncovered or orphaned)
+
+    if args.json_output:
+        result = {
+            "prd_file": str(prd_path),
+            "specs_dir": str(specs_dir),
+            "total_requirements": len(prd_reqs),
+            "total_spec_files": len(spec_files),
+            "uncovered_requirements": uncovered,
+            "orphaned_references": orphaned,
+            "coverage": coverage,
+            "valid": not has_issues,
+        }
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"PRD: {prd_path} ({len(prd_reqs)} requirements)")
+        print(f"Specs: {specs_dir} ({len(spec_files)} spec files)")
+        print()
+
+        if uncovered:
+            print(f"UNCOVERED REQUIREMENTS ({len(uncovered)}):")
+            for req_id in uncovered:
+                print(f"  - {req_id}: not found in any spec file")
+            print()
+
+        if orphaned:
+            print(f"ORPHANED REFERENCES ({len(orphaned)}):")
+            for req_id in orphaned:
+                sources = [
+                    name for name, reqs in spec_reqs.items() if req_id in reqs
+                ]
+                print(f"  - {req_id}: found in {', '.join(sources)} but not in PRD")
+            print()
+
+        if not has_issues:
+            print("All requirements covered. No orphaned references.")
+        else:
+            total_issues = len(uncovered) + len(orphaned)
+            print(f"Found {total_issues} issue(s).")
+
+    return 1 if has_issues else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -29,7 +29,7 @@ For pipeline architecture details, read `references/process-overview.md`.
 
 1. **Epics first.** Identify epic directories as any `{specsDir}/*/` that directly contains an `epic-manifest.json` **and no `.pipeline-state.json` of its own** (an epic root is never itself a feature). For each epic, 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
    ```
@@ -83,7 +83,7 @@ Use these status indicators:
 When the named argument is an epic (`{specsDir}/{name}/epic-manifest.json` exists), render the epic dashboard instead of a per-feature one. 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
 ```
@@ -142,18 +142,18 @@ Commands:
 Support these sub-commands for pipeline lifecycle management:
 - `/feature-forge:forge pause {feature}` — Set `pipelineStatus` to `"paused"`. Do NOT modify `currentStage` or any stage statuses. The pipeline freezes exactly as-is. Show a confirmation.
 - `/feature-forge:forge resume {feature}` — Set `pipelineStatus` back to `"active"`. Calculate how long the feature was paused (from `updatedAt` to now). If paused for more than 24 hours, show a hint: "This feature was paused for {duration}. Session context may have been lost — consider re-running `/feature-forge:forge-{currentStage} {feature}` to rebuild context."
-- `/feature-forge:forge abandon {feature}` — Set `pipelineStatus` to `"abandoned"`. Use `AskUserQuestion` to confirm with user first. Note: abandoned pipelines can be resumed with `/feature-forge:forge resume {feature}` if the user changes their mind.
+- `/feature-forge:forge abandon {feature}` — Set `pipelineStatus` to `"abandoned"`. Use `AskUserQuestion` to confirm first, and state what's reversible: abandoning does not delete artifacts and can be undone with `/feature-forge:forge resume {feature}`, so the cost is low — but if the user really means "stop and discard," point out that `pause` is the better choice when they're only setting it aside. Offer **Abandon** · **Pause instead** · **Cancel**.
 
 **Epic lifecycle.** When the argument names an **epic** (`{specsDir}/{name}/epic-manifest.json` exists), `pause` / `resume` / `abandon` operate on the epic manifest, not a `.pipeline-state.json`:
 
 - Set the manifest's top-level `status` (`paused` / `active` / `abandoned`) via the helper's `set-status` mutator — an atomic write that also bumps `updatedAt`:
   ```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" set-status "{epic}" --status paused --specs-dir "{specsDir}"
   ```
   For `complete`, do **not** set the status directly — completion is *derived* from member states (the rollup), so the manifest `status` is a lifecycle flag, never a completion signal.
-- **Member feature states are NOT silently mutated.** Pausing/abandoning the epic changes only the manifest `status`. Before doing so, use `AskUserQuestion` to make the relationship explicit: "Pausing the epic does not pause its in-flight member features. {N} members are active. Pause the epic only, or also pause each member?" If the user opts to pause members too, update each member's own `pipelineStatus` **individually and visibly** (one explicit action per member), never as a hidden side-effect.
+- **Member feature states are NOT silently mutated.** Pausing/abandoning the epic changes only the manifest `status`. Before doing so, use `AskUserQuestion` to make the relationship explicit and frame the trade-off: "Pausing the epic does not pause its in-flight member features. {N} members are active. Pause the epic only, or also pause each member?" Recommend **epic only** when members are mid-stage and the user just wants to stop *new* orchestration; recommend **also pause members** when the intent is a hard freeze of all in-flight work. If the user opts to pause members too, update each member's own `pipelineStatus` **individually and visibly** (one explicit action per member), never as a hidden side-effect.
 - Commit the change via the Git Commit Protocol, staging `{specsDir}/{epic}/`.
 
 When listing features, show active pipelines by default. Include a count of paused/abandoned: "3 active pipelines (1 paused, 1 abandoned — use `/feature-forge:forge list all` to see them)."

package/adapters/claude/skills/forge-0-epic/SKILL.md

@@ -39,7 +39,7 @@ checks but still load any on-disk artifacts.
 plugin path and the configured specs dir:
 
 ```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" <subcommand> ... --specs-dir "{specsDir}"
 ```
@@ -73,7 +73,7 @@ Resolve the epic subtree path `{specsDir}/{epic}/` and decide which branch to ru
    epic, confirm the epic name itself does not collide with any existing feature or epic:
 
    ```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" check-name "{epic}" --specs-dir "{specsDir}"
    ```
@@ -111,15 +111,13 @@ The epic `name` is the validated CLI argument from Step 0 — do NOT prompt for
 Drive a decomposition dialogue. Output your analysis as text first (how the goal might split,
 right-sizing guidance: each feature should be a single pipeline-sized unit — a unit forge-1-prd
 through forge-5-loop would carry end-to-end — not item-level interleaving). Then use
-`AskUserQuestion` to elicit the candidate feature list. Probe with questions like "Is any of
-these two features really one?" and "Is any one of these really two?" Iterate until the user
-confirms the set.
+`AskUserQuestion` to elicit the candidate feature list. Per the **Decision Support** protocol in `references/shared-conventions.md`, lead with a **recommended decomposition** and a one-line rationale rather than asking the user to invent it unaided, then probe its seams ("Is any of these two really one? Is any one really two?"), naming the trade-off (more features = more parallelism but more edges). Iterate until the user confirms.
 
 For **each** proposed feature name, before accepting it into the set, enforce global uniqueness
 and name safety 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" check-name "{feature}" --specs-dir "{specsDir}"
 ```
@@ -155,9 +153,7 @@ the structured arrays are the source of truth; EPIC.md renders them as prose lat
 For each feature, use `AskUserQuestion`: "Which sibling features must be complete before this
 one can build?" → populates `dependsOn: [names]`.
 
-**Seed the suggestion from `consumes`:** a `consumes.from` X strongly implies `dependsOn` X.
-Offer the union of each feature's `consumes.from` set as the default, but let the user confirm —
-`dependsOn` is the authoritative edge set.
+**Seed the suggestion from `consumes`:** a `consumes.from` X strongly implies `dependsOn` X. Per the **Decision Support** protocol, offer the union of each feature's `consumes.from` set as the **recommended default**, evidence-backed — but flag the cost (each edge serializes the loop and blocks dependents, so add only what contracts require). User confirms/overrides; `dependsOn` is authoritative.
 
 The `features[]` array order is the user-declared sequence from C2 (order is a presentation
 sequence, **not** a dependency ordering). Preserve the C2 order unless the user asks to reorder.
@@ -181,7 +177,7 @@ For the *initial* creation write the skill writes the file directly — atomic g
 required for in-place mutation, which is the helper mutators' job. Creating the epic dir first creates `{specsDir}/`, so after writing the manifest invoke the **Specs Directory Hygiene** block in `references/shared-conventions.md` (idempotent; stage anything it writes with this stage's commit). Then validate:
 
 ```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/claude/skills/forge-0-epic/references/edit-mode.md

@@ -16,7 +16,7 @@ question goes through `AskUserQuestion`.
 Before offering any edit, validate the existing manifest:
 
 ```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
 ```
@@ -77,7 +77,7 @@ status is **not** `not-started`, warn the user. Read the **live** status (never
 completion in prose):
 
 ```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
 ```

package/adapters/claude/skills/forge-0-epic/references/epic-manifest-subcommands.md

@@ -12,7 +12,7 @@ the write if it would introduce a cycle, dangling ref, duplicate, or schema viol
 flag surface (owned by 02 §7):
 
 ```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; }
 # Add a feature — seeds EMPTY exposes/consumes; contracts are populated below.
 python3 "$R/scripts/epic-manifest.py" add-feature "{epic}" "{feature}" \

package/adapters/claude/skills/forge-1-prd/SKILL.md

@@ -65,12 +65,12 @@ A technology constraint is valid when it stems from organizational mandate, exis
 
 **Pacing:** Cover one topic area at a time, asking 2-3 related questions per `AskUserQuestion` call. After receiving answers, probe deeper on anything incomplete before moving to the next topic. Signal progress in your text before the next question batch.
 
-**Question strategies** (use these as content for `AskUserQuestion`, not as inline prose):
+**Question strategies** (use these as content for `AskUserQuestion`, not as inline prose). The PRD stays at the requirements level (the *what*, not the *how* — that's forge-2-tech), so most questions are open elicitation. But whenever you offer the user a *choice* (scope boundary, MVP cut, a non-functional target), apply the **Decision Support** protocol in `references/shared-conventions.md`: propose a sensible default with its trade-off rather than an empty menu — e.g. "I'd scope V1 to X and defer Y; that ships sooner but means Y waits. Agree?":
 - Probe deeper after each answer: failure modes, stakeholders, minimum viable version
 - Challenge assumptions: which users specifically, what does "fast" mean quantitatively
 - Identify edge cases: empty input, concurrent access, scale
 - Capture non-functional requirements: performance, security, accessibility, observability
-- Ask about what's OUT of scope — as important as what's in scope
+- Ask about what's OUT of scope — as important as what's in scope; when proposing a scope line, recommend one and name what each side gives up
 
 **Completion criteria:** The interview is complete when:
 1. Every category in `references/prd-template.md` has been covered with at least one question

package/adapters/claude/skills/forge-2-tech/SKILL.md

@@ -56,7 +56,7 @@ If the `forge-researcher` subagent is not available, perform the research inline
 ### Manual Research (fallback)
 
 1. **Read the PRD thoroughly**: Understand all requirements and constraints
-2. **Check for project-level stack decisions**: Look for `.claude/references/stack-decisions.md` in the project root. If present, read it — these are established technology choices that should be respected unless there's a strong reason to deviate.
+2. **Check for project-level stack decisions**: Look for a project stack-decisions file, first existing path wins: `.feature-forge/stack-decisions.md` (preferred), then `.agents/references/stack-decisions.md`, then `.claude/references/stack-decisions.md` (legacy alias). If present, read it — these are established technology choices that should be respected unless there's a strong reason to deviate.
 3. **Read the plugin's default stack reference**: Read `references/stack-discovery-checklist.md` for general stack context (only if no project-level override exists)
 4. **Examine the existing codebase**: Look at `package.json` files, existing packages, directory structure, and established patterns. Understand what conventions are already in place.
 5. **Review other features' tech specs**: Check `{specsDir}/*/tech-spec.md` and `{specsDir}/*/*/tech-spec.md` (depth-2, to find nested epic members) for consistency in approach and to identify shared infrastructure. Apply the **feature-shaped-dir bound**: only treat a directory as a feature if it directly contains a `.pipeline-state.json` (filter matches whose parent directory holds one, or enumerate members via the helper). A flat-only tree has no depth-2 feature dirs, so this gains no new matches there (REQ-COMPAT-01).
@@ -69,7 +69,7 @@ After researching the codebase, identify the primary stack (language, build tool
 1. Check if `forge.config.json` already has a `stack` field — if so, use it
 2. Otherwise, detect from project files and use `AskUserQuestion` to confirm: "I detected this as a {stack} project. Correct?"
 3. Update `forge.config.json` with `stack`, `typeCheckCommand`, and `testCommand`
-4. Verify that a matching stack profile exists at `references/stacks/{stack}.md`. If it does, load it for stack-specific guidance during this and all subsequent stages. If no profile exists, inform the user: "No dedicated profile for {stack}. Using generic fallback — spec conventions, verification checks, and examples will be language-neutral. Consider creating a project-level override at `.claude/references/stack-decisions.md`." Then load `references/stacks/_generic.md`.
+4. Verify that a matching stack profile exists at `references/stacks/{stack}.md`. If it does, load it for stack-specific guidance during this and all subsequent stages. If no profile exists, inform the user: "No dedicated profile for {stack}. Using generic fallback — spec conventions, verification checks, and examples will be language-neutral. Consider creating a project-level override at `.feature-forge/stack-decisions.md`." Then load `references/stacks/_generic.md`.
 
 ## Step 3: Conduct the Interview
 
@@ -83,11 +83,12 @@ Interview the user about technology decisions. Unlike the PRD interview, here yo
 
 **First message pattern:** Output the research summary as text, then use `AskUserQuestion` to confirm the stack and ask about the first decision area (typically package/module structure). Wait for the user to respond before proceeding to subsequent areas.
 
-**Question strategies** (use these as content for `AskUserQuestion`, not as inline prose):
-- For each PRD requirement, propose a technical approach and ask for confirmation or alternatives
-- Proactively suggest approaches consistent with the established stack
-- Challenge over-engineering: does the feature need this, or is a simpler approach sufficient?
-- Ask about every integration point and how the feature interacts with existing modules
+**Question strategies** (use these as content for `AskUserQuestion`, not as inline prose). Follow the **Decision Support** protocol in `references/shared-conventions.md` — this interview is the richest decision surface in the pipeline, so don't just list options; lead with a recommended approach, put the trade-off in each option's description, and give a one-line rationale:
+- For each PRD requirement, propose a technical approach **with its trade-off and your recommendation**, then ask for confirmation or alternatives — don't present competing approaches flatly. You've just researched the codebase; spend that research here.
+- Recommend approaches consistent with the established stack, and say *why* the convention favors it (evidence-backed mode). Where the choice is genuine taste (e.g. folder layout, naming), give a default but flag it as preference.
+- Challenge over-engineering: does the feature need this, or is a simpler approach sufficient? Frame the simpler option's trade-off (less flexibility now vs. less to maintain).
+- Ask about every integration point and how the feature interacts with existing modules.
+- For competing module structures or code-shape choices, use the `AskUserQuestion` `preview` field to show the candidates side-by-side.
 
 **Parking lot:** If the user raises a concern that belongs to a different pipeline stage (e.g., backlog granularity, documentation format), acknowledge it and note it in the pipeline state's `notes` field: "Good point — I've noted that for the [specs/backlog/docs stage]. Let's continue with the tech spec."
 

package/adapters/claude/skills/forge-2-tech/references/stack-discovery-checklist.md

@@ -1,16 +1,16 @@
 # Stack Discovery Checklist (Plugin Default)
 
-This file contains a default stack discovery protocol for the feature-forge plugin. Projects can override this by placing a `stack-decisions.md` in `.claude/references/` at the project root.
+This file contains a default stack discovery protocol for the feature-forge plugin. Projects can override this by placing a `stack-decisions.md` at `.feature-forge/stack-decisions.md` (preferred; legacy alias `.claude/references/stack-decisions.md`) in the project root.
 
 ## Note to Agent
 
-This is a DISCOVERY PROTOCOL — it helps you identify what stack the project uses. It is NOT a set of decisions. Always check `.claude/references/stack-decisions.md` first — if present, it takes precedence.
+This is a DISCOVERY PROTOCOL — it helps you identify what stack the project uses. It is NOT a set of decisions. Always check for a project stack-decisions file first (`.feature-forge/stack-decisions.md`, then `.agents/references/stack-decisions.md`, then the legacy `.claude/references/stack-decisions.md`) — if present, it takes precedence.
 
 After discovering the stack, check if `references/stacks/{stack}.md` exists in the plugin for stack-specific guidance. See `references/stack-resolution.md` for the full resolution protocol.
 
 ## Purpose
 
-This is a default discovery guide for understanding a project's technology stack. Projects should create `.claude/references/stack-decisions.md` with their actual stack decisions, which takes precedence over this checklist.
+This is a default discovery guide for understanding a project's technology stack. Projects should create `.feature-forge/stack-decisions.md` (legacy alias: `.claude/references/stack-decisions.md`) with their actual stack decisions, which takes precedence over this checklist.
 
 ## Stack Discovery Protocol
 
@@ -68,7 +68,7 @@ Examine the dependency manifest for:
 
 ## How to Create a Project-Level Override
 
-Create `.claude/references/stack-decisions.md` in your project root with your specific stack decisions. See `references/stacks/typescript.md` or `references/stacks/python.md` for stack-specific examples of what to include.
+Create `.feature-forge/stack-decisions.md` (legacy alias: `.claude/references/stack-decisions.md`) in your project root with your specific stack decisions. See `references/stacks/typescript.md` or `references/stacks/python.md` for stack-specific examples of what to include.
 
 ```markdown
 # Stack Decisions

package/adapters/claude/skills/forge-3-specs/SKILL.md

@@ -54,7 +54,7 @@ Feature-specific:
   04-integration-points.md    — Integration with existing project modules
 ```
 
-**Then call `AskUserQuestion`** with: "Does this look right? Should I add or remove any documents?"
+**Then call `AskUserQuestion`** following the **Decision Support** protocol in `references/shared-conventions.md`: recommend this plan as the default (it's your evidence-backed read of the feature's complexity) and name the trade-off so the user can push back knowingly — more documents means finer separation of concerns but more to keep in sync; fewer means tighter docs but risks one document carrying multiple concerns. Lead with: "I recommend this plan. Add or remove any documents?" Note the guidance below — resist splitting a concern into a sub-50-line document.
 
 **Incremental artifact tracking:** After each spec document is written (by you or a writer subagent), immediately update the `artifacts` array in `.pipeline-state.json` with the new file path. This enables crash recovery if the session is interrupted mid-suite (see shared-conventions.md "Crash Recovery").
 

package/adapters/claude/skills/forge-4-backlog/SKILL.md

@@ -39,7 +39,7 @@ Resolve the **loop runner** from the `loopRunner` block in `forge.config.json`,
 
 **Prerequisite check:** Read `{resolvedFeatureDir}/.pipeline-state.json`. If not in force mode, stages `forge-1-prd`, `forge-2-tech`, and `forge-3-specs` must all be `complete`. If not, STOP and tell the user which prerequisites are missing.
 
-**Strongly recommended:** Check if specs have been verified. If not, use `AskUserQuestion` to warn: "Specs haven't been verified yet. It's recommended to run `/feature-forge:forge-verify {feature}` first. Continue anyway?"
+**Strongly recommended:** Check if specs have been verified. If not, use `AskUserQuestion` to warn with the cost of skipping: "Specs haven't been verified yet. Recommended: run `/feature-forge:forge-verify {feature}` first — unverified specs can carry gaps or contradictions that get baked into backlog items and only surface mid-loop, where they're far more expensive to fix. Continue anyway?" Offer **Verify first (recommended)** · **Continue without verifying**.
 
 ## Step 2: Load All Specs
 
@@ -68,7 +68,7 @@ Proposed backlog for {feature} ({N} items):
   ...
 ```
 
-After presenting the plan as text, use `AskUserQuestion` to ask: "Does this breakdown look right? Any items to split, merge, or reorder?" Do NOT include this question in your text output. Wait for the user's response before generating the JSON.
+After presenting the plan as text, use `AskUserQuestion` following the **Decision Support** protocol in `references/shared-conventions.md`: recommend this breakdown as the default (it's your evidence-backed read of the specs and dependency order) and name the trade-off that governs item granularity — finer items are each easier to verify in one loop iteration but multiply coordination and dependency edges; coarser items mean fewer handoffs but risk an item too big to complete or verify in a single iteration. Lead with: "I recommend this breakdown. Any items to split, merge, or reorder?" Do NOT include this question in your text output. Wait for the user's response before generating the JSON.
 
 ## Step 4: Author backlog.json — delegate to `author-backlog`
 

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

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

@@ -37,14 +37,14 @@ Also check `.pipeline-state.json` for `stages.forge-5-loop`. If it exists and ha
 
 ### Impl-Verify Backstop
 
-Check `.pipeline-state.json` for `stages.forge-verify-impl`. If it is **absent** or has status `"skipped"`, use `AskUserQuestion` to warn: "Implementation hasn't been verified yet. It's recommended to run `/feature-forge:forge-verify {feature} impl` first to audit the loop's output. 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.
+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
 ```

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

@@ -59,7 +59,7 @@ Every bash invocation begins with the byte-identical portable-root prelude, then
 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; 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/forge-bootstrap.py" check "<target-dir>" --json --specs-dir ./specs
 ```
@@ -136,7 +136,7 @@ when running under a Claude host (e.g. `AskUserQuestion` is available), else `"c
 `CLAUDE.md` only when `host == "claude"`.
 
 ```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/forge-bootstrap.py" scaffold "<target-dir>" --json --answers '<Answers JSON>'
 ```
@@ -144,7 +144,7 @@ python3 "$R/scripts/forge-bootstrap.py" scaffold "<target-dir>" --json --answers
 ### Step 5 — verify
 
 ```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/forge-bootstrap.py" verify "<target-dir>" --json --answers '<Answers JSON>'
 ```
@@ -170,7 +170,7 @@ and removes the sentinel before staging so it never enters history. Read
 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; 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/forge-bootstrap.py" commit "<target-dir>" --json --answers '<Answers JSON>' [--stage-only]
 ```

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

@@ -30,7 +30,7 @@ Read and follow `references/shared-conventions.md` for feature name validation,
 ## Step 3: Handle User Decisions
 
 If the "User Decisions Required" section has unresolved items:
-1. Present each decision to the user with the context from the findings, using `AskUserQuestion` for each decision point. Only recommend a specific option if the findings provide clear evidence for it; otherwise present options neutrally.
+1. Present each decision to the user with the context from the findings, using `AskUserQuestion` for each decision point. Follow the **Decision Support** protocol in `references/shared-conventions.md`: lead with a recommended option and put the trade-off in each option's description. When the findings provide clear evidence, recommend with confidence and cite it. When they don't, still offer a sensible default with the trade-offs, but flag it plainly as a judgment call rather than going neutral — a defaulted recommendation beats an unguided option dump.
 2. Wait for answers before proceeding
 3. Record decisions in the findings document under the "User Decisions Required" section (mark each as resolved)
 

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

@@ -9,7 +9,7 @@ description: Initialize feature-forge configuration in the current project. Use
 Run the initialization script to create `forge.config.json` with default settings:
 
 ```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; }
 bash "$R/scripts/forge-init.sh"
 ```