@garygentry/feature-forge 0.1.0

package/adapters/codex/references/stacks/rust.md

@@ -0,0 +1,151 @@
+# Rust Stack Profile
+
+Stack-specific guidance for Rust projects (stable channel).
+
+## Stack Identity
+
+- **Language**: Rust (stable channel, edition 2021 or later)
+- **Build system**: Cargo (`cargo build`, `cargo test`, `cargo run`)
+- **Package registry**: crates.io (dependencies declared in `Cargo.toml`)
+- **Philosophy**: Zero-cost abstractions, ownership model for memory safety, fearless concurrency
+
+## Discovery Checklist
+
+When examining a Rust project, check for:
+
+- **Project manifest**: `Cargo.toml` (package metadata, dependencies, features, workspace config)
+- **Dependency lock**: `Cargo.lock` (exact dependency versions for reproducible builds)
+- **Library entry**: `src/lib.rs` (library crate root)
+- **Binary entry**: `src/main.rs` (binary crate root), or `src/bin/` for multiple binaries
+- **Build script**: `build.rs` (compile-time code generation, native library linking)
+- **Cargo config**: `.cargo/config.toml` (target-specific settings, linker config, aliases)
+- **Workspace**: `[workspace]` table in root `Cargo.toml` with `members` list
+- **Framework**: Check `Cargo.toml` dependencies for actix-web, axum, rocket (web), clap (CLI), tokio (async)
+- **Async runtime**: tokio, async-std, smol
+- **Serialization**: serde, serde_json, serde_yaml
+
+## Archetype Conventions
+
+### 00-core-definitions.md (Rust)
+
+- **Structs**: Use `struct` types with derive macros (`#[derive(Debug, Clone, Serialize, Deserialize)]`). Document every public field with `///` doc comments.
+- **Enums**: Use for sum types / discriminated unions. Each variant documents its purpose. Exhaustive `match` for control flow.
+- **Traits**: Define shared behavior contracts. Keep focused (single responsibility). Use associated types for output types, generics for input types.
+- **Error types**: `thiserror::Error` for library errors (typed, specific), `anyhow::Error` for application errors (erased, convenient). Define `type Result<T> = std::result::Result<T, MyError>` aliases per module.
+- **Type aliases**: Use `type` for complex generic instantiations (e.g., `type DbPool = Pool<Postgres>`)
+- **Newtypes**: Single-field tuple structs for type safety (e.g., `struct UserId(Uuid)`)
+- **Constants**: `const` for compile-time values, `static` for global state (rarely needed), `lazy_static!` or `std::sync::LazyLock` for runtime-initialized globals
+
+### 01-architecture-layout.md (Rust)
+
+- **Single crate structure**:
+  - `src/lib.rs` — library root, declares modules with `mod` statements
+  - `src/main.rs` — binary entry point, imports from library crate
+  - `src/<module>.rs` or `src/<module>/mod.rs` — submodules
+  - `tests/` — integration tests (each file is a separate crate)
+  - `examples/` — runnable examples (`cargo run --example name`)
+  - `benches/` — benchmarks (`cargo bench`)
+- **Cargo workspace** (multi-crate):
+  - Root `Cargo.toml` with `[workspace]` and `members = ["crates/*"]`
+  - Shared dependencies via `[workspace.dependencies]` with `{ workspace = true }` in member crates
+  - Internal crate references as path dependencies
+- **Cargo.toml**: `[package]` (name, version, edition), `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]`, `[features]` for conditional compilation
+- **Module visibility**: `pub`, `pub(crate)`, `pub(super)` for fine-grained access control. Re-exports via `pub use` in parent modules.
+
+### NN-testing-strategy.md (Rust)
+
+- **Framework**: Built-in `#[test]` attribute (no external framework required)
+- **Unit tests**: `#[cfg(test)] mod tests { ... }` at bottom of each source file (white-box, access to private items)
+- **Integration tests**: `tests/` directory, each `.rs` file is a separate test crate (black-box, only public API)
+- **Test assertions**: `assert!`, `assert_eq!`, `assert_ne!` macros; custom messages as format string arguments
+- **Doc tests**: Code blocks in `///` doc comments run as tests with `cargo test`
+- **Examples**: `examples/` directory, verified to compile with `cargo test`, runnable with `cargo run --example`
+- **Test fixtures**: Builder pattern structs, helper functions in `tests/common/mod.rs`
+- **Async tests**: `#[tokio::test]` attribute for async test functions
+- **Property testing**: `proptest` or `quickcheck` crates for generative testing
+- **Snapshot testing**: `insta` crate for snapshot/approval testing
+
+## Spec Quality Rules
+
+- All Rust code must be valid syntax with complete type annotations — not pseudocode
+- Follow Rust idioms:
+  - `Result<T, E>` for fallible operations — never panic for expected failures
+  - `Option<T>` for nullable/optional values — never use sentinel values
+  - Ownership and borrowing: specify whether a function takes ownership (`T`), borrows (`&T`), or mutably borrows (`&mut T`). Note when `Clone` is required.
+  - Lifetime annotations when the compiler cannot infer them — document why a lifetime relationship exists
+  - Derive macros for common traits (`Debug`, `Clone`, `PartialEq`, `Eq`, `Hash`, `Serialize`, `Deserialize`)
+  - `impl` blocks for methods — group inherent methods and trait implementations separately
+  - Pattern matching with `match` for control flow over enums and `Result`/`Option`
+  - `?` operator for error propagation — avoid manual `match` on `Result` when `?` suffices
+- Document every public item with `///` doc comments including `# Examples` sections for non-trivial APIs
+- Use `#[must_use]` on functions whose return values should not be ignored
+- Include complete `use` statements in all code examples
+
+## Verification Specifics
+
+- **Type checking**: `cargo check` (fast compile without codegen — catches all type errors)
+- **Linting**: `cargo clippy` (idiomatic Rust lints, catches common mistakes)
+- **Testing**: `cargo test` (unit tests, integration tests, doc tests, examples)
+- **Documentation**: `cargo doc --no-deps` (ensures documentation compiles, catches broken links)
+- **Formatting**: `cargo fmt --check` (ensures code matches `rustfmt` style)
+- **Unsafe audit**: `cargo geiger` (if security-sensitive — counts unsafe blocks)
+
+## Testing
+
+- **Framework**: Built-in test harness (`#[test]`, `#[cfg(test)]`)
+- **Test command**: `cargo test` for all, `cargo test test_name` for specific, `cargo test --lib` for unit only
+- **Unit tests**: `#[cfg(test)] mod tests` at bottom of source files
+- **Integration tests**: `tests/` directory, each file is a separate crate
+- **Doc tests**: Code in `///` comments, verified by `cargo test --doc`
+- **Assertions**: `assert!`, `assert_eq!`, `assert_ne!` with optional format messages
+- **Async tests**: `#[tokio::test]` macro for async test functions
+- **Snapshot testing**: `insta` crate with `assert_snapshot!` / `assert_debug_snapshot!`
+- **Coverage**: `cargo llvm-cov` or `cargo tarpaulin`
+- **Benchmarks**: `criterion` crate or built-in `#[bench]` (nightly)
+
+## Common Frameworks
+
+| Category | Options |
+|----------|---------|
+| Web (async) | axum, actix-web, rocket, warp |
+| Serialization | serde, serde_json, serde_yaml, toml |
+| Async runtime | tokio, async-std, smol |
+| Database | sqlx, diesel, sea-orm |
+| Migrations | sqlx-cli, diesel-cli, refinery |
+| CLI | clap, argh, structopt (legacy) |
+| Observability | tracing, tracing-subscriber, metrics |
+| HTTP client | reqwest, hyper, ureq (blocking) |
+| Middleware | tower, tower-http, actix middleware |
+| Error handling | thiserror (library), anyhow (application), eyre |
+
+## Example: Project-Level Override
+
+Create `.claude/references/stack-decisions.md` in your project root:
+
+```markdown
+# Stack Decisions
+
+## Runtime & Build
+- Rust stable (edition 2021)
+- Cargo workspace with crates/ directory
+
+## Backend
+- axum for HTTP framework
+- sqlx with PostgreSQL (compile-time query checking)
+- tokio as async runtime
+
+## Serialization & Validation
+- serde for serialization/deserialization
+- Custom validation via trait implementations
+
+## Testing
+- Built-in #[test] with assert macros
+- Integration tests in tests/ directory
+- insta for snapshot testing
+
+## Conventions
+- thiserror for library error types, anyhow in binary
+- tracing for structured logging
+- cargo clippy must pass with no warnings
+- All public APIs documented with /// and examples
+```

