@izkac/forgekit 0.3.11 → 0.3.13

package/vendor/skills/archive-to-adr/SKILL.md

@@ -1,149 +1,149 @@
----
-name: archive-to-adr
-description: >-
-  Create or update Architecture Decision Records (ADRs) from an archived OpenSpec
-  change. Fire after archive-shaped Bash completes (hooks wrap `openspec archive`
-  plus `mv` into dated `openspec/changes/archive/…`). Also use when sessionStart
-  reports pending archives, the user says `/archive-to-adr`, or they ask to
-  generate ADRs from an archive. Skip entirely when the project has ADRs disabled
-  (`.forge/config.json` → `adr.enabled: false`).
-disable-model-invocation: false
----
-
-# Archive to ADR
-
-Turn a **completed and archived** OpenSpec change into one or more ADRs, following
-the project's decisions doc (scaffolded as `docs/decisions.md` by default via
-`forge init --adr`).
-
-This skill is **decoupled** from OpenSpec itself: archive hooks inject a reminder
-after successful archive-shaped shells; you judge whether an ADR is warranted.
-
-## Project config
-
-Read **`.forge/config.json`** at the repo root (written by `forge init` / optional
-`forgekit install` project scaffold):
-
-```json
-{
-  "adr": {
-    "enabled": true,
-    "dir": "docs/adr",
-    "decisionsDoc": "docs/decisions.md"
-  }
-}
-```
-
-| Field | Default | Meaning |
-|-------|---------|---------|
-| `adr.enabled` | `true` if file missing and `docs/adr/` exists; else follow install | When `false`, do **not** run this skill — no ADR, no "No ADR" stamp |
-| `adr.dir` | `docs/adr` | Directory for `NNNN-short-topic.md` + status `README.md` |
-| `adr.decisionsDoc` | sibling `decisions.md` of `adr.dir` | Process / template (when to write, format, hooks) |
-| `plan.engine` | `openspec` | `specs` = built-in engine; archives live under `<plan.dir>/changes/archive/` instead of `openspec/changes/archive/` |
-
-Below, **`{adrDir}`** and **`{decisionsDoc}`** mean those configured paths, and
-**`{archiveRoot}`** means `openspec/changes/archive` (OpenSpec engine) or
-`<plan.dir>/changes/archive` (specs engine, default `specs/changes/archive`).
-
-If `adr.enabled` is `false`, stop and tell the user ADRs are disabled for this project.
-
-## When to skip entirely (ADRs enabled)
-
-If the change is a bug fix, copy tweak, docs-only edit, or refactor with no
-architectural choice, **do not** create an ADR. Instead add this **single line**
-to the archived `proposal.md`:
-
-```text
-No ADR — non-architectural change
-```
-
-That silences the session-start pending-ADR backstop.
-
-## Input
-
-**Required:** the archive directory path, e.g.
-`{archiveRoot}/2026-05-15-payment-add-service/`.
-
-If the user only gives the change name, resolve it: list `{archiveRoot}/`
-and pick the matching dated folder.
-
-## Steps
-
-1. **Confirm ADRs are enabled** — read `.forge/config.json` as above.
-
-2. **Read the archived artifacts**
-   - `proposal.md` — Why, What Changes, Capabilities, Impact
-   - `design.md` — Context, Decisions, Risks, Migration
-   - `specs/**/*.md` in the archive (capability deltas)
-
-3. **Apply the ADR gate** (`{decisionsDoc}` § "When to write an ADR")
-   - Write an ADR when the change establishes/revises a **boundary**, picks one
-     approach over a **real** alternative, introduces a **constraint** future code
-     must respect, picks a **vendor/protocol/library** that is expensive to swap,
-     or codifies a **repo-wide** convention.
-   - Skip when it's purely implementation detail inside an existing decision.
-
-4. **Pick the next ADR number**
-   - List `{adrDir}/*.md` (four-digit prefix pattern `NNNN-*.md`).
-   - Use **the next sequential integer**; never reuse a number.
-   - If multiple distinct architectural decisions warrant separate ADRs in one
-     archive, create multiple files (`NNNN-…`, `NNNN+1-…`), each with one sharp decision.
-
-5. **Author the ADR file** at `{adrDir}/NNNN-short-topic.md` using the **exact
-   section structure** from `{decisionsDoc}`:
-   - Title: `# NNNN. <Short, decision-shaped title>`
-   - Frontmatter lines: **Status**, **Date**, **Area**, **Related** (link the
-     archive path, sibling ADRs)
-   - Body: Context, Decision, Alternatives considered, Consequences
-     (Positive / Negative / Neutral), References
-
-   Keep it terse (target ~80–200 lines total across all new ADRs for the change).
-   Link to the archive for forensic detail; don't paste the whole design.
-
-6. **Update the status index** `{adrDir}/README.md` — add or amend the table
-   row(s). If `README.md` is missing, create it with the table scaffold from
-   `{decisionsDoc}`.
-
-7. **Cross-reference from the archive**
-   - In `{archiveRoot}/<dated-change>/proposal.md`, add (or extend):
-
-   ```markdown
-   ## Decision record
-
-   This change is recorded as ADR-NNNN ({adrDir}/NNNN-short-topic.md).
-   ```
-
-   Use `ADR-NNNN` text so pending-ADR hooks (`grep 'ADR-[0-9]'`) recognize the link.
-
-8. **If capability specs were promoted** during archive: consider a one-line
-   pointer in the ADR **References** to `openspec/specs/<capability>/spec.md`
-   (optional but valuable).
-
-## Output
-
-- Paths of created/updated `{adrDir}/*.md`
-- Confirmation `{adrDir}/README.md` was updated
-- Confirmation the archived `proposal.md` now references `ADR-NNNN`
-- One-sentence summary per ADR written
-
-## Guardrails
-
-- Naming: **`NNNN-short-topic.md`**, not date-only filenames.
-- **Never** add `{adrDir}/` to `.cursorindexignore` (or equivalent ignore that
-  blocks agent retrieval).
-- Don't duplicate content that belongs only in OpenSpec — the archive remains
-  the verbose record; the ADR is the distilled "why."
-- If unsure whether to write an ADR, re-read the decisions gate; when still
-  ambiguous, ask the user once rather than inventing ceremony.
-
-## Relationship to hooks
-
-Project hooks (from `forge init --adr`) may:
-
-- Remind agents to run **archive-to-adr** after `openspec archive` / an archive
-  move (either engine)
-- At session start, list archives (both `openspec/changes/archive/` and
-  `specs/changes/archive/`) whose `proposal.md` lacks `ADR-*` **and** lacks
-  the `No ADR — non-architectural change` stamp
-
-Neither hook writes ADR files; **this skill** does.
+---
+name: archive-to-adr
+description: >-
+  Create or update Architecture Decision Records (ADRs) from an archived OpenSpec
+  change. Fire after archive-shaped Bash completes (hooks wrap `openspec archive`
+  plus `mv` into dated `openspec/changes/archive/…`). Also use when sessionStart
+  reports pending archives, the user says `/archive-to-adr`, or they ask to
+  generate ADRs from an archive. Skip entirely when the project has ADRs disabled
+  (`.forge/config.json` → `adr.enabled: false`).
+disable-model-invocation: false
+---
+
+# Archive to ADR
+
+Turn a **completed and archived** OpenSpec change into one or more ADRs, following
+the project's decisions doc (scaffolded as `docs/decisions.md` by default via
+`forge init --adr`).
+
+This skill is **decoupled** from OpenSpec itself: archive hooks inject a reminder
+after successful archive-shaped shells; you judge whether an ADR is warranted.
+
+## Project config
+
+Read **`.forge/config.json`** at the repo root (written by `forge init` / optional
+`forgekit install` project scaffold):
+
+```json
+{
+  "adr": {
+    "enabled": true,
+    "dir": "docs/adr",
+    "decisionsDoc": "docs/decisions.md"
+  }
+}
+```
+
+| Field | Default | Meaning |
+|-------|---------|---------|
+| `adr.enabled` | `true` if file missing and `docs/adr/` exists; else follow install | When `false`, do **not** run this skill — no ADR, no "No ADR" stamp |
+| `adr.dir` | `docs/adr` | Directory for `NNNN-short-topic.md` + status `README.md` |
+| `adr.decisionsDoc` | sibling `decisions.md` of `adr.dir` | Process / template (when to write, format, hooks) |
+| `plan.engine` | `openspec` | `specs` = built-in engine; archives live under `<plan.dir>/changes/archive/` instead of `openspec/changes/archive/` |
+
+Below, **`{adrDir}`** and **`{decisionsDoc}`** mean those configured paths, and
+**`{archiveRoot}`** means `openspec/changes/archive` (OpenSpec engine) or
+`<plan.dir>/changes/archive` (specs engine, default `specs/changes/archive`).
+
+If `adr.enabled` is `false`, stop and tell the user ADRs are disabled for this project.
+
+## When to skip entirely (ADRs enabled)
+
+If the change is a bug fix, copy tweak, docs-only edit, or refactor with no
+architectural choice, **do not** create an ADR. Instead add this **single line**
+to the archived `proposal.md`:
+
+```text
+No ADR — non-architectural change
+```
+
+That silences the session-start pending-ADR backstop.
+
+## Input
+
+**Required:** the archive directory path, e.g.
+`{archiveRoot}/2026-05-15-payment-add-service/`.
+
+If the user only gives the change name, resolve it: list `{archiveRoot}/`
+and pick the matching dated folder.
+
+## Steps
+
+1. **Confirm ADRs are enabled** — read `.forge/config.json` as above.
+
+2. **Read the archived artifacts**
+   - `proposal.md` — Why, What Changes, Capabilities, Impact
+   - `design.md` — Context, Decisions, Risks, Migration
+   - `specs/**/*.md` in the archive (capability deltas)
+
+3. **Apply the ADR gate** (`{decisionsDoc}` § "When to write an ADR")
+   - Write an ADR when the change establishes/revises a **boundary**, picks one
+     approach over a **real** alternative, introduces a **constraint** future code
+     must respect, picks a **vendor/protocol/library** that is expensive to swap,
+     or codifies a **repo-wide** convention.
+   - Skip when it's purely implementation detail inside an existing decision.
+
+4. **Pick the next ADR number**
+   - List `{adrDir}/*.md` (four-digit prefix pattern `NNNN-*.md`).
+   - Use **the next sequential integer**; never reuse a number.
+   - If multiple distinct architectural decisions warrant separate ADRs in one
+     archive, create multiple files (`NNNN-…`, `NNNN+1-…`), each with one sharp decision.
+
+5. **Author the ADR file** at `{adrDir}/NNNN-short-topic.md` using the **exact
+   section structure** from `{decisionsDoc}`:
+   - Title: `# NNNN. <Short, decision-shaped title>`
+   - Frontmatter lines: **Status**, **Date**, **Area**, **Related** (link the
+     archive path, sibling ADRs)
+   - Body: Context, Decision, Alternatives considered, Consequences
+     (Positive / Negative / Neutral), References
+
+   Keep it terse (target ~80–200 lines total across all new ADRs for the change).
+   Link to the archive for forensic detail; don't paste the whole design.
+
+6. **Update the status index** `{adrDir}/README.md` — add or amend the table
+   row(s). If `README.md` is missing, create it with the table scaffold from
+   `{decisionsDoc}`.
+
+7. **Cross-reference from the archive**
+   - In `{archiveRoot}/<dated-change>/proposal.md`, add (or extend):
+
+   ```markdown
+   ## Decision record
+
+   This change is recorded as ADR-NNNN ({adrDir}/NNNN-short-topic.md).
+   ```
+
+   Use `ADR-NNNN` text so pending-ADR hooks (`grep 'ADR-[0-9]'`) recognize the link.
+
+8. **If capability specs were promoted** during archive: consider a one-line
+   pointer in the ADR **References** to `openspec/specs/<capability>/spec.md`
+   (optional but valuable).
+
+## Output
+
+- Paths of created/updated `{adrDir}/*.md`
+- Confirmation `{adrDir}/README.md` was updated
+- Confirmation the archived `proposal.md` now references `ADR-NNNN`
+- One-sentence summary per ADR written
+
+## Guardrails
+
+- Naming: **`NNNN-short-topic.md`**, not date-only filenames.
+- **Never** add `{adrDir}/` to `.cursorindexignore` (or equivalent ignore that
+  blocks agent retrieval).
+- Don't duplicate content that belongs only in OpenSpec — the archive remains
+  the verbose record; the ADR is the distilled "why."
+- If unsure whether to write an ADR, re-read the decisions gate; when still
+  ambiguous, ask the user once rather than inventing ceremony.
+
+## Relationship to hooks
+
+Project hooks (from `forge init --adr`) may:
+
+- Remind agents to run **archive-to-adr** after `openspec archive` / an archive
+  move (either engine)
+- At session start, list archives (both `openspec/changes/archive/` and
+  `specs/changes/archive/`) whose `proposal.md` lacks `ADR-*` **and** lacks
+  the `No ADR — non-architectural change` stamp
+
+Neither hook writes ADR files; **this skill** does.

