@garygentry/feature-forge 0.1.0

package/adapters/claude/skills/forge-5-loop/references/runner-contract.md

@@ -0,0 +1,214 @@
+# forge-5-loop — Loop-Runner Contract (launch, supervision, model precedence)
+
+This file holds the detailed loop-runner contract relocated out of
+`forge-5-loop/SKILL.md`: the event-stream vs. log-fallback **launch** detail
+(Steps 3b/3d/3e), the structured-surface **monitoring** caveats, the **model
+precedence** rule, and the **optional-flags catalog** referenced from Step 2d.
+Every command below is rendered from `loopRunner` with token substitution, as in
+the skill body.
+
+## Model selection precedence (Step 2d)
+
+The runner picks the per-iteration model by precedence (highest wins):
+
+```
+item.model  >  --model / options  >  project default  >  provider default
+```
+
+So a backlog item's own `model` field overrides a `--model` flag passed to the
+run, which overrides the project's configured default, which overrides the
+runner/provider default. Pass `--model <model>` (optional flag below) to override
+the project default for the whole run.
+
+## Agent selection (Step 2d)
+
+This section is **parallel** to `## Model selection precedence` above: it governs
+which **coding agent** rauf drives for the run. The entire surface is
+**presence-gated** on `loopRunner.agentArgument` — when that field is absent or
+empty, there is no selector, no probe, and no `{agent}` substitution, and Step 2d /
+Step 3c are byte-identical to today (capability gate;
+`02-config-schema-and-gating.md`, REQ-PLUG-02). The rest assumes the gate is on.
+
+**Precedence (highest wins):**
+
+```
+item.provider  >  --agent (run selection)  >  loopRunner.defaultAgent (project)  >  runner default (claude-cli)
+```
+
+**Run-layer mapping — why forge never re-implements rauf's resolver.** forge owns
+**only** its run and project layers and collapses them into **one** value
+(`resolve()`: `run_selection or defaultAgent or none`), which it emits as a single
+`--agent {agent}` occupying rauf's **run layer only**. rauf alone resolves
+item-vs-run via its own 5-layer resolver, sitting the per-item `BacklogItem.provider`
+**above** forge's run layer — so a run selection can never clobber a deliberate
+per-item agent. forge **never reads, writes, or overrides** `BacklogItem.provider`
+(REQ-AGENT-05). When forge sends nothing (the default path), rauf applies its own
+default `claude-cli`, byte-identical to today. Empty/whitespace selections are
+treated as unset, and an explicit pick of the runner default id collapses to the
+default path (append nothing, run no probe). See
+`03-selection-resolution-observability.md §3–§4`.
+
+**Availability pre-check + disambiguation.** For a **non-default** resolved id only,
+forge runs `loopRunner.agentsProbeCommand` **once** (no retries) and classifies the
+id by **membership** in the advertised set (`{ row.id for row in agents }`), then the
+matching row's `available` flag — **never** by exit code, because `rauf agents
+--json` always exits 0 (an unknown id is simply absent; a known-unavailable one is
+present with `available: false`):
+
+- **UNKNOWN** (`∉` advertised set): hard-reject **before any loop side-effect**,
+  listing the sorted valid ids; **no proceed-anyway**; the value never interpolates
+  into `{agent}` (the advertised set IS the allow-list — REQ-SEC-01).
+- **UNAVAILABLE** (member, `available == False`): warn with the row's `detail`, then
+  offer **proceed-anyway OR choose-another** — never silent.
+- **AVAILABLE** (member, `available == True`): proceed; the validated id fills
+  `{agent}`.
+- **Probe failure** (non-zero exit / unparseable / wrong shape / empty `agents[]` /
+  row missing `id`): surface it and offer **choose-another OR abort**; never launch
+  the non-default agent unvalidated, never silently fall back to the default.
+
+The default / `claude-cli` path runs **no** probe (zero extra cost). See
+`04-availability-precheck.md` for the full pre-check, classification, and allow-list,
+and `02-config-schema-and-gating.md` for the capability gate.
+
+## Optional flags catalog (Step 2d, rauf)
+
+These are the optional flags the user may add to the rendered run command. If the
+user requests additional flags, append them to the rendered run command.
+
+```
+  --agent <id>      Coding agent rauf drives this run (see Agent selection below).
+                    Only the runner's advertised ids are valid; an unknown id is
+                    rejected before launch. Shown only when the runner advertises
+                    an agent surface (loopRunner.agentArgument present).
+  --review          Run a review pass after all iterations (extra agent session)
+  --model <model>   Override the model (see precedence above)
+  --timeout <min>   Per-session timeout in minutes (default: 60)
+  --retry-blocked   Unblock and retry previously blocked items
+```
+
+## Launch detail (Step 3b — background process)
+
+Launch the loop **backgrounded** so it survives session end and does not block the
+session, and prefer the machine-readable event stream so the session can supervise
+it live.
+
+- **If `loopRunner.eventStreamCommand` is configured (default for rauf):** render it
+  (it appends `--ndjson` to the run) and launch via the Bash tool with
+  `run_in_background: true`, redirecting stdout to a stable events file:
+
+  ```
+  mkdir -p {backlogDir}/{loopRunner.stateDir} && {rendered eventStreamCommand} > {backlogDir}/{loopRunner.stateDir}/events.ndjson 2>&1
+  ```
+
+  (The `mkdir -p` guards the very first run, before the runner has created its
+  state dir.) This emits one JSON event per line **and** keeps the loop detached. The background
+  task's exit notification remains the single authoritative terminal signal (Step 4).
+- **Fallback (runner has no `eventStreamCommand`):** launch the plain `runCommand`
+  with `run_in_background: true`. The session will then supervise by tailing the
+  human log (3d fallback) instead of the NDJSON file.
+
+Loop runs can take significant time (minutes to hours depending on backlog size).
+
+## Arm a Monitor on the event stream (Step 3d)
+
+Arm the **`Monitor` tool** on the structured event stream so events flow back into
+this session as they happen. Use **`persistent: true`** — runs can exceed `Monitor`'s
+maximum `timeout_ms` (1 hour), and a bounded timeout would silently stop watching a
+still-running loop.
+
+**Coverage-complete filter (silence is not success).** The filter MUST match every
+terminal and exception state, not just the happy path — otherwise a crash or hang
+looks identical to "still running." Monitor command (NDJSON path):
+
+```
+tail -n +1 -f {backlogDir}/{loopRunner.stateDir}/events.ndjson 2>&1 \
+  | jq -rc --unbuffered 'select(.type | test("item_completed|item_blocked|needs_human|signal_parsed|loop_completed|loop_error|loop_cancelled|llm_stuck_warning"))'
+```
+
+- **Fallback (log tail, no NDJSON):** match the runner's **structured prose
+  prefixes**, never the `RAUF_*` tokens (those leak inside agent output and
+  false-match). For rauf:
+
+  ```
+  tail -n +1 -f {backlogDir}/{loopRunner.stateDir}/{loopRunner.logFile} \
+    | grep -E --line-buffered 'Item [^ ]+ (completed|blocked):|Item [^ ]+ needs human input|Loop completed|Loop error:|Circuit breaker:'
+  ```
+
+  (Match `needs human input` **without** a trailing colon — the runner writes
+  `needs human input (set aside):`.)
+
+If the Monitor is ever auto-stopped for event volume, re-arm with a tighter filter
+(drop `item_completed`, keep the exception/terminal events).
+
+## React to events as they land (Step 3e)
+
+Each Monitor event arrives as a message. React per type — but keep the user signal
+high and the noise low:
+
+- **`item_completed`** → increment a running tally. These land minutes apart, so they
+  won't trip the volume auto-stop; still, surface a coalesced milestone ("12/30 done")
+  rather than echoing every line. For an exact breakdown, run the one-shot
+  `{rendered statusJsonCommand}` and report `done/total` from `backlogSummary`.
+- **`needs_human`** (or `signal_parsed` with `signal: "needs_human"`) → **surface
+  immediately** and send a **`PushNotification`** (an hours-long run means the user has
+  likely stepped away). **Important — the loop is NOT paused:** the runner has set that
+  item aside and kept working other items. So report *what* needs a human and *which*
+  item, then either (a) collect the user's answer via `AskUserQuestion` to **stage a
+  post-run retry**, or (b) offer to **cancel the run early** if the answer changes the
+  whole plan. Do not tell the user the loop is waiting on their reply — it isn't.
+- **`item_blocked`** → surface the blocked item + reason now (visibility) and
+  accumulate for the final summary. Use `{rendered statusJsonCommand}` to distinguish a
+  genuine `blocked` from a runner-`deferred` "false block" (`backlogSummary.deferred`).
+- **`loop_error`** → a real failure (this is also what a circuit-breaker halt — too many
+  consecutive infra failures — emits). Surface now and `PushNotification`. Offer
+  inspection / `--force` / re-run as appropriate.
+- **Stall detection** → rauf emits an **`llm_stuck_warning`** event when an iteration
+  stops making progress; the filter above includes it, so surface it live (a hang
+  warning, not yet a failure) and offer `--force` if it persists. If you instead want to
+  probe on quiet, run `{rendered watchCommand}` (or read
+  `{backlogDir}/{loopRunner.stateDir}/iteration-status.json`) and key off its
+  `stuckWarning` flag. Do **not** infer a stall from `state.json.updatedAt` alone — it is
+  not a liveness proof.
+
+## Inform-user output template (Step 3c)
+
+This is the verbatim "Loop started…" output the session shows the user after
+launch. Commands are the rendered `loopRunner` monitoring commands.
+
+When the agent surface is gated on (`loopRunner.agentArgument` present), add the
+`Coding agent:` line shown below immediately after the opening `Loop started …`
+line, using the same `sourceLabel` mapping as the Step 2d confirmation
+(`RUN` → `"per-run selection"`, `PROJECT` →
+`"project default (loopRunner.defaultAgent)"`, `DEFAULT` →
+`"runner default — claude-cli"`). When the gate is off, the line is **absent** and
+the template is byte-identical to today (REQ-PLUG-02). When the launch proceeded via
+the UNAVAILABLE *proceed-anyway* path, use the audit variant instead:
+
+```
+Coding agent: {resolved.agent or claude-cli} (source: {sourceLabel}).
+Coding agent: {resolved.agent} (source: {sourceLabel}; proceeded despite unavailability warning).
+```
+
+(The two lines above are alternatives — the first is the normal line; the second
+replaces it only on the proceed-anyway path. This is session-side prose only; it
+introduces no new event type, so the Step 3d Monitor filter is unchanged.)
+
+```
+Loop started for {feature} ({N} items to process).
+Coding agent: {resolved.agent or claude-cli} (source: {sourceLabel}).   # only when the agent surface is gated on
+This session is now monitoring it live — I'll report milestones and stop you in if
+the loop needs a human. The loop also runs detached and survives this session ending.
+Each item gets a fresh agent session with full context from the backlog and specs.
+
+Watch directly if you like (another terminal or `!` prefix):
+  {rendered statusCommand}              # one-shot status
+  {rendered followCommand}              # stream live events (human)
+  {rendered logCommand}                 # tail log file
+  {rendered listCommand}                # check item statuses
+
+State files are at: {backlogDir}/{loopRunner.stateDir}/
+  - state.json             (loop state)
+  - events.ndjson          (structured event stream this session is watching)
+  - {loopRunner.logFile}   (human event log)
+  - iteration-status.json  (live activity, incl. stuckWarning)
+```

package/adapters/claude/skills/forge-6-docs/SKILL.md

@@ -0,0 +1,179 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-6-docs/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-6-docs
+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.
+argument-hint: <feature-name>
+---
+
+# 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/claude/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/claude/skills/forge-fix/SKILL.md

@@ -0,0 +1,65 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-fix/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-fix
+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.
+argument-hint: <feature-name>
+---
+
+# 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/claude/skills/forge-init/SKILL.md

@@ -0,0 +1,29 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-init/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-init
+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.
+---
+
+# 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>`.