package/adapters/codex/references/stacks/typescript.md

@@ -0,0 +1,111 @@
+# TypeScript Stack Profile
+
+Stack-specific guidance for TypeScript projects (Node.js/Bun, monorepo or single-package).
+
+## Stack Identity
+
+- **Language**: TypeScript
+- **Runtime**: Node.js or Bun (check `package.json` `engines` field and lock files)
+- **Package management**: npm, pnpm, yarn, or bun (check for respective lock files)
+- **Common monorepo tools**: Turborepo (`turbo.json`), Nx (`nx.json`), Lerna (`lerna.json`)
+
+## Discovery Checklist
+
+When examining a TypeScript project, check for:
+
+- **Runtime**: Bun or Node.js (check `package.json` for which)
+- **Package management**: Check for `bun.lockb`, `pnpm-lock.yaml`, `package-lock.json`, or `yarn.lock`
+- **Monorepo**: Check for `turbo.json` (Turborepo), `nx.json` (Nx), or `lerna.json` (Lerna)
+- **Framework**: Check existing packages for Hono, Express, Fastify, etc.
+- **Frontend**: Check for React, Vue, Svelte, etc.
+- **Routing**: Check for TanStack Router, React Router, Next.js, etc.
+- **Database**: Check for Drizzle, Prisma, TypeORM, etc.
+- **Validation**: Check for Zod, Yup, io-ts, etc.
+- **UI Components**: Check for shadcn/ui, Radix, MUI, etc.
+- **Styling**: Check for Tailwind (v3 or v4), CSS Modules, styled-components, etc.
+
+## Archetype Conventions
+
+### 00-core-definitions.md (TypeScript)
+
+- **Type aliases and union types**: Use `type` declarations for unions, intersections, utility types
+- **Core interfaces**: Define with `interface` keyword, JSDoc on every field
+- **Error class hierarchy**: Base error class extending `Error` with `code: string` property; domain-specific subclasses with typed properties
+- **Constants and enums**: Use `const` declarations and `as const` assertions; prefer string union types over `enum`
+- **Utility types**: Generic helpers like `Result<T, E>`, `Optional<T>`, etc.
+- **Barrel exports**: Export everything from `src/index.ts`
+
+### 01-architecture-layout.md (TypeScript)
+
+- **Package.json**: `name`, `exports` map (subpath exports like `.`, `./server`, `./client`, `./react`), `dependencies`, `devDependencies`, `scripts`
+- **tsconfig.json**: Key compiler options, extends root config
+- **Barrel export structure**: What each `index.ts` re-exports
+- **Build considerations**: Bundle vs unbundled, ESM vs CJS
+
+### Monorepo conventions
+
+- **Package naming**: `@repo/{name}` for shared packages, `@starter/{name}` for app-specific (adapt to project convention)
+- **Internal dependencies**: Reference as `@repo/{package}` in `package.json`
+- **Workspace protocol**: `"@repo/config": "workspace:*"` in pnpm, `"@repo/config": "*"` in bun
+
+## Spec Quality Rules
+
+- All TypeScript must be valid syntax — not pseudocode
+- Include complete interfaces with generics where applicable
+- Use discriminated unions for result types (e.g., `{ success: true; data: T } | { success: false; error: E }`)
+- Every interface field must have JSDoc explaining its purpose
+- Include explicit import paths in all code examples
+- Use `async/await` for asynchronous operations (not raw Promises)
+
+## Verification Specifics
+
+- **Type checking**: `bun run typecheck`, `tsc --noEmit`, or `npx tsc --noEmit`
+- **Barrel export validation**: Every `index.ts` re-exports what the spec says
+- **Cross-package type checks**: `bun run typecheck` (or equivalent) passes for both the feature package AND packages that depend on it
+- **Import path validation**: All import paths resolve correctly per the `exports` map in `package.json`
+
+## Testing
+
+- **Framework**: Vitest (most common in modern TS), Jest, or testing-library
+- **Test file location**: Co-located (`*.test.ts` next to source) or in `__tests__/` directories
+- **Fixture patterns**: Factory functions, test builders
+- **Type testing**: `expectTypeOf` from vitest for type-level assertions
+
+## Common Frameworks
+
+| Category | Options |
+|----------|---------|
+| Backend | Hono, Express, Fastify, Koa |
+| Frontend | React, Vue, Svelte, Solid |
+| Routing | TanStack Router, React Router, Next.js App Router |
+| Database | Drizzle, Prisma, TypeORM, Kysely |
+| Validation | Zod, Valibot, Yup, io-ts |
+| UI Components | shadcn/ui, Radix, MUI, Mantine |
+| Styling | Tailwind CSS, CSS Modules, styled-components, vanilla-extract |
+
+## Example: Project-Level Override
+
+Create `.claude/references/stack-decisions.md` in your project root:
+
+```markdown
+# Stack Decisions
+
+## Runtime & Build
+- Bun 1.x for runtime and package management
+- Turborepo for monorepo orchestration
+
+## Backend
+- Hono for HTTP framework
+- Drizzle ORM with PostgreSQL
+- Zod for runtime validation
+
+## Frontend
+- React 19 with TanStack Router (SPA-first)
+- shadcn/ui component library
+- Tailwind CSS v4 with oklch color theming
+
+## Conventions
+- Barrel exports from index.ts in every package
+- Package naming: @repo/{name} for shared, @starter/{name} for app-specific
+- Vitest for testing
+```