package/vendor/skills/forge/SKILL.md

@@ -1,136 +1,136 @@
----
-name: forge
-description: >-
-  Forge — self-contained disciplined development workflow. Triage substantial work,
-  brainstorm, tracked plan (OpenSpec or built-in specs engine), subagent-driven TDD
-  implementation, verify, review, and finish.
-  Use when building features, fixing non-trivial bugs, or when the user invokes /forge.
-  Skip only when user says /forge:skip or work is trivial.
-disable-model-invocation: false
----
-
-# Forge
-
-Spec-tracked development pipeline. Planning engine is per-project
-(`.forge/config.json` → `plan.engine`): **OpenSpec** (vendor CLI) or the
-**built-in specs engine** (`specs/changes/`, same layout). **Self-contained** —
-all workflow skills live under `./skills/` (vendored from Superpowers MIT; see
-[skills/NOTICE.md](./skills/NOTICE.md)).
-
-Full reference: [docs/forge.md](./docs/forge.md) (ships with this skill).
-
-**Announce at start:** "Using Forge for this work." Include effective pace from
-`forge status` (e.g. `Pace: auto → brisk (…)`) — see [references/pace.md](./references/pace.md).
-
-## Instruction priority
-
-1. User explicit instructions (including `/forge:skip` and pace overrides)
-2. This skill + `./phases/`, `./references/`, and `./skills/`
-3. Project OpenSpec skills (`openspec-propose`, `openspec-apply-change`) — do not edit vendor copies (OpenSpec-engine projects only)
-
-## Pace (thoroughness)
-
-Checkout-local prefs control review/verify ceremony. Default pace is **`auto`**
-(resolves once per session from risk signals).
-
-```bash
-forge prefs                         # print effective pace (does NOT write a file)
-forge prefs brisk                   # WRITE .forge/preferences.local.json
-forge prefs --session-set lite
-forge models                        # print billing (does NOT write); set: included|metered
-forge doctor                        # plan-engine readiness (OpenSpec CLI or specs/ layout)
-```
-
-Honor [references/pace.md](./references/pace.md) in implement / verify / review.
-Hard floor: money/auth/contracts/migrations always get per-task review (even under `standard` mid-group / `brisk` / `lite`).
-Local overlays: [docs/forge.md](./docs/forge.md) § Checkout-local overrides.
-
-## Bundled skills
-
-| Skill | Path | When |
-| ----- | ---- | ---- |
-| Brainstorming | [skills/brainstorming/SKILL.md](./skills/brainstorming/SKILL.md) | brainstorm phase |
-| TDD | [skills/test-driven-development/SKILL.md](./skills/test-driven-development/SKILL.md) | every implement task |
-| Subagent-driven dev | [skills/subagent-driven-development/SKILL.md](./skills/subagent-driven-development/SKILL.md) | implement phase |
-| Systematic debugging | [skills/systematic-debugging/SKILL.md](./skills/systematic-debugging/SKILL.md) | blockers / test failures |
-| Verification | [skills/verification-before-completion/SKILL.md](./skills/verification-before-completion/SKILL.md) | verify phase |
-| Code review | [skills/requesting-code-review/SKILL.md](./skills/requesting-code-review/SKILL.md) | review phase |
-
-## Step 0 — Triage (default)
-
-Before coding on any non-trivial request, run triage per
-[references/substantial-work.md](./references/substantial-work.md).
-
-- **Substantial (tracked-change-worthy)** → continue Forge (bootstrap session if needed)
-- **Too small for a tracked change** → execute directly, no session
-- **`/forge:skip`** → mark session `phase: skipped` if one exists; execute directly
-
-Bootstrap session when entering Forge:
-
-```bash
-forge new <kebab-slug>
-# optional: forge new <slug> --signal "add stripe refund"
-```
-
-`forge new` resolves pace (default `auto`) onto the session and runs the
-plan-engine doctor in warn-only mode (missing OpenSpec CLI does not block
-session creation; specs-engine projects skip the CLI check).
-
-Resume: read `.forge/active.json` → `forge status`.
-
-Update phase as you progress:
-
-```bash
-forge phase <phase> [--plan-type openspec|specs] [--openspec <change>]
-```
-
-Valid phases: `triage`, `brainstorm`, `plan`, `implement`, `verify`, `review`, `finish`, `done`, `skipped`.
-
-## Phase flow
-
-| Phase | Action |
-| ----- | ------ |
-| brainstorm | [phases/brainstorm.md](./phases/brainstorm.md) → **skills/brainstorming** |
-| plan | [references/plan-routing.md](./references/plan-routing.md) → engine from `.forge/config.json`: **OpenSpec** ([plan-openspec.md](./phases/plan-openspec.md)) or **specs** ([plan-specs.md](./phases/plan-specs.md)) |
-| implement | [phases/implement.md](./phases/implement.md) → **subagent-driven-development** + **TDD** |
-| verify | [phases/verify.md](./phases/verify.md) → **verification-before-completion** |
-| review | [phases/review.md](./phases/review.md) → **requesting-code-review** |
-| finish | [phases/finish.md](./phases/finish.md) |
-
-<HARD-GATE>
-Do NOT write implementation code during brainstorm or plan phases until the user approves the tracked change (OpenSpec or specs).
-</HARD-GATE>
-
-<HARD-GATE>
-Subagent dispatch: NEVER pass a model slug you picked yourself (including any from the host's model list). Run `forge resolve-model --tier <fast|standard|capable>` and honor its JSON — omit the `model` parameter when `omitModel` is true, else pass `model` exactly. Metered/API models only on explicit user request. This applies to retries and fallbacks too: if a dispatch fails, re-resolve — do not hand-pick a replacement slug.
-</HARD-GATE>
-
-## Session artefacts
-
-Layout: [references/forge-layout.md](./references/forge-layout.md)
-
-Testing: [references/test-strategy.md](./references/test-strategy.md) — tier 1 scoped TDD per task, tier 2 narrow evidence per task, tier 3 full workspace once at verify.
-
-## Guardrails (every phase)
-
-- No autonomous `git commit` / push unless the user explicitly asks
-- Tests required for behavior changes
-- Trace ecosystem consumers when contracts change
-- Honor `openspec/config.yaml` prefixes when the project uses them (OpenSpec engine)
-- **Runtime integrity** — [references/runtime-integrity.md](./references/runtime-integrity.md): **spine.json mandatory every change** (rows or `notApplicable` — not keyword-gated); no stubs / false success; capability specs beat narrow task wording; every claimed capability needs a named production caller; when spine has rows the product loop must be **executed** — `e2e.json` steps + green `forge e2e run` (or BLOCKED), prose does not satisfy the gate; deferred wiring only via `forge defer` — `forge phase done` mechanically refuses on `forge integrity-check` failures
-
-## Agent surfaces
-
-| Agent | Skill (after `forgekit install`) | Project wiring (`forge init`) |
-| ----- | ----------------------------- | ----------------------------- |
-| **Cursor** | `~/.cursor/skills/forge/` | commands, `forge.mdc`, SessionStart hook |
-| **Claude Code** | `~/.claude/skills/forge/` | commands, `forge.md`, SessionStart + prompt hooks |
-| **Codex CLI** | `~/.codex/skills/forge/` | thin rule |
-
-**Planning (all agents):** after brainstorm, proceed directly to the configured engine — no plan-mode prompt. See [references/plan-routing.md](./references/plan-routing.md). Hooks remind agents to run the propose flow when `planType` is unset.
-
-**Distribute:** edit `skills/forge/` in forgekit, then `forgekit install --skills forge --force` on each machine. The bundled skills are a maintained fork (see [skills/NOTICE.md](./skills/NOTICE.md)) — do not re-vendor from Superpowers.
-
-## Do not edit vendor OpenSpec skills
-
-OpenSpec vendor skills upgrade in place. Forge behaviour lives in this tree and [docs/forge.md](./docs/forge.md). Re-apply vendor patches with `forge overlay` after OpenSpec upgrades.
+---
+name: forge
+description: >-
+  Forge — self-contained disciplined development workflow. Triage substantial work,
+  brainstorm, tracked plan (OpenSpec or built-in specs engine), subagent-driven TDD
+  implementation, verify, review, and finish.
+  Use when building features, fixing non-trivial bugs, or when the user invokes /forge.
+  Skip only when user says /forge:skip or work is trivial.
+disable-model-invocation: false
+---
+
+# Forge
+
+Spec-tracked development pipeline. Planning engine is per-project
+(`.forge/config.json` → `plan.engine`): **OpenSpec** (vendor CLI) or the
+**built-in specs engine** (`specs/changes/`, same layout). **Self-contained** —
+all workflow skills live under `./skills/` (vendored from Superpowers MIT; see
+[skills/NOTICE.md](./skills/NOTICE.md)).
+
+Full reference: [docs/forge.md](./docs/forge.md) (ships with this skill).
+
+**Announce at start:** "Using Forge for this work." Include effective pace from
+`forge status` (e.g. `Pace: auto → brisk (…)`) — see [references/pace.md](./references/pace.md).
+
+## Instruction priority
+
+1. User explicit instructions (including `/forge:skip` and pace overrides)
+2. This skill + `./phases/`, `./references/`, and `./skills/`
+3. Project OpenSpec skills (`openspec-propose`, `openspec-apply-change`) — do not edit vendor copies (OpenSpec-engine projects only)
+
+## Pace (thoroughness)
+
+Checkout-local prefs control review/verify ceremony. Default pace is **`auto`**
+(resolves once per session from risk signals).
+
+```bash
+forge prefs                         # print effective pace (does NOT write a file)
+forge prefs brisk                   # WRITE .forge/preferences.local.json
+forge prefs --session-set lite
+forge models                        # print billing (does NOT write); set: included|metered
+forge doctor                        # plan-engine readiness (OpenSpec CLI or specs/ layout)
+```
+
+Honor [references/pace.md](./references/pace.md) in implement / verify / review.
+Hard floor: money/auth/contracts/migrations always get per-task review (even under `standard` mid-group / `brisk` / `lite`).
+Local overlays: [docs/forge.md](./docs/forge.md) § Checkout-local overrides.
+
+## Bundled skills
+
+| Skill | Path | When |
+| ----- | ---- | ---- |
+| Brainstorming | [skills/brainstorming/SKILL.md](./skills/brainstorming/SKILL.md) | brainstorm phase |
+| TDD | [skills/test-driven-development/SKILL.md](./skills/test-driven-development/SKILL.md) | every implement task |
+| Subagent-driven dev | [skills/subagent-driven-development/SKILL.md](./skills/subagent-driven-development/SKILL.md) | implement phase |
+| Systematic debugging | [skills/systematic-debugging/SKILL.md](./skills/systematic-debugging/SKILL.md) | blockers / test failures |
+| Verification | [skills/verification-before-completion/SKILL.md](./skills/verification-before-completion/SKILL.md) | verify phase |
+| Code review | [skills/requesting-code-review/SKILL.md](./skills/requesting-code-review/SKILL.md) | review phase |
+
+## Step 0 — Triage (default)
+
+Before coding on any non-trivial request, run triage per
+[references/substantial-work.md](./references/substantial-work.md).
+
+- **Substantial (tracked-change-worthy)** → continue Forge (bootstrap session if needed)
+- **Too small for a tracked change** → execute directly, no session
+- **`/forge:skip`** → mark session `phase: skipped` if one exists; execute directly
+
+Bootstrap session when entering Forge:
+
+```bash
+forge new <kebab-slug>
+# optional: forge new <slug> --signal "add stripe refund"
+```
+
+`forge new` resolves pace (default `auto`) onto the session and runs the
+plan-engine doctor in warn-only mode (missing OpenSpec CLI does not block
+session creation; specs-engine projects skip the CLI check).
+
+Resume: read `.forge/active.json` → `forge status`.
+
+Update phase as you progress:
+
+```bash
+forge phase <phase> [--plan-type openspec|specs] [--openspec <change>]
+```
+
+Valid phases: `triage`, `brainstorm`, `plan`, `implement`, `verify`, `review`, `finish`, `done`, `skipped`.
+
+## Phase flow
+
+| Phase | Action |
+| ----- | ------ |
+| brainstorm | [phases/brainstorm.md](./phases/brainstorm.md) → **skills/brainstorming** |
+| plan | [references/plan-routing.md](./references/plan-routing.md) → engine from `.forge/config.json`: **OpenSpec** ([plan-openspec.md](./phases/plan-openspec.md)) or **specs** ([plan-specs.md](./phases/plan-specs.md)) |
+| implement | [phases/implement.md](./phases/implement.md) → **subagent-driven-development** + **TDD** |
+| verify | [phases/verify.md](./phases/verify.md) → **verification-before-completion** |
+| review | [phases/review.md](./phases/review.md) → **requesting-code-review** |
+| finish | [phases/finish.md](./phases/finish.md) |
+
+<HARD-GATE>
+Do NOT write implementation code during brainstorm or plan phases until the user approves the tracked change (OpenSpec or specs).
+</HARD-GATE>
+
+<HARD-GATE>
+Subagent dispatch: NEVER pass a model slug you picked yourself (including any from the host's model list). Run `forge resolve-model --tier <fast|standard|capable>` and honor its JSON — omit the `model` parameter when `omitModel` is true, else pass `model` exactly. Metered/API models only on explicit user request. This applies to retries and fallbacks too: if a dispatch fails, re-resolve — do not hand-pick a replacement slug.
+</HARD-GATE>
+
+## Session artefacts
+
+Layout: [references/forge-layout.md](./references/forge-layout.md)
+
+Testing: [references/test-strategy.md](./references/test-strategy.md) — tier 1 scoped TDD per task, tier 2 narrow evidence per task, tier 3 full workspace once at verify.
+
+## Guardrails (every phase)
+
+- No autonomous `git commit` / push unless the user explicitly asks
+- Tests required for behavior changes
+- Trace ecosystem consumers when contracts change
+- Honor `openspec/config.yaml` prefixes when the project uses them (OpenSpec engine)
+- **Runtime integrity** — [references/runtime-integrity.md](./references/runtime-integrity.md): **spine.json mandatory every change** (rows or `notApplicable` — not keyword-gated); no stubs / false success; capability specs beat narrow task wording; every claimed capability needs a named production caller; when spine has rows the product loop must be **executed** — `e2e.json` steps + green `forge e2e run` (or BLOCKED), prose does not satisfy the gate; deferred wiring only via `forge defer` — `forge phase done` mechanically refuses on `forge integrity-check` failures
+
+## Agent surfaces
+
+| Agent | Skill (after `forgekit install`) | Project wiring (`forge init`) |
+| ----- | ----------------------------- | ----------------------------- |
+| **Cursor** | `~/.cursor/skills/forge/` | commands, `forge.mdc`, SessionStart hook |
+| **Claude Code** | `~/.claude/skills/forge/` | commands, `forge.md`, SessionStart + prompt hooks |
+| **Codex CLI** | `~/.codex/skills/forge/` | thin rule |
+
+**Planning (all agents):** after brainstorm, proceed directly to the configured engine — no plan-mode prompt. See [references/plan-routing.md](./references/plan-routing.md). Hooks remind agents to run the propose flow when `planType` is unset.
+
+**Distribute:** edit `skills/forge/` in forgekit, then `forgekit install --skills forge --force` on each machine. The bundled skills are a maintained fork (see [skills/NOTICE.md](./skills/NOTICE.md)) — do not re-vendor from Superpowers.
+
+## Do not edit vendor OpenSpec skills
+
+OpenSpec vendor skills upgrade in place. Forge behaviour lives in this tree and [docs/forge.md](./docs/forge.md). Re-apply vendor patches with `forge overlay` after OpenSpec upgrades.