@garygentry/feature-forge 0.1.5 → 0.2.1

package/adapters/cursor/skills/forge-2-tech/forge-2-tech.mdc

@@ -29,7 +29,7 @@ Before interviewing, you need to understand the existing codebase. This involves
 
 ### Recommended: Delegate to forge-researcher Subagent
 
-Spawn the `forge-researcher` subagent via the Agent tool to scan the codebase. Pass a prompt like: "Research the codebase for planning the {feature} feature. Focus on integration points, established patterns, and relevant packages."
+Spawn the `forge-researcher` subagent via the host's subagent mechanism to scan the codebase. Pass a prompt like: "Research the codebase for planning the {feature} feature. Focus on integration points, established patterns, and relevant packages."
 
 If this feature belongs to an epic, also add to the dispatch prompt: "If this feature belongs to an epic, also account for these epic contracts: {paste this feature's `consumes` and the `exposes` of its direct deps}, and the completed dependency tech-specs at {paths}. Do not re-research transitive deps." This threads epic context into the researcher without changing the agent's behavior.
 
@@ -38,7 +38,7 @@ The researcher runs in its own context window, reads the project structure, and
 **Single vs. parallel research.** For a small or well-understood codebase, **one**
 researcher is the right default. For a **large codebase or uncertain scope** (many
 packages, several integration surfaces, monorepo), dispatch **multiple `forge-researcher`
-subagents in parallel — a single message with multiple Agent calls** (the
+subagents in parallel — a single message with multiple subagent calls** (the
 `superpowers:dispatching-parallel-agents` pattern), each scoped to a **disjoint focus**
 so they don't re-read the same ground:
 - one on **project structure & conventions** (layout, build, naming, error/test patterns),
@@ -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).
@@ -67,9 +67,9 @@ If the `forge-researcher` subagent is not available, perform the research inline
 After researching the codebase, identify the primary stack (language, build tool, package manager, framework). Read `references/stack-resolution.md` for the full resolution protocol.
 
 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?"
+2. Otherwise, detect from project files and use the host's question mechanism 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
 
@@ -77,17 +77,18 @@ Interview the user about technology decisions. Unlike the PRD interview, here yo
 
 ### Interview Approach
 
-**Turn structure:** Output your research findings, analysis, or technical proposals 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 research findings, analysis, or technical proposals 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:** Present 1-2 decision areas per `AskUserQuestion` call and STOP to wait for the user's response before continuing. After receiving answers, probe deeper on anything incomplete before moving to the next topic. Signal progress in your text before the next question batch. Do NOT dump all decision areas in a single message — the interview is a conversation, not a document.
+**Pacing:** Present 1-2 decision areas per the host's question mechanism call and STOP to wait for the user's response before continuing. After receiving answers, probe deeper on anything incomplete before moving to the next topic. Signal progress in your text before the next question batch. Do NOT dump all decision areas in a single message — the interview is a conversation, not a document.
 
-**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.
+**First message pattern:** Output the research summary as text, then use the host's question mechanism 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 the host's question mechanism, 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 the host's question mechanism `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."
 
@@ -175,7 +176,7 @@ Present the complete tech spec. Ask:
 - "Any patterns from the existing codebase I missed?"
 - "Are the integration points complete?"
 
-Use `AskUserQuestion` to collect this feedback.
+Use the host's question mechanism to collect this feedback.
 
 ## Step 7: Update Pipeline State and Commit
 
@@ -186,7 +187,7 @@ Write pipeline state conforming to `references/pipeline-state-schema.json`.
    - Record `artifacts`, `completedAt`, `version`
    - Set `stages.forge-2-tech.basedOnVersions` to `{"forge-1-prd": <current forge-1-prd version>}`
    - Check downstream stages (forge-3-specs, forge-4-backlog, forge-5-loop, forge-6-docs). If any have `basedOnVersions` referencing an older version of forge-2-tech, set their status to `stale`
-2. Use `AskUserQuestion` to ask about notes to persist
+2. Use the host's question mechanism to ask about notes to persist
 3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files, attempt commit with message `"{commitPrefix}({feature}): complete tech-spec v{n}"`, then set `stages.forge-2-tech.status` to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
 5. Tell the user: "Tech spec complete. Next steps:\n  - `/feature-forge:forge-verify {feature}` to verify the tech spec\n  - `/feature-forge:forge-3-specs {feature}` to create implementation specs\n  - `/feature-forge:forge {feature}` to see full pipeline status"
 
@@ -196,3 +197,13 @@ Write pipeline state conforming to `references/pipeline-state-schema.json`.
 - When the user's stack decisions differ from what you'd recommend, document their choice AND note your concern as an "Alternatives Considered" item — don't silently override their preference.
 - Integration points are the #1 source of implementation surprises. Spend extra time here. Read the actual code of packages this feature touches, don't just guess at their APIs.
 - If the existing codebase has inconsistent patterns (it happens), call it out and ask which pattern should be followed for this feature.