package/adapters/codex/references/vendor-construct-inventory.md

@@ -0,0 +1,49 @@
+# Vendor-Construct Inventory
+
+> Feature: `forge-skill-spec-purity` (epic `agent-agnostic`, target repo **feature-forge**).
+> Source of truth: `PRD.md` (v1) + `tech-spec.md` (v1).
+> This file is the REQ-VND-03 audit output — the single, exhaustive record of every vendor-specific
+> construct found across all 11 skills and their `references/`, each with exactly one disposition.
+
+## Disposition Legend
+
+Every disposition cell in the inventory below is exactly one member of the closed `Disposition`
+vocabulary defined in `00-core-definitions.md` §8. No free-form values are permitted.
+
+| Disposition | Meaning |
+|---|---|
+| `relocated` | Moved to a spec-allowed location (e.g. `metadata`). |
+| `removed` | Deleted from canon (none expected in this tree). |
+| `preserved-as-spec-allowed` | Kept as-is; already spec-legal. |
+| `out-of-canon` | Kept but documented as non-canonical (e.g. `hooks/hooks.json`). |
+| `routed-through-resolver` | `${CLAUDE_PLUGIN_ROOT}` replaced by the bootstrap prelude + `scripts/forge-root.sh`. |
+
+## Inventory
+
+| Construct | Locations / count | Disposition | Rationale / notes |
+|---|---|---|---|
+| `argument-hint` (top-level frontmatter key) | 10 `skills/*/SKILL.md` (all skills **except** `forge-init`) | `relocated` | Claude-specific vendor key (constraint C-2). Moved verbatim to `metadata.argument-hint` per REQ-VND-01 (see `02-frontmatter-purity-and-inventory.md` §2). Value byte-identical; `description` untouched. |
+| `${CLAUDE_PLUGIN_ROOT}` — canonical invocations + prose | 23 occurrences across 9 canonical surfaces: `skills/forge-0-epic/SKILL.md` (12), `skills/forge/SKILL.md` (3), `skills/forge-5-loop/SKILL.md` (1), `skills/forge-6-docs/SKILL.md` (1), `skills/forge-init/SKILL.md` (1), `skills/forge-verify/SKILL.md` (1), `skills/forge-verify/references/verification-checklists.md` (1), `references/shared-conventions.md` (2), `agents/forge-verifier.md` (1) | `routed-through-resolver` | Claude-only env var. Routed through the byte-identical bootstrap prelude + `scripts/forge-root.sh` per REQ-RES-03. Mechanics owned by `03-portable-root-resolver.md`; recorded here for audit completeness. |
+| `${CLAUDE_PLUGIN_ROOT}` — sanctioned residual | 1 occurrence in `scripts/forge-root.sh` (env-fallback, REQ-RES-02 step 3) | `preserved-as-spec-allowed` | The single sanctioned residual: the resolver's documented Claude-compat fallback (REQ-RES-03 / REQ-RES-05). Exempt from the residual-var scan (`00-core-definitions.md` §6 `RESIDUAL_VAR_EXEMPT`). |
+| `${CLAUDE_PLUGIN_ROOT}` — in `hooks/hooks.json` | 1 occurrence in `hooks/hooks.json` | `out-of-canon` | Non-canonical Claude artifact (REQ-VND-04). Not a canonical surface; exempt from the REQ-RES-03 scan. Left in place. |
+| `hooks/hooks.json` SessionStart wiring | 1 file (`hooks/hooks.json`) — Claude `SessionStart` → `bash ${CLAUDE_PLUGIN_ROOT}/scripts/session-check.sh` | `out-of-canon` | Claude-specific plugin hook wiring (REQ-VND-04, decision D3). Preserved + documented so `forge-agent-adapters-build` treats it as a Claude artifact, not portable canon. |
+| (contingency) any other vendor invocation directive | none found in the audit | — | REQ-VND-02 contingency did not fire (see Notes). If one is later surfaced, add a row with `removed` or `out-of-canon` per `02-frontmatter-purity-and-inventory.md` §3. |
+
+## Notes
+
+- **REQ-VND-02 contingency did not fire.** The exhaustive audit found **no** Codex / Copilot /
+  Cursor / Gemini invocation directive — and no other agent-specific run-this command block — in any
+  skill body or frontmatter. The only vendor constructs in scope across the suite are the three
+  recorded above: `argument-hint`, `${CLAUDE_PLUGIN_ROOT}`, and the `hooks/hooks.json` SessionStart
+  wiring. Treating REQ-VND-02 as a contingency rather than an action item is therefore correct.
+- **`${CLAUDE_PLUGIN_ROOT}` relocation mechanics** — the prelude replacement, the resolver, and the
+  canonical-surface routing — are owned by `03-portable-root-resolver.md`; this file only records the
+  inventory dispositions.
+- **The closed `Disposition` vocabulary** is defined in `00-core-definitions.md` §8; the legend above
+  reproduces it so this file is self-contained for a downstream reader.
+- The two surviving `${CLAUDE_PLUGIN_ROOT}` instances (the `forge-root.sh` env fallback and the
+  `hooks/hooks.json` literal) are written here as descriptive text in code spans so they are not
+  routable invocations and do not trip the spec-purity checker's residual-var rule, consistent with
+  how `02-frontmatter-purity-and-inventory.md` §5 records them.
+</content>
+</invoke>

