@garygentry/feature-forge 0.1.0

package/adapters/cursor/skills/forge-6-docs/forge-6-docs.mdc

@@ -0,0 +1,179 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-6-docs/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+description: Generate developer-focused architecture documentation for a forge pipeline feature. Use when user runs /feature-forge:forge-6-docs or asks to generate docs after implementation is complete. Do NOT trigger for general documentation writing, README creation, or doc generation outside the forge pipeline.
+globs: []
+alwaysApply: false
+---
+
+# forge-6-docs — Architecture Documentation Generator
+
+Generate developer-focused architecture documentation for a feature, suitable for onboarding, reference, and maintenance.
+
+## Prerequisites
+
+Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
+
+**Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
+
+## Step 1: Read Context
+
+Resolve the feature directory via the **Feature Directory Resolution** block in `references/shared-conventions.md` (so a standalone feature resolves to its flat `{specsDir}/{feature}/` path exactly as today, and an epic member resolves to its nested path). Use the resulting `{resolvedFeatureDir}` everywhere this skill previously wrote `{specsDir}/{feature}/`.
+
+Read `{resolvedFeatureDir}/.pipeline-state.json` to understand what exists.
+
+### Gather Sources
+
+Load into context:
+1. **Specs**: PRD.md, tech-spec.md, all implementation specs
+2. **Implementation**: Read the actual source code for this feature's package
+3. **Existing docs**: Check `{docsDir}/` for other features' docs to match conventions
+4. **README**: Check if the feature package has its own README.md
+
+### Implementation Completeness Check
+
+Check `{resolvedFeatureDir}/backlog.json` (or `{backlogDir}/{feature}/backlog.json` if configured). Count items with status `complete` vs total. If implementation is less than 80% complete, use `AskUserQuestion` to warn: "Implementation is only N% complete. Documentation will be based primarily on specs and may need updates after implementation. Proceed?" If user proceeds, add a `PRE-IMPLEMENTATION` notice at the top of each generated doc.
+
+Also check `.pipeline-state.json` for `stages.forge-5-loop`. If it exists and has status `in-progress` (some items incomplete), include this in the warning: "The rauf loop has not fully completed — {done}/{total} items done. Documentation may need updates after remaining items are implemented."
+
+### Epic-Level Documentation (epic members only)
+
+If the resolved feature has an `epic` back-pointer in its `.pipeline-state.json`, run:
+
+```bash
+R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
+```
+
+If `render-status` fails, skip the epic-level offer and proceed with the per-feature docs only; surface the error per the exit-1/exit-2 split in the **Feature Directory Resolution** block of `references/shared-conventions.md` (exit 1 → parse `{findings[]}` from stdout; exit 2 → surface the plain `Error:` stderr line verbatim).
+
+**Only if `rollup.total > 0 AND rollup.complete == rollup.total`** (every member is complete-for-orchestration; the `total > 0` guard excludes an empty epic), use `AskUserQuestion` to offer:
+
+"All {total} features in the '{epic}' epic are complete. Generate an **epic-level architecture document** spanning the features, in addition to {feature}'s per-feature docs?"
+
+On yes, synthesize a doc at **`{docsDir}/{epic}/`** sourced from: the `EPIC.md` narrative, each member's per-feature docs, and the manifest contracts (each feature's `exposes`/`consumes`). When the epic-level doc is written, the Step 5 commit also stages `{docsDir}/{epic}/`.
+
+If not all members are complete (or the feature has no `epic` back-pointer), **do not offer** — the per-feature doc flow proceeds unchanged.
+
+Read `references/doc-conventions.md` for documentation standards.
+
+## Step 2: Plan Documentation Structure
+
+Based on feature complexity and existing doc conventions, propose a doc plan:
+
+**Minimum (simple feature):**
+```
+{docsDir}/{feature}/
+├── README.md          — Overview, quick start, key concepts
+└── api-reference.md   — Exported APIs, types, configuration
+```
+
+**Standard (typical feature):**
+```
+{docsDir}/{feature}/
+├── README.md          — Overview, quick start, key concepts
+├── architecture.md    — Design decisions, data flow, component relationships
+├── api-reference.md   — Exported APIs, types, configuration
+└── guides/
+    └── integration.md — How to integrate this feature into an app
+```
+
+**Comprehensive (complex feature):**
+```
+{docsDir}/{feature}/
+├── README.md          — Overview, quick start, key concepts
+├── architecture.md    — Design decisions, data flow, component relationships
+├── api-reference.md   — Exported APIs, types, configuration
+├── configuration.md   — All configuration options with examples
+├── guides/
+│   ├── getting-started.md  — Step-by-step setup
+│   ├── integration.md      — How to integrate with other packages
+│   └── troubleshooting.md  — Common issues and solutions
+└── decisions/
+    └── adr-001-*.md   — Architecture decision records (if significant decisions were made)
+```
+
+Present the plan and use `AskUserQuestion` to get the user's confirmation.
+
+## Step 3: Write Documentation
+
+### Key Principles
+
+**Write for the reader, not the writer.**
+- A developer encountering this feature for the first time should be able to understand it from the docs alone
+- Lead with the "what" and "why" before the "how"
+- Include code examples for every exported API
+- Don't assume familiarity with the spec documents
+
+**Be accurate to the implementation, not the spec.**
+- If the implementation diverged from the spec, document the implementation
+- Specs are the source of truth for design intent; code is the source of truth for behavior
+- Read the actual source code to verify your documentation is correct
+
+**Match existing conventions.**
+- If other features' docs use a specific heading structure, follow it
+- If they include diagrams, include diagrams
+- If they use a specific tone (formal, casual, tutorial-style), match it
+
+### README.md Structure
+
+```markdown
+# {Feature Name}
+
+{One-paragraph description of what this feature does and why it exists.}
+
+## Quick Start
+
+{Minimal code to get started — import, configure, use.}
+
+## Key Concepts
+
+{Explain the domain model and core abstractions in plain language.}
+
+## Package Exports
+
+{Table of subpath exports and what each contains.}
+
+| Export / Entry Point | Description |
+|---------------------|-------------|
+| `{module}` | Shared types and utilities |
+| `{module}/server` | Server-side functionality |
+| ...    | ... |
+
+Adapt export paths to match the project's module/package conventions.
+
+## Configuration
+
+{Key configuration options with defaults.}
+
+## Further Reading
+
+- [Architecture](./architecture.md) — Design decisions and data flow
+- [API Reference](./api-reference.md) — Complete API documentation
+- [Integration Guide](./guides/integration.md) — How to use with other packages
+```
+
+## Step 4: Review with User
+
+Present the docs as text. Then use `AskUserQuestion` to collect feedback — do NOT include these questions in your text output:
+
+"1. Does this accurately reflect the implementation? 2. Is the level of detail appropriate for your team? 3. Any areas that need more explanation?"
+
+## Step 5: Update Pipeline State and Commit
+
+Write pipeline state conforming to `references/pipeline-state-schema.json`.
+
+1. Update `{resolvedFeatureDir}/.pipeline-state.json`:
+   - Set `currentStage` to `complete`
+   - Record `artifacts`
+   - Set `stages.forge-6-docs.basedOnVersions` to include versions for all completed upstream stages. Always include forge-1-prd, forge-2-tech, forge-3-specs. Include forge-4-backlog and forge-5-loop ONLY if they have status `complete`.
+2. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files (`git add {docsDir}/{feature}/ {resolvedFeatureDir}/` — and **also** `{docsDir}/{epic}/` when an epic-level doc was written in Step 1), attempt commit with message `"{commitPrefix}({feature}): complete architecture docs"`, then set `stages.forge-6-docs.status` to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
+4. Tell user: "Documentation complete. Feature pipeline for '{feature}' is finished!\n  `/feature-forge:forge {feature}` to see the final pipeline status."
+
+## Gotchas
+
+- Don't just rephrase the specs. Documentation should explain the implemented system, not the planned system. Read the actual code.
+- If the implementation doesn't exist yet (backlog hasn't been run), document based on specs but note prominently that docs are pre-implementation and may need updating.
+- API reference should include actual function signatures from the code, not from the spec (they may differ).
+- Don't generate docs that will immediately be stale. Focus on concepts, architecture, and patterns rather than line-by-line code walkthroughs.
+- Include "When to use" and "When NOT to use" sections — they save developers more time than any other documentation pattern.

