@garygentry/feature-forge 0.1.4 → 0.2.0

package/adapters/cursor/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/cursor/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/cursor/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/cursor/skills/forge/forge.mdc

@@ -29,13 +29,13 @@ 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
    ```
    and show one rollup line: `{epic} — {complete}/{total} complete, next: {nextCommand}`.
 2. **Standalone features below.** Scan the remaining `{specsDir}/*/` that directly contain a `.pipeline-state.json` **without** an `epic` back-pointer. A nested member's `.pipeline-state.json` is **attributed to its epic (Tier 1), never listed as a standalone feature**.
-   - Within this standalone tier the existing logic still applies: if exactly one active (non-complete) standalone pipeline exists, show its dashboard; if multiple exist, list them with a one-line summary each and use `AskUserQuestion` to ask which to focus on.
+   - Within this standalone tier the existing logic still applies: if exactly one active (non-complete) standalone pipeline exists, show its dashboard; if multiple exist, list them with a one-line summary each and use the host's question mechanism to ask which to focus on.
 
 If no epics and no standalone features exist, say: "No active feature pipelines found. Start one with `/feature-forge:forge-1-prd <feature-name>` or group several with `/feature-forge:forge-0-epic <epic-name>`."
 
@@ -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 the host's question mechanism 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 the host's question mechanism 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)."
@@ -163,3 +163,13 @@ When listing features, show active pipelines by default. Include a count of paus
 - Never modify any spec files, backlog files, or pipeline state beyond the `notes`, `updatedAt`, and `pipelineStatus` fields. The navigator is read-only except for notes and lifecycle commands.
 - If a user asks to "continue" or "pick up where I left off" without naming a feature, check for active pipelines before asking. Only ask if ambiguous.
 - The pipeline state file is the source of truth. Don't infer stage from the existence of files alone — a file might exist from a previous incomplete run.
+
+---
+
+## Host execution notes
+
+This skill was authored Claude-first; the body above refers to "the host's question mechanism", "the host's subagent mechanism", and "the host's background-execution mechanism". Use your runtime's equivalent for each — and if your runtime has no such tool:
+
+- **User input:** ask the question directly and wait for the answer before proceeding. Do not skip a required question or assume an answer.
+- **Subagents:** if your host cannot dispatch the named custom agent, run that step inline yourself.
+- **Background / monitoring:** run long-lived commands in the foreground (or your host's background facility) and report progress as it arrives.

package/adapters/cursor/skills/forge-0-epic/forge-0-epic.mdc

@@ -14,13 +14,13 @@ is delegated to `scripts/epic-manifest.py`.
 
 This skill **composes** JSON and **issues** helper commands. It NEVER eyeballs a dependency
 graph for cycles, NEVER hand-rolls a manifest write where a mutator exists, and NEVER asks a
-question in inline prose — every question goes through `AskUserQuestion`.
+question in inline prose — every question goes through the host's question mechanism.
 
 ## Prerequisites
 
 Read and follow `references/shared-conventions.md` for:
 - the **Feature Name Requirement** (applied here to the *epic* name — see below),
-- the **User Input Protocol** (the AskUserQuestion guardrail — all questions go through the tool),
+- the **User Input Protocol** (the the host's question mechanism guardrail — all questions go through the tool),
 - **Configuration Reading**, and
 - the **Git Commit Protocol**.
 
@@ -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,30 +73,32 @@ 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}"
    ```
 
    - Exit `0` → the name is free; proceed to C1.
    - Exit `1` (`duplicate-name`) → STOP and surface the helper's finding **verbatim**; ask
-     (via `AskUserQuestion`) for a different epic name, then re-run check-name.
+     (via the host's question mechanism) for a different epic name, then re-run check-name.
    - Exit `2` (unsafe name) → STOP and surface the finding; ask for a corrected name.
 
 ---
 
 ## 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
 
 Output context as text (what an epic is, that a decomposition interview will follow). Then
-call `AskUserQuestion` to elicit:
+call the host's question mechanism to elicit:
 
 1. **Epic goal / problem** — the overarching change being decomposed. Becomes the EPIC.md
    "Overall Goal" narrative and seeds the manifest `description`.
@@ -109,29 +111,27 @@ 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.
+the host's question mechanism 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}"
 ```
 
 - Exit `0` → accept the name.
 - Exit `1` (`duplicate-name`) → reject that name; surface the finding verbatim and re-prompt
-  (via `AskUserQuestion`) for a different name.
+  (via the host's question mechanism) for a different name.
 - Exit `2` (`unsafe-name`) → reject; surface the finding and re-prompt.
 
 Never accept a feature name that has not passed `check-name` exit 0.
 
 ### Step C3 — Per-Feature Charter + Structured Contracts
 
-For each confirmed feature, run a focused `AskUserQuestion` batch (one feature at a time,
+For each confirmed feature, run a focused the host's question mechanism batch (one feature at a time,
 2–3 questions per call) eliciting:
 
 - **Charter** — a single paragraph: scope statement + contract obligations. This is a
@@ -150,12 +150,10 @@ the structured arrays are the source of truth; EPIC.md renders them as prose lat
 
 ### Step C4 — Dependency-Edge Interview
 
-For each feature, use `AskUserQuestion`: "Which sibling features must be complete before this
+For each feature, use the host's question mechanism: "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
 ```
@@ -240,7 +238,7 @@ now self-contained: manifest + EPIC.md + one subdirectory per member.
 ### Step C8 — Review, Pipeline State & Commit
 
 1. **Review.** Present a summary (epic name, N features, dependency edges, contracts) as text,
-   then use `AskUserQuestion`: "Does this epic decomposition look right? Any feature, dependency,
+   then use the host's question mechanism: "Does this epic decomposition look right? Any feature, dependency,
    or contract to change before I commit?" If the user wants changes, loop back to the relevant
    creation step, re-compose, and re-validate.
 
@@ -271,7 +269,7 @@ Entered from Step 0 when `{specsDir}/{epic}/epic-manifest.json` already exists (
 branch). The edit branch mutates the manifest **only** through helper mutators — atomic
 (temp file + `os.replace`) and internally re-validated, so a refused write leaves the manifest
 **byte-identical**; the skill never hand-rolls an in-place write. Every question goes through
-`AskUserQuestion`, and **every mutation is committed individually** so git history is the audit trail.
+the host's question mechanism, and **every mutation is committed individually** so git history is the audit trail.
 
 For the full E1–E6 mechanics — the E1 refuse-if-invalid protocol, E2 operation→mutator table, E3
 contracts/remove-feature caveats (incl. the verbatim WARN block), E4 impact-warning rules, E5
@@ -300,4 +298,14 @@ section).
 - A charter is one paragraph, not a PRD. Redirect requirement-level detail to `forge-1-prd`.
 - Contracts have no mutator: edit `exposes`/`consumes` in the composed manifest entry, then
   re-run `validate`.
-- All questions go through `AskUserQuestion`. Never put a question in your text output.
+- All questions go through the host's question mechanism. Never put a question in your text output.
+
+---
+
+## Host execution notes
+
+This skill was authored Claude-first; the body above refers to "the host's question mechanism", "the host's subagent mechanism", and "the host's background-execution mechanism". Use your runtime's equivalent for each — and if your runtime has no such tool:
+
+- **User input:** ask the question directly and wait for the answer before proceeding. Do not skip a required question or assume an answer.
+- **Subagents:** if your host cannot dispatch the named custom agent, run that step inline yourself.
+- **Background / monitoring:** run long-lived commands in the foreground (or your host's background facility) and report progress as it arrives.

package/adapters/cursor/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/cursor/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/cursor/skills/forge-1-prd/forge-1-prd.mdc

@@ -16,11 +16,11 @@ 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.
 
-If `.pipeline-state.json` exists for this feature and `forge-1-prd` is already marked complete, use `AskUserQuestion` to warn: "A PRD already exists for '{feature}'. Continuing will create a new version. Proceed?"
+If `.pipeline-state.json` exists for this feature and `forge-1-prd` is already marked complete, use the host's question mechanism to warn: "A PRD already exists for '{feature}'. Continuing will create a new version. Proceed?"
 
 ## Step 2: Examine Existing Context
 
@@ -61,23 +61,23 @@ A technology constraint is valid when it stems from organizational mandate, exis
 
 ### Interview Approach
 
-**Turn structure:** Output your analysis or context as regular text, then use `AskUserQuestion` for the actual questions. NEVER put questions in your text output — they MUST go through `AskUserQuestion`.
+**Turn structure:** Output your analysis or context as regular text, then use the host's question mechanism for the actual questions. NEVER put questions in your text output — they MUST go through the host's question mechanism.
 
-**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.
+**Pacing:** Cover one topic area at a time, asking 2-3 related questions per the host's question mechanism 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 the host's question mechanism, 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
 2. The user has confirmed there's nothing else to add
 3. You can draft every PRD section without leaving TBD placeholders
 
-Before moving to Step 4, summarize your coverage as text, then use `AskUserQuestion` to ask: "Anything I'm missing?"
+Before moving to Step 4, summarize your coverage as text, then use the host's question mechanism to ask: "Anything I'm missing?"
 
 **Parking lot:** If the user raises a concern that belongs to a different pipeline stage, acknowledge it and note it in the pipeline state's `notes` field: "Good point — I've noted that for the [tech spec/implementation specs]. Let's continue with [current stage]."
 
@@ -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:
@@ -94,7 +96,7 @@ Present the complete PRD to the user. Ask:
 - "Are the priorities correct?"
 - "Anything in here that should be out of scope?"
 
-Use `AskUserQuestion` to collect this feedback.
+Use the host's question mechanism to collect this feedback.
 
 Iterate until the user confirms the PRD is complete.
 
@@ -108,9 +110,9 @@ Write pipeline state conforming to `references/pipeline-state-schema.json`.
    - Record `artifacts`, `completedAt`
    - Set `stages.forge-1-prd.basedOnVersions` to `{}` (no upstream dependencies)
    - 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)"
+2. Use the host's question mechanism 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
@@ -119,3 +121,13 @@ Write pipeline state conforming to `references/pipeline-state-schema.json`.
 - If the user provides a very detailed initial description, don't skip the interview. Use their description as a starting point but probe for what's missing. Long descriptions often have big gaps in edge cases and non-functional requirements.
 - Don't number requirements sequentially across categories (REQ-01, REQ-02...). Use category prefixes (REQ-AUTH-01, REQ-PERF-01) so inserting new requirements doesn't require renumbering.
 - The PRD should be readable by a non-technical stakeholder. If a section requires deep technical knowledge to understand, it probably belongs in the tech spec, not the PRD.
+
+---
+
+## Host execution notes
+
+This skill was authored Claude-first; the body above refers to "the host's question mechanism", "the host's subagent mechanism", and "the host's background-execution mechanism". Use your runtime's equivalent for each — and if your runtime has no such tool:
+
+- **User input:** ask the question directly and wait for the answer before proceeding. Do not skip a required question or assume an answer.
+- **Subagents:** if your host cannot dispatch the named custom agent, run that step inline yourself.
+- **Background / monitoring:** run long-lived commands in the foreground (or your host's background facility) and report progress as it arrives.