@garygentry/feature-forge 0.1.0

package/adapters/claude/skills/forge/SKILL.md

@@ -0,0 +1,165 @@
+---
+# 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.
+argument-hint: <feature-name> (optional — lists all active features if omitted)
+---
+
+# 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.

package/adapters/claude/skills/forge-0-epic/SKILL.md

@@ -0,0 +1,303 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-0-epic/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-0-epic
+description: 'Create or edit a forge epic: decompose a large change into discrete member features with dependencies, charters, and structured contracts, producing epic-manifest.json + EPIC.md. Re-run on an existing epic to enter edit mode (add/remove/reorder features, change dependencies). Use when the user runs /feature-forge:forge-0-epic or explicitly asks to start/modify an epic. Do NOT trigger for single-feature PRD work (that is forge-1-prd) or for general project planning outside forge.'
+argument-hint: <epic-name>
+---
+
+# forge-0-epic — Epic Decomposition & Orchestration
+
+Create an epic — a named grouping of related forge features with declared dependencies
+and shared contracts — through a structured decomposition interview, OR edit an existing
+epic. The manifest is the source of truth; EPIC.md mirrors it. All graph/validation work
+is delegated to `scripts/epic-manifest.py`.
+
+This skill **composes** JSON and **issues** helper commands. It NEVER eyeballs a dependency
+graph for cycles, NEVER hand-rolls a manifest write where a mutator exists, and NEVER asks a
+question in inline prose — every question goes through `AskUserQuestion`.
+
+## Prerequisites
+
+Read and follow `references/shared-conventions.md` for:
+- the **Feature Name Requirement** (applied here to the *epic* name — see below),
+- the **User Input Protocol** (the AskUserQuestion guardrail — all questions go through the tool),
+- **Configuration Reading**, and
+- the **Git Commit Protocol**.
+
+**Epic name handling.** The single positional argument is the **epic** name (not a feature).
+If no name is given, STOP and ask for one — do not guess. Convert multi-word input to a single
+kebab-case token. The name must satisfy `SAFE_NAME_RE` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`); the
+helper rejects unsafe names. Member feature names are elicited later, in the interview.
+
+**Force mode.** `--force` is honored as in shared-conventions: skip pipeline-state prerequisite
+checks but still load any on-disk artifacts.
+
+**Config values read** (defaults from shared-conventions): `specsDir` (default `./specs`),
+`gitCommitAfterStage` (default true), `commitPrefix` (default `forge`).
+
+**Helper invocation.** Every helper call uses the convention from 01 §2.2 — the absolute
+plugin path and the configured specs dir:
+
+```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" <subcommand> ... --specs-dir "{specsDir}"
+```
+
+`$R` resolves to the installed plugin root via the portable resolver (`scripts/forge-root.sh`,
+bootstrapped by the prelude above; see `references/portable-root.md`). Pass `--specs-dir "{specsDir}"`
+on every invocation.
+
+---
+
+## Step 0 — Dispatch Detection
+
+Resolve the epic subtree path `{specsDir}/{epic}/` and decide which branch to run.
+
+1. **Collision check — is this name already a standalone feature?** If `{specsDir}/{epic}/`
+   exists and directly contains a `.pipeline-state.json` of its own (i.e. it is itself a
+   *feature* directory, not an epic root), STOP. Surface verbatim:
+   > `{epic}` is already a standalone feature, not an epic. Choose a different epic name or
+   > relocate the feature.
+
+2. **Manifest existence probe** — does this epic already have a manifest?
+
+   ```bash
+   test -f "{specsDir}/{epic}/epic-manifest.json" && echo EXISTS || echo NEW
+   ```
+
+   - **NEW** (no `epic-manifest.json`) → **Creation branch** (Step C1 onward).
+   - **EXISTS** → **Edit branch** (§ Edit Mode below).
+
+3. **Pre-flight epic-name uniqueness (creation only).** Before composing anything for a NEW
+   epic, confirm the epic name itself does not collide with any existing feature or epic:
+
+   ```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" check-name "{epic}" --specs-dir "{specsDir}"
+   ```
+
+   - Exit `0` → the name is free; proceed to C1.
+   - Exit `1` (`duplicate-name`) → STOP and surface the helper's finding **verbatim**; ask
+     (via `AskUserQuestion`) for a different epic name, then re-run check-name.
+   - Exit `2` (unsafe name) → STOP and surface the finding; ask for a corrected name.
+
+---
+
+## Creation Branch
+
+### Step 1 — Branch Setup (optional)
+
+If `gitCommitAfterStage` is true and the project uses git, use `AskUserQuestion`:
+"Create a `forge/{epic}` branch for this epic? (Recommended — keeps epic work isolated.)"
+If yes, create and checkout the branch before proceeding.
+
+### Step C1 — Epic Framing Interview
+
+Output context as text (what an epic is, that a decomposition interview will follow). Then
+call `AskUserQuestion` to elicit:
+
+1. **Epic goal / problem** — the overarching change being decomposed. Becomes the EPIC.md
+   "Overall Goal" narrative and seeds the manifest `description`.
+2. **One-paragraph description** — a confirmed/edited summary. Becomes the manifest `description`.
+
+The epic `name` is the validated CLI argument from Step 0 — do NOT prompt for it again.
+
+### Step C2 — Feature-List Interview
+
+Drive a decomposition dialogue. Output your analysis as text first (how the goal might split,
+right-sizing guidance: each feature should be a single pipeline-sized unit — a unit forge-1-prd
+through forge-5-loop would carry end-to-end — not item-level interleaving). Then use
+`AskUserQuestion` to elicit the candidate feature list. Probe with questions like "Is any of
+these two features really one?" and "Is any one of these really two?" Iterate until the user
+confirms the set.
+
+For **each** proposed feature name, before accepting it into the set, enforce global uniqueness
+and name safety via the helper:
+
+```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" check-name "{feature}" --specs-dir "{specsDir}"
+```
+
+- Exit `0` → accept the name.
+- Exit `1` (`duplicate-name`) → reject that name; surface the finding verbatim and re-prompt
+  (via `AskUserQuestion`) for a different name.
+- Exit `2` (`unsafe-name`) → reject; surface the finding and re-prompt.
+
+Never accept a feature name that has not passed `check-name` exit 0.
+
+### Step C3 — Per-Feature Charter + Structured Contracts
+
+For each confirmed feature, run a focused `AskUserQuestion` batch (one feature at a time,
+2–3 questions per call) eliciting:
+
+- **Charter** — a single paragraph: scope statement + contract obligations. This is a
+  **charter only, NOT a PRD**. Do NOT conduct a full requirements interview here. If the user
+  starts dictating detailed requirements, redirect (as context text, then continue the batch):
+  > "That's PRD-level detail — `forge-1-prd` will capture it when this feature is ready. For
+  > the charter I just need the one-paragraph scope and what it must expose/consume."
+- **`exposes`** — zero or more structured `Contract` objects this feature provides to
+  dependents. Each is `{ "name", "kind", "summary" }` where `kind` ∈
+  `function | type | endpoint | module | event`.
+- **`consumes`** — zero or more structured `ConsumedContract` objects this feature relies on.
+  Each is `{ "from", "name", "summary" }`, where `from` is a sibling feature name in this epic.
+
+Collect these into plain JSON objects per feature. Do NOT free-form the contracts in prose —
+the structured arrays are the source of truth; EPIC.md renders them as prose later (Step C6).
+
+### Step C4 — Dependency-Edge Interview
+
+For each feature, use `AskUserQuestion`: "Which sibling features must be complete before this
+one can build?" → populates `dependsOn: [names]`.
+
+**Seed the suggestion from `consumes`:** a `consumes.from` X strongly implies `dependsOn` X.
+Offer the union of each feature's `consumes.from` set as the default, but let the user confirm —
+`dependsOn` is the authoritative edge set.
+
+The `features[]` array order is the user-declared sequence from C2 (order is a presentation
+sequence, **not** a dependency ordering). Preserve the C2 order unless the user asks to reorder.
+
+### Step C5 — Compose & Validate the Manifest
+
+Compose the full `epic-manifest.json` per the 00 §2 schema, setting:
+
+- `schemaVersion`: `1`
+- `epic`: `"{epic}"`
+- `description`: from C1
+- `status`: `"active"`
+- `narrativeDoc`: `"EPIC.md"`
+- `createdAt` and `updatedAt`: the **same** current ISO-8601 UTC timestamp (`createdAt == updatedAt`)
+- `features[]`: in declared order, each with `name`, `charter`, `dependsOn`, `exposes`,
+  `consumes`. **No per-feature `status` field** — including one makes the manifest fail
+  validation (the `cached-status` finding).
+
+Write the composed JSON to `{specsDir}/{epic}/epic-manifest.json` (creating the epic dir first).
+For the *initial* creation write the skill writes the file directly — atomic guarantees are only
+required for in-place mutation, which is the helper mutators' job. Then validate:
+
+```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` → proceed to C6.
+- Exit `1` → the manifest is malformed. Surface **every** `findings[]` entry **verbatim**, do
+  NOT proceed, and loop back into the relevant interview step to correct, then re-compose and
+  re-validate:
+  - `cycle` → re-open the dependency interview (C4).
+  - `dangling-ref` → re-open C4 (bad `dependsOn`) or C3 (bad `consumes.from`).
+  - `duplicate-name` / `unsafe-name` → re-open the feature-list interview (C2).
+  - `cached-status` / schema violation → fix the composed JSON and re-validate.
+- Exit `2` → IO/usage error (missing manifest or unreadable). Surface and STOP.
+
+Acyclicity, uniqueness, and dangling-ref checks are thus ALWAYS performed by the helper, never
+by the LLM eyeballing the graph.
+
+> **Contracts have no mutator.** There is intentionally no `--exposes-json`/`--consumes-json`
+> flag. At creation, the skill populates each feature's `exposes`/`consumes` directly in the
+> composed manifest entry (above), then re-runs `validate` — exactly as described here. The
+> same pattern applies after an edit-mode `add-feature` (see Edit Mode).
+
+### Step C6 — Generate EPIC.md
+
+Generate `{specsDir}/{epic}/EPIC.md` from the **validated** manifest. It is the human-readable
+**mirror** of the manifest (the manifest is the source of truth). For the full EPIC.md structure
+skeleton, read `references/edit-mode.md` (EPIC.md Mirror Template section) — the same template the
+edit-mode E5 patch applies.
+
+**The mirror rule.** Render each feature's `exposes`/`consumes` arrays as prose, one bullet per
+contract entry, preserving `name`, `kind`/`from`, and `summary`. Do not invent a contract that
+is not in the manifest, and do not omit one that is. The Overall Goal and Decomposition
+Rationale are the only prose without a 1:1 manifest counterpart. The skill does NOT itself diff
+EPIC.md against the manifest — drift detection is `forge-verify` epic mode CHECK-E06.
+
+### Step C7 — Create Member Subdirectories + Back-Pointer States
+
+After the manifest validates and EPIC.md is written, create one subdirectory per member feature
+so the navigator and resolver can see them before any stage runs. For each `features[].name`:
+
+1. Create `{specsDir}/{epic}/{feature}/`.
+2. Write `{specsDir}/{epic}/{feature}/.pipeline-state.json` conforming to
+   `references/pipeline-state-schema.json`, carrying:
+   - `epic`: `"{epic}"` — the back-pointer.
+   - `currentStage`: `"forge-1-prd"` — the next actionable stage for the member.
+   - `stages["forge-0-epic"]`: `{ "status": "complete", "version": 1, "completedAt": "<ts>" }`
+     — recording that the epic stage seeded this member.
+   - No other stages (all other stages absent/pending), exactly as a freshly-initialized
+     standalone feature. **No per-feature `status` beyond the stage entry** — the member state
+     holds derived stage progress only.
+
+For an example member state, read `references/edit-mode.md` (Member State Example section).
+
+The member subtree holds the **same** artifact set a standalone feature holds; only
+`.pipeline-state.json` exists at creation. No PRD/specs are authored here. The epic subtree is
+now self-contained: manifest + EPIC.md + one subdirectory per member.
+
+### Step C8 — Review, Pipeline State & Commit
+
+1. **Review.** Present a summary (epic name, N features, dependency edges, contracts) as text,
+   then use `AskUserQuestion`: "Does this epic decomposition look right? Any feature, dependency,
+   or contract to change before I commit?" If the user wants changes, loop back to the relevant
+   creation step, re-compose, and re-validate.
+
+2. **Commit (Git Commit Protocol).** If `gitCommitAfterStage` is true, follow the Git Commit
+   Protocol in shared-conventions:
+   - Stage the whole epic subtree only: `git add {specsDir}/{epic}/` — never `git add -A`. This
+     captures `epic-manifest.json`, `EPIC.md`, and all member `.pipeline-state.json` files
+     atomically.
+   - Commit with message `"{commitPrefix}({epic}): create epic with {N} features"`.
+   - On success, capture the commit hash. On failure (pre-commit hook, conflict), report and do
+     not mark complete; never use `--no-verify`/`--force`.
+
+3. **Closing message.** After a successful creation, tell the user the next steps:
+
+   > Epic `{epic}` created with {N} features. Next steps:
+   >  - `/feature-forge:forge {epic}` to see the epic dashboard
+   >  - `/feature-forge:forge-verify {epic}` to verify the epic
+   >  - `/feature-forge:forge-1-prd {first-actionable-feature}` to start the first feature
+
+   The first-actionable feature is any feature with empty `dependsOn` (or the first entry of
+   `render-status`'s `actionable` set).
+
+---
+
+## Edit Mode
+
+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 — atomic
+(temp file + `os.replace`) and internally re-validated, so a refused write leaves the manifest
+**byte-identical**; the skill never hand-rolls an in-place write. Every question goes through
+`AskUserQuestion`, and **every mutation is committed individually** so git history is the audit trail.
+
+For the full E1–E6 mechanics — the E1 refuse-if-invalid protocol, E2 operation→mutator table, E3
+contracts/remove-feature caveats (incl. the verbatim WARN block), E4 impact-warning rules, E5
+EPIC.md patch rule, and the E6 Observability / Pipeline State & Commit machinery
+(`.epic-state.json` schema, `updatedAt` rules, Git Commit Protocol shared with C8) — read
+`references/edit-mode.md`. For the exact `epic-manifest.py` mutator flag surface and
+per-subcommand exit-code (`0`/`1`/`2`) handling, read `references/epic-manifest-subcommands.md`.
+
+---
+
+## Error Handling
+
+The skill **never** repairs a corrupt manifest automatically and **never** proceeds past a gating
+helper exit `≥ 1`. All findings are surfaced **verbatim**. For the full condition → helper-signal →
+skill-behavior disposition table, read `references/epic-manifest-subcommands.md` (Error Handling
+section).
+
+---
+
+## Gotchas
+
+- The argument names an **epic**, not a feature — this is the only stage where that is true.
+  Member feature names come from the C2 interview, each gated through `check-name`.
+- Never eyeball the dependency graph for cycles. Compose the manifest, run `validate`, and
+  surface findings. The helper owns acyclicity, uniqueness, dangling-ref, and schema checks.
+- A charter is one paragraph, not a PRD. Redirect requirement-level detail to `forge-1-prd`.
+- Contracts have no mutator: edit `exposes`/`consumes` in the composed manifest entry, then
+  re-run `validate`.
+- All questions go through `AskUserQuestion`. Never put a question in your text output.