package/adapters/cursor/skills/forge-6-docs/references/doc-conventions.md

@@ -0,0 +1,126 @@
+# Documentation Conventions
+
+Standards and patterns for feature architecture documentation.
+
+## General Rules
+
+- Write in present tense ("The auth module validates..." not "The auth module will validate...")
+- Use second person for guides ("You can configure..." not "One can configure...")
+- Include code examples for every exported function, class, or component
+- Code examples must be runnable — no pseudocode, no incomplete snippets
+- Use the project's primary language for all code examples
+
+## Heading Structure
+
+- H1: Feature name (only in README.md)
+- H2: Major sections
+- H3: Subsections
+- Don't go deeper than H4
+
+## Code Examples
+
+The following examples use TypeScript. Adapt language and import syntax to your project's stack. The principle — always include imports, show complete runnable examples — applies to all languages.
+
+Always include import statements:
+```typescript
+// Good
+import { createAuthMiddleware } from '@repo/auth/server';
+
+const middleware = createAuthMiddleware({ secret: process.env.JWT_SECRET });
+
+// Bad — missing import, unclear where this comes from
+const middleware = createAuthMiddleware({ secret: process.env.JWT_SECRET });
+```
+
+### Complete Quick Start Example
+
+Here's a complete "Quick Start" section showing the expected quality:
+
+```markdown
+## Quick Start
+
+Install the auth package:
+
+```bash
+bun add @repo/auth
+```
+
+Add the auth middleware to your Hono server:
+
+```typescript
+import { createAuthMiddleware } from '@repo/auth/server';
+import { getConfig } from '@repo/config';
+
+const config = getConfig();
+
+app.use('*', createAuthMiddleware({
+  secret: config.auth.jwtSecret,
+  cookieName: 'session',
+}));
+```
+
+Access the session in any route handler:
+
+```typescript
+app.get('/api/me', (c) => {
+  const session = c.get('session');
+  if (!session) return c.json({ error: 'Not authenticated' }, 401);
+  return c.json({ userId: session.userId, roles: session.roles });
+});
+```
+
+For full configuration options, see [API Reference](./api-reference.md).
+For setting up OAuth providers, see [Integration Guide](./guides/integration.md).
+```
+
+## API Reference Format
+
+For each exported item:
+
+```markdown
+### `functionName(params): ReturnType`
+
+Brief description of what this does.
+
+**Parameters:**
+- `param1` (`Type`) — Description
+- `param2` (`Type`, optional) — Description. Defaults to `defaultValue`.
+
+**Returns:** `ReturnType` — Description
+
+**Throws:** `ErrorType` — When condition
+
+**Example:**
+\`\`\`typescript
+import { functionName } from '@repo/feature';
+
+const result = functionName({ param1: 'value' });
+\`\`\`
+```
+
+## Diagrams
+
+If the feature has complex data flow or component relationships, include a Mermaid diagram:
+
+```markdown
+\`\`\`mermaid
+graph LR
+  A[Request] --> B[Auth Middleware]
+  B --> C{Valid Session?}
+  C -->|Yes| D[Route Handler]
+  C -->|No| E[401 Response]
+\`\`\`
+```
+
+## Cross-References
+
+When referencing other packages or features:
+- Link to their docs if they exist: `[Configuration package](../config/README.md)`
+- Use the package name in backticks: `@repo/config`
+- Don't duplicate their documentation — link to it
+
+## File Naming
+
+- All lowercase with hyphens: `api-reference.md`, `getting-started.md`
+- Guides go in a `guides/` subdirectory
+- ADRs go in a `decisions/` subdirectory with format `adr-NNN-short-title.md`

