@garygentry/feature-forge 0.1.0

package/adapters/claude/references/forge-config-schema.json

@@ -0,0 +1,166 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature Forge Configuration",
+  "description": "Project-level configuration for the feature-forge plugin. Place as forge.config.json in your project root.",
+  "type": "object",
+  "properties": {
+    "specsDir": {
+      "type": "string",
+      "default": "./specs",
+      "description": "Root directory for feature spec documents. Each feature gets a subdirectory."
+    },
+    "docsDir": {
+      "type": "string",
+      "default": "./docs/architecture",
+      "description": "Root directory for generated architecture documentation."
+    },
+    "backlogDir": {
+      "type": "string",
+      "description": "Optional override for backlog location. If set, backlog.json is written here instead of with the feature specs. Default behavior: backlog.json is written to {specsDir}/{feature}/backlog.json."
+    },
+    "gitCommitAfterStage": {
+      "type": "boolean",
+      "default": true,
+      "description": "Automatically commit after each pipeline stage completes."
+    },
+    "commitPrefix": {
+      "type": "string",
+      "default": "forge",
+      "description": "Prefix for conventional commit messages, e.g., forge(auth): complete PRD"
+    },
+    "stack": {
+      "type": "string",
+      "description": "Detected or configured project stack identifier. Selects guidance from references/stacks/{stack}.md. Set during forge-2-tech or manually. Examples: 'typescript', 'python', 'go', 'rust'."
+    },
+    "typeCheckCommand": {
+      "type": "string",
+      "description": "Command to verify type correctness or lint. Examples: 'bun run typecheck', 'mypy .', 'go vet ./...'. Used in acceptance criteria and verification."
+    },
+    "testCommand": {
+      "type": "string",
+      "description": "Command to run tests. Examples: 'bun test', 'pytest', 'go test ./...'. Used in acceptance criteria and verification."
+    },
+    "loopIterationMultiplier": {
+      "type": "number",
+      "default": 1.5,
+      "minimum": 1,
+      "description": "Multiplier applied to pending backlog item count to calculate loop iterations. Higher values allow more retries. Default: 1.5 (e.g., 10 items = 15 iterations)."
+    },
+    "loopRunner": {
+      "type": "object",
+      "description": "The autonomous loop runner feature-forge drives. Defaults to rauf when absent (forge-5 states 'defaulting to rauf loop runner'). Every command is a template — {bin}, {backlogDir}, {specsDir}, {iterations} are substituted at call time — so an alternative ralph-style runner conforming to rauf's SPEC-BACKLOG-TOOL-CONTRACT.md can be swapped in without editing any skill. See references/ralph-loop-contract.md.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "default": "rauf",
+          "description": "Display name of the loop runner."
+        },
+        "bin": {
+          "type": "string",
+          "default": "rauf",
+          "description": "The runner executable. Assumed on PATH; may be an absolute path. Substituted as {bin} in every command."
+        },
+        "runCommand": {
+          "type": "string",
+          "default": "{bin} loop run . --backlog {backlogDir} --iterations {iterations}",
+          "description": "Run the loop. Launched in the background by forge-5. Human-formatted output; used as the fallback launch command when eventStreamCommand is absent."
+        },
+        "eventStreamCommand": {
+          "type": "string",
+          "default": "{bin} loop run . --backlog {backlogDir} --iterations {iterations} --ndjson",
+          "description": "PREFERRED launch command for forge-5. Same as runCommand but emits one machine-readable JSON event per stdout line (NDJSON): item_completed / item_blocked / needs_human / signal_parsed / loop_completed / loop_error / loop_cancelled / llm_stuck_warning, each with {type, timestamp, projectPath} plus payload (a circuit-breaker halt surfaces as loop_error). forge-5 redirects this stdout to {backlogDir}/{stateDir}/events.ndjson and arms a Monitor on it for live, structured supervision. If a runner cannot emit NDJSON, omit this field — forge-5 falls back to runCommand + tailing the human log."
+        },
+        "validateCommand": {
+          "type": "string",
+          "default": "{bin} backlog validate . --backlog {backlogDir} --specs-dir {specsDir} --json",
+          "description": "Validate a backlog. MUST exit 0=valid, 1=findings, 2=usage/IO, and emit { valid, findings[] } with --json. `specReferences` are project-root-relative (resolved against the project root); `--specs-dir` only gates the existence check, so passing the specs root ({specsDir}) is sufficient."
+        },
+        "statusCommand": {
+          "type": "string",
+          "default": "{bin} status . --backlog {backlogDir}",
+          "description": "One-shot loop status, human-formatted. Shown to the user as a monitoring hint."
+        },
+        "statusJsonCommand": {
+          "type": "string",
+          "default": "{bin} status . --backlog {backlogDir} --json",
+          "description": "Machine-readable derived status used by forge-5 for milestone tallies and the final summary. Emits { loopState, iteration, maxIterations, currentItem, lastSignal, backlogSummary{pending,inProgress,blocked,needsHuman,deferred,done,total}, lock{...} }. Distinguishes the three non-done outcomes (genuine blocked vs needsHuman vs runner-deferred 'false blocks')."
+        },
+        "listCommand": {
+          "type": "string",
+          "default": "{bin} backlog list . --backlog {backlogDir} --json",
+          "description": "List backlog items as JSON."
+        },
+        "followCommand": {
+          "type": "string",
+          "default": "{bin} follow . --backlog {backlogDir}",
+          "description": "Stream live loop events, HUMAN-formatted (pretty-printed / log tail) — for a person watching in another terminal, NOT a machine-readable surface. forge-5 supervises via eventStreamCommand (NDJSON) instead."
+        },
+        "logCommand": {
+          "type": "string",
+          "default": "{bin} log . --backlog {backlogDir} --follow",
+          "description": "Tail the runner log, human-formatted. Monitoring hint for the user."
+        },
+        "watchCommand": {
+          "type": "string",
+          "default": "{bin} status . --backlog {backlogDir} --json",
+          "description": "Machine-readable status used by forge-5 for stall detection. rauf's `loop watch` verb was removed in v0.5.0, so this now points at `status --json`; forge-5 keys off the iteration-status `stuckWarning` flag (read from `status --json` / `iteration-status.json`) rather than guessing liveness from state.json timestamps."
+        },
+        "versionCommand": {
+          "type": "string",
+          "default": "{bin} version --json",
+          "description": "Report runner version as { version: <semver> }. Used to enforce minRunnerVersion before running."
+        },
+        "agentArgument": {
+          "type": "string",
+          "default": "--agent {agent}",
+          "description": "Tokenized argument appended to the launch command (eventStreamCommand/runCommand) when forge resolves a non-default coding agent for the run. {agent} is substituted ONLY with a validated, advertised agent id (a member of the set agentsProbeCommand reports). PRESENCE of this field advertises the runner's agent surface: when present and non-empty, forge-5 offers the per-run agent selector, honors defaultAgent, and may run agentsProbeCommand; OMIT it for a runner with no agent dimension and forge skips agent selection entirely — no selector, no probe, no {agent} substitution, no agent argument sent (byte-identical to today). Distinct from the version gate (minRunnerVersion)."
+        },
+        "agentsProbeCommand": {
+          "type": "string",
+          "default": "{bin} agents --json",
+          "description": "Coding-agent availability probe. MUST emit { agents: [{ id, displayName, available, ... }] } and exit 0 (it always exits 0: an unknown id simply never appears; a known-unavailable one appears with available:false). forge-5 runs it ONCE (no retries) before launching a non-default agent to (a) validate the resolved id against the advertised id set and (b) report availability in the pre-launch confirmation. Ignored on the default path and when agentArgument is absent."
+        },
+        "defaultAgent": {
+          "type": "string",
+          "default": "",
+          "description": "Project-default coding agent id, so a project can fix its agent once without specifying it every run. Empty string ⇒ no project default (the runner's own default — claude-cli for rauf — applies, behaving exactly as today). Overridden by the per-run agent selector (run > project precedence, resolved inside forge before the single --agent is emitted). Ignored when agentArgument is absent."
+        },
+        "preconditionFile": {
+          "type": "string",
+          "default": ".rauf.json",
+          "description": "Project-root marker file that must exist (runner installed into the target project)."
+        },
+        "stateDir": {
+          "type": "string",
+          "default": ".rauf",
+          "description": "Per-backlog state directory name created under the backlog dir."
+        },
+        "logFile": {
+          "type": "string",
+          "default": "rauf.log",
+          "description": "Human-readable event log filename written under {stateDir}. Substituted as {loopRunner.logFile} in the log-tail fallback Monitor command when eventStreamCommand (events.ndjson) is unavailable. The structured NDJSON path uses the contract-standard name events.ndjson and is not configurable here."
+        },
+        "setupHint": {
+          "type": "string",
+          "default": "Run `rauf install .` to install rauf's per-project artifacts (.rauf/, RAUF.md, schema), then re-run forge-5.",
+          "description": "Shown when preconditionFile is missing — how to set up the runner IN THIS PROJECT (per-project artifacts)."
+        },
+        "installHint": {
+          "type": "string",
+          "default": "Provision rauf for a multi-agent setup with the cross-agent installer: `npx @garygentry/feature-forge install` (records the pinned rauf@0.6.0 default). Or install/upgrade just the rauf CLI: `curl -fsSL https://raw.githubusercontent.com/garygentry/rauf/main/scripts/install-binary.sh | bash`.",
+          "description": "Shown when the runner BINARY is missing or too old (version gate fails, minRunnerVersion floor) — how to obtain/upgrade the CLI itself. Names two distinct binary-provisioning paths: (1) the cross-agent installer (`npx @garygentry/feature-forge install`, the multi-agent provisioning path that pins rauf@0.6.0), and (2) the direct rauf-CLI install/upgrade one-liner. Distinct from setupHint (which installs per-project artifacts); a version-gate failure is ALWAYS this hint, never setupHint."
+        },
+        "schemaVersion": {
+          "type": "string",
+          "default": "1",
+          "description": "Backlog schemaVersion this runner config targets."
+        },
+        "minRunnerVersion": {
+          "type": "string",
+          "default": "0.6.0",
+          "description": "Minimum runner version (semver). 0.6.0 is the AGENT-SURFACE FLOOR: the rauf version that ships the coding-agent selection surface (the --agent flag, the `agents` availability probe, and the preset agent registry) that this config's agentArgument/agentsProbeCommand consume. Flooring here guarantees a successful gate implies those surfaces exist. (0.5.0 was the prior grammar/contract-flip floor — unified exit codes, `loop run --detached`, explicit `review` signal, versioned events.ndjson — which predates the agent surface and so could not guarantee it.) forge-5 enforces this via versionCommand before any loop side-effects."
+        }
+      }
+    }
+  }
+}

