@garygentry/feature-forge 0.2.14 → 0.3.1

package/adapters/pi/skills/forge-1-prd/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-2-tech/SKILL.md

@@ -0,0 +1,243 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-2-tech/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-2-tech
+description: Create a technical specification from an existing PRD in the forge pipeline. Use when user runs /skill:forge-2-tech or asks to create a tech spec for a forge feature after PRD completion. Do NOT trigger for general technical design discussions, architecture reviews, or tech specs outside the forge pipeline.
+---
+
+# forge-2-tech — Technical Specification Driver
+
+Create a thorough technical specification by interviewing the user about technology decisions, grounded in PRD requirements.
+
+## Prerequisites
+
+Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
+
+## Step 1: Validate Prerequisites
+
+**Resolve the feature directory first** via the **Feature Directory Resolution** block in `references/shared-conventions.md`, setting `{resolvedFeatureDir}`.
+
+**Prerequisite check:** Read `{resolvedFeatureDir}/.pipeline-state.json`. If not in force mode and `forge-1-prd` is not `complete`, STOP and tell the user: "The PRD for '{feature}' isn't complete yet. Run `/skill:forge-1-prd {feature}` first."
+
+After the prerequisite check, invoke the **Stage-Entry Guard** block in `references/shared-conventions.md` with `{stage}` = `forge-2-tech` — it detects an interrupted or already-complete tech-spec, runs the resume/restart or new-version gate, and stamps `status: "in-progress"` + `startedAt` + `currentStage` before the research and interview.
+
+Read `{resolvedFeatureDir}/PRD.md` into context. This is your foundation — every technology decision must trace back to a PRD requirement.
+
+After reading the PRD, invoke the **Epic Context Injection** block in `references/shared-conventions.md`. It self-gates on the resolved feature's `epic` back-pointer: for a standalone feature it is a no-op; for an epic member it loads EPIC.md, this feature's charter, and the completed direct dependencies' specs into context before the research and interview.
+
+## Step 2: Examine Existing Context
+
+Before interviewing, you need to understand the existing codebase. This involves reading many files across the project, which consumes context.
+
+### Recommended: Delegate to forge-researcher Subagent
+
+Spawn the `forge-researcher` subagent via the host's subagent mechanism to scan the codebase. Pass a prompt like: "Research the codebase for planning the {feature} feature. Focus on integration points, established patterns, and relevant packages."
+
+If this feature belongs to an epic, also add to the dispatch prompt: "If this feature belongs to an epic, also account for these epic contracts: {paste this feature's `consumes` and the `exposes` of its direct deps}, and the completed dependency tech-specs at {paths}. Do not re-research transitive deps." This threads epic context into the researcher without changing the agent's behavior.
+
+The researcher runs in its own context window, reads the project structure, and returns a concise integration report. This keeps your main conversation context clean for the interactive interview.
+
+**Single vs. parallel research.** For a small or well-understood codebase, **one**
+researcher is the right default. For a **large codebase or uncertain scope** (many
+packages, several integration surfaces, monorepo), dispatch **multiple `forge-researcher`
+subagents in parallel — a single message with multiple subagent calls** (the
+`superpowers:dispatching-parallel-agents` pattern), each scoped to a **disjoint focus**
+so they don't re-read the same ground:
+- one on **project structure & conventions** (layout, build, naming, error/test patterns),
+- one per **major integration area / subsystem** the feature touches (its exports, types,
+  public API),
+- optionally one on **existing feature specs & in-progress conflicts**.
+
+Each returns its own report; **you merge them** into a single integration picture for the
+interview. This cuts latency and deepens coverage versus one researcher sweeping
+everything serially. No agent change is needed — `forge-researcher` already returns a
+self-contained report; just give each instance a narrower focus.
+
+If the `forge-researcher` subagent is not available, perform the research inline (steps below).
+
+### Manual Research (fallback)
+
+1. **Read the PRD thoroughly**: Understand all requirements and constraints
+2. **Check for project-level stack decisions**: Look for a project stack-decisions file, first existing path wins: `.feature-forge/stack-decisions.md` (preferred), then `.agents/references/stack-decisions.md`, then `.claude/references/stack-decisions.md` (legacy alias). If present, read it — these are established technology choices that should be respected unless there's a strong reason to deviate.
+3. **Read the plugin's default stack reference**: Read `references/stack-discovery-checklist.md` for general stack context (only if no project-level override exists)
+4. **Examine the existing codebase**: Look at `package.json` files, existing packages, directory structure, and established patterns. Understand what conventions are already in place.
+5. **Review other features' tech specs**: Check `{specsDir}/*/tech-spec.md` and `{specsDir}/*/*/tech-spec.md` (depth-2, to find nested epic members) for consistency in approach and to identify shared infrastructure. Apply the **feature-shaped-dir bound**: only treat a directory as a feature if it directly contains a `.pipeline-state.json` (filter matches whose parent directory holds one, or enumerate members via the helper). A flat-only tree has no depth-2 feature dirs, so this gains no new matches there (REQ-COMPAT-01).
+6. **Identify integration points**: For each existing package that this feature touches, read its exports, types, and public API. Document these as constraints.
+
+### Stack Detection and Persistence
+
+After researching the codebase, identify the primary stack (language, build tool, package manager, framework). Read `references/stack-resolution.md` for the full resolution protocol.
+
+1. Check if `forge.config.json` already has a `stack` field — if so, use it
+2. Otherwise, detect from project files and use `AskUserQuestion` to confirm: "I detected this as a {stack} project. Correct?"
+3. Update `forge.config.json` with `stack`, `typeCheckCommand`, and `testCommand`. If the feature has a runtime entrypoint (HTTP server, CLI, worker, or a library with a bootstrap contract), also offer to set `smokeCommand` — an end-to-end command that boots the wired app and drives one happy-path request (exit 0 = pass). It is distinct from `testCommand` (unit tests, which may self-bootstrap) and powers impl-verify's runnability check; leave it `null` for a pure library with no runnable surface.
+4. Verify that a matching stack profile exists at `references/stacks/{stack}.md`. If it does, load it for stack-specific guidance during this and all subsequent stages. If no profile exists, inform the user: "No dedicated profile for {stack}. Using generic fallback — spec conventions, verification checks, and examples will be language-neutral. Consider creating a project-level override at `.feature-forge/stack-decisions.md`." Then load `references/stacks/_generic.md`.
+
+## Step 3: Conduct the Interview
+
+Interview the user about technology decisions. Unlike the PRD interview, here you SHOULD discuss specific technologies, libraries, patterns, and architecture.
+
+### Interview Approach
+
+**Turn structure:** Output your research findings, analysis, or technical proposals as regular text. Then use `AskUserQuestion` for the actual questions. NEVER put questions in your text output — they MUST go through `AskUserQuestion`.
+
+**Pacing:** Present 1-2 decision areas per `AskUserQuestion` call and STOP to wait for the user's response before continuing. After receiving answers, probe deeper on anything incomplete before moving to the next topic. Signal progress in your text before the next question batch. Do NOT dump all decision areas in a single message — the interview is a conversation, not a document.
+
+**First message pattern:** Output the research summary as text, then use `AskUserQuestion` to confirm the stack and ask about the first decision area (typically package/module structure). Wait for the user to respond before proceeding to subsequent areas.
+
+**Question strategies** (use these as content for `AskUserQuestion`, not as inline prose). Follow the **Decision Support** protocol in `references/shared-conventions.md` — this interview is the richest decision surface in the pipeline, so don't just list options; lead with a recommended approach, put the trade-off in each option's description, and give a one-line rationale:
+- For each PRD requirement, propose a technical approach **with its trade-off and your recommendation**, then ask for confirmation or alternatives — don't present competing approaches flatly. You've just researched the codebase; spend that research here.
+- Recommend approaches consistent with the established stack, and say *why* the convention favors it (evidence-backed mode). Where the choice is genuine taste (e.g. folder layout, naming), give a default but flag it as preference.
+- Challenge over-engineering: does the feature need this, or is a simpler approach sufficient? Frame the simpler option's trade-off (less flexibility now vs. less to maintain).
+- Ask about every integration point and how the feature interacts with existing modules.
+- For competing module structures or code-shape choices, use the `AskUserQuestion` `preview` field to show the candidates side-by-side.
+
+**Parking lot:** If the user raises a concern that belongs to a different pipeline stage (e.g., backlog granularity, documentation format), acknowledge it and note it in the pipeline state's `notes` field: "Good point — I've noted that for the [specs/backlog/docs stage]. Let's continue with the tech spec."
+
+**Epic-level concern (backflow):** The parking lot above is for concerns about a *later stage of THIS feature*. If instead the design 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. To record one, run `state-ecr` (fenced below) with `--kind` (`add-feature`|`redep`|`move-boundary`|`split`), `--target`, `--rationale`, `--raised-by forge-2-tech` 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 to specs would build on a soon-to-change decomposition (this is the point of no cheap return, so bias toward `true`); `false` for a peer/downstream change this feature does not consume. When a contract/dep edge is touched and the classification is ambiguous, confirm `blocksCurrent` with a single `AskUserQuestion`, defaulting to `true`. **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 and continue the tech spec.
+
+```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-2-tech --blocks-current "<true|false>" \
+  --specs-dir "{specsDir}"
+```
+
+### Key Decision Areas to Cover
+
+Work through these areas across multiple turns, grouping related areas (1-2 per message):
+
+- **Package/module structure**: Where does this live in the project? What are its exports? (For non-monorepo projects, this becomes module organization — where the code lives, how it's organized, and what its exports are.)
+- **Data model**: What are the key entities, their schemas, and storage approach?
+- **API design**: What endpoints or interfaces does this expose?
+- **Dependencies**: What external and internal packages are needed?
+- **Patterns**: Which established patterns from the codebase apply here?
+- **Error handling**: How are errors surfaced, propagated, and recovered from?
+- **Testing strategy**: Unit, integration, e2e — what approach for this feature?
+- **Configuration**: What's configurable? How is it configured?
+- **Migration/deployment**: Any special rollout considerations?
+
+### Requirement Traceability
+
+Every technical decision MUST reference the PRD requirement(s) it addresses. Use the format:
+
+```
+### JWT-based Session Tokens (REQ-AUTH-01, REQ-SEC-02)
+Sessions will use signed JWT tokens with...
+```
+
+If you find yourself writing a technical section that doesn't trace to any PRD requirement, STOP and ask: "I'm about to specify X, but I can't find a PRD requirement for it. Should we add one, or is this unnecessary?"
+
+## Step 4: Integration Analysis (Required)
+
+Before finalizing the tech spec, this section is MANDATORY:
+
+1. List every existing package this feature depends on
+2. List every existing package that will need to import from this feature
+3. For each integration point, document:
+   - Which types or contracts are shared
+   - How data flows between packages
+   - Any patterns established by existing code that must be followed
+   - The EXACT function signatures and import paths verified from source code. If you cannot locate an expected export, note explicitly: "WARNING: Could not locate X export in {module} — verify this exists before implementing."
+4. Check for potential conflicts with in-progress features (other spec directories)
+
+## Step 5: Write the Tech Spec
+
+Write `{resolvedFeatureDir}/tech-spec.md` with this structure:
+
+```markdown
+# {Feature Name} — Technical Specification
+
+## 1. Overview
+Brief technical summary and key architectural decisions.
+
+## 2. Module Structure
+Project location, directory layout, public API surface.
+
+## 3. Technical Decisions
+### 3.1 {Decision Area} (REQ-XXX-NN)
+Decision, rationale, alternatives considered.
+
+## 4. Data Model
+Schemas, types, storage approach.
+
+## 5. API Design
+Endpoints, interfaces, contracts.
+
+## 6. Integration Points
+How this feature connects to existing packages.
+
+## 7. Error Handling
+Error types, propagation, recovery.
+
+## 8. Testing Approach
+Strategy, tooling, coverage targets.
+
+## 9. Dependencies
+External packages, internal packages, version constraints.
+
+## 10. Open Technical Questions
+Unresolved technical decisions.
+```
+
+## Step 6: Review with User
+
+Present the complete tech spec. Ask:
+- "Does this capture all the technical decisions correctly?"
+- "Any patterns from the existing codebase I missed?"
+- "Are the integration points complete?"
+
+Use `AskUserQuestion` to collect this feedback.
+
+## Step 7: 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-2-tech` — a resumed mid-stage continuation must not overwrite a committed `tech-spec.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`, one `--artifact` per file this stage produced, and `--based-on forge-1-prd=<current forge-1-prd version>`. It sets `status: "complete"`, `completedAt`, the version and `basedOnVersions`, 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, attempt commit with message `"{commitPrefix}({feature}): complete tech-spec v{n}"` (marking `stages.forge-2-tech.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-2-tech --version {n} \
+  --based-on "forge-1-prd=<n>" --artifact tech-spec.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-2-tech --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
+
+- Don't duplicate the PRD. The tech spec answers HOW, not WHAT. If you find yourself restating requirements, reference them by ID instead.
+- When the user's stack decisions differ from what you'd recommend, document their choice AND note your concern as an "Alternatives Considered" item — don't silently override their preference.
+- Integration points are the #1 source of implementation surprises. Spend extra time here. Read the actual code of packages this feature touches, don't just guess at their APIs.
+- If the existing codebase has inconsistent patterns (it happens), call it out and ask which pattern should be followed for this feature.
+
+---
+
+## Host execution notes (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.