+
+---
+
+## 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-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/cursor/skills/forge-3-specs/forge-3-specs.mdc

@@ -13,7 +13,7 @@ Generate a comprehensive suite of numbered implementation specification document
 
 Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
 
-**Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
+**Turn structure reminder:** Output analysis/context as text, then route ALL questions through the host's question mechanism. Never embed questions in text output — the user will not be prompted and the session will stall.
 
 ## Step 1: Validate Prerequisites
 
@@ -37,7 +37,7 @@ After reading the PRD and tech spec, invoke the **Epic Context Injection** block
 
 Read `references/spec-archetypes.md` for the menu of document types.
 
-Based on the feature's complexity, propose a document plan to the user before writing. Output the document list as text, then use `AskUserQuestion` for the question — do NOT include the question in your text output.
+Based on the feature's complexity, propose a document plan to the user before writing. Output the document list as text, then use the host's question mechanism for the question — do NOT include the question in your text output.
 
 **Example text output (no question here):**
 ```
@@ -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 the host's question mechanism** 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").
 
@@ -73,7 +73,7 @@ and the directory/exports map, so they must exist and be stable first.
 ### 4b. Domain fan-out (parallel `forge-spec-writer` subagents)
 
 Once the foundation is written, dispatch the remaining numbered docs in parallel — **one
-`forge-spec-writer` subagent per document, in a single message with multiple Agent
+`forge-spec-writer` subagent per document, in a single message with multiple subagent
 calls** (the `superpowers:dispatching-parallel-agents` pattern). Each writer is given:
 - the PRD and tech-spec,
 - the just-written `00-core-definitions.md` and `01-architecture-layout.md` (so it builds
@@ -128,7 +128,7 @@ List any gaps or inconsistencies found and resolve them.
 
 ## Step 6: Review with User
 
-Present a summary of all documents created as text, with key decisions highlighted. Then use `AskUserQuestion` to collect feedback — do NOT include these questions in your text output:
+Present a summary of all documents created as text, with key decisions highlighted. Then use the host's question mechanism to collect feedback — do NOT include these questions in your text output:
 
 "1. Does the level of detail match what you need? 2. Any areas that need more depth? 3. Any missing subsystems or concerns?"
 
@@ -141,7 +141,7 @@ Write pipeline state conforming to `references/pipeline-state-schema.json`.
    - Record all created files in `artifacts`, including `TRACEABILITY.md`
    - Set `stages.forge-3-specs.basedOnVersions` to `{"forge-1-prd": <current version>, "forge-2-tech": <current version>}`
    - Check downstream stages (forge-4-backlog, forge-5-loop, forge-6-docs). If any have `basedOnVersions` referencing older versions, set their status to `stale`
-2. Use `AskUserQuestion` to ask about notes to persist
+2. Use the host's question mechanism to ask about notes to persist
 3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files, attempt commit with message `"{commitPrefix}({feature}): complete implementation specs v{n}"`, then set `stages.forge-3-specs.status` to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
 5. Tell the user: "Implementation specs complete. Next steps:\n  - `/feature-forge:forge-verify {feature}` to verify the specs (strongly recommended)\n  - `/feature-forge:forge-4-backlog {feature}` to generate the backlog\n  - `/feature-forge:forge {feature}` to see full pipeline status"
 
@@ -152,3 +152,13 @@ Write pipeline state conforming to `references/pipeline-state-schema.json`.
 - Resist the urge to create too many documents. Each document should represent a major concern. If a "document" would be under 50 lines, it probably belongs as a section in another document.
 - Watch for implicit dependencies between subsystems. If subsystem A's types are used by subsystem B, the spec should explicitly state this and ensure the types are defined in the shared types document.
 - If the feature is large, the spec suite might be 8-12 documents. If it's simple, 3-4 is fine. Match complexity to the feature, not a fixed template.
+
+---
+
+## 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-4-backlog/forge-4-backlog.mdc

@@ -31,7 +31,7 @@ This is the **single** place this rule is implemented. forge-5-loop's backlog-fi
 
 Resolve the **loop runner** from the `loopRunner` block in `forge.config.json`, filling missing fields from the defaults in `references/forge-config-schema.json` (defaults to rauf). You need its `bin`, `validateCommand`, `versionCommand`, `minRunnerVersion`, and `installHint`.
 
-**Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
+**Turn structure reminder:** Output analysis/context as text, then route ALL questions through the host's question mechanism. Never embed questions in text output — the user will not be prompted and the session will stall.
 
 ## Step 1: Validate Prerequisites
 
@@ -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 the host's question mechanism 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 the host's question mechanism 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`
 
