@garygentry/feature-forge 0.1.0

package/adapters/claude/references/ralph-loop-contract.md

@@ -0,0 +1,221 @@
+# The Loop-Runner Contract (consumer side)
+
+feature-forge's pipeline ends by handing a `backlog.json` to an autonomous
+**loop runner** that implements each item. feature-forge does not embed any
+runner's internals — it talks to the runner through one indirection point: the
+**`loopRunner`** block in `forge.config.json`.
+
+## The seam
+
+Every command feature-forge runs against the runner is a template in
+`loopRunner`, with `{bin}`, `{backlogDir}`, `{specsDir}`, and `{iterations}`
+substituted at call time. `forge-5-loop` (execution), `forge-4-backlog`
+(validation), and `forge-verify` (backlog validation) all render their commands
+from this block — there are no hardcoded `rauf …` commands in the skills, and
+even the human log filename is tokenized via `{loopRunner.logFile}`.
+
+When `forge.config.json` has no `loopRunner` block, feature-forge uses the
+built-in defaults (see `references/forge-config-schema.json`) and announces
+"defaulting to the rauf loop runner."
+
+## The contract a runner MUST satisfy
+
+A conforming runner MUST implement the **backlog-tool / loop-runner contract**
+defined authoritatively in rauf's
+[`SPEC-BACKLOG-TOOL-CONTRACT.md`](https://github.com/garygentry/rauf/blob/main/docs/SPEC-BACKLOG-TOOL-CONTRACT.md)
+(Part A). In summary, it must provide:
+
+- **A backlog schema** with the published `$id` and an optional `schemaVersion`,
+  whose `type`/`status` vocabularies match the contract
+  (`type ∈ bug|bugfix|refactor|feature|chore|test`,
+  `status ∈ pending|in_progress|done|blocked`).
+- **A `validate` verb** with exit codes `0` (valid) / `1` (findings) / `2`
+  (usage/IO) that emits `{ valid, findings[] }` under `--json`. This is the
+  single check feature-forge trusts — it never re-implements validation.
+- **The signal protocol** (`RAUF_DONE` / `RAUF_BLOCKED` / `RAUF_NEEDS_HUMAN` /
+  `RAUF_REVIEW`). These are emitted by the *coding agent* into its stdout and
+  parsed by the runner — they are not runner-authored log lines, so consumers key
+  off the runner's parsed events (below), never the raw `RAUF_*` tokens (which can
+  also appear inside an agent's prose and produce false matches).
+- **A machine-readable event stream** for live supervision (`loopRunner.eventStreamCommand`,
+  rauf: `loop run … --ndjson`): one JSON event per line with a stable `type`
+  vocabulary — `item_completed` / `item_blocked` / `needs_human` / `signal_parsed`
+  / `loop_completed` / `loop_error` / `loop_cancelled` / `llm_stuck_warning` (a
+  circuit-breaker halt surfaces as `loop_error`) — plus a
+  derived-status JSON (`loopRunner.statusJsonCommand`, rauf: `status … --json`) and
+  per-iteration telemetry with a `stuckWarning` flag (`loopRunner.watchCommand`,
+  rauf: `status … --json` — the `loop watch` verb was removed in v0.5.0). `forge-5-loop` supervises the run through these,
+  **not** by parsing the human log. `followCommand` / `logCommand` are
+  human-formatted streams for a person watching in a terminal, not machine surfaces.
+- **The state-dir layout** (per-`--backlog` isolation under `loopRunner.stateDir`).
+- **The CLI verbs** mapped by `loopRunner`: run (+ event-stream) / validate /
+  status (+ `--json`) / list / follow / log / version.
+- **A `version` verb** (`{bin} version --json` → `{ version: <semver> }`) so
+  feature-forge can enforce `loopRunner.minRunnerVersion` before running.
+
+> **The runner does not pause for human input.** When the coding agent signals
+> `RAUF_NEEDS_HUMAN`/`RAUF_BLOCKED`/`RAUF_REVIEW`, a conforming runner sets that
+> item aside and **keeps working other runnable items to completion** (rauf:
+> `runner.ts` needs_human handler). So a supervising session can surface those
+> events live (visibility) and cancel early, but it cannot inject an answer and
+> resume the set-aside item mid-run — resolution is a follow-up retry pass. A
+> first-class pause/resume-with-answer capability is a desirable runner
+> enhancement (see `plans/rauf-enhancement-recommendations.md`).
+
+## rauf is the default and reference implementation
+
+rauf owns the contract spec and is the runner feature-forge defaults to. The
+authoring craft itself (how to decompose specs into well-scoped, verifiable
+items) lives in rauf's **`author-backlog`** skill, which `forge-4-backlog`
+delegates to — so the only thing binding feature-forge to a particular runner is
+the schema + `validate` verb that this contract formalizes. A future runner swap
+supplies its own `loopRunner` block (its own `bin`, schema, and `validate`
+command) without touching any pipeline skill.
+
+The coding-agent dimension this contract adds (below) is **additive and
+presence-gated**: it exists only when the `loopRunner` block advertises it via
+`agentArgument`. A runner that omits that field has no agent dimension at all —
+the seam degrades to exactly today's behavior with no error, so default-to-rauf
+and pluggability are unchanged. See `## Agent selection`.
+
+## Agent selection
+
+This section is **contract-level**: it states what a conforming runner exposes
+and what forge does with it, and defers every algorithm to the owning specs
+(`02`/`03`/`04`/`05`).
+
+### What a conforming runner exposes (the consumed surface)
+
+A runner that carries a coding-agent dimension exposes, in its `loopRunner`
+block:
+
+- an **`agentArgument`** template (rauf default `--agent {agent}`) — the
+  tokenized launch-time flag; its **presence** advertises the agent surface;
+- an **`agentsProbeCommand`** (rauf default `{bin} agents --json`) emitting
+  `{ agents: [{ id, displayName, available, detail? }] }` and **always exiting
+  0**;
+- an optional **`defaultAgent`** project-default id.
+
+These three fields are specified in full in `references/forge-config-schema.json`
+and are the schema half of this contract. forge consumes rauf's existing
+`--agent <id>` flag, `rauf agents` probe, `BacklogItem.provider`, and 5-layer
+precedence — it conforms to them, it does not redesign them.
+
+### Precedence and the run-layer mapping
+
+The agent-selection precedence is **`item > run > project > default`**,
+deliberately parallel to the model-selection precedence (`item.model >
+--model/options > project default > provider default`). It is realized as:
+
+- **item** — `BacklogItem.provider`, applied by **rauf** from the backlog. forge
+  **never reads, writes, or overrides** it (pass-through), so a deliberate
+  per-item agent always wins.
+- **run** — forge's per-run selector (`forge-5-loop` Step 2d).
+- **project** — forge's `loopRunner.defaultAgent`.
+- **default** — the runner's own default (`claude-cli` for rauf) when forge sends
+  nothing.
+
+forge owns **only** the run and project layers. It collapses run-over-project
+*inside itself* into the **single** `--agent {agent}` value it emits at the
+**run layer**, and lets rauf apply the item override *above* that. forge **never
+re-implements rauf's resolver**. The resolution algorithm itself lives in
+`03-selection-resolution-observability.md`.
+
+### Availability probe + unknown/unavailable disambiguation
+
+When the resolved agent is a **non-default** id, forge runs `agentsProbeCommand`
+**once (no retries)** before any loop side-effect, parses the advertised
+`agents[]`, and builds the advertised id set. Because the probe **always exits
+0**, an unknown id is distinguished from a known-but-unavailable one **only by
+set membership**, not by exit code:
+
+- **Unknown id** (not in the advertised set — a typo or unsupported agent):
+  **hard-reject before launch**, listing the valid ids. No proceed-anyway path.
+  No value is interpolated into `{agent}`.
+- **Known but unavailable** (`available: false`): **warn** (showing the probe's
+  `detail`) and let the user **proceed-anyway or choose another** — never
+  silently abort, never silently proceed.
+- **Available**: proceed.
+
+The advertised id set is also the **allow-list**: the only value ever
+interpolated into `{agent}` is a validated, advertised id. The **default /
+claude path never reaches the probe** — it incurs no extra cost. The
+`classify(...)` algorithm and the rejection-error text live in
+`04-availability-precheck.md`.
+
+### Capability gate + version floor
+
+Agent selection is **capability-gated** on the runner advertising
+`agentArgument`: a runner whose `loopRunner` omits (or empties) that field
+exposes no agent surface, so the per-run selector, the probe, and any `{agent}`
+substitution **vanish entirely** and no agent argument is sent — byte-identical
+to today. Degradation is **silent, not an error**, keeping alternate (non-rauf)
+runners first-class. The gate condition is owned by
+`02-config-schema-and-gating.md`.
+
+Independently, the **version gate** floors at the runner version that ships the
+agent surface. For rauf that is **0.6.0** (`loopRunner.minRunnerVersion`): the
+`--agent` flag, the `agents` probe, and the preset agent registry are present in
+rauf source at 0.6.0. A successful gate therefore guarantees those surfaces
+exist before any run. See `## Version gating` and
+`05-runner-discovery-version-gate.md`.
+
+**This document — the `## Agent selection` section, the `## Per-stage agent
+applicability` table, and the `## validate is agent-agnostic` note — together
+with the augmented `loopRunner` schema block in
+`references/forge-config-schema.json` constitute the `forge-loop-runner-contract`
+expose, consumed by the `packaging-docs-ci` capstone as documentation input.**
+
+## Per-stage agent applicability
+
+Every forge stage that invokes the loop runner is classified here. Only
+`forge-5-loop` (execution) carries the coding-agent dimension; the two
+validation-only stages are agent-agnostic.
+
+| Stage | Runner verbs | Agent dimension |
+|-------|-------------|-----------------|
+| `forge-5-loop` | run / eventStream / status / version | **Full** — selector, probe, `--agent` |
+| `forge-4-backlog` | `validate` | **None** — agent-agnostic |
+| `forge-verify` | `validate` | **None** — agent-agnostic |
+
+- **`forge-5-loop`** is the executor: it drives the run, so it renders the run /
+  event-stream / status / version verbs (and `list`) and carries the full agent
+  surface — the Step 2d selector, the availability probe, and the rendered
+  `agentArgument`.
+- **`forge-4-backlog`** authors and then *validates* the backlog; its only runner
+  call is `validateCommand`. It also reads `versionCommand` for a graceful-degrade
+  check, but **passes no agent** and never runs `loop run`.
+- **`forge-verify`** (backlog mode) re-runs the same `validateCommand` to surface
+  validation findings. It carries no agent dimension. This is **contract
+  coverage** of forge-verify (it is classified here), with an explicit agnostic
+  note (below) — **not** a new agent-driven run in forge-verify.
+
+### `validate` is agent-agnostic
+
+The `validate` verb (`loopRunner.validateCommand`) checks a `backlog.json`
+against the backlog schema and spec references. **It does not run a coding agent
+and has no agent dimension.** No agent argument — `--agent`, the `{agent}` token,
+or any agent id — may **ever** be passed to backlog validation, in **any** stage
+(`forge-4-backlog`, `forge-verify`, or any future caller). Backlog validation is
+a pure, deterministic check; the coding agent is irrelevant to it. A contributor
+who later adds agent selection to a *new* stage MUST confirm that stage runs the
+*execution* surface (like `forge-5-loop`), not `validate` — agent selection
+belongs to execution only. If you find yourself adding `--agent` near a
+`validateCommand` render, that is a bug.
+
+## Version gating
+
+feature-forge requires a runner exposing `backlog validate` + backlog
+`schemaVersion`, and the unified exit-code/status contract it reads. The floor is
+now the **agent-surface floor**: the runner version that ships the `--agent`
+flag, the `agents` probe, and the preset agent registry. For rauf that is
+**0.6.0** (`loopRunner.minRunnerVersion`).
+`forge-5-loop` runs `{bin} version --json`, semver-compares the reported version
+against `minRunnerVersion`, and on a missing-or-too-old runner stops with
+`loopRunner.installHint` (the CLI install/upgrade command) — **before** invoking
+the loop. See `COMPATIBILITY.md` for the version matrix.
+
+> **Two different "installs."** `installHint` obtains/upgrades the runner **CLI
+> binary** (e.g. rauf's `install-binary.sh`). `setupHint` installs the runner's
+> **per-project artifacts** (rauf: `rauf install .`). A failing version gate is
+> always the former, never the latter.

package/adapters/claude/references/shared-conventions.md

@@ -0,0 +1,144 @@
+# Shared Pipeline Conventions
+
+These conventions apply to every forge pipeline skill. Skills reference this file to avoid duplicating shared logic.
+
+## Feature Name Requirement
+
+Every pipeline skill requires a feature name as the first argument (e.g., `/feature-forge:forge-1-prd auth`).
+
+If no feature name is provided:
+1. STOP IMMEDIATELY
+2. Do NOT attempt to guess or infer a feature name
+3. Ask the user to provide one
+4. Do NOT proceed until a feature name is explicitly given
+5. 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`.
+
+## User Input Protocol
+
+### CRITICAL GUARDRAIL: Use AskUserQuestion for All Questions
+
+You MUST use the `AskUserQuestion` tool whenever you need the user's input before proceeding. This includes yes/no confirmations, choices between options, interview questions, and feedback on artifacts. NEVER output questions as inline prose text — the user may not be prompted and the session will stall.
+
+**Required turn structure:** Output your analysis, findings, or context as regular text. Then call `AskUserQuestion` with your questions. Do NOT mix questions into your text output.
+
+**WRONG — questions as inline prose (causes stalling):**
+```
+I found that the codebase uses React and TanStack Router. Here are my questions:
+1. Where should this component live?
+2. Should we use server-side rendering?
+```
+
+**RIGHT — context as text, questions via tool:**
+```
+I found that the codebase uses React and TanStack Router.
+[then call AskUserQuestion with: "1. Where should this component live? 2. Should we use server-side rendering?"]
+```
+
+**Recommendations:** Only recommend a specific option when codebase evidence, established conventions, or strong technical rationale clearly favors it. If options are equally valid, present them neutrally — let the user decide without bias.
+
+## Configuration Reading
+
+Read `forge.config.json` from the project root. If it doesn't exist, use defaults.
+
+If `forge.config.json` does not exist and no `.pipeline-state.json` files exist anywhere in `{specsDir}/`, suggest: "No forge.config.json found. Run `/feature-forge:forge-init` to create one with defaults, or I'll use built-in defaults. Want me to continue with defaults?"
+
+Extract these config values (use defaults if not present):
+- `specsDir` (default: `./specs`)
+- `docsDir` (default: `./docs/architecture`)
+- `backlogDir` (default: null — backlog lives at `{specsDir}/{feature}/backlog.json`; when `backlogDir` is configured, forge-4 composes `{backlogDir}/{feature}/`)
+- `gitCommitAfterStage` (default: true)
+- `commitPrefix` (default: `forge`)
+- `loopIterationMultiplier` (default: `1.5`)
+- `loopRunner` (optional object — the loop runner to drive; **defaults to rauf** when absent, with every command templated. See `references/forge-config-schema.json` and `references/ralph-loop-contract.md`.)
+
+## Feature Directory Resolution
+
+Before any file I/O against a feature's artifacts, resolve its directory through the deterministic helper rather than hardcoding `{specsDir}/{feature}/`. This makes flat (`{specsDir}/{feature}/`) and nested (`{specsDir}/{epic}/{feature}/`) layouts both resolve from a bare feature name (REQ-DIR-03), with standalone features behaving exactly as today.
+
+```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; }
+resolvedFeatureDir=$(python3 "$R/scripts/epic-manifest.py" \
+  resolve "<feature>" --specs-dir "<specsDir>")
+```
+
+- **Exit 0:** stdout is the absolute feature directory. Use it everywhere this skill previously wrote `{specsDir}/{feature}/`.
+- **Exit 1:** the helper reports a structured finding (`not-found`, `ambiguous` — see `00-core-definitions.md §4`). Because this `resolve` call passes **no `--json`** (the subcommand has no such flag), the finding is a plain `not-found:`/`ambiguous:` line on **stderr** with empty stdout — there is no findings JSON to parse. **STOP** and surface that stderr line verbatim. (The `{valid, findings[]}`-on-stdout envelope is the `--json` shape used by `render-status`/`validate`, not by `resolve`.)
+- **Exit 2:** a usage / safety error (`unsafe-name`, a path-containment escape, missing file). The message is a plain `Error: …` line on **stderr** with empty stdout — there is no findings JSON to parse. **STOP** and surface that stderr line verbatim.
+
+In both failure cases, do not fall back to a guessed path.
+
+**Resolution algorithm (summary; full spec in `02-manifest-helper-cli.md §4`):**
+1. Reject the name if unsafe (path separator, `..`, absolute, or failing `SAFE_NAME_RE`) — before any filesystem access.
+2. If `{specsDir}/{name}/.pipeline-state.json` exists → return that flat path.
+3. Else if exactly one `{specsDir}/*/{name}/.pipeline-state.json` exists → return that nested path.
+4. More than one match anywhere → `ambiguous` error listing all matching paths (uniqueness violation, REQ-DIR-04).
+5. Zero matches → `not-found` error.
+
+A directory counts as a **feature** only if it directly contains a `.pipeline-state.json` (the *feature-shaped-dir bound*, `00-core-definitions.md §6`). Non-feature subtrees (`.verification/`, `tests/`, fixture dirs, and the epic root itself — which holds `epic-manifest.json` but no `.pipeline-state.json`) are therefore never matched as features.
+
+**Compatibility:** for a standalone feature the resolver returns its flat path with no epic logic engaged (REQ-COMPAT-01/02) — standalone-feature behavior is unchanged. A pre-existing latent name collision is reported for manual cleanup by the navigator / forge-verify epic mode (CHECK-E08), not by aborting an unrelated command whose name resolves to exactly one dir (tech-spec §3.4).
+
+## Epic Context Injection
+
+After resolving the feature directory, check the feature's `.pipeline-state.json` for an `epic` back-pointer. **If absent, skip this block entirely** (standalone feature — REQ-COMPAT-01; standalone-feature behavior is unchanged). **If present**, load exactly the following context, and nothing transitive (REQ-CTX-01):
+
+1. **`{specsDir}/{epic}/EPIC.md`** — the epic narrative, including the per-feature Contracts sections.
+2. **This feature's `charter`** — read from `{specsDir}/{epic}/epic-manifest.json` (the `features[]` entry whose `name` matches), together with its `exposes` and `consumes` arrays. These are the feature's **contract obligations** (REQ-CTX-02): what it must expose to dependents and what it consumes from dependencies.
+3. **Direct completed dependencies only** — for each `name` in this feature's `dependsOn`, resolve that sibling's directory and, **only if it is complete-for-orchestration** (`00-core-definitions.md §7`), load its `PRD.md` and `tech-spec.md`.
+
+**Do NOT load** transitive (indirect) dependencies' specs. Indirect contracts reach this feature only through the *direct* deps' Contracts sections in `EPIC.md`. This bounds context size and keeps the injected set deterministic (REQ-CTX-01).
+
+To obtain the manifest contracts and the live completion status of each dependency in one deterministic call, run `render-status` and read the per-feature `status` and the `consumes`/`exposes` arrays rather than re-deriving them:
+
+```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, proceed with **only** EPIC.md + charter (a corrupt manifest must not silently inject stale dep specs — REQ-ROBUST-02): on **exit 1**, parse the `{findings[]}` JSON from stdout and surface each; on **exit 2**, surface the plain `Error:` line from stderr verbatim. Do not attempt to parse findings JSON on an exit-2 failure (stdout is empty).
+
+## Pipeline State Protocol
+
+Write pipeline state conforming to `references/pipeline-state-schema.json`. Always update `updatedAt` when modifying pipeline state.
+
+### Staleness Detection (Read-Time)
+
+When loading upstream artifacts as prerequisites, check `basedOnVersions` in the pipeline state for this stage. If any upstream stage's current version is newer than the version recorded in `basedOnVersions`, warn the user before proceeding:
+
+> "This stage was built against {upstream} v{old}, but {upstream} is now at v{new}. The current artifacts may be outdated. Consider re-running this stage, or use --force to proceed with potentially stale inputs."
+
+## Git Commit Protocol
+
+When `gitCommitAfterStage` is true, follow this exact order to avoid state inconsistency:
+
+1. **Stage specific files only:** `git add {specsDir}/{feature}/` — never use `git add -A` or `git add .`
+2. **Attempt commit:** `git commit -m "{commitPrefix}({feature}): <action>"`
+3. **If commit succeeds:** capture the commit hash, then update pipeline state with `status: "complete"` and the `commitHash`
+4. **If commit fails:** do NOT update pipeline state to complete. Report the error to the user and leave state as `in-progress` so the stage can be resumed. Common failure causes:
+   - **Pre-commit hook failure:** Report the hook output. Never use `--no-verify` to bypass. Help the user fix the underlying issue.
+   - **Merge conflicts:** Report conflicting files. Suggest resolution steps appropriate to the conflict.
+   - **Nothing to commit:** If all artifacts were already committed, this is fine — proceed with state update but note the absence of a new commit hash.
+5. **Never** use `git add -A`, `--no-verify`, or `--force` flags
+
+## Crash Recovery
+
+When a skill detects that `currentStage` matches itself and the stage status is `in-progress`, a previous run was interrupted. Follow this recovery protocol:
+
+1. **Inventory existing artifacts:** List all files on disk in `{specsDir}/{feature}/` that this stage would produce
+2. **Compare against state:** Check the `artifacts` array in the pipeline state for this stage — it tracks files written incrementally during the previous run
+3. **Present options to user:** "This stage was interrupted. Found {N} artifacts from the previous run: {list}. Would you like to resume from where it left off, or restart the stage from scratch?"
+4. **If resume:** Skip artifact generation for files that already exist and appear complete (non-empty, properly structured). Continue from the next unwritten artifact.
+5. **If restart:** Proceed normally. The version number will increment.
+
+**Incremental artifact tracking:** When a stage writes multiple files (e.g., forge-3-specs writing a suite of spec documents), update the `artifacts` array in `.pipeline-state.json` after writing each file — not just at stage completion. This ensures crash recovery knows exactly which files were successfully written.
+
+## Force Mode
+
+If the user passes `--force` as an argument, skip prerequisite validation with a warning:
+
+> Force mode: skipping prerequisite checks. Pipeline state tracking may be incomplete. Recommend running `/feature-forge:forge {feature}` after to verify status.
+
+Continue with the stage even if prior stages are not marked complete. Still read any existing artifacts (PRD.md, tech-spec.md, etc.) if they exist on disk — force mode skips the pipeline state check, not the artifact loading.

package/adapters/claude/references/skill-frontmatter.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/garygentry/feature-forge/references/skill-frontmatter.schema.json",
+  "title": "feature-forge canonical SKILL.md frontmatter",
+  "description": "Spec-pure frontmatter for canonical skills/*/SKILL.md. Source of truth for the allowed/required key sets loaded by scripts/check-spec-purity.py. NO version key (REQ-VER-03): versions live in manifests only.",
+  "type": "object",
+  "required": ["name", "description"],
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "license": { "type": "string" },
+    "compatibility": {},
+    "metadata": { "type": "object" },
+    "allowed-tools": {}
+  }
+}