package/adapters/cursor/skills/forge-fix/forge-fix.mdc

@@ -0,0 +1,65 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-fix/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+description: Apply fixes from the most recent forge-verify findings document. Use when user runs /feature-forge:forge-fix or asks to apply verification fixes for a forge feature. Do NOT trigger for general code fixes, bug fixes, or repairs outside the forge verification workflow.
+globs: []
+alwaysApply: false
+---
+
+# forge-fix — Apply Verification Fixes
+
+Apply fixes from the most recent forge-verify findings document, with step-level tracking for crash recovery.
+
+## Prerequisites
+
+Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
+
+**Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
+
+## Step 1: Locate Findings Document
+
+1. Read `forge.config.json` for `specsDir` (default: `./specs`)
+2. Resolve the feature directory via the **Feature Directory Resolution** block in `references/shared-conventions.md` (a standalone feature resolves to its flat `{specsDir}/{feature}/` path exactly as today; an epic member resolves to its nested path). Then find the most recent `VERIFY-*-*.md` file in `{resolvedFeatureDir}/.verification/`.
+3. If no findings document exists, tell the user: "No verification findings found. Run `/feature-forge:forge-verify {feature}` first."
+
+## Step 2: Parse Fix Execution Plan
+
+1. Read the "Fix Execution Plan" section of the findings document
+2. Identify all execution steps and their dependencies
+3. Check for a `## Fix Progress` section at the bottom of the findings document — if present, some steps were already applied in a previous interrupted run
+
+## Step 3: Handle User Decisions
+
+If the "User Decisions Required" section has unresolved items:
+1. Present each decision to the user with the context from the findings, using `AskUserQuestion` for each decision point. Only recommend a specific option if the findings provide clear evidence for it; otherwise present options neutrally.
+2. Wait for answers before proceeding
+3. Record decisions in the findings document under the "User Decisions Required" section (mark each as resolved)
+
+## Step 4: Execute Fix Steps
+
+For each step in the "Execution Steps" section, in order:
+
+1. **Check if already applied:** If the step appears in the "Fix Progress" section as `[APPLIED]`, skip it
+2. **Check dependencies:** If the step depends on another step, verify that step is marked as applied
+3. **Apply the fix:** Execute the change described in the step's "Action" field
+4. **Verify the change:** Re-read the modified file and check that the change is correct and consistent with the step's rationale
+5. **Record progress:** Append to the `## Fix Progress` section at the bottom of the findings document:
+   ```
+   - Step {N}: [APPLIED] {date} — {short summary of what was done}
+   ```
+6. If a step fails or produces unexpected results, STOP. Report the issue to the user. Do not continue to dependent steps.
+
+## Step 5: Update Pipeline State and Commit
+
+Follow the Git Commit Protocol in `references/shared-conventions.md`.
+
+1. Update `{resolvedFeatureDir}/.pipeline-state.json`:
+   - Set the relevant `forge-verify-*` entry status to `findings-applied`
+   - Record `fixedAt` timestamp
+2. If `gitCommitAfterStage` is true, follow the Git Commit Protocol: stage files (`git add {resolvedFeatureDir}/` — or `{specsDir}/{epic}/` for an epic member so the member-state change commits atomically with the epic subtree), attempt commit with message `"{commitPrefix}({feature}): apply {mode} verification fixes"`, then record commit hash only on success.
+
+## Step 6: Next Steps
+
+Tell the user:
+"Fixes applied. Next steps:
+  - Run `/feature-forge:forge-verify {feature}` again to confirm all issues are resolved
+  - Or `/feature-forge:forge {feature}` to see pipeline status"