@@ -123,7 +123,7 @@ Interpret the result:
 
 Present a summary: total items N, dependency-chain depth, estimated loop iterations (`ceil(pendingItems * loopIterationMultiplier)`). Note whether validation passed or was skipped (runner not yet available).
 
-Use `AskUserQuestion` to ask: "Ready to proceed, or any adjustments needed?"
+Use the host's question mechanism to ask: "Ready to proceed, or any adjustments needed?"
 
 ## Step 7: Update Pipeline State and Commit
 
@@ -134,7 +134,7 @@ Write pipeline state conforming to `references/pipeline-state-schema.json`. Foll
    - Set `stages.forge-4-backlog.basedOnVersions` to `{"forge-1-prd": <current version>, "forge-2-tech": <current version>, "forge-3-specs": <current version>}`
    - Set `currentStage` to `forge-5-loop`
    - Check downstream stages (`forge-5-loop`, `forge-6-docs`). If any have `basedOnVersions` referencing an older version of `forge-4-backlog`, set their status to `stale`.
-2. Use `AskUserQuestion` to ask about notes to persist
+2. Use the host's question mechanism to ask about notes to persist
 3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol: stage files, attempt commit, then set status to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
 4. If verification was available but the user chose to skip it, record `stages.forge-verify-backlog.status` as `"skipped"` in pipeline state.
 5. Tell user: "Backlog complete with {N} items. Next steps:\n  - `/feature-forge:forge-verify {feature}` to verify the backlog\n  - `/feature-forge:forge-5-loop {feature}` to run the loop\n  - `/feature-forge:forge {feature}` to see full pipeline status"
@@ -144,3 +144,13 @@ Write pipeline state conforming to `references/pipeline-state-schema.json`. Foll
 - The loop runs each item in a FRESH context. Every item description must be self-contained — `author-backlog` enforces this, but double-check Step-3 plan items aren't "same as above."
 - Spec references must be project-root-relative paths that actually exist — the validate command enforces this when `--specs-dir` is passed (resolving them from the project root).
 - Don't present a backlog to the user before it validates (or before you've explicitly recorded that validation was skipped because the runner isn't installed yet).
+
+---
+
+## 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-5-loop/forge-5-loop.mdc

@@ -36,7 +36,7 @@ Token substitution applies to every `*Command` string. Substitute:
 Whenever this skill says "run the **run command**" / "**status command**" /
 etc., it means the corresponding substituted `loopRunner.*Command`.
 
-**Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
+**Turn structure reminder:** Output analysis/context as text, then route ALL questions through the host's question mechanism. Never embed questions in text output — the user will not be prompted and the session will stall.
 
 ## Step 1: Validate Prerequisites
 
@@ -50,9 +50,9 @@ Read `{resolvedFeatureDir}/.pipeline-state.json`. If not in force mode, `stages.
 
 ### 1b. Verification Check
 
-Check if `stages.forge-verify-backlog` exists and has status `passed` or `findings-applied`. If not, use `AskUserQuestion` to warn:
+Check if `stages.forge-verify-backlog` exists and has status `passed` or `findings-applied`. If not, use the host's question mechanism 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
@@ -69,7 +69,7 @@ python3 "$R/scripts/epic-manifest.py" \
 
 2. Find this feature's entry; read its `unmetDeps` (the direct `dependsOn` not yet complete-for-orchestration per `00-core-definitions.md §7`).
 3. **If `unmetDeps` is empty**, proceed to 1c with no prompt.
-4. **If `unmetDeps` is non-empty**, use `AskUserQuestion` (do NOT inline the question as prose) to warn that the feature depends on the unmet dependencies, which are not yet complete, and that running the loop now means implementing against contracts that may still change:
+4. **If `unmetDeps` is non-empty**, use the host's question mechanism (do NOT inline the question as prose) to warn that the feature depends on the unmet dependencies, which are not yet complete, and that running the loop now means implementing against contracts that may still change:
 
    > "{feature} depends on {unmetDeps joined}, which are not yet complete. Running the loop now means implementing against contracts that may still change. Proceed anyway, or stop and finish the dependencies first?"
 
@@ -114,7 +114,7 @@ Verify the file exists on disk. If not, STOP and tell the user: "No backlog.json
 
 ### 1f. Branch Pre-flight (if using git)
 
-The runner commits each completed item straight onto the current branch, so guard against committing onto the default branch. Skip if not a git repo or `branchPerFeature` is false. Read the current branch (`git rev-parse --abbrev-ref HEAD`) and default branch (`git symbolic-ref --quiet refs/remotes/origin/HEAD`, else `main`/`master`). If `.pipeline-state.json` records a `branch` that differs from the current one, warn via `AskUserQuestion` (offer **switch back** or **proceed here**). Otherwise, if the current branch **is** the default, strongly recommend via `AskUserQuestion` creating/switching to `{branchPrefix}{feature}` (`git switch -c`, then record it to the state `branch` field) before the loop commits — still allowing **proceed on `{defaultBranch}`**. Never hard-stop.
+The runner commits each completed item straight onto the current branch, so guard against committing onto the default branch. Skip if not a git repo or `branchPerFeature` is false. Read the current branch (`git rev-parse --abbrev-ref HEAD`) and default branch (`git symbolic-ref --quiet refs/remotes/origin/HEAD`, else `main`/`master`). If `.pipeline-state.json` records a `branch` that differs from the current one, warn via the host's question mechanism (offer **switch back** or **proceed here**). Otherwise, if the current branch **is** the default, strongly recommend via the host's question mechanism creating/switching to `{branchPrefix}{feature}` (`git switch -c`, then record it to the state `branch` field) before the loop commits — still allowing **proceed on `{defaultBranch}`**. Never hard-stop.
 
 ## Step 2: Construct the Loop Command
 
@@ -147,7 +147,7 @@ rauf loop run . --backlog specs/auth --iterations 15
 
 ### 2d. Confirm with User
 
-Use `AskUserQuestion` to present the rendered run command and options. The following block is the content for `AskUserQuestion` — do NOT output it as text:
+Use the host's question mechanism to present the rendered run command and options. The following block is the content for the host's question mechanism — do NOT output it as text:
 
 ```
 Ready to run the loop for {feature}:
