@garygentry/feature-forge 0.2.14 → 0.3.1

package/adapters/pi/skills/forge-0-epic/references/stage-exit-protocol.md

@@ -0,0 +1,268 @@
+# Stage Exit Protocol
+
+The single source of truth for how every forge **authoring** stage closes. It
+replaces the old ad-hoc "Next steps:" bullet lists with one fixed, correctly-ordered
+sequence: **verify (if missing or stale) → `/clear` → run the next command.**
+
+Two principles this protocol encodes (do not relitigate — they are locked product
+decisions):
+
+1. **Clearing is recommended on its own merits at every stage boundary** — a clean
+   start for the next stage — *not* as a proxy for a full context window. Window
+   fullness only changes *how emphatically* the clear is recommended, never *whether*
+   it is.
+2. **Verify happens before the clear, never after** — in the authoring session, whether
+   manual **or** auto. Verify's clean-room subagent is dispatched from the *current*
+   session, so the findings digest and any fix decision land where the context to act on
+   them still exists. This holds for auto-verify too: the stage skill dispatches the
+   clean-room verify (and any autoFix) at stage end, in-session, before the exit — it is
+   **not** deferred to the navigator, which runs *after* the `/clear` with none of the
+   authoring context. Clearing first throws that context away.
+
+## How this file is used
+
+The five authoring stages (`forge-0-epic` … `forge-4-backlog`) close with the
+**Scripted Stage Exit**: a short stamped block (below) that runs
+`forge-session.py stage-exit`, obeys the DIRECTIVES it prints per the **directive
+contract** in this file, and prints the script-emitted NEXT-STEPS block verbatim as the
+absolute last output. All the conditional logic the old prose blocks asked the model to
+compute (effective auto-verify, freshness collapse, gate selection, host wording) now
+lives in the script, deterministically; only genuinely interactive work (clean-room
+subagent dispatch, `AskUserQuestion` gates) remains prose — specified once here, not
+per stage.
+
+The loop (`forge-5-loop`) keeps its bespoke exits: it stamps the **standard block**
+(step-6 epic-member handoff) and the **warm variant** (all-done closing) below,
+verbatim. `forge-6-docs` is **terminal** — it stamps no exit block.
+
+A drift-guard test (`tests/test_stage_exit_protocol.py`) asserts each stamp site still
+contains its block, so an edit here must be mirrored into every stamp site (and
+vice-versa).
+
+## Stamp sites
+
+| Stamp site | Block |
+|---|---|
+| `forge-0-epic` … `forge-4-backlog` | scripted-stage-exit stamp |
+| `forge-5-loop` (step-6 epic-member handoff) | standard |
+| `forge-5-loop` (all-done closing → docs) | warm |
+
+The scripted stamp fills one build-time slot, `{stage-exit-args}` — the per-stage
+argument list (e.g. `--feature "{feature}" --stage forge-2-tech`; the epic stage passes
+`--feature "{epic}" --stage forge-0-epic --next-feature "{first-actionable-feature}"`).
+`{feature}` / `{epic}` / `{specsDir}` / `{first-actionable-feature}` remain runtime
+placeholders the skill resolves before running the command, exactly as elsewhere.
+
+<!-- BEGIN: scripted-stage-exit-stamp -->
+**Close this stage with the Scripted Stage Exit** (contract: `references/stage-exit-protocol.md`; do not improvise a "Next steps" list). Run:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/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-session.py" stage-exit {stage-exit-args} --specs-dir "{specsDir}" --host claude
+```
+
+Obey the DIRECTIVES it prints, in order, per the directive contract: `runInStageVerify: true` → dispatch the in-stage clean-room verify now (honoring `autoFixEligible`); `verifyGate: "standard"` → present the Standard Verify Gate; `verifyGate: "manual-print"` → print the `verifyCommand` for the user; non-empty `invalidAutoVerifyKeys` → print a one-line warning. Then **print the NEXT-STEPS block verbatim as your absolute last output — nothing after its sentinel line.**
+<!-- END: scripted-stage-exit-stamp -->
+
+## Directive contract
+
+`stage-exit` emits a DIRECTIVES object and a NEXT-STEPS block. The skill executes the
+directives **in this order**; the script has already computed every conditional, so a
+directive is an instruction, not a question to re-derive.
+
+### `invalidAutoVerifyKeys` (non-empty)
+
+Print a one-line warning first (e.g. "⚠️ forge.config.json `autoVerifyStages` has
+unknown keys: … — they are ignored; fix the typo").
+
+### `runInStageVerify: true` — in-stage auto-verify {stageNoun}
+
+Auto-verify is effective for this stage and verification is outstanding — verify **now,
+in this session** (principle #2 applied to auto-verify: the digest and any fix decision
+land here, where the authoring context still exists — not deferred to a post-`/clear`
+navigator):
+
+1. **Clean-room verify (require-clean).** Dispatch the clean-room `forge-verifier`
+   subagent from this session in require-clean mode — the same path the navigator uses
+   (`skills/forge-verify/SKILL.md`). Dispatch it **synchronously and await its digest
+   inline** — do **not** run it in the background or announce it as "still running";
+   the digest and any fix decision must land in this session. It inherits none of this
+   session's context, so no `/clear` is needed and only a compact digest returns.
+   **Clean-room unavailable** (no `Agent` tool, `forge-verifier` not dispatchable) **or
+   a non-answer returned** (the verifier returned a placeholder / "still running" /
+   delegation message instead of a findings block): do **not** run inline and do **not**
+   silently accept the non-answer as a pass — leave verify **pending** so the navigator
+   catch-up fires on a later Claude-host `/skill:forge`, print the
+   `verifyCommand` for the user to run, and continue to the NEXT-STEPS block.
+2. **Verify passed / no findings** → the fresh verify state is recorded by the
+   clean-room run; continue to the NEXT-STEPS block.
+3. **Verify found findings** →
+   - **`autoFixEligible: true` AND the findings document has zero unresolved decision
+     points** → chain `feature-forge:forge-fix` in-session (it owns its own commit +
+     step tracking), then run a **mandatory re-verify** in require-clean mode. Continue
+     to the NEXT-STEPS block only if the re-verify passes. On any precondition miss, a
+     forge-fix early stop, or a red re-verify, fall through to the digest gate below —
+     never a silent partial mutation. (`autoFixEligible` already folds in the config
+     `autoFix` flag and the clean-tree precondition; a dirty tree or
+     `gitCommitAfterStage: false` arrives here as `false`.)
+   - **`autoFixEligible: false`, or unresolved decision points** → surface a **compact
+     findings digest** as text, then present the gate via `AskUserQuestion`: **Run
+     `forge-fix` now** *(recommended — you are in-context and the digest is right
+     here)* / **Clear + advance anyway** (leave the findings for later) / **Stop
+     here**. Do **not** hard-stop and do **not** silently walk past. Act on the choice,
+     then continue to the NEXT-STEPS block.
+
+### `verifyGate: "standard"` — the Standard Verify Gate
+
+Auto-verify is off for this stage and verification is outstanding (`verifyState` is
+`never`, `stale`, or `failing`). Verify **now, before clearing**, using
+`AskUserQuestion` with exactly these three options — but only when the host has a
+question mechanism **and** the clean-room path is available (the `Agent` tool plus a
+dispatchable `forge-verifier` subagent); otherwise degrade exactly as `manual-print`
+below:
+
+- **Verify {stageNoun} now** *(recommended)* — dispatch the clean-room `forge-verifier`
+  subagent from this session in require-clean mode; the digest returns here so any fix
+  decision keeps its context. One-time — it does **not** change config.
+- **Verify now + enable auto-verify going forward** — verify now **and** patch
+  `"autoVerify": true` into `forge.config.json` in place (preserve formatting and every
+  other key) so future stages verify automatically, no prompt. This complements the
+  `forge-init` opt-in. **Do not auto-commit this config change** — treat it like
+  `notes`: a user-facing edit the user commits on their own cadence, never folded into
+  a stage's artifact commit.
+- **Skip for now** — go straight to the NEXT-STEPS block without verifying. Record this
+  stage's verify status as `"skipped"` in pipeline state (mirroring the existing skip
+  handling) **only** on an explicit skip — a skip does not go stale.
+
+If verify runs and finds findings, handle them exactly as in the in-stage flow above
+(digest + `AskUserQuestion` gate; `autoFixEligible` applies unchanged).
+
+### `verifyGate: "manual-print"`
+
+Verification is outstanding but the host cannot present the gate or dispatch
+clean-room. Do **not** run verify inline — print the `verifyCommand` for the user to
+run (mirroring `autoInvokeNextStage`), offer the auto-verify enable as plain text only
+if a config write is possible, and continue to the NEXT-STEPS block. Verify state stays
+outstanding, so the navigator catch-up can fire later.
+
+### `verifyGate: "none"`
+
+Verification is already resolved (fresh or explicitly skipped) or the in-stage run
+above covers it. Say so in one line and continue to the NEXT-STEPS block.
+
+### `epicReconcile` (epic backflow — present only when there are open requests)
+
+Emitted only when the exiting member carries `open` `epicChangeRequests` (recorded by
+`forge-1-prd`/`forge-2-tech` when the epic *decomposition* itself must change — see
+`references/pipeline-state-schema.json`). Absent on the common path and for standalone
+features. The script has already folded the routing into the NEXT-STEPS block, so this
+directive is informational — you do **not** re-derive the wording:
+
+- `required: true` (at least one `blocksCurrent: true` request) — the NEXT-STEPS block's
+  fenced **primary** command is the epic reconcile command
+  (`/skill:forge-0-epic {epic}`), and the normal next stage is demoted to a
+  follow-up line ("After reconciling, continue with …"). This is *reconcile-before-specs*:
+  proceeding would author artifacts against a decomposition that is about to change. It is
+  strongest when exiting `forge-2-tech` (next is `forge-3-specs`, the point of no cheap
+  return).
+- `reminder: true` (only `blocksCurrent: false` requests) — normal next-stage routing is
+  unchanged; the block appends a non-blocking reminder line ("You also flagged N epic
+  change(s) to reconcile when convenient …"). This is *finish-then-edit*.
+
+Either way the added lines are host-neutral (no literal `/clear`) and sit **above** the
+sentinel; just print the NEXT-STEPS block verbatim as always.
+
+### Deferred decisions — do not solicit next-stage decisions at this exit
+
+Each stage owns its own decisions. At a stage exit, do **not** pull a *later* stage's
+decision forward — do not ask the user (or decide unilaterally) something that properly
+belongs to the next stage's interview (e.g. at `forge-1-prd` exit, don't settle the
+concrete cache backend that `forge-2-tech` will design). Soliciting it here guesses ahead
+of the stage that owns the context, and the answer has nowhere durable to live.
+
+Instead, when you notice a decision that belongs downstream, **record it structurally** as
+a `deferredDecisions[]` entry on this feature's `.pipeline-state.json` by running
+`state-decision` (`--rationale` and `--target-stage` are optional; the verb stamps
+`raisedAt` and `status: "open"` for you). Add `--epic "{epic}"` when this feature is an
+epic member — required, per the Pipeline State Protocol in `references/shared-conventions.md`:
+
+```bash
+R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/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-session.py" state-decision \
+  --feature "{feature}" --question "<phrased for the target stage>" \
+  --rationale "<why it belongs downstream>" --target-stage "<owning stage>" \
+  --raised-by "{stage}" --specs-dir "{specsDir}"
+```
+
+This keeps the exit focused on *this* stage's next-step routing while carrying the open
+question forward for the owning stage to resolve (it flips `status` to `addressed` when it
+does). Prefer a `deferredDecisions[]` entry over stuffing the same thing into the free-text
+`notes` string. This is a recording affordance, not a gate: never block the exit on it.
+
+### The NEXT-STEPS block (always last)
+
+Print the script's NEXT-STEPS block **verbatim as your absolute last output**. Nothing
+follows its final sentinel line (`─ forge: end of stage ─`) — no caveats, no summary,
+no sign-off. The block already carries the `/clear` recommendation (host-aware wording
+via `--host`) and the exact next command, so trailing prose can only push the user's
+next action out of view.
+
+---
+
+## Standard block
+
+Stamped at the loop's step-6 epic-member handoff (finishing feature A → starting
+feature B's PRD). It self-adapts: step 1's verify gate only fires when verification is
+actually outstanding, so at a boundary where verify already ran (or was explicitly
+skipped, or auto-verify is on) it silently collapses to just the `/clear` →
+next-command steps.
+
+Slots: `{stage}` (a lowercase noun phrase), `{verify-command}`, `{next-command}`.
+
+<!-- BEGIN: standard-exit-block -->
+**This stage is done — walk the user through the Stage Exit Protocol** before moving on. The order is fixed, and step 2 is something only the user can do:
+
+1. **Verify {stage} first — if it isn't already verified.** If verify already ran in this session — via the in-stage auto-verify on the authoring stages, or the interactive impl-verify offered above on the loop — or is already fresh on record, or the stage was explicitly skipped, say so and go straight to step 2. Only when `autoVerify` is off for this stage **and** verify is **missing or stale** do you present the **Standard Verify Gate**: verify **now, before clearing**, using `AskUserQuestion` with exactly these three options — but only when the host has a question mechanism **and** the clean-room path is available (the `Agent` tool plus a dispatchable `forge-verifier` subagent):
+   - **Verify {stage} now** *(recommended)* — dispatch the clean-room `forge-verifier` subagent from this session in require-clean mode; the digest returns here so any fix decision keeps its context. One-time — it does **not** change config.
+   - **Verify now + enable auto-verify going forward** — verify now **and** patch `"autoVerify": true` into `forge.config.json` in place (preserve formatting and every other key) so future stages verify automatically, no prompt. This complements the `forge-init` opt-in. **Do not auto-commit this config change** — treat it like `notes`: a user-facing edit the user commits on their own cadence, never folded into a stage's artifact commit.
+   - **Skip for now** — go straight to `/clear` and the next command without verifying. Record this stage's verify status as `"skipped"` in pipeline state (mirroring the existing skip handling) **only** on an explicit skip — a skip does not go stale.
+
+   **Host / clean-room fallback (not a user-selectable option):** if the question mechanism, the `Agent` tool, or the `forge-verifier` subagent is unavailable, do **not** run clean-room — degrade to printing `{verify-command}` for the user to run inline/manually (mirroring `autoInvokeNextStage`), and offer the auto-verify enable as plain text only if a config write is possible.
+2. **Then `/clear`.** Recommended **unconditionally** at this boundary for a clean start — independent of how full the context window is. Every artifact is on disk, so the work survives the clear. **I can't `/clear` for you — you have to run it yourself.**
+3. **Then run the next command** in the fresh session — or re-run `/skill:forge` to let the navigator resume from disk:
+
+   ```
+   {next-command}
+   ```
+<!-- END: standard-exit-block -->
+
+---
+
+## Warm-acceptable variant
+
+Stamp this only at the `forge-5-loop → forge-6-docs` boundary (the all-done result
+report). Here clearing is **optional**: the docs stage benefits from the still-warm
+context of what the loop actually did, and impl-verify is already offered interactively
+by the loop itself, so this block defers rather than re-presenting a gate.
+
+> **Note — no literal `/clear` here.** The warm block lives in `result-reporting.md`, a
+> skill-*own* reference that the adapter build copies **verbatim** (unlike skill bodies,
+> it is not host-term translated), so a literal `/clear` would reach non-Claude adapters
+> undegraded. The warm variant says "clearing is optional" anyway, so it is phrased
+> host-neutrally without the token on purpose — do not reintroduce `/clear` here. (The
+> standard block *does* use `/clear`; that is fine because every standard stamp site is a
+> skill **body**, where `scripts/build-adapters.py` degrades it.)
+
+<!-- BEGIN: warm-exit-block -->
+**The loop is complete — this is the one boundary where clearing before the next stage is optional.**
+
+1. **Verify is already offered above.** Impl-verify is offered interactively right after this report (Step 5b for a standalone feature, Step 6.1 for an epic member) — run it there rather than as a second gate. It runs clean-room, so it needs no fresh session.
+2. **Clearing is optional here — warm is fine.** `forge-6-docs` benefits from the still-warm context of what the loop actually did, so continuing in this same session is the easy default. A cold start also works — every artifact is on disk — but there is no need to force it.
+3. **Then run the next command** — in this warm session, or a fresh one if you prefer:
+
+   ```
+   {next-command}
+   ```
+<!-- END: warm-exit-block -->

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

@@ -0,0 +1,181 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-1-prd/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-1-prd
+description: Create a requirements PRD for a feature through structured interview. Use when user runs /skill: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.
+---
+
+# forge-1-prd — Requirements Interviewer
+
+Create a thorough, requirements-only PRD through relentless structured interviewing. The PRD captures WHAT the feature must do, not HOW it will be built.
+
+## Prerequisites
+
+Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
+
+**`--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.
+
+## Step 1: Read Configuration and Check State
+
+### Branch Setup (if using git)
+Invoke the **Branch Setup** block in `references/shared-conventions.md` with `{label}` = `{feature}` and `{scope}` = `feature`. It self-gates (skips when not a git repo, when `branchPerFeature` is false, or for an epic member that inherits the epic's branch), detects whether you're on the default branch, and strongly recommends — still optionally — creating `{branchPrefix}{feature}` when you are. Do this before directory resolution.
+
+Set the working directory by invoking the **Feature Directory Resolution** block in `references/shared-conventions.md`, which yields `{resolvedFeatureDir}`. Note one PRD-specific caveat: at PRD time a brand-new standalone feature may have NO directory yet, so resolution is expected to fail for a never-started standalone feature — as `not-found` (exit 1) when `{specsDir}/` already exists (other features present), or as `specs dir not found` (exit 2) when `{specsDir}/` 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}/{feature}/` 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.
+
+### Mint Guard: refuse to fork a known epic member into a detached standalone (Issue #125)
+
+Run this sub-step **whenever forge-1 is about to mint a brand-new flat standalone `{specsDir}/{feature}/`** — 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}/` 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` / path-containment — those STOP, they never mint), and when `--force-standalone` was passed (see below).
+
+1. Run cross-branch discovery for this exact name (branch-agnostic — it scans all refs regardless of current HEAD):
+   ```bash
+R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/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-session.py" discover-feature "{feature}" --specs-dir "{specsDir}" --json
+   ```
+2. **If any candidate has `isEpicMember: true` → HARD STOP.** This is not the soft switch/fetch/treat-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`):
+   > `{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 `/skill:forge-1-prd {feature}` there, or pass `--force-standalone` to intentionally fork a detached standalone feature.
+3. **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 / fetch+switch / treat-as-new / stop). Defer to it.
+4. **If nothing was found** (no candidates) → proceed to mint the flat standalone feature as today.
+5. **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).
+
+After resolution, invoke the **Stage-Entry Guard** block in `references/shared-conventions.md` with `{stage}` = `forge-1-prd`. It classifies re-entry (fresh / interrupted / 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.
+
+## Step 2: Examine Existing Context
+
+Before starting the interview, invoke the **Epic Context Injection** block in `references/shared-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`/`consumes` are requirement inputs — every contract obligation must appear as a REQ in the PRD.
+
+1. **Check the project structure**: Read the project's build configuration and dependency manifests to understand what modules/packages exist. Look for `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, workspace configs, or equivalent.
+2. **Check existing specs**: Look at `{specsDir}/` for other features' PRDs to understand conventions and the overall system
+3. **Check existing docs**: Look at the docs directory for architecture documentation
+4. **Note integration surfaces**: Identify which existing packages might be relevant to this feature
+
+This context helps you ask informed questions and spot gaps the user might not think of.
+
+## Step 3: Conduct the Interview
+
+Interview the user relentlessly. Your goal is to extract complete, unambiguous requirements.
+
+Read `references/prd-template.md` for the interview structure and question categories. Cover every category. Don't rush — missing a requirement now costs 10x to fix later.
+
+### CRITICAL GUARDRAIL: No Technology Decisions
+
+The PRD is EXCLUSIVELY about requirements. You MUST enforce this boundary:
+
+**When the user says something like:**
+- "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.
+- "We'll store it in Drizzle/PostgreSQL" → Capture as: "Persistent storage required for X data with Y query patterns."
+- "I want a React component that..." → Capture as: "A user interface is required that allows users to..."
+- "We should use WebSockets for..." → Capture as: "Real-time updates are required when X changes, with latency under Y."
+- "I want a REST API" → Capture as: "An HTTP-accessible interface is required for X operations"
+- "We need a microservice for X" → Capture as: "X must be independently deployable and scalable"
+- "Use a queue for Y" → Capture as: "Y must be processed asynchronously with guaranteed delivery"
+
+**When YOU start drifting into technology:**
+If 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.
+
+**The one exception:** When a technology choice IS the requirement (e.g., "must integrate with the existing @repo/auth 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.
+
+A 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.
+
+### Interview Approach
+
+**Turn structure:** Output your analysis or context as regular text, then use `AskUserQuestion` for the actual questions. NEVER put questions in your text output — they MUST go through `AskUserQuestion`.
+
+**Pacing:** Cover one topic area at a time, asking 2-3 related questions per `AskUserQuestion` call. After receiving answers, probe deeper on anything incomplete before moving to the next topic. Signal progress in your text before the next question batch.
+
+**Question strategies** (use these as content for `AskUserQuestion`, not as inline prose). The PRD stays at the requirements level (the *what*, not the *how* — that's forge-2-tech), so most questions are open elicitation. But whenever you offer the user a *choice* (scope boundary, MVP cut, a non-functional target), apply the **Decision Support** protocol in `references/shared-conventions.md`: propose a sensible default with its trade-off rather than an empty menu — e.g. "I'd scope V1 to X and defer Y; that ships sooner but means Y waits. Agree?":
+- Probe deeper after each answer: failure modes, stakeholders, minimum viable version
+- Challenge assumptions: which users specifically, what does "fast" mean quantitatively
+- Identify edge cases: empty input, concurrent access, scale
+- Capture non-functional requirements: performance, security, accessibility, observability
+- Ask about what's OUT of scope — as important as what's in scope; when proposing a scope line, recommend one and name what each side gives up
+
+**Completion criteria:** The interview is complete when:
+1. Every category in `references/prd-template.md` has been covered with at least one question
+2. The user has confirmed there's nothing else to add
+3. You can draft every PRD section without leaving TBD placeholders
+
+Before moving to Step 4, summarize your coverage as text, then use `AskUserQuestion` to ask: "Anything I'm missing?"
+
+**Parking lot:** If the user raises a concern that belongs to a different pipeline stage, acknowledge it and note it in the pipeline state's `notes` field: "Good point — I've noted that for the [tech spec/implementation specs]. Let's continue with [current stage]."
+
+**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`/`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/downstream change this feature does not consume. When the change touches a contract/dep 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 `/skill: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.
+
+```bash
+R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/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-session.py" state-ecr \
+  --feature "{feature}" --epic "{epic}" --kind "<kind>" --target "<target>" \
+  --rationale "<why>" --raised-by forge-1-prd --blocks-current "<true|false>" \
+  --specs-dir "{specsDir}"
+```
+
+## Step 4: Write the PRD
+
+Once the interview is thorough, write `{resolvedFeatureDir}/PRD.md` following the structure in `references/prd-template.md`.
+
+Every requirement MUST have a unique ID (e.g., REQ-AUTH-01, REQ-PERF-01). These IDs are referenced by all downstream documents.
+
+After writing the PRD (this is the point where `{specsDir}/{feature}/` is first created for a standalone feature), invoke the **Specs Directory Hygiene** block in `references/shared-conventions.md` to ensure `{specsDir}/AGENTS.md` (and `{specsDir}/CLAUDE.md` on the Claude host) exists. It is idempotent — it never overwrites an existing file.
+
+## Step 5: Review with User
+
+Present the complete PRD to the user. Ask:
+- "Does this capture everything? Any requirements missing?"
+- "Are the priorities correct?"
+- "Anything in here that should be out of scope?"
+
+Use `AskUserQuestion` to collect this feedback.
+
+Iterate until the user confirms the PRD is complete.
+
+## Step 6: Update Pipeline State and Commit
+
+Before writing state or running the stage exit, invoke the **Stage-Completion Re-check** block in `references/shared-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.
+
+Pipeline state is written by the `state-*` verbs — see the Pipeline State Protocol in `references/shared-conventions.md`.
+
+1. 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.
+2. **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; otherwise proceed.
+3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files (including `{specsDir}/AGENTS.md` / `{specsDir}/CLAUDE.md` if the Specs Directory Hygiene step just wrote them), attempt commit with message `"{commitPrefix}({feature}): complete PRD v{n}"` (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`.
+4. **Close with the Stage Exit Protocol** (single-sourced in `references/stage-exit-protocol.md`; do not improvise a "Next steps" list):
+
+The `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/shared-conventions.md`:
+
+```bash
+R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/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-session.py" state-complete \
+  --feature "{feature}" --stage forge-1-prd --version {n} \
+  --artifact PRD.md --specs-dir "{specsDir}"
+# ONLY run the next call if the user volunteered a note in item 2 — otherwise stop here.
+python3 "$R/scripts/forge-session.py" state-note \
+  --feature "{feature}" --note "<what the user volunteered>" --specs-dir "{specsDir}"
+```
+
+**Close this stage with the Scripted Stage Exit** (contract: `references/stage-exit-protocol.md`; do not improvise a "Next steps" list). Run:
+
+```bash
+R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/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-session.py" stage-exit --feature "{feature}" --stage forge-1-prd --specs-dir "{specsDir}" --host pi
+```
+
+Obey the DIRECTIVES it prints, in order, per the directive contract: `runInStageVerify: true` → dispatch the in-stage clean-room verify now (honoring `autoFixEligible`); `verifyGate: "standard"` → present the Standard Verify Gate; `verifyGate: "manual-print"` → print the `verifyCommand` for the user; non-empty `invalidAutoVerifyKeys` → print a one-line warning. Then **print the NEXT-STEPS block verbatim as your absolute last output — nothing after its sentinel line.**
+
+## Gotchas
+
+- 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.
+- If the user provides a very detailed initial description, don't skip the interview. Use their description as a starting point but probe for what's missing. Long descriptions often have big gaps in edge cases and non-functional requirements.
+- Don't number requirements sequentially across categories (REQ-01, REQ-02...). Use category prefixes (REQ-AUTH-01, REQ-PERF-01) so inserting new requirements doesn't require renumbering.
+- The PRD should be readable by a non-technical stakeholder. If a section requires deep technical knowledge to understand, it probably belongs in the tech spec, not the PRD.
+
+---
+
+## Host execution notes (Pi)
+
+This Pi bundle preserves Claude's `AskUserQuestion` references because it ships a Pi compatibility extension registering an `AskUserQuestion` tool. On Pi:
+
+- **User input:** use `AskUserQuestion` for genuine user decisions. It supports multiple questions, option descriptions, recommended ordering, multi-select, previews, and free-form Other/custom answers.
+- **Skill dispatch:** Pi uses `/skill:<name>` commands. If you cannot invoke a skill directly, print the exact `/skill:<name> ...` command for the user to run.
+- **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.
+- **Background / monitoring:** run long-lived commands in the foreground and report progress as it arrives.

package/adapters/pi/skills/forge-1-prd/references/prd-template.md

@@ -0,0 +1,106 @@
+# PRD Template and Interview Guide
+
+This reference defines the standard PRD structure and the interview questions to cover for each section.
+
+## PRD Document Structure
+
+```markdown
+# {Feature Name} — Product Requirements Document
+
+## 1. Problem Statement
+What problem does this feature solve? Who has this problem? Why does it matter now?
+
+## 2. User Stories
+As a [role], I want [capability], so that [benefit].
+- Include primary actors and secondary actors
+- Include admin/operator stories, not just end-user stories
+
+## 3. Functional Requirements
+
+### 3.1 {Capability Area}
+- REQ-{CAT}-01: {Requirement description}
+  - Priority: P0 (must have) | P1 (should have) | P2 (nice to have)
+  - Notes: {Any clarification}
+
+### 3.2 {Another Capability Area}
+...
+
+## 4. Non-Functional Requirements
+
+### 4.1 Performance
+- REQ-PERF-01: ...
+
+### 4.2 Security
+- REQ-SEC-01: ...
+
+### 4.3 Observability
+- REQ-OBS-01: ...
+
+### 4.4 Accessibility
+- REQ-A11Y-01: ...
+
+### 4.5 Scalability
+- REQ-SCALE-01: ...
+
+## 5. Constraints
+Technical, organizational, or external constraints that must be respected.
+(This is where technology mandates go — e.g., "must integrate with existing @repo/auth package")
+
+## 6. Out of Scope
+Explicitly list what this feature will NOT do in this version.
+
+## 7. Open Questions
+Unresolved items that need answers before or during implementation.
+
+## 8. Success Criteria
+How do we know this feature is done and working correctly?
+```
+
+## Interview Question Categories
+
+Cover ALL of these areas during the interview. Don't move on until each is addressed.
+
+### Core Understanding
+- What is the feature in one sentence?
+- Who are the primary users? Secondary users? Admins/operators?
+- What workflow or process does this support?
+- What exists today that this replaces or augments?
+
+### Functional Depth
+- Walk me through the happy path end to end
+- What are the key data entities involved?
+- What inputs does the system accept? What are valid/invalid inputs?
+- What outputs does the system produce?
+- What states can things be in? What transitions are allowed?
+- What happens when the user makes a mistake?
+
+### Error and Edge Cases
+- What happens when X is unavailable?
+- What if two users do Y at the same time?
+- What happens with empty inputs? Huge inputs? Malformed inputs?
+- What does partial failure look like?
+- How should the system recover from crashes mid-operation?
+
+### Integration
+- What existing parts of the system does this interact with?
+- What data does it need from other features?
+- What data does it provide to other features?
+- Are there external systems or APIs involved?
+
+### Non-Functional
+- What's the expected load? (requests/sec, concurrent users, data volume)
+- What are the latency requirements?
+- What security considerations exist? (authn, authz, data sensitivity)
+- What needs to be logged, monitored, or alerted on?
+- Are there accessibility requirements?
+
+### Scope and Priority
+- What's the minimum viable version of this?
+- What would you cut if you had to ship in half the time?
+- What's explicitly NOT part of this feature?
+- Are there follow-up features that depend on decisions made here?
+
+### Success
+- How do you know this feature is working correctly?
+- What would a user complain about if we got it wrong?
+- Are there quantitative targets? (latency < Xms, uptime > Y%)