package/adapters/cursor/skills/forge-init/forge-init.mdc

@@ -0,0 +1,30 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-init/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+description: Initialize feature-forge configuration in the current project. Use when user runs /feature-forge:forge-init or asks to set up forge for the first time. Creates forge.config.json with defaults. Do NOT trigger for general project initialization or setup tasks outside the forge pipeline.
+globs: []
+alwaysApply: false
+---
+
+# Initialize Feature Forge
+
+Run the initialization script to create `forge.config.json` with default settings:
+
+```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; }
+bash "$R/scripts/forge-init.sh"
+```
+
+After initialization, the config file will contain defaults for:
+- `specsDir`: `./specs`
+- `docsDir`: `./docs/architecture`
+- `backlogDir`: `null` (backlog lives alongside specs)
+- `gitCommitAfterStage`: `true`
+- `commitPrefix`: `forge`
+- `stack`: `null` (detected during `/feature-forge:forge-2-tech`)
+- `typeCheckCommand`: `null` (set during `/feature-forge:forge-2-tech`)
+- `testCommand`: `null` (set during `/feature-forge:forge-2-tech`)
+
+If `forge.config.json` already exists, the script will not overwrite it.
+
+After initialization, start the pipeline with `/feature-forge:forge-1-prd <feature-name>`.

package/adapters/cursor/skills/forge-verify/forge-verify.mdc