@@ -176,10 +176,10 @@ For the full loop-runner contract — event-stream vs. log-fallback launch, the
 **Capability gate.** Everything below applies **only when** the effective `loopRunner.agentArgument` is present and non-empty. **When it is absent or empty, Step 2d is exactly the confirmation above — no probe, no agent question, no availability listing, no `Agent:` line — byte-identical to today** (REQ-PLUG-02, REQ-COMPAT-01). The full algorithm, precedence, and verbatim message shapes are in `## Agent selection` of `references/runner-contract.md`; read it. When the gate is on, augment Step 2d in order:
 
 - **(a) Probe once.** Before confirming, run `loopRunner.agentsProbeCommand` (default `{bin} agents --json`) **exactly once** (no retries, no second probe); it exits 0 with `{ agents: [...] }`. Parse `agents[]`; build the advertised set `{ row.id }` — this one parsed array drives (b)–(d).
-- **(b) Agent question.** Add an **"agent"** question to the same `AskUserQuestion` surface: **one option per advertised row** labelled `"{displayName} ({id}) — available/not found"`, **plus an explicit `"default (claude-cli)"` choice mapping to `run_selection = None`**. Resolve the pick (run > project, empty/whitespace unset, an explicit runner-default pick collapses to the default path) into `{resolved.agent, resolved.source}`. Precedence: `item.provider > --agent > project defaultAgent > runner default` (forge never reads a backlog item's provider).
+- **(b) Agent question.** Add an **"agent"** question to the same the host's question mechanism surface: **one option per advertised row** labelled `"{displayName} ({id}) — available/not found"`, **plus an explicit `"default (claude-cli)"` choice mapping to `run_selection = None`**. Resolve the pick (run > project, empty/whitespace unset, an explicit runner-default pick collapses to the default path) into `{resolved.agent, resolved.source}`. Precedence: `item.provider > --agent > project defaultAgent > runner default` (forge never reads a backlog item's provider).
 - **(c) Availability listing.** From the **same** parsed `agents[]` (no second probe), list `id` / `displayName` / available (`yes`/`no`, `detail` on unavailable rows).