package/adapters/claude/references/pipeline-state-schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature Forge Pipeline State",
+  "description": "Tracks pipeline progress for a single feature across sessions. Lives at {specsDir}/{feature}/.pipeline-state.json",
+  "type": "object",
+  "required": ["feature", "createdAt", "updatedAt", "currentStage", "stages", "pipelineStatus"],
+  "properties": {
+    "pipelineStatus": {
+      "type": "string",
+      "enum": ["active", "paused", "abandoned"],
+      "default": "active"
+    },
+    "feature": {
+      "type": "string",
+      "description": "Feature name (matches directory name under specsDir)"
+    },
+    "epic": {
+      "type": "string",
+      "description": "Back-pointer to the owning epic's name. Absent for standalone features. The epic-manifest.json is canonical on conflict (REQ-STATE-01)."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "currentStage": {
+      "type": "string",
+      "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop", "forge-6-docs", "complete", "forge-verify-prd", "forge-verify-tech", "forge-verify-specs", "forge-verify-backlog", "forge-verify-impl", "forge-0-epic", "forge-verify-epic"],
+      "description": "The stage currently in progress or next to start"
+    },
+    "notes": {
+      "type": "string",
+      "description": "Free-form notes persisted between sessions (user can add context before stepping away)"
+    },
+    "stages": {
+      "type": "object",
+      "properties": {
+        "forge-0-epic": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-epic": { "$ref": "#/definitions/verifyEntry" },
+        "forge-1-prd": { "$ref": "#/definitions/stageEntry" },
+        "forge-2-tech": { "$ref": "#/definitions/stageEntry" },
+        "forge-3-specs": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-specs": { "$ref": "#/definitions/verifyEntry" },
+        "forge-4-backlog": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-backlog": { "$ref": "#/definitions/verifyEntry" },
+        "forge-5-loop": { "$ref": "#/definitions/stageEntry" },
+        "forge-6-docs": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-impl": { "$ref": "#/definitions/verifyEntry" },
+        "forge-verify-prd": { "$ref": "#/definitions/verifyEntry" },
+        "forge-verify-tech": { "$ref": "#/definitions/verifyEntry" }
+      }
+    }
+  },
+  "definitions": {
+    "stageEntry": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "in-progress", "complete", "stale"]
+        },
+        "version": {
+          "type": "integer",
+          "description": "Incremented each time this stage's artifacts are revised"
+        },
+        "artifacts": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Relative paths to artifacts produced by this stage"
+        },
+        "startedAt": { "type": ["string", "null"], "format": "date-time" },
+        "completedAt": { "type": ["string", "null"], "format": "date-time" },
+        "commitHash": {
+          "type": ["string", "null"],
+          "description": "Git commit SHA after this stage completed"
+        },
+        "basedOnVersions": {
+          "type": "object",
+          "description": "Upstream stage versions this artifact was built against",
+          "additionalProperties": { "type": "integer" }
+        }
+      }
+    },
+    "verifyEntry": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "passed", "findings-reported", "findings-applied", "skipped"]
+        },
+        "findingsFile": {
+          "type": ["string", "null"],
+          "description": "Path to the verification findings document"
+        },
+        "findingsCount": {
+          "type": ["integer", "null"],
+          "description": "Number of findings reported"
+        },
+        "verifiedAt": { "type": ["string", "null"], "format": "date-time" },
+        "fixedAt": { "type": ["string", "null"], "format": "date-time" },
+        "commitHash": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