package/adapters/claude/references/stack-resolution.md

@@ -0,0 +1,51 @@
+# Stack Resolution Protocol
+
+How feature-forge resolves stack-specific guidance for a project.
+
+## Resolution Order (highest priority first)
+
+1. **Project-level override**: `.claude/references/stack-decisions.md` in the project root. If this file exists, it takes absolute precedence — it contains the team's explicit technology decisions.
+
+2. **Detected stack profile**: `references/stacks/{stack}.md` in this plugin, where `{stack}` matches the `stack` field in `forge.config.json`. Provides language-specific conventions for spec writing, verification, and examples.
+
+3. **Generic fallback**: `references/stacks/_generic.md` in this plugin. Language-neutral guidance that works for any stack. Used when no stack is detected or no matching profile exists.
+
+## How Stack Detection Works
+
+Stack detection happens during **forge-2-tech** (the technical specification stage), which is the natural point where technology decisions are made.
+
+1. The agent examines the project's root manifest and build files
+2. Identifies the primary language, build tool, package manager, and framework
+3. Asks the user to confirm: "I detected this as a {stack} project. Correct?"
+4. Persists the stack identity in `forge.config.json` via the `stack`, `typeCheckCommand`, and `testCommand` fields
+5. All downstream stages (forge-3-specs, forge-4-backlog, forge-verify, forge-6-docs) read the `stack` field and load the matching profile
+
+## forge.config.json Fields
+
+```json
+{
+  "stack": "typescript",
+  "typeCheckCommand": "bun run typecheck",
+  "testCommand": "bun test"
+}
+```
+
+- `stack` — Identifier matching a profile filename in `references/stacks/` (e.g., "typescript", "python", "go")
+- `typeCheckCommand` — Used in acceptance criteria and verification checks. Null if the stack has no type checker.
+- `testCommand` — Used in acceptance criteria and verification checks.
+
+## Available Profiles
+
+| Profile | File | Covers |
+|---------|------|--------|
+| TypeScript | `references/stacks/typescript.md` | Node.js/Bun, npm/pnpm/bun, monorepo patterns, TS-specific spec conventions |
+| Python | `references/stacks/python.md` | Python 3.10+, pip/uv/poetry, pytest, type hints, Pydantic/dataclasses |
+| Generic | `references/stacks/_generic.md` | Any stack — language-neutral guidance using placeholders |
+
+## When No Stack Is Configured
+
+If `forge.config.json` has no `stack` field and forge-2-tech hasn't run yet (e.g., when using `--force`), skills should:
+
+1. Attempt basic detection from project files (look for manifest files)
+2. Use `_generic.md` as fallback
+3. Note in the pipeline state that stack detection was skipped

