@garygentry/feature-forge 0.1.4 → 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}"
    ```
@@ -87,11 +87,13 @@ python3 "$R/scripts/epic-manifest.py" check-name "{epic}" --specs-dir "{specsDir
 
 ## Creation Branch
 
-### Step 1 — Branch Setup (optional)
+### Step 1 — Branch Setup
 
-If `gitCommitAfterStage` is true and the project uses git, use `AskUserQuestion`:
-"Create a `forge/{epic}` branch for this epic? (Recommended — keeps epic work isolated.)"
-If yes, create and checkout the branch before proceeding.
+Invoke the **Branch Setup** block in `references/shared-conventions.md` with `{label}` = `{epic}` and
+`{scope}` = `epic`. It self-gates (skips when not a git repo or when `branchPerFeature` is false),
+detects whether you're on the default branch, and strongly recommends — still optionally — creating
+`{branchPrefix}{epic}` when you are. Each member feature's `forge-1-prd` inherits this branch rather
+than prompting again.
 
 ### Step C1 — Epic Framing Interview
 
@@ -109,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}"
 ```
@@ -153,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.
@@ -176,10 +174,10 @@ Compose the full `epic-manifest.json` per the 00 §2 schema, setting:
 
 Write the composed JSON to `{specsDir}/{epic}/epic-manifest.json` (creating the epic dir first).
 For the *initial* creation write the skill writes the file directly — atomic guarantees are only
-required for in-place mutation, which is the helper mutators' job. Then validate:
+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

@@ -16,7 +16,7 @@ Read and follow `references/shared-conventions.md` for feature name validation,
 ## Step 1: Read Configuration and Check State
 
 ### Branch Setup (if using git)
-If `gitCommitAfterStage` is true and the project uses git, use `AskUserQuestion` to offer: "Want me to create a `forge/{feature}` branch for this pipeline? (Recommended — keeps forge work isolated.)" If yes, create and checkout the branch before proceeding.
+Invoke the **Branch Setup** block in `references/shared-conventions.md` with `{label}` = `{feature}` and `{scope}` = `feature`. It self-gates (skips when not a git repo, when `branchPerFeature` is false, or for an epic member that inherits the epic's branch), detects whether you're on the default branch, and strongly recommends — still optionally — creating `{branchPrefix}{feature}` when you are. Do this before directory resolution.
 
 Set the working directory by invoking the **Feature Directory Resolution** block in `references/shared-conventions.md`, which yields `{resolvedFeatureDir}`. Note one PRD-specific caveat: at PRD time a brand-new standalone feature may have NO directory yet, so resolution is expected to fail `not-found` for a never-started standalone feature — in that case forge-1 creates `{specsDir}/{feature}/` as today. For an epic member the directory already exists (created empty by forge-0-epic with an `epic` back-pointer), so resolution succeeds and yields the nested path.
 
@@ -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
@@ -87,6 +87,8 @@ Once the interview is thorough, write `{resolvedFeatureDir}/PRD.md` following th
 
 Every requirement MUST have a unique ID (e.g., REQ-AUTH-01, REQ-PERF-01). These IDs are referenced by all downstream documents.
 
+After writing the PRD (this is the point where `{specsDir}/{feature}/` is first created for a standalone feature), invoke the **Specs Directory Hygiene** block in `references/shared-conventions.md` to ensure `{specsDir}/AGENTS.md` (and `{specsDir}/CLAUDE.md` on the Claude host) exists. It is idempotent — it never overwrites an existing file.
+
 ## Step 5: Review with User
 
 Present the complete PRD to the user. Ask:
@@ -110,7 +112,7 @@ Write pipeline state conforming to `references/pipeline-state-schema.json`.
    - Check downstream stages (`forge-2-tech`, `forge-3-specs`, `forge-4-backlog`, `forge-5-loop`, `forge-6-docs`). If any have `basedOnVersions` referencing an older version of `forge-1-prd`, set their status to `stale`.
 2. Use `AskUserQuestion` to ask: "Anything you want to note before we wrap? (preserved across sessions)"
    - If yes, store in the `notes` field
-3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files, attempt commit with message `"{commitPrefix}({feature}): complete PRD v{n}"`, then set `stages.forge-1-prd.status` to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
+3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files (including `{specsDir}/AGENTS.md` / `{specsDir}/CLAUDE.md` if the Specs Directory Hygiene step just wrote them), attempt commit with message `"{commitPrefix}({feature}): complete PRD v{n}"`, then set `stages.forge-1-prd.status` to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
 5. Tell the user: "PRD complete. Next steps:\n  - `/feature-forge:forge-verify {feature}` to verify the PRD\n  - `/feature-forge:forge-2-tech {feature}` to start the tech spec\n  - `/feature-forge:forge {feature}` to see full pipeline status"
 
 ## Gotchas

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`