@@ -0,0 +1,219 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-verify/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+description: Verify forge pipeline artifacts for completeness, consistency, and quality. Use when user runs /feature-forge:forge-verify or asks to check forge specs, backlog, or implementation for gaps. Do NOT trigger for general code review, quality checks, or verification tasks outside the forge pipeline.
+globs: []
+alwaysApply: false
+---
+
+# forge-verify — Verification Gate
+
+Analyze feature artifacts for completeness, consistency, and quality. Produce structured, actionable findings designed for a fresh-context agent to apply.
+
+## Subagent Delegation
+
+This skill is delegated to the `forge-verifier` subagent via the Agent tool. The verifier subagent has:
+- **Read-only tools** (Read, Glob, Grep, Bash) — it cannot accidentally modify specs
+- **Persistent memory** — it accumulates knowledge about this project's recurring issues and patterns across sessions
+- **The forge-verify skill pre-loaded** — so it has all verification checklists and guidance at startup
+
+### Choose single vs. parallel dispatch
+
+Pick based on how many checks the mode carries (see the per-mode totals in Step 3):
+
+- **Small modes (prd ~15, tech ~15): single verifier.** Use the Agent tool once with
+  `subagent_type="forge-verifier"`, passing the feature name and mode. It runs all
+  checks and returns findings.
+- **Large modes (specs ~38, backlog ~25, impl ~20): parallel dimensioned fan-out.**
+  Split the mode's checklist into **dimension groups** and dispatch **one
+  `forge-verifier` per group, in parallel — a single message with multiple Agent
+  calls** (the `superpowers:dispatching-parallel-agents` pattern). Each instance owns a
+  disjoint slice of CHECK-IDs, so it verifies deeper over a narrower scope and they all
+  run concurrently. Suggested groups (map to the category clusters in
+  `references/verification-checklists.md`):
+  - **specs:** (1) types/contracts, (2) architecture/layout, (3) cross-reference &
+    traceability, (4) testing strategy, (5) integration.
+  - **backlog:** (1) item scoping & acceptance criteria, (2) dependency/ordering sanity,
+    (3) spec coverage & traceability, (4) schema/enum correctness.
+  - **impl:** (1) requirement coverage vs specs, (2) integration correctness,
+    (3) testing, (4) code-quality/conventions.
+
+  In each parallel instance's prompt, pass: the feature, the mode, the **dimension
+  label**, the **exact CHECK-IDs it owns**, and a note that **it is one of several
+  parallel instances** — it must verify ONLY its assigned checks and return findings
+  for that slice. Tell parallel instances to treat their `MEMORY.md` as **read-only**
+  (apply learned patterns, but do NOT write it — concurrent writers would race);
+  memory consolidation is left to single-verifier runs.
+
+### Synthesize (parent session)
+
+The verifier(s) are read-only — they return findings as their response; **you** (the
+parent) assemble and write the single document to
+`{specsDir}/{feature}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`. When you fanned out:
+1. Concatenate all instances' findings and **renumber `V-NNN` IDs uniquely** across the
+   merged set.
+2. **Dedup** overlaps — when two instances flag the same file+location+issue (e.g. a
+   cross-reference and a type-contract verifier both catch one mismatch), keep one,
+   union their `Checklist:` IDs.
+3. Build the **single Fix Execution Plan** over the merged findings (Step 5). The output
+   document format is unchanged, so `forge-fix` consumes it identically.
+
+### Adversarial confirmation (opt-in "deep verify")
+
+When the user asks for a deep/thorough verify, add a confirmation pass before writing:
+for each `error`- and `gap`-severity finding, dispatch a short skeptic `forge-verifier`
+prompted to **refute** it ("here is a claimed finding; prove it wrong; default to
+REFUTED if you cannot confirm it from the artifacts"). Drop findings the skeptic refutes
+with confidence — this cuts false positives before they reach the user. Lower-severity
+findings (`improvement`, `inconsistency`) skip this pass.
+
+### Fallback
+
+If the `forge-verifier` subagent is not available (not installed, or an environment
+without subagents), fall back to running verification inline in the current session.
+
+**Inline execution guidance:** If running inline (not as subagent), process verification checklists one category at a time to manage context pressure. Load only the artifacts needed for each category, verify, summarize findings, then move to the next category.
+
+## Prerequisites
+
+Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
+
+**Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
+
+## Step 1: Read Configuration and Determine Mode
+
+Read `{specsDir}/{feature}/.pipeline-state.json` to understand current pipeline state.
+
+### Mode Selection
+
+If a stage is specified as a second argument (e.g., `/feature-forge:forge-verify auth specs`), use that mode. Otherwise, auto-detect based on pipeline state:
+
+- **epic mode**: Explicit via `/feature-forge:forge-verify {epic} epic`, or auto-detected when the named argument resolves to an **epic directory** — i.e. `{specsDir}/{name}/epic-manifest.json` exists (an epic root holds `epic-manifest.json` but no `.pipeline-state.json` of its own). When the argument is an epic, prefer epic mode over feature-mode resolution.
+- **prd mode**: If `forge-1-prd` is complete but `forge-verify-prd` is not `passed` or `findings-applied`
+- **tech mode**: If `forge-2-tech` is complete but `forge-verify-tech` is not `passed` or `findings-applied`
+- **specs mode**: If `forge-3-specs` is complete but `forge-verify-specs` is not `passed` or `findings-applied`
+- **backlog mode**: If `forge-4-backlog` is complete but `forge-verify-backlog` is not `passed` or `findings-applied`
+- **impl mode**: If user explicitly requests or if implementation code exists for this feature
+
+If ambiguous, use `AskUserQuestion` to ask which stage to verify.
+
+## Step 2: Load All Relevant Artifacts
+
+Load into context ALL artifacts for this feature based on mode:
+
+**For prd mode:**
+- `{specsDir}/{feature}/PRD.md`
+
+**For tech mode:**
+- `{specsDir}/{feature}/PRD.md`
+- `{specsDir}/{feature}/tech-spec.md`
+
+**For specs mode:**
+- `{specsDir}/{feature}/PRD.md`
+- `{specsDir}/{feature}/tech-spec.md`
+- `{specsDir}/{feature}/##-*.md` (all implementation specs)
+
+**For backlog mode:**
+- All of the above, PLUS
+- `{resolvedFeatureDir}/backlog.json` (or `{backlogDir}/{feature}/backlog.json` if `backlogDir` is configured) — resolve `{resolvedFeatureDir}` via the **Feature Directory Resolution** block in `references/shared-conventions.md`, using the same composed path as forge-4-backlog and forge-5-loop (04 §6.2)
+
+**For impl mode:**
+- All of the above, PLUS
+- The actual source code for this feature (read package directory)
+- Source code of packages this feature integrates with
+
+**For epic mode:**
+- `{specsDir}/{epic}/epic-manifest.json`
+- `{specsDir}/{epic}/EPIC.md`
+- each member feature's `.pipeline-state.json` (for the `epic` back-pointer + derived status)
+- each **completed** member's `PRD.md` + `tech-spec.md` (for contract-drift checking, CHECK-E06)
+
+## Step 3: Run Verification Checklists
+
+Read `references/verification-checklists.md` for the detailed checklists per mode. Execute every check. Do not skip checks because things "look fine." That same reference also holds the relocated **Findings Document Template (Step 4)**, the worked **Example Findings (Step 4)**, and the **Epic Mode State Write Detail (Step 6)** sections used later in this skill.
+
+Each check in `verification-checklists.md` has a unique ID (CHECK-P01, CHECK-T01, CHECK-S01, CHECK-B01, etc.). As you execute each check, record its ID and result (pass/fail/not-applicable). After completing all checks, report the total: "Executed N of M checks. Results: X pass, Y fail, Z not-applicable." If your count is significantly below the expected total for the mode (prd: ~15 checks, tech: ~15 checks, specs: ~38 checks, backlog: ~25 checks, impl: ~20 checks, epic: ~8 checks), you likely skipped checks — go back and complete them.
+
+**Epic mode dispatch.** Epic mode is a small (~8-check) checklist, so per the single-vs-parallel rule above, dispatch a **single `forge-verifier`** via the Agent tool, passing the epic name and `mode=epic`. The verifier runs CHECK-E01..E08 from the `## Epic Mode Checklist` in `references/verification-checklists.md` (E01/E02/E03/E08 are delegated to `epic-manifest.py validate`/`check-name`; E04–E07 are verifier judgment) and returns its findings.
+
+### Important: Be Specific, Not General
+
+BAD finding: "The error handling could be more thorough."
+GOOD finding: "PRD.md REQ-ERR-04 requires rate limit retry behavior, but spec 03-provider-registry.md only handles rate limits by throwing — no retry logic is specified."
+
+Every finding must include:
+1. A unique ID (V-001, V-002, etc.)
+2. Severity: `gap` (missing requirement coverage), `inconsistency` (contradictory specs), `improvement` (not wrong but could be better), `error` (factually incorrect)
+3. Exact location (file + section)
+4. What's wrong
+5. Suggested fix (specific enough that a fresh agent can apply it)
+6. References (which other files/sections are involved)
+7. Related checklist item(s) (e.g., CHECK-P01, CHECK-S12)
+
+## Step 4: Write Findings Document
+
+Ensure the `.verification/` subdirectory exists, then write findings to `{specsDir}/{feature}/.verification/VERIFY-{mode}-{YYYY-MM-DD}.md`.
+
+**For epic mode**, the target is `{specsDir}/{epic}/.verification/VERIFY-epic-{YYYY-MM-DD}.md` (the same format, with `{mode}=epic`).
+
+The full findings-document template (report header, `V-NNN` finding shape, and the
+Fix Execution Plan layout) and the worked **Example Findings** (gap / inconsistency /
+improvement) live in `references/verification-checklists.md` under the **Findings
+Document Template (Step 4)** and **Example Findings (Step 4)** sections — follow that
+template verbatim when writing the document.
+
+## Step 5: Fix Plan and Next Steps
+
+The Fix Execution Plan (written as part of the findings document in Step 4) is ALWAYS generated regardless of mode. This ensures the findings document is self-contained: diagnosis + action plan in one artifact.
+
+When building the Fix Execution Plan:
+1. Group related findings into logical steps (e.g., all type-system fixes together)
+2. Order steps to avoid conflicts (fix shared types before documents that reference them)
+3. Each step must be specific enough for a fresh agent with zero prior context to execute
+4. Flag any findings that require user decisions before fixes can be applied
+
+**If in plan mode:** Also write the Fix Execution Plan to the active plan file so the plan mode workflow is preserved. The user reviews the plan, exits plan mode, and a fresh agent executes the fixes.
+
+**If not in plan mode:** Output the following as text:
+"Findings and fix plan written to `{findings-file}`."
+
+Then use `AskUserQuestion` to ask: "Would you like to: (a) Review the findings first, (b) Run `/feature-forge:forge-fix {feature}` to apply fixes now, or (c) Enter plan mode and re-run `/feature-forge:forge-verify {feature}` for plan-mode workflow?" Do NOT embed this question in your text output.
+
+## Step 6: Update Pipeline State
+
+Write pipeline state conforming to `references/pipeline-state-schema.json`.
+
+Update `{specsDir}/{feature}/.pipeline-state.json`:
+- Set the relevant verify entry status to `findings-reported`
+- Record `findingsFile`, `findingsCount`, `verifiedAt`
+
+Do NOT mark as `findings-applied` — that happens after the fix pass.
+
+### Epic mode state (`.epic-state.json`)
+
+Epic mode is **epic-scoped**, not per-feature: record its result into the epic-level
+state file `{specsDir}/{epic}/.epic-state.json` — **never** into any member's
+`.pipeline-state.json`. Set `stages.forge-verify-epic.status` to `findings-reported`
+(or `passed` if zero findings), recording `findingsFile`, `findingsCount`, and
+`verifiedAt`. The full `.epic-state.json` schema (minimal shape) and the atomic
+temp-file + `os.replace()` **write-mechanism** detail (lazy-create, merge/replace,
+fail-intact) — including the worked Python snippet — live in
+`references/verification-checklists.md` under the **Epic Mode State Write Detail
+(Step 6)** section. Follow it verbatim.
+
+Do NOT mark as `findings-applied` — that happens after the fix pass.
+
+## Gotchas
+
+- This skill should be run in plan mode for best results. The plan gives the user a chance to review before committing to changes.
+- Verification is most valuable when it finds things that are MISSING, not just things that are present but imperfect. Prioritize gap detection over style preferences.
+- Don't verify things that are intentionally left open (check the PRD's "Open Questions" section).
+- If you find zero issues, say so honestly. Don't manufacture findings to seem thorough. But zero findings on a complex feature is suspicious — double-check.
+- The findings document must be self-contained. A fresh agent reading it should be able to apply every fix without needing conversational context from this session.
+- For backlog verification, also run the loop runner's validate command (resolve `loopRunner` from `forge.config.json`, default rauf: `rauf backlog validate . --backlog {backlogDir} --specs-dir {specsDir}/{feature} --json`). Include any findings it reports (exit 1) as verification findings; if the runner isn't installed yet (command missing), note that backlog validation was skipped rather than failing.
+- For specs verification, also run the deterministic traceability validator to supplement agent-driven traceability checks. Include any uncovered requirements or orphaned references as findings:
+
+```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/validate-traceability.py" {specsDir}/{feature}/PRD.md {specsDir}/{feature}/ --json
+```