[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75H3DK88DZ6BFQJ2VCWC6T8":3,"skill-same:01M75H3DK88DZ6BFQJ2VCWC6T8":58},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":13,"repositoryHtmlUrl":26,"repositoryHomepageUrl":27,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M75H3DK88DZ6BFQJ2VCWC6T8","forge-1-prd",null,"Create a requirements PRD for a feature through structured interview. Use when user runs \u002Fskill:forge-1-prd or explicitly asks to start the forge pipeline for a new feature. Do NOT trigger for general requirements discussions, project scoping outside forge, or PRD questions unrelated to the forge pipeline.","garygentry\u002Ffeature-forge","garygentry","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F12444042?v=4","01M75GWTRXHQMKFWDVG9N8ENNS","01M75GWTSZ5NV3MYKFWVCZJKW4",0,"MIT","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fpi\u002Fskills\u002Fforge-1-prd\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\n# GENERATED — DO NOT EDIT. Source: skills\u002Fforge-1-prd\u002FSKILL.md. Regenerate: python3 scripts\u002Fbuild-adapters.py\nname: forge-1-prd\ndescription: Create a requirements PRD for a feature through structured interview. Use when user runs \u002Fskill:forge-1-prd or explicitly asks to start the forge pipeline for a new feature. Do NOT trigger for general requirements discussions, project scoping outside forge, or PRD questions unrelated to the forge pipeline.\n---\n\n# forge-1-prd — Requirements Interviewer\n\nCreate a thorough, requirements-only PRD through relentless structured interviewing. The PRD captures WHAT the feature must do, not HOW it will be built.\n\n## Prerequisites\n\nRead and follow `references\u002Fshared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.\n\n**`--force-standalone` (forge-1-prd only).** A distinct flag from `--force`: it bypasses only the **Mint Guard** in Step 1 (letting you intentionally fork a name that is a known epic member into a detached standalone feature). It does **not** imply `--force` — prerequisite checks and the Stage-Entry Guard still run. Use it only when you genuinely mean to create a standalone feature that shares a name with an epic member on another branch.\n\n## Step 1: Read Configuration and Check State\n\n### Branch Setup (if using git)\nInvoke the **Branch Setup** block in `references\u002Fshared-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.\n\nSet the working directory by invoking the **Feature Directory Resolution** block in `references\u002Fshared-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 for a never-started standalone feature — as `not-found` (exit 1) when `{specsDir}\u002F` already exists (other features present), or as `specs dir not found` (exit 2) when `{specsDir}\u002F` itself does not exist yet (the very first feature, or a branch that never had a specs tree). In **both** of those \"about to create a brand-new standalone\" cases forge-1 creates `{specsDir}\u002F{feature}\u002F` as today. (The *other* exit-2 errors — `unsafe-name`, a path-containment escape — are genuine STOPs, never a mint.) 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.\n\n### Mint Guard: refuse to fork a known epic member into a detached standalone (Issue #125)\n\nRun this sub-step **whenever forge-1 is about to mint a brand-new flat standalone `{specsDir}\u002F{feature}\u002F`** — that is, when Feature Directory Resolution returned either `not-found` (exit 1) **or** `specs dir not found` (the exit-2 missing-specs-dir flavor, e.g. a clean default branch that has never had a specs tree). The exit-2 case is the *cleanest* split-brain trigger: on a branch that predates the epic, `{specsDir}\u002F` may not exist at all, yet cross-branch discovery still sees the member on the epic branch. It prevents the split-brain-epic failure where a member of an epic (whose manifest lives on a *different, unmerged* branch) is silently forged as a disjoint standalone feature carrying no `epic` back-pointer. Skip it entirely when resolution succeeded (an epic member's directory already exists — resolution yields the nested path, so this never fires), on the other exit-2 errors (`unsafe-name` \u002F path-containment — those STOP, they never mint), and when `--force-standalone` was passed (see below).\n\n1. Run cross-branch discovery for this exact name (branch-agnostic — it scans all refs regardless of current HEAD):\n   ```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" discover-feature \"{feature}\" --specs-dir \"{specsDir}\" --json\n   ```\n2. **If any candidate has `isEpicMember: true` → HARD STOP.** This is not the soft switch\u002Ffetch\u002Ftreat-as-new menu from the Feature Directory Resolution block — do **not** create any directory and do **not** fall through to the interview. Emit verbatim (filling `{epic}` and `{stateBranch}` from that candidate's `epic` and `stateBranch`):\n   > `{feature}` is a member of epic `{epic}` (recorded on branch `{stateBranch}`). You appear to be on a branch that does not contain that epic. Switch to `{stateBranch}` and run `\u002Fskill:forge-1-prd {feature}` there, or pass `--force-standalone` to intentionally fork a detached standalone feature.\n3. **If candidates exist but none are epic members** → keep today's soft behavior: this is the ordinary cross-branch-discovery case already handled by the Feature Directory Resolution block's **Candidates found** menu (switch \u002F fetch+switch \u002F treat-as-new \u002F stop). Defer to it.\n4. **If nothing was found** (no candidates) → proceed to mint the flat standalone feature as today.\n5. **If `--force-standalone` was passed** → skip this guard entirely, log a one-line warning (\"Forking `{feature}` as a detached standalone despite epic membership on `{stateBranch}`\"), and proceed to create the flat feature. `--force-standalone` is distinct from `--force` and does **not** imply it (see the Force Mode note below).\n\nAfter resolution, invoke the **Stage-Entry Guard** block in `references\u002Fshared-conventions.md` with `{stage}` = `forge-1-prd`. It classifies re-entry (fresh \u002F interrupted \u002F re-authoring), runs the resume-vs-restart gate and the \"create a new version?\" warning as applicable, and applies the entry stamp on the authoring paths. For a brand-new standalone feature there is no state file yet, so the guard's **fresh** arm applies with nothing to prompt; the entry stamp lands when the state file is first created in Step 6.\n\n## Step 2: Examine Existing Context\n\nBefore starting the interview, invoke the **Epic Context Injection** block in `references\u002Fshared-conventions.md`. This block self-gates: it skips entirely if the feature has no `epic` back-pointer, so standalone behavior is unchanged. If this feature is an epic member, the injected charter's `exposes`\u002F`consumes` are requirement inputs — every contract obligation must appear as a REQ in the PRD.\n\n1. **Check the project structure**: Read the project's build configuration and dependency manifests to understand what modules\u002Fpackages exist. Look for `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, workspace configs, or equivalent.\n2. **Check existing specs**: Look at `{specsDir}\u002F` for other features' PRDs to understand conventions and the overall system\n3. **Check existing docs**: Look at the docs directory for architecture documentation\n4. **Note integration surfaces**: Identify which existing packages might be relevant to this feature\n\nThis context helps you ask informed questions and spot gaps the user might not think of.\n\n## Step 3: Conduct the Interview\n\nInterview the user relentlessly. Your goal is to extract complete, unambiguous requirements.\n\nRead `references\u002Fprd-template.md` for the interview structure and question categories. Cover every category. Don't rush — missing a requirement now costs 10x to fix later.\n\n### CRITICAL GUARDRAIL: No Technology Decisions\n\nThe PRD is EXCLUSIVELY about requirements. You MUST enforce this boundary:\n\n**When the user says something like:**\n- \"I want to use Zod for validation\" → Capture as: \"Runtime schema validation with type inference is required.\" Note their Zod preference as a constraint but not a requirement.\n- \"We'll store it in Drizzle\u002FPostgreSQL\" → Capture as: \"Persistent storage required for X data with Y query patterns.\"\n- \"I want a React component that...\" → Capture as: \"A user interface is required that allows users to...\"\n- \"We should use WebSockets for...\" → Capture as: \"Real-time updates are required when X changes, with latency under Y.\"\n- \"I want a REST API\" → Capture as: \"An HTTP-accessible interface is required for X operations\"\n- \"We need a microservice for X\" → Capture as: \"X must be independently deployable and scalable\"\n- \"Use a queue for Y\" → Capture as: \"Y must be processed asynchronously with guaranteed delivery\"\n\n**When YOU start drifting into technology:**\nIf you catch yourself writing about specific libraries, API designs, database schemas, or implementation patterns — STOP. Ask yourself: \"Is this a requirement or an implementation choice?\" Rewrite it as the underlying requirement.\n\n**The one exception:** When a technology choice IS the requirement (e.g., \"must integrate with the existing @repo\u002Fauth package\" or \"must work with our Hono backend\"). These are constraints, and they belong in the Constraints section of the PRD, clearly labeled as such.\n\nA technology constraint is valid when it stems from organizational mandate, existing infrastructure, or team expertise — not from preference. Ask \"Why must it be X specifically?\" If the answer is \"because we already run X in production,\" that's a legitimate constraint. If the answer is \"because it's fast,\" capture the performance requirement instead.\n\n### Interview Approach\n\n**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`. At rung 2\u002F3, follow the Interaction Capability Ladder.\n\n**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.\n\n**Question strategies** (use these as content for `AskUserQuestion`, not as inline prose). The PRD stays at the requirements level (the *what*, not the *how* — that's forge-2-tech), so most questions are open elicitation. But whenever you offer the user a *choice* (scope boundary, MVP cut, a non-functional target), apply the **Decision Support** protocol in `references\u002Fshared-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?\":\n- Probe deeper after each answer: failure modes, stakeholders, minimum viable version\n- Challenge assumptions: which users specifically, what does \"fast\" mean quantitatively\n- Identify edge cases: empty input, concurrent access, scale\n- Capture non-functional requirements: performance, security, accessibility, observability\n- **Record a position on cross-cutting concerns, including when the position is \"out of scope.\"** Concurrency is the recurring one: if the feature writes shared state, the PRD must say whether simultaneous writers are in scope. \"Single writer assumed; atomicity protects only against an interrupted write\" is a complete, valid answer — but it has to be *written down as a requirement*. An unstated position is not neutral: downstream `forge-verify` runs `CHECK-S27` (\"Concurrent access scenarios are addressed if relevant\") against the specs, and with nothing to point at, that check has been observed to induce a full locking protocol that no requirement asked for. State the position and the check resolves in one sentence. The same applies to any concern a verification checklist probes generically — failure modes, ordering, idempotency, resource limits.\n- 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\n\n**Completion criteria:** The interview is complete when:\n1. Every category in `references\u002Fprd-template.md` has been covered with at least one question\n2. The user has confirmed there's nothing else to add\n3. You can draft every PRD section without leaving TBD placeholders\n\nBefore moving to Step 4, summarize your coverage as text, then use `AskUserQuestion` to ask: \"Anything I'm missing?\"\n\n**Parking lot:** If the user raises a concern that belongs to a different pipeline stage, acknowledge it and persist it **immediately, at the moment it is raised** — never deferred to stage closure — by running `state-note` (fenced immediately below) with a concise one-line statement of the concern, then say \"Good point — I've noted that for the [tech spec\u002Fimplementation specs]. Let's continue with [current stage].\" Add `--epic \"{epic}\"` to that call when this feature is an epic member — required, per the Pipeline State Protocol in `references\u002Fshared-conventions.md`; omitting it for a member is an error and must never fall back to a same-named flat feature. `state-note` **overwrites** the single top-level `notes` string rather than appending, so when a note already exists, read the current `notes` value out of the feature's `.pipeline-state.json` first and pass one combined concise string in a single `--note` — never edit or round-trip the JSON by hand. This interview-time call is separate from the optional completion note in Step 6 and must not be folded into it. If the call exits 2, surface the `Error:` line verbatim with the named feature (and epic) and the recovery instruction, and **stop claiming the concern was recorded** — it was not. The full recipe is single-sourced as **Immediate Downstream Note (Parking Lot)** in `references\u002Fshared-conventions.md`.\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" state-note \\\n  --feature \"{feature}\" --note \"\u003Cconcise downstream concern>\" \\\n  --specs-dir \"{specsDir}\"\n```\n\n**Epic-level concern (backflow):** The parking lot above is for concerns about a *later stage of THIS feature*. If instead the interview reveals the **epic decomposition itself** is wrong — a **sibling feature must be added**, a **frozen boundary between features must move**, a feature must **split**, or a **dependency edge is wrong** — that is an *epic-level* concern and does **not** go in `notes`. It only applies when this feature is an epic member (its `.pipeline-state.json` has an `epic` back-pointer); for a standalone feature there is no epic to reconcile, so treat the concern as same-feature or out of scope. To record one, run `state-ecr` (fenced below) with `--kind` (`add-feature`|`redep`|`move-boundary`|`split`), `--target`, `--rationale`, `--raised-by forge-1-prd` and `--blocks-current` — it appends the entry to the member state's `epicChangeRequests[]` array, filling in `raisedAt` (ISO-8601 UTC) and `status: \"open\"` for you. Set `blocksCurrent: true` when the change alters a contract (`exposes`\u002F`consumes`) or dependency edge this feature relies on for its *next* stage (proceeding would build specs on a soon-to-change decomposition); `false` for a peer\u002Fdownstream change this feature does not consume. When the change touches a contract\u002Fdep edge and the classification is genuinely ambiguous, confirm `blocksCurrent` with a single `AskUserQuestion`, defaulting to `true` (a false negative silently diverges two members' contracts). **Do not** edit `epic-manifest.json` here — recording is not applying; only `\u002Fskill:forge-0-epic` edit mode mutates the epic. Then acknowledge without blocking: \"That's an epic-level change — I've recorded it so `forge-0-epic` can reconcile it. [Blocking: We'll want to reconcile the epic before writing specs. | Non-blocking: We can finish this feature first and reconcile when convenient.]\" and continue the interview.\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" state-ecr \\\n  --feature \"{feature}\" --epic \"{epic}\" --kind \"\u003Ckind>\" --target \"\u003Ctarget>\" \\\n  --rationale \"\u003Cwhy>\" --raised-by forge-1-prd --blocks-current \"\u003Ctrue|false>\" \\\n  --specs-dir \"{specsDir}\"\n```\n\n## Step 4: Write the PRD\n\nOnce the interview is thorough, write `{resolvedFeatureDir}\u002FPRD.md` following the structure in `references\u002Fprd-template.md`.\n\nEvery requirement MUST have a unique ID (e.g., REQ-AUTH-01, REQ-PERF-01). These IDs are referenced by all downstream documents.\n\nAfter writing the PRD (this is the point where `{specsDir}\u002F{feature}\u002F` is first created for a standalone feature), invoke the **Specs Directory Hygiene** block in `references\u002Fshared-conventions.md` to ensure `{specsDir}\u002FAGENTS.md` (and `{specsDir}\u002FCLAUDE.md` on the Claude host) exists. It is idempotent — it never overwrites an existing file.\n\n## Step 5: Review with User\n\nThis is a **blocking review** — per the **Stage Review Gate** in `references\u002Fshared-conventions.md`, do not proceed until the user confirms.\n\nPresent the complete PRD to the user. Ask:\n- \"Does this capture everything? Any requirements missing?\"\n- \"Are the priorities correct?\"\n- \"Anything in here that should be out of scope?\"\n\nUse `AskUserQuestion` to collect this feedback.\n\nIterate until the user confirms the PRD is complete.\n\n## Step 6: Update Pipeline State and Commit\n\nBefore writing state or running the stage exit, invoke the **Stage-Completion Re-check** block in `references\u002Fshared-conventions.md` with `{stage}` = `forge-1-prd` — a resumed mid-stage continuation must not overwrite a committed `PRD.md` or re-fire a finished exit.\n\nPipeline state is written by the `state-*` verbs — see the Pipeline State Protocol in `references\u002Fshared-conventions.md`.\n\n1. Record completion by running `state-complete` (below) with `--version` 1 (or the incremented version if revising) and one `--artifact` per file this stage produced. It sets `status: \"complete\"`, `completedAt`, the version and `basedOnVersions` (`{}` here — no upstream dependencies), and applies the downstream staleness cascade deterministically, so no downstream status is set by hand.\n2. **Offer a note — don't force one.** As a statement (not a blocking question), let the user know they can jot anything worth preserving across sessions and you'll store it in the `notes` field. If they volunteer something, store it via `state-note` — it **overwrites** the single `notes` string (latest note wins), so fold any still-relevant existing note into the one combined string; otherwise proceed. The next stage's Step 1 reads and surfaces this note.\n3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references\u002Fshared-conventions.md`: stage files (including `{specsDir}\u002FAGENTS.md` \u002F `{specsDir}\u002FCLAUDE.md` if the Specs Directory Hygiene step just wrote them), attempt commit with message `\"{commitPrefix}({feature}): complete PRD v{n}\"` (marking `stages.forge-1-prd.status` `complete` with `commitHash: null` in that commit), then record the artifact-commit hash via the protocol's two-commit follow-up (never `--amend`) only on success. If commit fails, leave status as `in-progress`.\n4. **Close with the Stage Exit Protocol** (single-sourced in `references\u002Fstage-exit-protocol.md`; do not improvise a \"Next steps\" list):\n\nThe `state-complete` call for item 1 — and the `state-note` call only when the user volunteered a note in item 2 — with the portable plugin-root prelude. Add `--epic \"{epic}\"` to each call when this feature is an epic member — required, per the Pipeline State Protocol in `references\u002Fshared-conventions.md`:\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" state-complete \\\n  --feature \"{feature}\" --stage forge-1-prd --version {n} \\\n  --artifact PRD.md --specs-dir \"{specsDir}\"\n# ONLY run the next call if the user volunteered a note in item 2 — otherwise stop here.\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" state-note \\\n  --feature \"{feature}\" --note \"\u003Cwhat the user volunteered>\" --specs-dir \"{specsDir}\"\n```\n\n**Determine `--verify-capability` before running the exit** per **Host and capability determination** in `references\u002Fstage-exit-protocol.md` (summarized under **Verify Capability** in `references\u002Fshared-conventions.md`): pass `interactive` only when a question mechanism equivalent to `AskUserQuestion` is available **and** dispatching a clean-room `forge-verifier` is *permitted* (the test is \"may I dispatch right now\", not tool presence) — otherwise `manual`. That reference owns the full rule, including why a consent-only bar is still `interactive` and the `none`-gate consent variant. Add `--epic \"{epic}\"` to the call below when this feature is an epic member.\n\n**Close this stage with the Scripted Stage Exit** (contract: `references\u002Fstage-exit-protocol.md`; do not improvise a \"Next steps\" list). Run:\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" stage-exit --feature \"{feature}\" --stage forge-1-prd --specs-dir \"{specsDir}\" --host pi --verify-capability \"{verify-capability}\"\n```\n\nObey the DIRECTIVES it prints, in the consumption order this protocol fixes: surface `invalidAutoVerifyKeys` and every `warnings` entry first; `runInStageVerify: true` → run the in-stage clean-room verify chain now (honoring `autoFixEligible`, and asking through the Standard Verify Gate first when you may not dispatch unsolicited); `verifyGate: \"standard\"` → present the Standard Verify Gate; `verifyGate: \"manual-print\"` → print the `verifyCommand` for the user and do **not** dispatch inline. Then, and only when `terminalOwnedBy` is `\"self\"`, **print the NEXT-STEPS block verbatim as your absolute last output — nothing after its sentinel line.** A `terminalOwnedBy: \"outer\"` payload carries `nextSteps: null`: return your structured result to the caller and print no terminal block at all.\n\n## Gotchas\n\n- Users often front-load their feature description with tech decisions because that's how engineers think. Gently but firmly redirect to requirements. Don't be preachy about it — just reframe what they said.\n- 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.\n- 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.\n- 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.\n\n---\n\n## Host execution notes (Pi)\n\nThis Pi bundle preserves Claude's `AskUserQuestion` references because it ships a Pi compatibility extension registering an `AskUserQuestion` tool. On Pi:\n\n- **User input:** use `AskUserQuestion` for genuine user decisions. It supports multiple questions, option descriptions, recommended ordering, multi-select, previews, and free-form Other\u002Fcustom answers.\n- **Non-interactive (`-p`\u002F`--mode json`):** `AskUserQuestion` is stripped from the tool list, so its absence alone cannot tell you the rung — read that from the Interaction Capability Ladder's `interaction-mode` record. A call attempted anyway fails with `Error: UI not available (running in non-interactive mode)` — never read that as a decline. Take the Interaction Capability Ladder's declared conservative default, state it in your output, and use `no-default: abort — \u003Cquestion> requires a human answer` for an interview question with no sane default (`references\u002Fshared-conventions.md`).\n- **Skill dispatch:** Pi uses `\u002Fskill:\u003Cname>` commands. If you cannot invoke a skill directly, print the exact `\u002Fskill:\u003Cname> ...` command for the user to run. A **forge-invocation-args** compatibility extension wraps the arguments of a `\u002Fskill:forge-*` command in a `\u003Cfeature-forge-invocation>` envelope before Pi expands it, so read the feature name from that envelope's `\u003Carguments>` element (an empty element means none was supplied) rather than from unlabeled trailing text — see `references\u002Fshared-conventions.md` § Feature Name Requirement.\n- **Subagents:** this bundle declares its custom agents (`forge-researcher`, `forge-spec-writer`, `forge-verifier`) as package agents. If a `subagent` tool is registered, dispatch one with `{ agent: \"forge-verifier\", task: \"...\" }`, or fan several out concurrently with `{ tasks: [{ agent: \"forge-spec-writer\", task: \"...\" }, ...] }`. If no `subagent` tool is available, run that step inline yourself.\n- **Background \u002F monitoring (forge-5-loop):** run the loop through **rauf's Pi package** (`pi install npm:@garygentry\u002Frauf`, rauf >= 0.18.0), whose `rauf-loop-supervisor` extension registers `rauf_loop_launch`, `rauf_loop_status`, `rauf_loop_wait` and `rauf_loop_stop`. Launch with `rauf_loop_launch`; it starts the loop **detached** (it outlives this session), posts a one-line card per completed item, and **wakes this session** on needs-human, blocked, stuck, review failure, loop errors and completion — so end your turn after the launch: do not poll, sleep, tail, run the loop in the foreground or behind `nohup`\u002F`&`, or hand it to a subagent (the extension blocks those calls). Read `rauf_loop_status` before acting on a wake; use `rauf_loop_stop` only to deliberately stop the runner. Full detail: `references\u002Frunner-contract.md` Steps 3b\u002F3d. If the `rauf_loop_*` tools are not registered, `forge-session.py doctor` says how to install the package; until then use the `rauf loop wait` recipe there.\n","# forge-1-prd — Requirements Interviewer\n\nCreate a thorough, requirements-only PRD through relentless structured interviewing. The PRD captures WHAT the feature must do, not HOW it will be built.\n\n## Prerequisites\n\nRead and follow `references\u002Fshared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.\n\n**`--force-standalone` (forge-1-prd only).** A distinct flag from `--force`: it bypasses only the **Mint Guard** in Step 1 (letting you intentionally fork a name that is a known epic member into a detached standalone feature). It does **not** imply `--force` — prerequisite checks and the Stage-Entry Guard still run. Use it only when you genuinely mean to create a standalone feature that shares a name with an epic member on another branch.\n\n## Step 1: Read Configuration and Check State\n\n### Branch Setup (if using git)\nInvoke the **Branch Setup** block in `references\u002Fshared-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.\n\nSet the working directory by invoking the **Feature Directory Resolution** block in `references\u002Fshared-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 for a never-started standalone feature — as `not-found` (exit 1) when `{specsDir}\u002F` already exists (other features present), or as `specs dir not found` (exit 2) when `{specsDir}\u002F` itself does not exist yet (the very first feature, or a branch that never had a specs tree). In **both** of those \"about to create a brand-new standalone\" cases forge-1 creates `{specsDir}\u002F{feature}\u002F` as today. (The *other* exit-2 errors — `unsafe-name`, a path-containment escape — are genuine STOPs, never a mint.) 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.\n\n### Mint Guard: refuse to fork a known epic member into a detached standalone (Issue #125)\n\nRun this sub-step **whenever forge-1 is about to mint a brand-new flat standalone `{specsDir}\u002F{feature}\u002F`** — that is, when Feature Directory Resolution returned either `not-found` (exit 1) **or** `specs dir not found` (the exit-2 missing-specs-dir flavor, e.g. a clean default branch that has never had a specs tree). The exit-2 case is the *cleanest* split-brain trigger: on a branch that predates the epic, `{specsDir}\u002F` may not exist at all, yet cross-branch discovery still sees the member on the epic branch. It prevents the split-brain-epic failure where a member of an epic (whose manifest lives on a *different, unmerged* branch) is silently forged as a disjoint standalone feature carrying no `epic` back-pointer. Skip it entirely when resolution succeeded (an epic member's directory already exists — resolution yields the nested path, so this never fires), on the other exit-2 errors (`unsafe-name` \u002F path-containment — those STOP, they never mint), and when `--force-standalone` was passed (see below).\n\n1. Run cross-branch discovery for this exact name (branch-agnostic — it scans all refs regardless of current HEAD):\n   ```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" discover-feature \"{feature}\" --specs-dir \"{specsDir}\" --json\n   ```\n2. **If any candidate has `isEpicMember: true` → HARD STOP.** This is not the soft switch\u002Ffetch\u002Ftreat-as-new menu from the Feature Directory Resolution block — do **not** create any directory and do **not** fall through to the interview. Emit verbatim (filling `{epic}` and `{stateBranch}` from that candidate's `epic` and `stateBranch`):\n   > `{feature}` is a member of epic `{epic}` (recorded on branch `{stateBranch}`). You appear to be on a branch that does not contain that epic. Switch to `{stateBranch}` and run `\u002Fskill:forge-1-prd {feature}` there, or pass `--force-standalone` to intentionally fork a detached standalone feature.\n3. **If candidates exist but none are epic members** → keep today's soft behavior: this is the ordinary cross-branch-discovery case already handled by the Feature Directory Resolution block's **Candidates found** menu (switch \u002F fetch+switch \u002F treat-as-new \u002F stop). Defer to it.\n4. **If nothing was found** (no candidates) → proceed to mint the flat standalone feature as today.\n5. **If `--force-standalone` was passed** → skip this guard entirely, log a one-line warning (\"Forking `{feature}` as a detached standalone despite epic membership on `{stateBranch}`\"), and proceed to create the flat feature. `--force-standalone` is distinct from `--force` and does **not** imply it (see the Force Mode note below).\n\nAfter resolution, invoke the **Stage-Entry Guard** block in `references\u002Fshared-conventions.md` with `{stage}` = `forge-1-prd`. It classifies re-entry (fresh \u002F interrupted \u002F re-authoring), runs the resume-vs-restart gate and the \"create a new version?\" warning as applicable, and applies the entry stamp on the authoring paths. For a brand-new standalone feature there is no state file yet, so the guard's **fresh** arm applies with nothing to prompt; the entry stamp lands when the state file is first created in Step 6.\n\n## Step 2: Examine Existing Context\n\nBefore starting the interview, invoke the **Epic Context Injection** block in `references\u002Fshared-conventions.md`. This block self-gates: it skips entirely if the feature has no `epic` back-pointer, so standalone behavior is unchanged. If this feature is an epic member, the injected charter's `exposes`\u002F`consumes` are requirement inputs — every contract obligation must appear as a REQ in the PRD.\n\n1. **Check the project structure**: Read the project's build configuration and dependency manifests to understand what modules\u002Fpackages exist. Look for `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, workspace configs, or equivalent.\n2. **Check existing specs**: Look at `{specsDir}\u002F` for other features' PRDs to understand conventions and the overall system\n3. **Check existing docs**: Look at the docs directory for architecture documentation\n4. **Note integration surfaces**: Identify which existing packages might be relevant to this feature\n\nThis context helps you ask informed questions and spot gaps the user might not think of.\n\n## Step 3: Conduct the Interview\n\nInterview the user relentlessly. Your goal is to extract complete, unambiguous requirements.\n\nRead `references\u002Fprd-template.md` for the interview structure and question categories. Cover every category. Don't rush — missing a requirement now costs 10x to fix later.\n\n### CRITICAL GUARDRAIL: No Technology Decisions\n\nThe PRD is EXCLUSIVELY about requirements. You MUST enforce this boundary:\n\n**When the user says something like:**\n- \"I want to use Zod for validation\" → Capture as: \"Runtime schema validation with type inference is required.\" Note their Zod preference as a constraint but not a requirement.\n- \"We'll store it in Drizzle\u002FPostgreSQL\" → Capture as: \"Persistent storage required for X data with Y query patterns.\"\n- \"I want a React component that...\" → Capture as: \"A user interface is required that allows users to...\"\n- \"We should use WebSockets for...\" → Capture as: \"Real-time updates are required when X changes, with latency under Y.\"\n- \"I want a REST API\" → Capture as: \"An HTTP-accessible interface is required for X operations\"\n- \"We need a microservice for X\" → Capture as: \"X must be independently deployable and scalable\"\n- \"Use a queue for Y\" → Capture as: \"Y must be processed asynchronously with guaranteed delivery\"\n\n**When YOU start drifting into technology:**\nIf you catch yourself writing about specific libraries, API designs, database schemas, or implementation patterns — STOP. Ask yourself: \"Is this a requirement or an implementation choice?\" Rewrite it as the underlying requirement.\n\n**The one exception:** When a technology choice IS the requirement (e.g., \"must integrate with the existing @repo\u002Fauth package\" or \"must work with our Hono backend\"). These are constraints, and they belong in the Constraints section of the PRD, clearly labeled as such.\n\nA technology constraint is valid when it stems from organizational mandate, existing infrastructure, or team expertise — not from preference. Ask \"Why must it be X specifically?\" If the answer is \"because we already run X in production,\" that's a legitimate constraint. If the answer is \"because it's fast,\" capture the performance requirement instead.\n\n### Interview Approach\n\n**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`. At rung 2\u002F3, follow the Interaction Capability Ladder.\n\n**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.\n\n**Question strategies** (use these as content for `AskUserQuestion`, not as inline prose). The PRD stays at the requirements level (the *what*, not the *how* — that's forge-2-tech), so most questions are open elicitation. But whenever you offer the user a *choice* (scope boundary, MVP cut, a non-functional target), apply the **Decision Support** protocol in `references\u002Fshared-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?\":\n- Probe deeper after each answer: failure modes, stakeholders, minimum viable version\n- Challenge assumptions: which users specifically, what does \"fast\" mean quantitatively\n- Identify edge cases: empty input, concurrent access, scale\n- Capture non-functional requirements: performance, security, accessibility, observability\n- **Record a position on cross-cutting concerns, including when the position is \"out of scope.\"** Concurrency is the recurring one: if the feature writes shared state, the PRD must say whether simultaneous writers are in scope. \"Single writer assumed; atomicity protects only against an interrupted write\" is a complete, valid answer — but it has to be *written down as a requirement*. An unstated position is not neutral: downstream `forge-verify` runs `CHECK-S27` (\"Concurrent access scenarios are addressed if relevant\") against the specs, and with nothing to point at, that check has been observed to induce a full locking protocol that no requirement asked for. State the position and the check resolves in one sentence. The same applies to any concern a verification checklist probes generically — failure modes, ordering, idempotency, resource limits.\n- 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\n\n**Completion criteria:** The interview is complete when:\n1. Every category in `references\u002Fprd-template.md` has been covered with at least one question\n2. The user has confirmed there's nothing else to add\n3. You can draft every PRD section without leaving TBD placeholders\n\nBefore moving to Step 4, summarize your coverage as text, then use `AskUserQuestion` to ask: \"Anything I'm missing?\"\n\n**Parking lot:** If the user raises a concern that belongs to a different pipeline stage, acknowledge it and persist it **immediately, at the moment it is raised** — never deferred to stage closure — by running `state-note` (fenced immediately below) with a concise one-line statement of the concern, then say \"Good point — I've noted that for the [tech spec\u002Fimplementation specs]. Let's continue with [current stage].\" Add `--epic \"{epic}\"` to that call when this feature is an epic member — required, per the Pipeline State Protocol in `references\u002Fshared-conventions.md`; omitting it for a member is an error and must never fall back to a same-named flat feature. `state-note` **overwrites** the single top-level `notes` string rather than appending, so when a note already exists, read the current `notes` value out of the feature's `.pipeline-state.json` first and pass one combined concise string in a single `--note` — never edit or round-trip the JSON by hand. This interview-time call is separate from the optional completion note in Step 6 and must not be folded into it. If the call exits 2, surface the `Error:` line verbatim with the named feature (and epic) and the recovery instruction, and **stop claiming the concern was recorded** — it was not. The full recipe is single-sourced as **Immediate Downstream Note (Parking Lot)** in `references\u002Fshared-conventions.md`.\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" state-note \\\n  --feature \"{feature}\" --note \"\u003Cconcise downstream concern>\" \\\n  --specs-dir \"{specsDir}\"\n```\n\n**Epic-level concern (backflow):** The parking lot above is for concerns about a *later stage of THIS feature*. If instead the interview reveals the **epic decomposition itself** is wrong — a **sibling feature must be added**, a **frozen boundary between features must move**, a feature must **split**, or a **dependency edge is wrong** — that is an *epic-level* concern and does **not** go in `notes`. It only applies when this feature is an epic member (its `.pipeline-state.json` has an `epic` back-pointer); for a standalone feature there is no epic to reconcile, so treat the concern as same-feature or out of scope. To record one, run `state-ecr` (fenced below) with `--kind` (`add-feature`|`redep`|`move-boundary`|`split`), `--target`, `--rationale`, `--raised-by forge-1-prd` and `--blocks-current` — it appends the entry to the member state's `epicChangeRequests[]` array, filling in `raisedAt` (ISO-8601 UTC) and `status: \"open\"` for you. Set `blocksCurrent: true` when the change alters a contract (`exposes`\u002F`consumes`) or dependency edge this feature relies on for its *next* stage (proceeding would build specs on a soon-to-change decomposition); `false` for a peer\u002Fdownstream change this feature does not consume. When the change touches a contract\u002Fdep edge and the classification is genuinely ambiguous, confirm `blocksCurrent` with a single `AskUserQuestion`, defaulting to `true` (a false negative silently diverges two members' contracts). **Do not** edit `epic-manifest.json` here — recording is not applying; only `\u002Fskill:forge-0-epic` edit mode mutates the epic. Then acknowledge without blocking: \"That's an epic-level change — I've recorded it so `forge-0-epic` can reconcile it. [Blocking: We'll want to reconcile the epic before writing specs. | Non-blocking: We can finish this feature first and reconcile when convenient.]\" and continue the interview.\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" state-ecr \\\n  --feature \"{feature}\" --epic \"{epic}\" --kind \"\u003Ckind>\" --target \"\u003Ctarget>\" \\\n  --rationale \"\u003Cwhy>\" --raised-by forge-1-prd --blocks-current \"\u003Ctrue|false>\" \\\n  --specs-dir \"{specsDir}\"\n```\n\n## Step 4: Write the PRD\n\nOnce the interview is thorough, write `{resolvedFeatureDir}\u002FPRD.md` following the structure in `references\u002Fprd-template.md`.\n\nEvery requirement MUST have a unique ID (e.g., REQ-AUTH-01, REQ-PERF-01). These IDs are referenced by all downstream documents.\n\nAfter writing the PRD (this is the point where `{specsDir}\u002F{feature}\u002F` is first created for a standalone feature), invoke the **Specs Directory Hygiene** block in `references\u002Fshared-conventions.md` to ensure `{specsDir}\u002FAGENTS.md` (and `{specsDir}\u002FCLAUDE.md` on the Claude host) exists. It is idempotent — it never overwrites an existing file.\n\n## Step 5: Review with User\n\nThis is a **blocking review** — per the **Stage Review Gate** in `references\u002Fshared-conventions.md`, do not proceed until the user confirms.\n\nPresent the complete PRD to the user. Ask:\n- \"Does this capture everything? Any requirements missing?\"\n- \"Are the priorities correct?\"\n- \"Anything in here that should be out of scope?\"\n\nUse `AskUserQuestion` to collect this feedback.\n\nIterate until the user confirms the PRD is complete.\n\n## Step 6: Update Pipeline State and Commit\n\nBefore writing state or running the stage exit, invoke the **Stage-Completion Re-check** block in `references\u002Fshared-conventions.md` with `{stage}` = `forge-1-prd` — a resumed mid-stage continuation must not overwrite a committed `PRD.md` or re-fire a finished exit.\n\nPipeline state is written by the `state-*` verbs — see the Pipeline State Protocol in `references\u002Fshared-conventions.md`.\n\n1. Record completion by running `state-complete` (below) with `--version` 1 (or the incremented version if revising) and one `--artifact` per file this stage produced. It sets `status: \"complete\"`, `completedAt`, the version and `basedOnVersions` (`{}` here — no upstream dependencies), and applies the downstream staleness cascade deterministically, so no downstream status is set by hand.\n2. **Offer a note — don't force one.** As a statement (not a blocking question), let the user know they can jot anything worth preserving across sessions and you'll store it in the `notes` field. If they volunteer something, store it via `state-note` — it **overwrites** the single `notes` string (latest note wins), so fold any still-relevant existing note into the one combined string; otherwise proceed. The next stage's Step 1 reads and surfaces this note.\n3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references\u002Fshared-conventions.md`: stage files (including `{specsDir}\u002FAGENTS.md` \u002F `{specsDir}\u002FCLAUDE.md` if the Specs Directory Hygiene step just wrote them), attempt commit with message `\"{commitPrefix}({feature}): complete PRD v{n}\"` (marking `stages.forge-1-prd.status` `complete` with `commitHash: null` in that commit), then record the artifact-commit hash via the protocol's two-commit follow-up (never `--amend`) only on success. If commit fails, leave status as `in-progress`.\n4. **Close with the Stage Exit Protocol** (single-sourced in `references\u002Fstage-exit-protocol.md`; do not improvise a \"Next steps\" list):\n\nThe `state-complete` call for item 1 — and the `state-note` call only when the user volunteered a note in item 2 — with the portable plugin-root prelude. Add `--epic \"{epic}\"` to each call when this feature is an epic member — required, per the Pipeline State Protocol in `references\u002Fshared-conventions.md`:\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" state-complete \\\n  --feature \"{feature}\" --stage forge-1-prd --version {n} \\\n  --artifact PRD.md --specs-dir \"{specsDir}\"\n# ONLY run the next call if the user volunteered a note in item 2 — otherwise stop here.\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" state-note \\\n  --feature \"{feature}\" --note \"\u003Cwhat the user volunteered>\" --specs-dir \"{specsDir}\"\n```\n\n**Determine `--verify-capability` before running the exit** per **Host and capability determination** in `references\u002Fstage-exit-protocol.md` (summarized under **Verify Capability** in `references\u002Fshared-conventions.md`): pass `interactive` only when a question mechanism equivalent to `AskUserQuestion` is available **and** dispatching a clean-room `forge-verifier` is *permitted* (the test is \"may I dispatch right now\", not tool presence) — otherwise `manual`. That reference owns the full rule, including why a consent-only bar is still `interactive` and the `none`-gate consent variant. Add `--epic \"{epic}\"` to the call below when this feature is an epic member.\n\n**Close this stage with the Scripted Stage Exit** (contract: `references\u002Fstage-exit-protocol.md`; do not improvise a \"Next steps\" list). Run:\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" stage-exit --feature \"{feature}\" --stage forge-1-prd --specs-dir \"{specsDir}\" --host pi --verify-capability \"{verify-capability}\"\n```\n\nObey the DIRECTIVES it prints, in the consumption order this protocol fixes: surface `invalidAutoVerifyKeys` and every `warnings` entry first; `runInStageVerify: true` → run the in-stage clean-room verify chain now (honoring `autoFixEligible`, and asking through the Standard Verify Gate first when you may not dispatch unsolicited); `verifyGate: \"standard\"` → present the Standard Verify Gate; `verifyGate: \"manual-print\"` → print the `verifyCommand` for the user and do **not** dispatch inline. Then, and only when `terminalOwnedBy` is `\"self\"`, **print the NEXT-STEPS block verbatim as your absolute last output — nothing after its sentinel line.** A `terminalOwnedBy: \"outer\"` payload carries `nextSteps: null`: return your structured result to the caller and print no terminal block at all.\n\n## Gotchas\n\n- Users often front-load their feature description with tech decisions because that's how engineers think. Gently but firmly redirect to requirements. Don't be preachy about it — just reframe what they said.\n- 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.\n- 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.\n- 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.\n\n---\n\n## Host execution notes (Pi)\n\nThis Pi bundle preserves Claude's `AskUserQuestion` references because it ships a Pi compatibility extension registering an `AskUserQuestion` tool. On Pi:\n\n- **User input:** use `AskUserQuestion` for genuine user decisions. It supports multiple questions, option descriptions, recommended ordering, multi-select, previews, and free-form Other\u002Fcustom answers.\n- **Non-interactive (`-p`\u002F`--mode json`):** `AskUserQuestion` is stripped from the tool list, so its absence alone cannot tell you the rung — read that from the Interaction Capability Ladder's `interaction-mode` record. A call attempted anyway fails with `Error: UI not available (running in non-interactive mode)` — never read that as a decline. Take the Interaction Capability Ladder's declared conservative default, state it in your output, and use `no-default: abort — \u003Cquestion> requires a human answer` for an interview question with no sane default (`references\u002Fshared-conventions.md`).\n- **Skill dispatch:** Pi uses `\u002Fskill:\u003Cname>` commands. If you cannot invoke a skill directly, print the exact `\u002Fskill:\u003Cname> ...` command for the user to run. A **forge-invocation-args** compatibility extension wraps the arguments of a `\u002Fskill:forge-*` command in a `\u003Cfeature-forge-invocation>` envelope before Pi expands it, so read the feature name from that envelope's `\u003Carguments>` element (an empty element means none was supplied) rather than from unlabeled trailing text — see `references\u002Fshared-conventions.md` § Feature Name Requirement.\n- **Subagents:** this bundle declares its custom agents (`forge-researcher`, `forge-spec-writer`, `forge-verifier`) as package agents. If a `subagent` tool is registered, dispatch one with `{ agent: \"forge-verifier\", task: \"...\" }`, or fan several out concurrently with `{ tasks: [{ agent: \"forge-spec-writer\", task: \"...\" }, ...] }`. If no `subagent` tool is available, run that step inline yourself.\n- **Background \u002F monitoring (forge-5-loop):** run the loop through **rauf's Pi package** (`pi install npm:@garygentry\u002Frauf`, rauf >= 0.18.0), whose `rauf-loop-supervisor` extension registers `rauf_loop_launch`, `rauf_loop_status`, `rauf_loop_wait` and `rauf_loop_stop`. Launch with `rauf_loop_launch`; it starts the loop **detached** (it outlives this session), posts a one-line card per completed item, and **wakes this session** on needs-human, blocked, stuck, review failure, loop errors and completion — so end your turn after the launch: do not poll, sleep, tail, run the loop in the foreground or behind `nohup`\u002F`&`, or hand it to a subagent (the extension blocks those calls). Read `rauf_loop_status` before acting on a wake; use `rauf_loop_stop` only to deliberately stop the runner. Full detail: `references\u002Frunner-contract.md` Steps 3b\u002F3d. If the `rauf_loop_*` tools are not registered, `forge-session.py doctor` says how to install the package; until then use the `rauf loop wait` recipe there.\n",{"name":5,"description":7},"main","ce0d6d40bba1d87039b0397041d15cb56c934037","adapters\u002Fpi\u002Fskills\u002Fforge-1-prd","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge","https:\u002F\u002Fgarygentry.github.io\u002Ffeature-forge\u002F","https:\u002F\u002Fgithub.com\u002Fgarygentry","2026-10-15 10:14:13",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add garygentry\u002Ffeature-forge --skill forge-1-prd",{"tool":36,"command":37},"bunx","bunx skills add garygentry\u002Ffeature-forge --skill forge-1-prd",{"tool":39,"command":40},"pnpm","pnpm dlx skills add garygentry\u002Ffeature-forge --skill forge-1-prd","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fpi\u002Fskills\u002Fforge-1-prd\u002FSKILL.md",true,[44,50,54],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":48,"sourceHtmlUrl":49},"references\u002Fprd-template.md","REFERENCE","参考文档",3326,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fpi\u002Fskills\u002Fforge-1-prd\u002Freferences\u002Fprd-template.md",{"path":51,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":52,"sourceHtmlUrl":53},"references\u002Fshared-conventions.md",73992,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fpi\u002Fskills\u002Fforge-1-prd\u002Freferences\u002Fshared-conventions.md",{"path":55,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":56,"sourceHtmlUrl":57},"references\u002Fstage-exit-protocol.md",35623,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fpi\u002Fskills\u002Fforge-1-prd\u002Freferences\u002Fstage-exit-protocol.md",[59,66,71,77,82,88],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":18},"01M75H8RTWSJ2HYCPPKA3FRG42","alpha","A valid skill description.","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-nested-metadata\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":67,"name":61,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":18},"01M75H8QXKFS116EF1009KB3CY","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-malformed\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":72,"name":61,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":18},"01M75H8PKNSV4WEREK6D91G9T4","This is a folded scalar description.","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-folded-scalar\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":78,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":18},"01M75H8MAV261C8QJ4S8CGRHV5","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-crlf\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":83,"name":61,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":18},"01M75H8KDW98YF0PBHPD5V1GKR","foo: bar","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-colon-value\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":89,"name":61,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":18},"01M75H8JFYFCGYNRCRTS4PMKKX","A valid description.","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-blank-lines\u002Fskills\u002Falpha\u002FSKILL.md",[],[]]