package/adapters/claude/references/portable-root.md

@@ -0,0 +1,56 @@
+# Portable Script-Root Resolution
+
+This file is the **single canonical home** of the feature-forge bootstrap prelude and the
+portable invocation convention. Each fenced shell block an agent runs is a separate process
+with no persisted state, so the plugin root must be re-resolved within the same block as every
+bundled-script call. The prelude below is the fixed, byte-identical snippet that does this by
+discovering and delegating to `scripts/forge-root.sh`. Downstream consumers
+(`forge-agent-adapters-build`, `cross-agent-installer`) and the spec-purity checker treat this
+file as authoritative: the checker's rule 5 compares every prelude occurrence across the canon
+against the fenced block here, byte-for-byte.
+
+## Canonical bootstrap prelude
+
+```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; }
+```
+
+## Usage
+
+Prepend the prelude to a fenced shell block once, then invoke bundled scripts via `$R`:
+`python3 "$R/scripts/<x>"` or `bash "$R/scripts/<x>"`. One prelude per fenced block — if a block
+makes several calls, add the prelude once and reuse `$R` for each. A fresh block gets its own
+prelude (per-block re-resolution). Worked example:
+
+```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
+```
+
+## Invariants (do NOT "fix" these)
+
+1. **Probes paths, not the env var.** The prelude's `for d in …` enumerates directory paths to
+   locate an executable `forge-root.sh`; it contains no plugin-root environment variable. That is what lets
+   a prelude occurrence satisfy the "zero residual var in canonical surfaces" rule while staying
+   portable.
+2. **First-discoverable-resolver-wins.** The `exec` inside the `$(…)` command substitution means
+   the loop stops at the first directory holding an executable `forge-root.sh` and delegates ALL
+   final root resolution to that script. The `for` list is a discovery order for `forge-root.sh`
+   itself, not a fallback chain for the plugin root. Removing the `exec` to "keep looping" is a
+   regression — once `exec`'d, the loop is replaced by the resolver process and never advances.
+3. **Prelude candidate set is a minimal `$HOME` bootstrap subset.** The prelude's `for d` list
+   exists only to bootstrap-discover `forge-root.sh`; the authoritative multi-root probe lives in
+   `forge-root.sh` step 2. When adding an install root, update `forge-root.sh` first; extend the
+   prelude only if the new root is needed to bootstrap-discover `forge-root.sh` itself.
+
+## The resolver
+
+The prelude delegates to [`scripts/forge-root.sh`](../scripts/forge-root.sh) — the portable
+skill/plugin-root resolver. It takes no arguments, prints the absolute plugin root to stdout and
+exits `0`, or writes an actionable message to stderr and exits `1`. It resolves the root by
+self-location → candidate-root probe → plugin-root environment-variable fallback → actionable failure,
+and never sources or executes a discovered path — it only ever prints a directory string. The
+spec-purity checker (rule 5) enforces that every prelude occurrence across the canon is
+byte-identical to the fenced block in this file.