-- **(d) Verdict** — only for a **non-default** resolved agent (default path `None`/`claude-cli` → no probe, byte-identical to today). Classify by **membership** then `available` (never by exit code): **UNKNOWN** (`∉` set) → **hard-reject BEFORE any loop side-effect**, error lists the **sorted** valid ids, **NO proceed-anyway**; **UNAVAILABLE** (member, `available False`) → warn with `detail`, `AskUserQuestion` offering **proceed-anyway OR choose-another** (re-presents the same `agents[]`), never silent; **AVAILABLE** → proceed, the validated id fills `{agent}`; **probe failure** (non-zero exit / unparseable / missing or empty `agents[]` / row lacking `id`) → surface it, offer **choose-another OR abort**, **never launch the non-default agent unvalidated** and never silently fall back to the default.
-- **(d-model) Claude-only model-alias guard.** Runs **only** when the resolved agent is **non-default** (not the default / `claude-cli` path). Read the backlog.json (Step 1e path); collect items whose `model` is a **Claude-specific alias** (tier `opus`/`sonnet`/`haiku` or a `claude-*` id). **If none, skip silently.** Otherwise warn before launch via `AskUserQuestion` (NOT prose): `item.model` outranks `--agent`, so the alias is forwarded verbatim to `{agent}`, which will likely reject it (e.g. codex 400 *"The 'sonnet' model is not supported…"*) — every spawn exits 1 and rauf circuit-breaks (*"3 consecutive infra failures — halting"*) with no hint of the cause. Offer: **(1) Strip `model` for this run (recommended)** — rewrite backlog.json removing the `model` key from each affected item (persistent edit; re-run forge-4-backlog to restore), then proceed; **(2) Proceed as-is** — only safe if `{agent}` understands the pinned ids. forge touches only `model`, never `provider`. Full rationale: `references/runner-contract.md`.
+- **(d) Verdict** — only for a **non-default** resolved agent (default path `None`/`claude-cli` → no probe, byte-identical to today). Classify by **membership** then `available` (never by exit code): **UNKNOWN** (`∉` set) → **hard-reject BEFORE any loop side-effect**, error lists the **sorted** valid ids, **NO proceed-anyway**; **UNAVAILABLE** (member, `available False`) → warn with `detail`, the host's question mechanism offering **proceed-anyway OR choose-another** (re-presents the same `agents[]`), never silent; **AVAILABLE** → proceed, the validated id fills `{agent}`; **probe failure** (non-zero exit / unparseable / missing or empty `agents[]` / row lacking `id`) → surface it, offer **choose-another OR abort**, **never launch the non-default agent unvalidated** and never silently fall back to the default.
+- **(d-model) Claude-only model-alias guard.** Runs **only** when the resolved agent is **non-default** (not the default / `claude-cli` path). Read the backlog.json (Step 1e path); collect items whose `model` is a **Claude-specific alias** (tier `opus`/`sonnet`/`haiku` or a `claude-*` id). **If none, skip silently.** Otherwise warn before launch via the host's question mechanism (NOT prose): `item.model` outranks `--agent`, so the alias is forwarded verbatim to `{agent}`, which will likely reject it (e.g. codex 400 *"The 'sonnet' model is not supported…"*) — every spawn exits 1 and rauf circuit-breaks (*"3 consecutive infra failures — halting"*) with no hint of the cause. Offer: **(1) Strip `model` for this run (recommended)** — rewrite backlog.json removing the `model` key from each affected item (persistent edit; re-run forge-4-backlog to restore), then proceed; **(2) Proceed as-is** — only safe if `{agent}` understands the pinned ids. forge touches only `model`, never `provider`. Full rationale: `references/runner-contract.md`.
 - **(e) Optional-flags line.** Replace the confirmation's optional-flags line with one that lists `--agent <id>` first plus the agent precedence pointer (`item.provider > --agent > project defaultAgent > runner default`) alongside the model precedence.
 - **(f) Resolved-agent line.** Add to the confirmation block: `Agent: {resolved.agent or claude-cli} (source: {sourceLabel})` — `sourceLabel`: `RUN` → `"per-run selection"`, `PROJECT` → `"project default (loopRunner.defaultAgent)"`, `DEFAULT` → `"runner default — claude-cli"`.
 
@@ -197,7 +197,7 @@ Then commit this state write before launching (mandatory). The runner refuses to
 
 ### 3b. Launch Background Process
 
