@garygentry/feature-forge 0.1.0

package/adapters/claude/skills/forge-0-epic/references/edit-mode.md

@@ -0,0 +1,222 @@
+# forge-0-epic — Edit Mode (E1–E6) + Observability / Pipeline State & Commit
+
+Lookup detail relocated out of the `forge-0-epic` SKILL.md body. The skill body keeps the
+entry condition (the **EXISTS** branch from Step 0) and the high-level "every mutation is
+committed individually" rule, and points here for the full mechanics. The exact mutator flag
+surface and per-subcommand exit-code handling live in `references/epic-manifest-subcommands.md`.
+
+Entered from Step 0 when `{specsDir}/{epic}/epic-manifest.json` already exists (the **EXISTS**
+branch). The edit branch mutates the manifest **only** through helper mutators — the skill never
+hand-rolls an in-place write. Every mutator is atomic (temp file + `os.replace`) and re-validates
+the edited graph internally, so a refused write leaves the manifest **byte-identical**. Every
+question goes through `AskUserQuestion`.
+
+## Step E1 — Load + Validate, Refuse if Invalid
+
+Before offering any edit, validate the existing manifest:
+
+```bash
+R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/epic-manifest.py" validate "{epic}" --specs-dir "{specsDir}" --json
+```
+
+- Exit `0` → the manifest is well-formed; proceed to E2.
+- Exit `1` or `2` → the manifest is corrupt or invalid (hand-edited, `corrupt-json`, `cycle`,
+  `dangling-ref`, `duplicate-name`, `cached-status`, `unsafe-name`, …). Surface **every**
+  `findings[]` entry **verbatim**, then **refuse ALL mutation** until the user repairs the
+  manifest by hand. **Never auto-repair**, never offer an edit operation, and never proceed past
+  this gate. Tell the user what is wrong and STOP.
+
+## Step E2 — Choose Operation
+
+Use `AskUserQuestion` to offer the edit operations, each mapping to one helper mutator:
+
+| Operation | Helper subcommand |
+|-----------|-------------------|
+| Add a feature | `add-feature` |
+| Remove a feature | `remove-feature` |
+| Reorder features | `reorder` |
+| Change a dependency edge | `set-dep` |
+| Change epic lifecycle status | `set-status` |
+
+For **add-feature**, first run `check-name "{feature}"` (exactly as C2) so no new duplicate is
+introduced — surface a `duplicate-name`/`unsafe-name` finding verbatim and re-prompt — then
+elicit the new feature's **charter** + **`exposes`/`consumes`** + **`dependsOn`** exactly as in
+C3/C4.
+
+## Step E3 — Apply via Helper Mutator (re-validated)
+
+Issue the chosen mutator. Each writes atomically and re-runs full validation internally, refusing
+the write if it would introduce a cycle, dangling ref, duplicate, or schema violation. For the
+exact `epic-manifest.py` mutator flag surface and per-subcommand exit-code handling, read
+`references/epic-manifest-subcommands.md`.
+
+**Contracts have no mutator.** `add-feature` seeds empty `exposes`/`consumes`. To populate the
+new feature's contracts, edit its `exposes`/`consumes` arrays **directly in the composed manifest
+entry** (exactly as creation C5 does), then re-run `validate "{epic}" --json` to confirm — there
+is intentionally no `--exposes-json`/`--consumes-json` flag.
+
+**remove-feature leaves the member directory in place (§7.5).** The mutator drops only the
+manifest entry. The skill does **not** delete or relocate `{specsDir}/{epic}/{feature}/`. WARN the
+user verbatim:
+
+> Removed `{feature}` from the manifest. Its directory `{specsDir}/{epic}/{feature}/` is left in
+> place; move it to `{specsDir}/{feature}/` by hand if you want it as a standalone feature.
+> Relocation is manual — there is no migration tooling.
+
+The orphaned subdir still holds a `.pipeline-state.json` with an `epic` back-pointer the manifest
+no longer lists; per the conflict rule the **manifest wins**, and `forge-verify` epic mode
+CHECK-E07 reports the inconsistency non-fatally. The skill does **not** silently edit the orphaned
+state file.
+
+## Step E4 — Impact Warning (in-flight / completed features)
+
+Before applying — or immediately after eliciting — a mutation that affects a feature whose derived
+status is **not** `not-started`, warn the user. Read the **live** status (never re-derive
+completion in prose):
+
+```bash
+R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
+```
+
+If the operation removes, reorders-around, or re-deps a feature whose derived status is
+`in-progress` or `complete`, use `AskUserQuestion` with an explicit warning naming the affected
+in-flight/completed feature(s) and **require confirmation** before applying. Example: "`token-service`
+is already in-progress (forge-3-specs). Removing `config-store`, which it consumes `JWT_SECRET`
+from, may invalidate its in-flight specs. Proceed?" If `render-status` exits `≥ 1`, surface the
+findings and STOP (do not mutate over an invalid graph).
+
+## Step E5 — Patch EPIC.md
+
+Patch **only** the affected feature/Contracts section(s) — the section(s) for the added, removed,
+or changed feature and any feature whose `dependsOn`/`consumes` changed — applying the §C6 mirror
+rule (one bullet per `exposes`/`consumes` entry). **Full regeneration happens only on explicit
+user request**: offer it via `AskUserQuestion` but default to the targeted patch. The skill keeps
+EPIC.md in sync but does not itself diff it against the manifest — drift detection is `forge-verify`
+epic mode CHECK-E06.
+
+## Step E6 — Pipeline State & Commit
+
+Proceed to the **Observability, Pipeline State & Commit** section below. Each edit-mode mutation is
+committed individually so git history is the audit trail.
+
+## Observability, Pipeline State & Commit
+
+### Manifest `updatedAt`
+
+Every helper mutator bumps the manifest's top-level `updatedAt` to the current ISO-8601 UTC
+timestamp as part of the same atomic write. The skill does **not** bump it manually in edit mode.
+For the initial creation write (C5) the skill sets `createdAt == updatedAt`.
+
+### Pipeline state
+
+- **Epic-level:** the epic subtree has **no `.pipeline-state.json` of its own** (that is what
+  distinguishes an epic root from a feature). The epic's lifecycle lives in the manifest `status`
+  field. The `forge-0-epic` run is recorded in **member** states, not in an epic-level state file.
+- **Member-level (creation):** each member's `.pipeline-state.json` records
+  `stages["forge-0-epic"].status = "complete"` and `currentStage = "forge-1-prd"` (see C7).
+- **Edit mode:** edits mutate the **manifest**, not member pipeline states — except the
+  newly-created subdir for `add-feature`, which follows C7 (create the member subdir + back-pointer
+  state). The skill does **not** rewrite existing members' `stages` on an edit.
+- **`.epic-state.json` (lazily created, written by skills — NOT the helper):** epic-*scoped* stage
+  entries that belong to no single member — currently only `forge-verify-epic` — are persisted in a
+  dedicated `{specsDir}/{epic}/.epic-state.json`. It holds **only** epic-scoped stage entries,
+  never derived per-feature status (so it does not violate REQ-STATE-02). `forge-0-epic` does
+  **not** create this file — no epic-scoped stage runs during creation or edit; it appears only once
+  `forge-verify` epic mode runs. When a skill does write it (e.g. forge-verify epic mode), it writes
+  **directly** using an atomic temp-file + `os.replace` pattern — the helper exposes no subcommand
+  for it. On I/O failure the skill reports and leaves any prior file intact (never a partial write).
+  Minimal schema:
+
+  ```jsonc
+  {
+    "epic": "auth-overhaul",            // matches manifest `epic`
+    "stages": {
+      "forge-verify-epic": {
+        "status": "findings-reported",   // "findings-reported" | "passed" | "findings-applied"
+        "findingsFile": ".verification/VERIFY-epic-2026-06-12.md",
+        "findingsCount": 3,
+        "verifiedAt": "2026-06-12T00:00:00Z"
+      }
+    }
+  }
+  ```
+
+  The git-commit step below stages the whole epic subtree, so `.epic-state.json` is captured
+  automatically when present.
+
+### Git Commit Protocol
+
+After creation (C8) **and after each edit-mode mutation (E6)**, if `gitCommitAfterStage` is true,
+follow the Git Commit Protocol in shared-conventions:
+
+1. Stage the whole epic subtree only: `git add {specsDir}/{epic}/` — **never** `git add -A`. This
+   captures `epic-manifest.json`, `EPIC.md`, member `.pipeline-state.json` files, and any
+   `.epic-state.json` together atomically.
+2. Commit with message `"{commitPrefix}({epic}): <action>"`, e.g.
+   `"forge({epic}): create epic with 4 features"`, `"forge({epic}): add feature api-gateway"`,
+   `"forge({epic}): remove feature legacy-session"`, `"forge({epic}): reorder features"`,
+   `"forge({epic}): set dependency on token-service"`, or `"forge({epic}): set status paused"`.
+3. On success, capture the commit hash. On failure (pre-commit hook, conflict), report and do
+   **not** mark complete; never use `--no-verify`/`--force`.
+
+Because every mutation is committed, the git history of `epic-manifest.json` is the audit trail; no
+separate in-manifest audit log is kept.
+
+### Closing message
+
+After a successful **creation**, present the next-steps message (already specified in C8). After a
+successful **edit-mode mutation**, confirm the change and re-surface the dashboard pointer:
+
+> Epic `{epic}` updated (`<action>`). Run `/feature-forge:forge {epic}` to see the refreshed
+> dashboard, or re-run `/feature-forge:forge-0-epic {epic}` to make another change.
+
+## EPIC.md Mirror Template (creation C6 / edit E5)
+
+`forge-0-epic` Step C6 generates `{specsDir}/{epic}/EPIC.md` from the **validated** manifest; the
+edit-mode E5 patch applies the **same mirror rule** to the affected sections. The full skeleton:
+
+```markdown
+# {epic} — Epic
+
+## Overall Goal
+{the epic goal from C1, expanded into narrative prose}
+
+## Decomposition Rationale
+{why the change was split this way; right-sizing notes; ordering rationale}
+
+## Features
+{for each feature, in manifest order:}
+
+### {feature.name}
+{feature.charter, as prose}
+
+**Depends on:** {comma-separated dependsOn, or "nothing"}
+
+#### Contracts
+**Exposes:**
+- `{exposes[i].name}` ({exposes[i].kind}) — {exposes[i].summary}
+{… or "Nothing exposed." if the exposes array is empty}
+
+**Consumes:**
+- `{consumes[i].name}` from `{consumes[i].from}` — {consumes[i].summary}
+{… or "Nothing consumed." if the consumes array is empty}
+```
+
+## Member State Example (creation C7)
+
+Each member's `.pipeline-state.json` (created in Step C7) conforms to
+`references/pipeline-state-schema.json`. Example member state:
+
+```json
+{
+  "epic": "{epic}",
+  "currentStage": "forge-1-prd",
+  "stages": {
+    "forge-0-epic": { "status": "complete", "version": 1, "completedAt": "<iso-8601-utc>" }
+  }
+}
+```