package/adapters/claude/references/process-overview.md

@@ -0,0 +1,123 @@
+# Feature Forge Pipeline Overview
+
+This document describes the end-to-end feature development pipeline managed by the feature-forge plugin. All forge skills reference this document to understand the overall flow and their position within it.
+
+## Pipeline Stages
+
+```
+forge-1-prd → forge-2-tech → forge-3-specs → forge-verify → forge-4-backlog → forge-verify → forge-5-loop → forge-verify → forge-6-docs
+```
+
+### Stage 1: PRD (`/feature-forge:forge-1-prd <feature>`)
+**Input:** User's feature idea and domain knowledge
+**Output:** `{specsDir}/{feature}/PRD.md`
+**Method:** Structured interview focused exclusively on requirements. No technology decisions.
+
+### Stage 2: Tech Spec (`/feature-forge:forge-2-tech <feature>`)
+**Input:** PRD.md
+**Output:** `{specsDir}/{feature}/tech-spec.md`
+**Method:** Structured interview for technology decisions, grounded in PRD requirements.
+
+### Stage 3: Implementation Specs (`/feature-forge:forge-3-specs <feature>`)
+**Input:** PRD.md + tech-spec.md
+**Output:** `{specsDir}/{feature}/##-<name>.md` (suite of numbered documents)
+**Method:** Generate detailed implementation documents from spec archetypes.
+
+### Verification Gate (`/feature-forge:forge-verify <feature>`)
+**Input:** All artifacts from current and prior stages
+**Output:** `{specsDir}/{feature}/.verification/VERIFY-<stage>-<timestamp>.md` (includes both findings and a Fix Execution Plan)
+**Method:** Clean-context analysis producing actionable findings with an ordered fix plan.
+
+After verification, fixes can be applied via:
+- `/feature-forge:forge-fix <feature>` — reads the Fix Execution Plan from the findings document and applies changes (works in any session)
+- Plan mode workflow — enter plan mode, run verify, review plan, exit and execute
+- Manual — read findings and apply fixes by hand
+
+### Stage 4: Backlog (`/feature-forge:forge-4-backlog <feature>`)
+**Input:** Full spec suite
+**Output:** `{specsDir}/{feature}/backlog.json` (or `{backlogDir}/backlog.json` if backlogDir is configured)
+**Method:** Generate structured backlog items with spec references, acceptance criteria, and dependencies. Backlog is collocated with feature specs by default.
+
+### Stage 5: Rauf Loop (`/feature-forge:forge-5-loop <feature>`)
+**Input:** `backlog.json` from Stage 4
+**Output:** Implemented source code (committed per-item by rauf)
+**Method:** Execute the rauf autonomous coding loop against the feature's backlog. Spawns a fresh Claude Code session per backlog item with full spec context.
+
+### Stage 6: Documentation (`/feature-forge:forge-6-docs <feature>`)
+**Input:** Specs + implementation
+**Output:** `{docsDir}/{feature}/` documentation suite
+**Method:** Generate developer-focused architecture documentation.
+
+## Pipeline State
+
+State is tracked in `{specsDir}/{feature}/.pipeline-state.json` and persists across session clears. The `/feature-forge:forge <feature>` navigator reads this file to show current progress.
+
+## Git Discipline
+
+Every stage completion should be followed by a git commit:
+- Commit message format: `{commitPrefix}({feature}): <action>`
+- Examples: `forge(auth): complete PRD v1`, `forge(auth): apply spec verification fixes`
+- Before applying verification fixes, commit current state first (so pre-fix state is recoverable)
+- After applying fixes, commit again
+
+## Configuration
+
+Read `forge.config.json` from project root for path overrides. See `references/forge-config-schema.json` for the full schema. If no config file exists, use defaults:
+- specsDir: `./specs`
+- docsDir: `./docs/architecture`
+- backlogDir: (null — backlog defaults to {specsDir}/{feature}/backlog.json)
+- gitCommitAfterStage: `true`
+- commitPrefix: `forge`
+
+## Git Workflow
+
+Recommended: create a `forge/{feature}` branch before starting the pipeline. All forge commits go to this branch. After implementation, merge to your development branch.
+
+If you prefer manual commit control, set `gitCommitAfterStage: false` in `forge.config.json`.
+
+## Cross-Cutting Concerns
+
+### Feature Name is Required
+Every forge skill requires a feature name as the first argument. If not provided, STOP and ask. Never guess.
+
+### Reference Existing Code
+When creating specs, always examine the existing codebase for patterns, conventions, and integration points. Check:
+- Other feature specs in `{specsDir}/`
+- Existing documentation in `{docsDir}/`
+- Module/package structure and exports in the project
+- Shared types, utilities, and conventions
+
+### Stack Context
+The project's stack is detected during forge-2-tech and persisted in `forge.config.json` (the `stack`, `typeCheckCommand`, and `testCommand` fields). See `references/stack-resolution.md` for the full resolution protocol. The project may also have a `stack-decisions.md` in `.claude/references/` with established technology decisions — if present, it takes highest precedence.
+
+## Subagents
+
+The plugin includes three specialized subagents in `agents/` that enhance specific
+pipeline steps. They use **model aliases** (`opus`/`sonnet`) rather than pinned IDs, so
+they track the current model tier automatically.
+
+### forge-verifier
+- **Purpose:** Read-only verification of pipeline artifacts
+- **Used by:** `forge-verify` skill (delegation via Agent tool)
+- **Tools:** Read, Glob, Grep, Bash (read-only operations only)
+- **Model:** Opus (judgement-heavy gap/inconsistency analysis)
+- **Memory:** Project-scoped persistent memory — accumulates knowledge about recurring issues and project-specific patterns across sessions
+- **Parallel:** For large modes (specs/backlog/impl), `forge-verify` dispatches several instances in parallel, one per **dimension group** (e.g. types/contracts, traceability, testing), and the parent merges their findings. An opt-in adversarial "deep verify" pass re-checks high-severity findings with a skeptic instance to cut false positives. A purely mechanical dimension (e.g. traceability validation) could run on a cheaper tier (Haiku) if cost matters.
+- **Why a subagent:** Verification reads the entire spec suite, backlog, and potentially source code. Running this in a separate context window prevents context pressure on the main conversation. The read-only tool restriction also makes it impossible to accidentally modify specs during verification.
+
+### forge-researcher
+- **Purpose:** Codebase exploration and integration mapping
+- **Used by:** `forge-2-tech` skill (spawned before the tech-spec interview)
+- **Tools:** Read, Glob, Grep, Bash (read-only)
+- **Model:** Sonnet (cost-efficient for exploration tasks)
+- **Parallel:** For a large codebase or uncertain scope, `forge-2-tech` may dispatch several researchers in parallel, each with a disjoint focus (structure/conventions, per-subsystem integration surfaces), and merge the reports.
+- **Why a subagent:** Tech-spec planning requires reading many files across the project to understand integration points. Running this in a separate context returns a concise report without consuming the main session's context, keeping the interview focused.
+
+### forge-spec-writer
+- **Purpose:** Author exactly one numbered implementation spec document to the forge-3-specs quality bar
+- **Used by:** `forge-3-specs` skill (parallel fan-out after the shared foundation docs are written)
+- **Tools:** Read, Glob, Grep, Bash, **Write** (the only authoring agent — constrained to write its single assigned file)
+- **Model:** Opus (spec authoring is detail- and judgement-heavy)
+- **Why a subagent:** Authoring the whole suite in the main session serializes the work and pressures context. Writing the foundation (00/01) first, then fanning out one writer per remaining doc, parallelizes authoring while the parent keeps the cross-reference + traceability finish in view.
+
+All three subagents are optional. If the agents are not installed or the environment doesn't support subagents, the corresponding skills fall back to running inline (or, for spec authoring, batched in the main session).