package/adapters/claude/references/stacks/_generic.md

@@ -0,0 +1,90 @@
+# Generic Stack Profile
+
+Language-neutral guidance for projects without a dedicated stack profile. Use this as a fallback when no matching `references/stacks/{stack}.md` exists.
+
+## Discovery Protocol
+
+Identify the project's stack by checking for these manifest and build files:
+
+| File | Stack |
+|------|-------|
+| `package.json` | Node.js / Bun (JavaScript/TypeScript) |
+| `pyproject.toml`, `setup.py`, `setup.cfg` | Python |
+| `go.mod` | Go |
+| `Cargo.toml` | Rust |
+| `pom.xml`, `build.gradle`, `build.gradle.kts` | Java / Kotlin |
+| `*.csproj`, `*.sln` | .NET (C#/F#) |
+| `mix.exs` | Elixir |
+| `Gemfile` | Ruby |
+| `Package.swift` | Swift |
+
+Also check for:
+- **Lock files**: Reveal the package manager (`bun.lockb`, `uv.lock`, `poetry.lock`, `go.sum`, `Cargo.lock`, etc.)
+- **Workspace/monorepo configs**: `turbo.json`, `nx.json`, `lerna.json`, `pants.toml`, `Cargo workspace`, Go workspace `go.work`
+- **CI configuration**: `.github/workflows/`, `Makefile`, `justfile` — often reveals build and test commands
+
+## Archetype Adaptations
+
+### 00-core-definitions.md
+
+The shared type/data contract document. Language-neutral name for what TypeScript calls "core types and interfaces." Contents should include:
+
+- **Data structures**: The primary types, classes, structs, records, or models that define the feature's domain. Use the project's idiomatic type system (dataclasses, structs, interfaces, schemas, etc.)
+- **Error/exception hierarchy**: Base error type and domain-specific subtypes with structured properties. Every language has a mechanism for this (exception classes, error types, Result enums, etc.)
+- **Constants and enumerations**: Shared values referenced across the feature
+- **Public contracts**: Function signatures, protocols, interfaces, or traits that define the feature's API surface
+
+**Documentation rule**: Every type/structure must have documentation comments in the project's convention (JSDoc, docstrings, godoc, rustdoc, etc.)
+
+**Export rule**: Everything must be accessible through the module's entry point following project conventions.
+
+### 01-architecture-layout.md
+
+How the feature is structured in the project:
+
+- **Directory tree**: Full layout (not abbreviated)
+- **Project manifest**: Dependencies, entry points, build scripts
+- **Build/compiler configuration**: Key options
+- **Module export structure**: What each entry point exposes
+- **Build and deployment considerations**
+
+### NN-testing-strategy.md
+
+- **Testing framework and tooling**: Match project conventions
+- **Unit test approach**: What to test, what to mock/stub
+- **Integration test approach**: Cross-module interaction testing
+- **Test fixtures and factories**
+- **Coverage targets**
+- **Test file location conventions**
+
+## Spec Conventions
+
+When writing implementation specs:
+- Include complete type definitions and function signatures in the project's language — not pseudocode
+- Include documentation comments on every public type and function
+- Include error handling for every operation
+- Include example usage where it aids clarity
+- Cross-reference other spec documents by filename
+
+## Verification Adaptations
+
+Replace stack-specific checks with these generic equivalents:
+
+| Stack-specific check | Generic equivalent |
+|---------------------|-------------------|
+| "Valid TypeScript syntax" | "Valid syntax in the project's language" |
+| "Barrel exports (index.ts)" | "Module exports/entry points follow project conventions" |
+| "bun run typecheck passes" | "`{typeCheckCommand}` passes" (from forge.config.json) |
+| "bun test passes" | "`{testCommand}` passes" (from forge.config.json) |
+| "JSDoc on every field" | "Documentation comments on every field" |
+| "tsconfig.json extends root" | "Build configuration follows project conventions" |
+
+## Acceptance Criteria Patterns
+
+Use these placeholder patterns in backlog items. Replace `{typeCheckCommand}`, `{testCommand}`, and `{module}` with values from `forge.config.json` and the project structure:
+
+- `{typeCheckCommand} passes for {module}`
+- `{testCommand} passes for {module}`
+- `{module}/[entry point] exports [expected symbols]`
+- `[dependency manifest] includes [new dependency]`
+- `[build command] succeeds`