package/adapters/claude/skills/forge-0-epic/references/epic-manifest-subcommands.md

@@ -0,0 +1,64 @@
+# forge-0-epic — `epic-manifest.py` Subcommand Reference
+
+Lookup detail relocated out of the `forge-0-epic` SKILL.md body (Step E3 command
+catalog + exit-code disposition, and the Error Handling table). The skill body keeps
+the decision logic and step ordering; this file is the flag-surface catalog and the
+per-subcommand exit-code reference.
+
+## Edit-Mode Mutator Flag Surface (Step E3)
+
+Issue the chosen mutator. Each writes atomically and re-runs full validation internally, refusing
+the write if it would introduce a cycle, dangling ref, duplicate, or schema violation. The exact
+flag surface (owned by 02 §7):
+
+```bash
+R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+# Add a feature — seeds EMPTY exposes/consumes; contracts are populated below.
+python3 "$R/scripts/epic-manifest.py" add-feature "{epic}" "{feature}" \
+  --charter "…" --specs-dir "{specsDir}" [--depends-on a,b]
+
+# Remove a feature (drops its manifest entry; directory is left in place — see E3 note).
+python3 "$R/scripts/epic-manifest.py" remove-feature "{epic}" "{feature}" \
+  --specs-dir "{specsDir}"
+
+# Reorder the features[] sequence (must be an exact permutation of current member names).
+python3 "$R/scripts/epic-manifest.py" reorder "{epic}" \
+  --order "feat-a,feat-c,feat-b" --specs-dir "{specsDir}"
+
+# Change a dependency edge (--depends-on "" clears it).
+python3 "$R/scripts/epic-manifest.py" set-dep "{epic}" "{feature}" \
+  --depends-on "config-store,token-service" --specs-dir "{specsDir}"
+
+# Change epic lifecycle status (active|paused|abandoned|complete).
+python3 "$R/scripts/epic-manifest.py" set-status "{epic}" \
+  --status paused --specs-dir "{specsDir}"
+```
+
+### Per-Subcommand Exit-Code Disposition (Step E3)
+
+- Exit `0` → the mutator wrote the manifest and bumped `updatedAt`. Proceed to E4/E5.
+- Exit `1` → surface the `findings[]` **verbatim** and **abort the edit**. The manifest is
+  unchanged (the write was refused atomically — byte-identical). Loop back to E2 or re-elicit.
+- Exit `2` → unsafe name / missing|corrupt manifest / bad `--status` value / write failure.
+  Surface and STOP.
+
+## Error Handling
+
+The skill **never** repairs a corrupt manifest automatically and **never** proceeds past a gating
+helper exit `≥ 1`. All findings are surfaced **verbatim**.
+
+| Condition | Helper signal | Skill behavior |
+|-----------|---------------|----------------|
+| Epic name duplicates an existing name | `check-name` exit 1 (`duplicate-name`) | STOP creation; surface finding; ask for a new name via `AskUserQuestion` |
+| Member feature name duplicates | `check-name` exit 1 (`duplicate-name`) | Reject that name in C2 / add-feature; surface verbatim; re-prompt |
+| Unsafe name (`/`, `..`, absolute) | `check-name`/mutator exit 2 (`unsafe-name`) | Reject; surface; re-prompt |
+| Composed manifest has a cycle | `validate` exit 1 (`cycle`) | Surface verbatim; re-open the dependency interview (C4); never finalize |
+| Dangling `dependsOn`/`consumes.from` | `validate` exit 1 (`dangling-ref`) | Surface verbatim; re-open C4 (bad `dependsOn`) or C3 (bad `consumes.from`) |
+| Corrupt/unparseable manifest (edit) | `validate` exit 1 (`corrupt-json`) | Surface ALL findings verbatim; **refuse all mutation** until repaired; never auto-repair |
+| Existing manifest otherwise invalid (edit) | `validate` exit 1/2 | Surface ALL findings verbatim; **refuse all mutation** (E1) |
+| Mutator would introduce cycle/dangling ref/duplicate | mutator exit 1 | Abort the edit; manifest byte-identical (atomic refusal); surface finding |
+| Bad `--status` value | `set-status` exit 2 (argparse) | Surface; re-prompt via `AskUserQuestion` with the valid choices |
+| Edit affects in-flight/completed feature | `render-status` derived status (`in-progress`/`complete`) | Warn naming the affected feature(s); require confirmation before applying (E4) |
+| `render-status` over an invalid graph | `render-status` exit ≥ 1 | Surface findings; STOP (do not mutate over an invalid graph) |
+| Git commit fails | — | Report; leave state `in-progress`; never bypass hooks (`--no-verify`/`--force`) |

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