package/adapters/codex/scripts/forge-root.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# scripts/forge-root.sh — the portable skill/plugin-root resolver
+# (exposed contract: portable-skill-root-resolver; REQ-RES-01..05, REQ-SEC-01).
+#
+# Prints the absolute feature-forge plugin root to stdout and exits 0, or writes an
+# actionable error to stderr and exits 1. Takes no arguments. Idempotent and
+# side-effect-free: it NEVER sources or executes a discovered path — it only prints a
+# directory (REQ-SEC-01). Resolution is bounded to the candidate roots below plus this
+# script's own on-disk location.
+#
+# This file is copied VERBATIM into per-agent script mirrors by the downstream adapter
+# generator (REQ-RES-05); keep it dependency-free beyond POSIX/Bash + the sentinel files.
+set -euo pipefail
+
+# Sentinel predicate (00-core-definitions.md §2 / SENTINEL_FILES). A directory is a valid
+# plugin root iff BOTH sentinel files exist. Content-based, so it identifies a feature-forge
+# install under ANY agent's directory layout.
+is_root() {  # $1 = candidate dir
+  [ -f "$1/scripts/epic-manifest.py" ] && [ -f "$1/.claude-plugin/plugin.json" ]
+}
+
+# ── Step 1: self-location — parent of this script's dir is the plugin root. ──────────────
+self_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+root="$(cd -- "$self_dir/.." && pwd -P)"
+if is_root "$root"; then
+  printf '%s\n' "$root"
+  exit 0
+fi
+
+# ── Step 2: candidate-root probe (authoritative multi-root list; extend here first). ─────
+# Globs that match nothing expand to themselves; the is_root test rejects such literals.
+for candidate in \
+  "$HOME/.claude/skills/feature-forge" \
+  "$HOME"/.claude/plugins/*/feature-forge \
+; do
+  if is_root "$candidate"; then
+    printf '%s\n' "$candidate"
+    exit 0
+  fi
+done
+
+# ── Step 3: env fallback — the SINGLE sanctioned residual ${CLAUDE_PLUGIN_ROOT} (C-4). ───
+if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && is_root "$CLAUDE_PLUGIN_ROOT"; then
+  printf '%s\n' "$CLAUDE_PLUGIN_ROOT"
+  exit 0
+fi
+
+# ── Step 4: failure — actionable message to stderr, exit 1 (REQ-RES-04). ─────────────────
+echo "feature-forge: cannot locate plugin root. Set CLAUDE_PLUGIN_ROOT or run from an installed skill dir." >&2
+exit 1

package/adapters/codex/skills/forge/forge.md

@@ -0,0 +1,164 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge
+description: Feature-forge pipeline navigator and status dashboard. Use when the user references the forge pipeline, asks about forge status or progress, types /feature-forge:forge, or wants to check what stage a feature is at in the forge pipeline. Do NOT use for general feature requests, project status, or tasks unrelated to the forge development pipeline.
+---
+
+# Feature Forge — Pipeline Navigator
+
+You are the navigator for the feature-forge development pipeline. Your job is to orient the user: show where they are, what's been done, and what's next.
+
+## Behavior
+
+### 1. Read Configuration
+
+Read and follow `references/shared-conventions.md` for configuration reading (feature name validation, config defaults, force mode).
+
+For pipeline architecture details, read `references/process-overview.md`.
+
+### 2. Determine Context
+
+**If a feature name is provided** (e.g., `/feature-forge:forge auth`):
+- **First test whether the name is an epic:** if `{specsDir}/{name}/epic-manifest.json` exists, render the **Epic Dashboard** (see format below) and stop — do not treat it as a feature.
+- Otherwise, resolve the name via the **Feature Directory Resolution** block in `references/shared-conventions.md` (so a nested epic-member name finds its dashboard too). On a resolution failure (`not-found` / `ambiguous` at exit 1; `unsafe-name` or a path-containment escape at exit 2), surface it verbatim.
+  - On `not-found` for a never-started feature, ask: "No pipeline exists for '{feature}'. Want to start one? Run `/feature-forge:forge-1-prd {feature}` to begin."
+- If resolution succeeds, display the per-feature pipeline status dashboard (see format below) from `{resolvedFeatureDir}/`.
+
+**If no feature name is provided:** list in two tiers.
+
+1. **Epics first.** Identify epic directories as any `{specsDir}/*/` that directly contains an `epic-manifest.json` **and no `.pipeline-state.json` of its own** (an epic root is never itself a feature). For each epic, 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
+   ```
+   and show one rollup line: `{epic} — {complete}/{total} complete, next: {nextCommand}`.
+2. **Standalone features below.** Scan the remaining `{specsDir}/*/` that directly contain a `.pipeline-state.json` **without** an `epic` back-pointer. A nested member's `.pipeline-state.json` is **attributed to its epic (Tier 1), never listed as a standalone feature**.
+   - Within this standalone tier the existing logic still applies: if exactly one active (non-complete) standalone pipeline exists, show its dashboard; if multiple exist, list them with a one-line summary each and use `AskUserQuestion` to ask which to focus on.
+
+If no epics and no standalone features exist, say: "No active feature pipelines found. Start one with `/feature-forge:forge-1-prd <feature-name>` or group several with `/feature-forge:forge-0-epic <epic-name>`."
+
+The feature name must be a single kebab-case token. If the user provides multiple words (e.g., "user auth flow"), convert to kebab-case: `user-auth-flow`.
+
+### 3. Pipeline Status Dashboard
+
+Write pipeline state conforming to `references/pipeline-state-schema.json`.
+
+Display a clear, scannable status for the feature:
+
+```
+Feature: {feature}  [active]
+Stage: {currentStage} ({status}, started {relative time})
+
+✅ forge-1-prd     → PRD.md (v{n})
+⬜ forge-verify     (prd)          ← show only if forge-1-prd is complete
+✅ forge-2-tech    → tech-spec.md (v{n}, ⚠️ not yet verified)
+⬜ forge-verify     (tech)         ← show only if forge-2-tech is complete
+🔄 forge-3-specs   → in progress
+⬜ forge-verify     (specs)        ← show only if forge-3-specs is complete
+⬜ forge-4-backlog
+⬜ forge-verify     (backlog)      ← show only if forge-4-backlog is complete
+⬜ forge-5-loop
+⬜ forge-6-docs
+
+Next: Continue with /feature-forge:forge-3-specs {feature}
+      Or verify tech-spec with /feature-forge:forge-verify {feature}
+
+Notes: "{any persisted notes}"
+```
+
+Use these status indicators:
+- ✅ = complete
+- ✅⚠️ = complete but not yet verified
+- 🔄 = in progress
+- ⬜ = pending
+- ❌ = verification found issues (not yet fixed)
+- ✅🔍 = verified and fixes applied
+- ⏭️ = verification skipped (user chose to proceed without verifying)
+- ⚠️ = stale (built against an older version of an upstream artifact)
+
+### Epic Dashboard
+
+When the named argument is an epic (`{specsDir}/{name}/epic-manifest.json` exists), render the epic dashboard instead of a per-feature one. 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
+```
+
+and render from its output:
+
+- **Epic header:** name + `status` (active | paused | abandoned | complete).
+- **Dependency graph:** each feature with its `dependsOn`, as an arrow list or indented tree (the helper guarantees the graph is acyclic).
+- **Per-feature rows:** reuse the **existing status indicators** below (✅/✅⚠️/🔄/⬜/❌/✅🔍/⏭️/⚠️), driven by each feature's derived `stage`/`status`. Mark `blocked` features and list their `unmetDeps`.
+- **Actionable vs blocked:** list the `actionable` set and the recommended `nextCommand`.
+- **Rollup:** `{complete}/{total} features complete`.
+
+Example:
+
+```
+Epic: auth-overhaul  [active]   —   2/4 features complete
+
+Dependency graph:
+  config-store      (no deps)
+  token-service     → config-store
+  api-gateway       → token-service
+  audit-log         (no deps)
+
+✅ config-store     complete
+🔄 token-service    forge-3-specs (in progress)
+⬜ api-gateway      blocked — waiting on token-service
+✅ audit-log        complete
+
+Actionable now: token-service
+Next: /feature-forge:forge-3-specs token-service
+```
+
+All of this is reconstructed **purely from disk** — the manifest plus each member's `.pipeline-state.json`, with no in-memory state — so a fresh session renders the same dashboard. If `render-status` fails, do not render a partial dashboard; surface 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).
+
+### 4. Notes Management
+
+If the user says something like "note: switching to jose for JWT" or "remember: we decided X", update the `notes` field in `.pipeline-state.json`. This helps preserve context across session clears.
+
+### 5. Available Commands Reference
+
+When showing the dashboard, include a compact reference:
+
+```
+Commands:
+  /feature-forge:forge-1-prd <feature>      Create requirements document
+  /feature-forge:forge-2-tech <feature>     Create technical spec
+  /feature-forge:forge-3-specs <feature>    Create implementation specs
+  /feature-forge:forge-4-backlog <feature>  Generate rauf backlog
+  /feature-forge:forge-5-loop <feature>  Run rauf autonomous loop
+  /feature-forge:forge-6-docs <feature>     Generate architecture docs
+  /feature-forge:forge-verify <feature>     Run verification on current stage
+```
+
+### 6. Pipeline Lifecycle Commands
+
+Support these sub-commands for pipeline lifecycle management:
+- `/feature-forge:forge pause {feature}` — Set `pipelineStatus` to `"paused"`. Do NOT modify `currentStage` or any stage statuses. The pipeline freezes exactly as-is. Show a confirmation.
+- `/feature-forge:forge resume {feature}` — Set `pipelineStatus` back to `"active"`. Calculate how long the feature was paused (from `updatedAt` to now). If paused for more than 24 hours, show a hint: "This feature was paused for {duration}. Session context may have been lost — consider re-running `/feature-forge:forge-{currentStage} {feature}` to rebuild context."
+- `/feature-forge:forge abandon {feature}` — Set `pipelineStatus` to `"abandoned"`. Use `AskUserQuestion` to confirm with user first. Note: abandoned pipelines can be resumed with `/feature-forge:forge resume {feature}` if the user changes their mind.
+
+**Epic lifecycle.** When the argument names an **epic** (`{specsDir}/{name}/epic-manifest.json` exists), `pause` / `resume` / `abandon` operate on the epic manifest, not a `.pipeline-state.json`:
+
+- Set the manifest's top-level `status` (`paused` / `active` / `abandoned`) via the helper's `set-status` mutator — an atomic write that also bumps `updatedAt`:
+  ```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" set-status "{epic}" --status paused --specs-dir "{specsDir}"
+  ```
+  For `complete`, do **not** set the status directly — completion is *derived* from member states (the rollup), so the manifest `status` is a lifecycle flag, never a completion signal.
+- **Member feature states are NOT silently mutated.** Pausing/abandoning the epic changes only the manifest `status`. Before doing so, use `AskUserQuestion` to make the relationship explicit: "Pausing the epic does not pause its in-flight member features. {N} members are active. Pause the epic only, or also pause each member?" If the user opts to pause members too, update each member's own `pipelineStatus` **individually and visibly** (one explicit action per member), never as a hidden side-effect.
+- Commit the change via the Git Commit Protocol, staging `{specsDir}/{epic}/`.
+
+When listing features, show active pipelines by default. Include a count of paused/abandoned: "3 active pipelines (1 paused, 1 abandoned — use `/feature-forge:forge list all` to see them)."
+
+## Gotchas
+
+- Never modify any spec files, backlog files, or pipeline state beyond the `notes`, `updatedAt`, and `pipelineStatus` fields. The navigator is read-only except for notes and lifecycle commands.
+- If a user asks to "continue" or "pick up where I left off" without naming a feature, check for active pipelines before asking. Only ask if ambiguous.
+- The pipeline state file is the source of truth. Don't infer stage from the existence of files alone — a file might exist from a previous incomplete run.