-Launch the loop **backgrounded** (`run_in_background: true`) so it survives session end and does not block the session, and prefer the machine-readable event stream (`loopRunner.eventStreamCommand`, default for rauf) redirected to a stable `events.ndjson` so the session can supervise it live; fall back to the plain `runCommand` (tailing the human log) when no `eventStreamCommand` is configured. The background task's exit notification is the single authoritative terminal signal (Step 4). Loop runs can take significant time (minutes to hours depending on backlog size). For the exact launch commands (incl. the `mkdir -p` state-dir guard) and the event-stream vs. log-fallback detail, read `references/runner-contract.md`.
+Launch the loop **backgrounded** (the host's background-execution mechanism) so it survives session end and does not block the session, and prefer the machine-readable event stream (`loopRunner.eventStreamCommand`, default for rauf) redirected to a stable `events.ndjson` so the session can supervise it live; fall back to the plain `runCommand` (tailing the human log) when no `eventStreamCommand` is configured. The background task's exit notification is the single authoritative terminal signal (Step 4). Loop runs can take significant time (minutes to hours depending on backlog size). For the exact launch commands (incl. the `mkdir -p` state-dir guard) and the event-stream vs. log-fallback detail, read `references/runner-contract.md`.
 
 ### 3c. Inform User
 
@@ -211,9 +211,9 @@ verbatim "Loop started…" inform-user output template is in
 
 ### 3d. Arm a Monitor on the event stream, and react to events
 
-Arm the **`Monitor` tool** on the structured event stream (the NDJSON file, or the
+Arm the **the host's monitoring mechanism** on the structured event stream (the NDJSON file, or the
 human log as fallback) so events flow back into this session as they happen. Use
-**`persistent: true`** — runs can exceed `Monitor`'s maximum `timeout_ms` (1 hour),
+**`persistent: true`** — runs can exceed the host's monitoring mechanism's maximum `timeout_ms` (1 hour),
 and a bounded timeout would silently stop watching a still-running loop. The filter
 MUST match every terminal and exception state, not just the happy path (silence is
 not success). Monitor the **structured** surface, never raw `RAUF_*` tokens.
@@ -271,13 +271,13 @@ Update `{resolvedFeatureDir}/.pipeline-state.json`:
 
 ## Step 5b: Offer Impl-Verify (standalone path)
 
-**Gate:** run only if (a) the feature's `.pipeline-state.json` has **no** `epic` key **and** (b) Step 5 set `stages.forge-5-loop.status` to `complete`. Otherwise **skip** — partial runs end as today, and epic members get the equivalent offer in Step 6.1 (do **not** prompt twice). This standalone counterpart to Step 6.1 nudges verification interactively rather than via the easily-missed "Next steps" text. Use `AskUserQuestion` (NOT inline prose) to offer: *"{feature}'s loop is complete. Recommended: run `/feature-forge:forge-verify {feature} impl` to audit the implementation before generating docs. Run it now, or skip to forge-6-docs?"* On **run**, hand off to `/feature-forge:forge-verify {feature} impl`. On **skip**, record `stages.forge-verify-impl.status` as `"skipped"` (mirrors `forge-4-backlog`'s skip handling) and point the user at `/feature-forge:forge-6-docs {feature}` — the forge-6-docs backstop re-surfaces the skip.
+**Gate:** run only if (a) the feature's `.pipeline-state.json` has **no** `epic` key **and** (b) Step 5 set `stages.forge-5-loop.status` to `complete`. Otherwise **skip** — partial runs end as today, and epic members get the equivalent offer in Step 6.1 (do **not** prompt twice). This standalone counterpart to Step 6.1 nudges verification interactively rather than via the easily-missed "Next steps" text. Use the host's question mechanism (NOT inline prose) to offer: *"{feature}'s loop is complete. Recommended: run `/feature-forge:forge-verify {feature} impl` to audit the implementation before generating docs. Run it now, or skip to forge-6-docs?"* On **run**, hand off to `/feature-forge:forge-verify {feature} impl`. On **skip**, record `stages.forge-verify-impl.status` as `"skipped"` (mirrors `forge-4-backlog`'s skip handling) and point the user at `/feature-forge:forge-6-docs {feature}` — the forge-6-docs backstop re-surfaces the skip.
 
 ## Step 6: Epic Handoff
 
 **Gate:** only run this step if (a) the resolved feature's `.pipeline-state.json` has an `epic` key **and** (b) Step 5 set `stages.forge-5-loop.status` to `complete` (all backlog items done). If either is false, **skip** — standalone completed features are handled by Step 5b, and partial runs end as today (REQ-COMPAT-01).
 
-1. **Offer impl-verify first (recommended, skippable).** Per the completion rule (`00-core-definitions.md §7`), a feature whose `forge-verify-impl.status == findings-reported` does **not** unblock dependents. Use `AskUserQuestion` (NOT inline prose) to offer:
+1. **Offer impl-verify first (recommended, skippable).** Per the completion rule (`00-core-definitions.md §7`), a feature whose `forge-verify-impl.status == findings-reported` does **not** unblock dependents. Use the host's question mechanism (NOT inline prose) to offer:
 
    > "{feature}'s loop is done. Recommended: run `/feature-forge:forge-verify {feature} impl` before unblocking dependents. Run it now, or skip and continue the handoff?"
 
@@ -287,7 +287,7 @@ Update `{resolvedFeatureDir}/.pipeline-state.json`:
    - **None actionable** (everything done, or remaining features still blocked): say so.
      - If `rollup.total > 0` **AND** `rollup.complete == rollup.total`, suggest `/feature-forge:forge-6-docs {feature}` and note the epic-level documentation offer (§10). The `rollup.total > 0` guard prevents an **empty epic** (`0 == 0`) from being reported complete.
      - Otherwise, list what is still blocked and on which dependencies. End — do not prompt to start a feature that cannot start.
-   - **One or more actionable:** use `AskUserQuestion` presenting **each actionable feature** as an option (plus "stop here"). Execution is **serial** — the user picks exactly one (REQ-ORCH-03). Do **not** autonomously chain into the next pipeline.
+   - **One or more actionable:** use the host's question mechanism presenting **each actionable feature** as an option (plus "stop here"). Execution is **serial** — the user picks exactly one (REQ-ORCH-03). Do **not** autonomously chain into the next pipeline.
 4. **Begin the chosen feature.** For the picked feature:
    - **PRD absent** (no `PRD.md`, or `stages.forge-1-prd` not complete): offer to author it now — "Start `/feature-forge:forge-1-prd {chosen}`?" (REQ-ORCH-02). On yes, hand off to forge-1-prd (which injects epic context per §5.1).
    - **PRD present:** point the user at the chosen feature's `nextCommand` from render-status.
@@ -299,7 +299,17 @@ Update `{resolvedFeatureDir}/.pipeline-state.json`:
 - rauf resolves `RAUF.md` with fallback: checks `{backlogDir}/.rauf/RAUF.md` first, then the project's `.rauf/RAUF.md`. As long as the runner is installed in the project, the prompt template will be found.
 - State files (state.json, {loopRunner.logFile}, etc.) are created at `{backlogDir}/{loopRunner.stateDir}/` — this is within the feature's spec directory and is expected. State is isolated per backlog dir, so concurrent features don't collide.
 - If the session disconnects during a long-running loop, the runner process continues independently. The user can check results later with the status / list commands.
-- Never run the run command in the foreground (without `run_in_background`) — it blocks and will hit the Bash tool timeout for any non-trivial backlog. "Don't block the foreground" is NOT "stay silent": supervise via the `Monitor` tool (3d), never `sleep`/poll in the foreground. The `Monitor` must use `persistent: true` (not a bounded `timeout_ms`), watch the **structured** surface (`events.ndjson`), and never filter on raw `RAUF_*` tokens — they appear in agent prose and false-match. A `needs_human`/`blocked`/`review` signal does **not** pause the loop — the runner sets the item aside and keeps going; surface it live but don't tell the user the loop is waiting. See `references/runner-contract.md` for the full monitoring rules.
+- Never run the run command in the foreground (without the host's background-execution mechanism) — it blocks and will hit the Bash tool timeout for any non-trivial backlog. "Don't block the foreground" is NOT "stay silent": supervise via the host's monitoring mechanism (3d), never `sleep`/poll in the foreground. The the host's monitoring mechanism must use `persistent: true` (not a bounded `timeout_ms`), watch the **structured** surface (`events.ndjson`), and never filter on raw `RAUF_*` tokens — they appear in agent prose and false-match. A `needs_human`/`blocked`/`review` signal does **not** pause the loop — the runner sets the item aside and keeps going; surface it live but don't tell the user the loop is waiting. See `references/runner-contract.md` for the full monitoring rules.
 - If a previous loop run left a stale lock, the user may need to pass `--force` to clear it. rauf will report this error clearly.
 - The version gate (1c) uses the `--json` form on purpose; never parse `rauf version`'s human output.
 - **Implementation artifacts must not cite specs.** The loop should **read** the specs and `backlog.json` freely — they are the source of truth for what to build, and the backlog rightly references specs for provenance. But the artifacts the loop **writes into the target repo** (source code, generated `SKILL.md`/agent files, configs, code comments) must be **self-contained**: they must NOT reference feature-forge spec files (no `See specs/{feature}/NN-*.md`, no "source spec" provenance notes in shipped output). Specs are pre-implementation inputs that may be archived or deleted once the feature ships; the implementation must stand on its own. This applies only to shipped implementation output — never to the backlog or spec documents, which should keep citing specs.
+
+---
+
+## 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-6-docs/forge-6-docs.mdc

@@ -13,7 +13,7 @@ Generate developer-focused architecture documentation for a feature, suitable fo
 
 Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
 
-**Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
+**Turn structure reminder:** Output analysis/context as text, then route ALL questions through the host's question mechanism. Never embed questions in text output — the user will not be prompted and the session will stall.
 
 ## Step 1: Read Context
 
@@ -31,27 +31,27 @@ Load into context:
 
 ### Implementation Completeness Check
 
-Check `{resolvedFeatureDir}/backlog.json` (or `{backlogDir}/{feature}/backlog.json` if configured). Count items with status `complete` vs total. If implementation is less than 80% complete, use `AskUserQuestion` to warn: "Implementation is only N% complete. Documentation will be based primarily on specs and may need updates after implementation. Proceed?" If user proceeds, add a `PRE-IMPLEMENTATION` notice at the top of each generated doc.
+Check `{resolvedFeatureDir}/backlog.json` (or `{backlogDir}/{feature}/backlog.json` if configured). Count items with status `complete` vs total. If implementation is less than 80% complete, use the host's question mechanism to warn: "Implementation is only N% complete. Documentation will be based primarily on specs and may need updates after implementation. Proceed?" If user proceeds, add a `PRE-IMPLEMENTATION` notice at the top of each generated doc.
 
 Also check `.pipeline-state.json` for `stages.forge-5-loop`. If it exists and has status `in-progress` (some items incomplete), include this in the warning: "The rauf loop has not fully completed — {done}/{total} items done. Documentation may need updates after remaining items are implemented."
 
 ### 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 the host's question mechanism 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
 ```
 
 If `render-status` fails, skip the epic-level offer and proceed with the per-feature docs only; surface the error per the exit-1/exit-2 split in the **Feature Directory Resolution** block of `references/shared-conventions.md` (exit 1 → parse `{findings[]}` from stdout; exit 2 → surface the plain `Error:` stderr line verbatim).
 
-**Only if `rollup.total > 0 AND rollup.complete == rollup.total`** (every member is complete-for-orchestration; the `total > 0` guard excludes an empty epic), use `AskUserQuestion` to offer:
+**Only if `rollup.total > 0 AND rollup.complete == rollup.total`** (every member is complete-for-orchestration; the `total > 0` guard excludes an empty epic), use the host's question mechanism to offer:
 
 "All {total} features in the '{epic}' epic are complete. Generate an **epic-level architecture document** spanning the features, in addition to {feature}'s per-feature docs?"
 
@@ -97,7 +97,7 @@ Based on feature complexity and existing doc conventions, propose a doc plan:
     └── adr-001-*.md   — Architecture decision records (if significant decisions were made)
 ```
 
-Present the plan and use `AskUserQuestion` to get the user's confirmation.
+Present the plan and use the host's question mechanism to get the user's confirmation.
 
 ## Step 3: Write Documentation
 
@@ -164,7 +164,7 @@ Adapt export paths to match the project's module/package conventions.
 
 ## Step 4: Review with User
 
-Present the docs as text. Then use `AskUserQuestion` to collect feedback — do NOT include these questions in your text output:
+Present the docs as text. Then use the host's question mechanism to collect feedback — do NOT include these questions in your text output:
 
 "1. Does this accurately reflect the implementation? 2. Is the level of detail appropriate for your team? 3. Any areas that need more explanation?"
 
@@ -187,3 +187,13 @@ Write pipeline state conforming to `references/pipeline-state-schema.json`.
 - API reference should include actual function signatures from the code, not from the spec (they may differ).
 - Don't generate docs that will immediately be stale. Focus on concepts, architecture, and patterns rather than line-by-line code walkthroughs.
 - Include "When to use" and "When NOT to use" sections — they save developers more time than any other documentation pattern.
+
+---
+
+## 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-bootstrap/forge-bootstrap.mdc

@@ -22,7 +22,7 @@ toolchain-missing.
 
 ## Host adaptation (conversational fallback)
 
-If the `AskUserQuestion` tool is available, ask the interview questions through it. If it is
+If the host's question mechanism is available, ask the interview questions through it. If it is
 **not** available (a non-Claude host such as Codex), emit the same questions as a single
 **numbered text list** — each line one question with its options in brackets and the default
 marked — then **stop and wait for a single text reply**. Parse the reply positionally
@@ -31,7 +31,7 @@ options, defaults) and the conditional gating (Q4 skipped for go/rust/generic; Q
 monorepo; Q8 only after a verified-green baseline) are **identical** across both paths — only
 the rendering changes. Never assume answers; always wait for the reply.
 
-Emit any context as plain text, then route **all** questions through `AskUserQuestion` (or the
+Emit any context as plain text, then route **all** questions through the host's question mechanism (or the
 fallback) — never as inline prose questions, which stall the session.
 
 ## Flow (Mode A — default)
@@ -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
 ```
@@ -131,12 +131,12 @@ it null.
 `host` — and pass it verbatim to `scaffold --answers '<json>'`. Invent no fields beyond that
 schema. Two fields come from your runtime, not the interview: `author` from `git config
 user.name` (else the project name; it is the LICENSE copyright holder), and `host` — `"claude"`
-when running under a Claude host (e.g. `AskUserQuestion` is available), else `"codex"`/`"other"`.
+when running under a Claude host (e.g. the host's question mechanism is available), else `"codex"`/`"other"`.
 `host` drives the host-conditional agent file: the helper always emits `AGENTS.md` and adds
 `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]
 ```
@@ -238,3 +238,13 @@ no run ends silently:
 - **Missing toolchain** — `verify` `toolchainPresent:false` (exit 2) → scaffold-anyway-unverified
   vs abort; mark **unverified**.
 - **Partial-state detected** — `check` `resumeMarker != null` → resume / restart / cancel.
+
+---
+
+## 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.