@@ -0,0 +1,121 @@
+---
+# 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 /feature-forge: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.
+argument-hint: <feature-name>
+---
+
+# 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.
+
+## Step 1: Read Configuration and Check State
+
+### Branch Setup (if using git)
+If `gitCommitAfterStage` is true and the project uses git, use `AskUserQuestion` to offer: "Want me to create a `forge/{feature}` branch for this pipeline? (Recommended — keeps forge work isolated.)" If yes, create and checkout the branch before proceeding.
+
+Set the working directory by invoking the **Feature Directory Resolution** block in `references/shared-conventions.md`, which yields `{resolvedFeatureDir}`. Note one PRD-specific caveat: at PRD time a brand-new standalone feature may have NO directory yet, so resolution is expected to fail `not-found` for a never-started standalone feature — in that case forge-1 creates `{specsDir}/{feature}/` as today. For an epic member the directory already exists (created empty by forge-0-epic with an `epic` back-pointer), so resolution succeeds and yields the nested path.
+
+If `.pipeline-state.json` exists for this feature and `forge-1-prd` is already marked complete, use `AskUserQuestion` to warn: "A PRD already exists for '{feature}'. Continuing will create a new version. Proceed?"
+
+## 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):
+- 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
+
+**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]."
+
+## 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.
+
+## 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
+
+Write pipeline state conforming to `references/pipeline-state-schema.json`.
+
+1. Create or update `{resolvedFeatureDir}/.pipeline-state.json`:
+   - Set `currentStage` to `forge-2-tech`
+   - Set `stages.forge-1-prd.version` to 1 (or increment if revising)
+   - Record `artifacts`, `completedAt`
+   - Set `stages.forge-1-prd.basedOnVersions` to `{}` (no upstream dependencies)
+   - Check downstream stages (`forge-2-tech`, `forge-3-specs`, `forge-4-backlog`, `forge-5-loop`, `forge-6-docs`). If any have `basedOnVersions` referencing an older version of `forge-1-prd`, set their status to `stale`.
+2. Use `AskUserQuestion` to ask: "Anything you want to note before we wrap? (preserved across sessions)"
+   - If yes, store in the `notes` field
+3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files, attempt commit with message `"{commitPrefix}({feature}): complete PRD v{n}"`, then set `stages.forge-1-prd.status` to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
+5. Tell the user: "PRD complete. Next steps:\n  - `/feature-forge:forge-verify {feature}` to verify the PRD\n  - `/feature-forge:forge-2-tech {feature}` to start the tech spec\n  - `/feature-forge:forge {feature}` to see full pipeline status"
+
+## Gotchas
+
+- 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.

package/adapters/claude/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%)