@izkac/forgekit 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,34 @@
+# @izkac/forgekit
+
+Portable agent skills + CLIs. One package, three bins:
+
+| Bin | Role |
+|-----|------|
+| **`forgekit`** | Install / list / update / uninstall skills × agents |
+| **`forge`** | Forge workflow sessions |
+| **`review`** | Thorough code review pipeline |
+
+## Install
+
+```bash
+npm i -g @izkac/forgekit
+forgekit install
+```
+
+Interactive install lets you pick **one or more** skills (comma-separated, e.g. `1,3`) or all. Same for agent environments.
+
+Non-interactive:
+
+```bash
+forgekit install --skills forge,thorough-code-review --agents cursor,claude --force
+```
+
+## Docs
+
+- After install, full Forge reference: `~/.cursor/skills/forge/docs/forge.md` (or `~/.claude/…` / `~/.codex/…`)
+- [How to use Forgekit](https://github.com/izkac/forgekit/blob/main/docs/usage.md)
+- [Repository README](https://github.com/izkac/forgekit#readme)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izkac/forgekit",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Forgekit CLIs — forgekit (install), forge (workflow), review (code review)",
   "type": "module",
   "bin": {
@@ -42,5 +42,8 @@
     "claude",
     "codex"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/prompts": "^8.5.2"
+  }
 }

package/src/init.mjs

@@ -11,10 +11,9 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import readline from 'node:readline/promises';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
-import { stdin as input, stdout as output } from 'node:process';
+import { checkbox, confirm, input } from '@inquirer/prompts';
 import {
   DEFAULT_ADR_DIR,
   disableProjectAdr,
@@ -391,30 +390,15 @@ export function initProject(selected, opts) {
 }
 
 async function promptAgents() {
-  const rl = readline.createInterface({ input, output });
-  try {
-    process.stdout.write(`Init Forge project wiring for which environments?\n`);
-    process.stdout.write(`  1) Cursor\n`);
-    process.stdout.write(`  2) Claude Code\n`);
-    process.stdout.write(`  3) Codex CLI\n`);
-    process.stdout.write(`  4) All\n`);
-    process.stdout.write(`Enter numbers separated by commas (e.g. 1,2) or 4 for all: `);
-    const answer = (await rl.question('')).trim();
-    if (!answer || answer === '4') return ['cursor', 'claude', 'codex'];
-    const map = { 1: 'cursor', 2: 'claude', 3: 'codex' };
-    const picked = [
-      ...new Set(
-        answer
-          .split(/[,\s]+/)
-          .map((s) => map[s.trim()])
-          .filter(Boolean),
-      ),
-    ];
-    if (picked.length === 0) throw new Error('No agents selected');
-    return picked;
-  } finally {
-    rl.close();
-  }
+  return checkbox({
+    message: 'Init Forge project wiring for which environments?',
+    choices: [
+      { value: 'cursor', name: 'Cursor' },
+      { value: 'claude', name: 'Claude Code' },
+      { value: 'codex', name: 'Codex CLI' },
+    ],
+    required: true,
+  });
 }
 
 /**
@@ -422,19 +406,11 @@ async function promptAgents() {
  * @returns {Promise<boolean>} true = user accepted OpenSpec setup
  */
 async function promptOpenSpecSetup() {
-  const rl = readline.createInterface({ input, output });
-  try {
-    const yn = (
-      await rl.question(
-        'OpenSpec is not set up in this project. Install and set it up now? [Y/n] (n = built-in specs engine) ',
-      )
-    )
-      .trim()
-      .toLowerCase();
-    return !(yn === 'n' || yn === 'no');
-  } finally {
-    rl.close();
-  }
+  return confirm({
+    message:
+      'OpenSpec is not set up in this project. Install and set it up now? (No = built-in specs engine)',
+    default: true,
+  });
 }
 
 /**
@@ -493,25 +469,16 @@ async function resolveInitPlanEngine(opts) {
  * @returns {Promise<{ enabled: boolean, dir: string }>}
  */
 async function promptAdrForInit(defaultDir = DEFAULT_ADR_DIR) {
-  const rl = readline.createInterface({ input, output });
-  let enabled = false;
-  try {
-    const yn = (
-      await rl.question(
-        'Use Architecture Decision Records (ADRs) in this project? [y/N] ',
-      )
-    )
-      .trim()
-      .toLowerCase();
-    enabled = yn === 'y' || yn === 'yes';
-    if (!enabled) return { enabled: false, dir: defaultDir };
-    const dirAnswer = (
-      await rl.question(`ADR directory inside the repo [${defaultDir}]: `)
-    ).trim();
-    return { enabled: true, dir: normalizeAdrDir(dirAnswer || defaultDir) };
-  } finally {
-    rl.close();
-  }
+  const enabled = await confirm({
+    message: 'Use Architecture Decision Records (ADRs) in this project?',
+    default: false,
+  });
+  if (!enabled) return { enabled: false, dir: defaultDir };
+  const dir = await input({
+    message: 'ADR directory inside the repo',
+    default: defaultDir,
+  });
+  return { enabled: true, dir: normalizeAdrDir(dir.trim() || defaultDir) };
 }
 
 async function main(argv = process.argv.slice(2)) {
@@ -569,6 +536,7 @@ if (isDirect) {
   main()
     .then((code) => process.exit(code))
     .catch((err) => {
+      if (err?.name === 'ExitPromptError') process.exit(130);
       process.stderr.write(`${err.message || err}\n`);
       process.exit(1);
     });

package/src/install.mjs

@@ -16,9 +16,8 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import readline from 'node:readline/promises';
 import { pathToFileURL } from 'node:url';
-import { stdin as input, stdout as output } from 'node:process';
+import { checkbox, confirm, input, select } from '@inquirer/prompts';
 import {
   ADR_SKILLS,
   DEFAULT_ADR_DIR,
@@ -414,51 +413,27 @@ export function listInstallStatus(opts = {}) {
 }
 
 /**
- * @param {string} question
- * @param {Record<string, string>} map  number → id
- * @param {string[]} allIds
+ * @param {string} message
+ * @param {string[]} ids
  * @returns {Promise<string[]>}
  */
-async function promptMulti(question, map, allIds) {
-  const rl = readline.createInterface({ input, output });
-  try {
-    process.stdout.write(`${question}\n`);
-    const entries = Object.entries(map);
-    for (const [num, id] of entries) {
-      const label =
-        SKILLS[id]?.label ?? AGENTS[id]?.label ?? id;
-      process.stdout.write(`  ${num}) ${label}\n`);
-    }
-    const allNum = String(entries.length + 1);
-    process.stdout.write(`  ${allNum}) All\n`);
-    process.stdout.write(
-      `Enter numbers separated by commas (e.g. 1,2) or ${allNum} for all: `,
-    );
-    const answer = (await rl.question('')).trim();
-    if (!answer || answer === allNum) return [...allIds];
-    const picked = [
-      ...new Set(
-        answer
-          .split(/[,\s]+/)
-          .map((s) => map[s.trim()])
-          .filter(Boolean),
-      ),
-    ];
-    if (picked.length === 0) throw new Error('Nothing selected');
-    return picked;
-  } finally {
-    rl.close();
-  }
+async function promptMulti(message, ids) {
+  return checkbox({
+    message,
+    choices: ids.map((id) => ({
+      value: id,
+      name: SKILLS[id]?.label ?? AGENTS[id]?.label ?? id,
+    })),
+    required: true,
+  });
 }
 
 async function promptSkills() {
-  const map = Object.fromEntries(SKILL_IDS.map((id, i) => [String(i + 1), id]));
-  return promptMulti('Install which skills?', map, SKILL_IDS);
+  return promptMulti('Install which skills?', SKILL_IDS);
 }
 
 async function promptAgents() {
-  const map = Object.fromEntries(AGENT_IDS.map((id, i) => [String(i + 1), id]));
-  return promptMulti('Install for which environments?', map, AGENT_IDS);
+  return promptMulti('Install for which environments?', AGENT_IDS);
 }
 
 /**
@@ -466,35 +441,21 @@ async function promptAgents() {
  * @returns {Promise<string>}
  */
 export async function promptAdrDir(defaultDir = DEFAULT_ADR_DIR) {
-  const rl = readline.createInterface({ input, output });
-  try {
-    const dirAnswer = (
-      await rl.question(`ADR directory inside each repo [${defaultDir}]: `)
-    ).trim();
-    return normalizeAdrDir(dirAnswer || defaultDir);
-  } finally {
-    rl.close();
-  }
+  const dir = await input({
+    message: 'ADR directory inside each repo',
+    default: defaultDir,
+  });
+  return normalizeAdrDir(dir.trim() || defaultDir);
 }
 
 /**
  * @returns {Promise<{ enabled: boolean, dir: string }>}
  */
 export async function promptAdrOptions() {
-  const rl = readline.createInterface({ input, output });
-  let enabled = false;
-  try {
-    const yn = (
-      await rl.question(
-        'Use Architecture Decision Records (ADRs) after OpenSpec archive? [y/N] ',
-      )
-    )
-      .trim()
-      .toLowerCase();
-    enabled = yn === 'y' || yn === 'yes';
-  } finally {
-    rl.close();
-  }
+  const enabled = await confirm({
+    message: 'Use Architecture Decision Records (ADRs) after OpenSpec archive?',
+    default: false,
+  });
   if (!enabled) return { enabled: false, dir: DEFAULT_ADR_DIR };
   const dir = await promptAdrDir(DEFAULT_ADR_DIR);
   return { enabled: true, dir };
@@ -504,19 +465,13 @@ export async function promptAdrOptions() {
  * @returns {Promise<boolean>} true = OpenSpec, false = built-in specs engine
  */
 export async function promptOpenSpec() {
-  const rl = readline.createInterface({ input, output });
-  try {
-    const yn = (
-      await rl.question(
-        'Plan with OpenSpec (vendor CLI)? [Y/n] (n = built-in specs engine) ',
-      )
-    )
-      .trim()
-      .toLowerCase();
-    return !(yn === 'n' || yn === 'no');
-  } finally {
-    rl.close();
-  }
+  return select({
+    message: 'Planning engine?',
+    choices: [
+      { value: true, name: 'OpenSpec (vendor CLI)' },
+      { value: false, name: 'Built-in specs engine' },
+    ],
+  });
 }
 
 /**
@@ -771,6 +726,7 @@ if (isDirect) {
   runInstall()
     .then((code) => process.exit(code))
     .catch((err) => {
+      if (err?.name === 'ExitPromptError') process.exit(130);
       process.stderr.write(`${err.message || err}\n`);
       process.exit(1);
     });

package/src/session-reminder.mjs

@@ -88,7 +88,7 @@ export function buildForgeMessage(info) {
   lines.push('Resume: invoke the forge skill for the current phase.');
   lines.push('Honor pace: see forge references/pace.md (`forge prefs`).');
   lines.push('Skip Forge for this task only: /forge:skip');
-  lines.push('Guide: Forge skill + forgekit docs/forge.md');
+  lines.push('Guide: Forge skill + docs/forge.md (under the installed forge skill)');
   return lines.join('\n');
 }
 

package/src/triage-prompt.mjs

@@ -91,7 +91,7 @@ export function buildForgeTriageMessage(options = {}) {
     for (const line of sessionLines) lines.push(`   ${line}`);
   }
   lines.push('3. Skip Forge for this task only: `/forge:skip`');
-  lines.push('Guide: Forge skill + forgekit docs/forge.md');
+  lines.push('Guide: Forge skill + docs/forge.md (under the installed forge skill)');
   return lines.join('\n');
 }
 

package/vendor/skills/forge/SKILL.md

@@ -17,7 +17,7 @@ Spec-tracked development pipeline. Planning engine is per-project
 all workflow skills live under `./skills/` (vendored from Superpowers MIT; see
 [skills/NOTICE.md](./skills/NOTICE.md)).
 
-Full reference: forgekit `docs/forge.md` (shipped with this skill’s source repo).
+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).
@@ -43,7 +43,7 @@ forge doctor                        # plan-engine readiness (OpenSpec CLI or spe
 
 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: forgekit `docs/forge.md` § Checkout-local overrides.
+Local overlays: [docs/forge.md](./docs/forge.md) § Checkout-local overrides.
 
 ## Bundled skills
 
@@ -133,4 +133,4 @@ Testing: [references/test-strategy.md](./references/test-strategy.md) — tier 1
 
 ## Do not edit vendor OpenSpec skills
 
-OpenSpec vendor skills upgrade in place. Forge behaviour lives in this tree and forgekit `docs/forge.md`. Re-apply vendor patches with `forge overlay` after OpenSpec upgrades.
+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.

package/vendor/skills/forge/docs/forge.md

@@ -0,0 +1,621 @@
+# Forge — disciplined development workflow
+
+Forge is an **OpenSpec-native**, **self-contained** development pipeline.
+All workflow skills (brainstorm, TDD, subagents, verify, review) live under the
+Forge skill’s `skills/` folder — **no Superpowers plugin required**.
+
+It does not stop at green unit tests or checked-off tasks: **runtime integrity**
+requires a named production path for every claimed capability, and (for
+jobs/workers) a closed product loop before `forge phase done`. See
+[Runtime integrity](#runtime-integrity).
+
+**Using Forgekit for the first time?** Start with the tutorial:
+[**How to use Forgekit**](https://github.com/izkac/forgekit/blob/main/docs/usage.md) (install → init → `/forge:apply` → examples).
+
+**Skill:** `forge` (Cursor, Claude Code, Codex CLI)  
+**Commands:** `/forge`, `/forge:*` (after `forge init`; Cursor and Claude Code)  
+**Scratch space:** `.forge/` (gitignored except README)  
+**CLI:** `@izkac/forgekit` → `forgekit` (install) · `forge` (workflow) · `review` (standalone deep review)
+
+---
+
+## Install
+
+```bash
+# Preferred — once per machine
+npm i -g @izkac/forgekit
+forgekit install --skills forge --agents cursor,claude
+# or: forge install                  # alias → --skills forge
+```
+
+```bash
+# Once per project
+forge init --cursor --claude         # commands, rules, hooks, .forge/
+forge init --overlay                 # optional OpenSpec vendor patches
+```
+
+Hooks call `forge` on PATH. Merge the generated `forge-hooks.snippet.json`
+into your agent settings if hooks are not picked up automatically.
+
+---
+
+## When Forge runs
+
+**Default:** agents **triage** every task. Substantial work enters Forge
+automatically unless the user explicitly skips with **`/forge:skip`**.
+
+### Substantial work (enter Forge)
+
+**Forge = OpenSpec.** Enter the full flow only when the work warrants a tracked OpenSpec change — when **any** of:
+
+- New feature or behavior change
+- Multi-file or multi-package change
+- Public API, contract, or config schema change
+- Cross-product / ecosystem impact
+- User invokes `/forge`, `/forge:brainstorm`, `/forge:plan`, or `/forge:build`
+- Work would likely need an ADR or new OpenSpec capability when done
+
+### Trivial work (skip Forge)
+
+Execute directly when **all** of:
+
+- Question, explanation, or read-only review
+- Typo, comment, or purely cosmetic edit
+- Single localized change with no contract impact
+- User explicitly says **`/forge:skip`** for this task
+
+---
+
+## End-to-end decision tree
+
+This doc uses an **ASCII tree only** — no Mermaid. Lightweight viewers (e.g.
+MarkView) render Mermaid flowcharts with broken fills and connectors; ASCII
+works everywhere.
+
+```
+User request
+    │
+    ├─ /forge:skip? ── yes ──► Direct execution (no Forge session)
+    │
+    └─ no
+        │
+        └─ OpenSpec-worthy / substantial? ── no ──► Direct execution
+                │
+               yes
+                │
+                ▼
+        Start / resume Forge session
+                │
+                ▼
+           Phase: Brainstorm
+                │
+                ├─ design not approved ──► (loop back to Brainstorm)
+                │
+                └─ design approved
+                        │
+                        ▼
+                 Phase: Plan (OpenSpec)
+                        │
+                        ▼
+                 /opsx:propose
+                 openspec/changes/<name>/
+                        │
+                        ▼
+                 Phase: Implement
+                          │
+            ┌─────────────┴─────────────┐
+            │  PER TASK (loop until done) │
+            │  1. Subagent implementer  │
+            │  2. TDD (scoped tests)    │
+            │  3. Reviewer (pace):      │
+            │     thorough=per task     │
+            │     standard=per group    │
+            │     └─ fail ──► retry     │
+            │  (tier 2 narrow evidence) │
+            └─────────────┬─────────────┘
+                          ▼
+         Verify: audit tier 2 + tier 3 (scope from pace)
+                  + ## Product loop (or BLOCKED)
+                  + forge integrity-check
+                          │
+                          ▼
+         Final review (pace) — spine + product loop
+                          │
+                          ▼
+                 /opsx:archive (+ project ADR follow-up if any)
+                          │
+                          ▼
+            forge phase done  ← integrity gate (refuses if incomplete)
+            Done + cleanup .forge session
+```
+
+**Jobs / workers / queues:** spine is mandatory for *every* change (`forge spine
+init` — rows or `notApplicable`). Async work also needs wiring + product-loop
+tasks. See [Runtime integrity](#runtime-integrity).
+
+### Triage (top of tree)
+
+| Check | Outcome |
+| ----- | ------- |
+| User sent `/forge:skip` | Direct execution |
+| Not substantial / not tracked-change-worthy | Direct execution |
+| Otherwise | Enter Forge session (tracked change) |
+
+### Planning engine (per project)
+
+Forge always produces a tracked change; the **engine** is project config
+(`.forge/config.json` → `plan.engine`, set by `forge init`):
+
+| Engine | Change location | Tooling |
+| ------ | --------------- | ------- |
+| `openspec` | `openspec/changes/<name>/` | OpenSpec CLI + `/opsx:*` vendor skills |
+| `specs` | `specs/changes/<name>/` (dir from `plan.dir`) | Built-in — plain markdown, same layout |
+
+Selection flow: `forgekit install` asks once for a user default
+(`~/.forgekit/config.json` → `plan.engine`); `forge init` auto-detects
+(`openspec/config.yaml` present → openspec, silent), otherwise offers to
+install + `openspec init`, and falls back to the specs engine on decline
+(`--openspec` / `--no-openspec` skip prompts). Migration later: `openspec
+init`, then move `specs/changes/*` into `openspec/changes/`.
+
+### Planning (after brainstorm)
+
+Proceed directly to the configured engine's propose flow — do not ask for a plan mode.
+
+| Step | What happens |
+| ---- | ------------ |
+| **Propose** | `/opsx:propose` → `openspec/changes/<name>/` (openspec) or author `specs/changes/<name>/{proposal,tasks}.md` per [plan-specs.md](../phases/plan-specs.md) (specs) |
+| **User approval** | Confirm proposal, design, tasks before implement |
+| **Implement** | `/forge:apply` or `/forge:build` against `tasks.md` |
+
+See the Forge skill’s [references/plan-routing.md](../references/plan-routing.md).
+
+---
+
+## Phases
+
+| Phase | What happens | Skills / commands |
+| ----- | ------------ | ----------------- |
+| **triage** | Substantial? Skip allowed? Bootstrap session | `forge` skill |
+| **brainstorm** | Explore intent, approaches, approval | `skills/brainstorming` |
+| **plan** | Tracked-change propose; **`forge spine init` every change** (rows or `notApplicable`); wiring + product-loop tasks when async | [plan-routing.md](../references/plan-routing.md) |
+| **implement** | Subagent per task, TDD, tier 2 evidence; update spine rows; `forge defer` for deferred wiring | **`/forge:apply`** (OpenSpec) or `/forge:build` + `skills/subagent-driven-development` + `skills/test-driven-development` + [test-strategy](../references/test-strategy.md) |
+| **verify** | Audit tier 2; tier 3; product-loop evidence; `forge integrity-check` | `skills/verification-before-completion` + `verify-evidence.md` |
+| **review** | Combined task reviewer (spec + quality) per task; final review (spine + product loop) | `skills/requesting-code-review` |
+| **finish** | Archive (+ ADR if the project uses that); `forge phase done` (integrity gate); cleanup | `/opsx:archive`, `forge cleanup` |
+
+**Standalone deep review (outside Forge):** for pre-merge audits with adversarial false-positive filtering, use the **thorough code review** skill — see [thorough-code-review.md](https://github.com/izkac/forgekit/blob/main/docs/thorough-code-review.md). Forge's `requesting-code-review` stays the per-task checkpoint during `/forge:build`.
+
+---
+
+## `.forge/` session layout
+
+One session per substantial task. **Per-checkout** active pointer — works across
+Cursor, Claude Code, and Codex without requiring a chat ID.
+
+```
+.forge/
+  active.json                         ← current session (gitignored)
+  models.local.json                   ← optional billing overlay
+  preferences.local.json              ← optional pace overlay
+  sessions/
+    2026-06-05T143022Z-my-feature-a3f9b2/
+      session.json                    ← phase, planType, openspecChange, pace
+      status.json                     ← machine-readable progress
+      brainstorm/
+        notes.md
+        decisions.md
+      plan.md                         ← legacy throwaway plans only (deprecated)
+      verify-evidence.md              ← tier 3 + ## Product loop (or BLOCKED)
+      deferrals.json                  ← forge defer registry (when used)
+      spine.json                      ← fallback if no tracked change dir
+      scorecard.md / scorecard.json   ← L2 session score (written at done/finish)
+      tasks/
+        01-first-task/
+          brief.md
+          test-evidence.md
+          task-review.md              ← combined spec + quality verdict
+      reviews/
+        final-review.md
+```
+
+For OpenSpec / specs-engine changes, the canonical **spine matrix** lives next to
+the plan: `openspec/changes/<name>/spine.json` (or `<specsDir>/changes/<name>/spine.json`).
+
+**Session ID:** `<UTC-compact>-<kebab-slug>-<6-hex>`
+
+**Retention:** 14 days. Finished sessions (`phase: done|skipped`) are removed
+on cleanup. Active session is never removed unless `--include-active`.
+
+Optional `cursorChatId` on `session.json` when a hook can supply it — not
+required for correctness.
+
+---
+
+## Commands (project slash)
+
+| Command | Purpose |
+| ------- | ------- |
+| `/forge` | Start or resume from active session / current phase |
+| `/forge:brainstorm` | Brainstorm phase only |
+| `/forge:plan` | Plan phase — tracked-change propose (engine from `.forge/config.json`) |
+| `/forge:apply` | **Tracked-change implement** — subagent TDD + verify + review (preferred over `/opsx:apply`) |
+| `/forge:build` | Implement phase (`tasks.md` from either engine) |
+| `/forge:status` | Show active session progress |
+| `/forge:skip` | **Explicit** opt-out of Forge for this task |
+
+OpenSpec commands remain available standalone (OpenSpec-engine projects):
+
+| Command | Purpose |
+| ------- | ------- |
+| `/opsx:propose` | Create OpenSpec change + artifacts |
+| `/opsx:apply` | Vendor OpenSpec task loop — **re-overlay** with Forge via `forge overlay`; prefer **`/forge:apply`** |
+| `/opsx:archive` | Archive completed change |
+| `/opsx:explore` | Explore without committing to a change |
+
+---
+
+## CLI (`forge`)
+
+```bash
+forge new <slug> [--signal "…"]   # new session + set active (resolves pace; warn-only doctor)
+forge status                      # active session JSON (+ effective pace)
+forge phase <phase> […]           # update phase / openspec / task counters
+forge cleanup [--dry-run]         # prune sessions >14 days or finished
+forge evidence --task <nn>-<slug> --command "<cmd>" --exit 0 --summary "<text>"
+                                  # stamp tier-2 test-evidence.md
+forge resolve-model --tier <fast|standard|capable>
+                                  # JSON model resolution (included billing by default)
+forge models                      # print effective billing (does NOT write a file)
+forge models included|metered     # WRITE .forge/models.local.json
+forge prefs                       # print effective pace (does NOT write a file)
+forge prefs auto|thorough|standard|brisk|lite
+                                  # WRITE .forge/preferences.local.json
+forge prefs --session-set lite    # pin active session only
+forge doctor                      # plan-engine readiness (OpenSpec or specs layout)
+forge doctor --install            # attempt npm install -g @fission-ai/openspec
+forge spine init|check            # capability→runtime spine matrix (spine.json in change dir)
+forge defer add|resolve|list      # deferral registry — deferred wiring is tracked debt
+forge integrity-check             # mechanical gate: spine + deferrals + product-loop evidence
+forge score [--write] [--md]      # L2 session scorecard (also auto-written at phase done)
+forge overlay                     # re-apply OpenSpec vendor overlays in this project
+forge init […]                    # wire project commands / hooks / rules
+forge install […]                 # alias → forgekit install --skills forge
+```
+
+Meta install (skills × agents):
+
+```bash
+forgekit install
+forgekit install --skills forge,thorough-code-review --agents cursor,claude
+forgekit list
+```
+
+---
+
+## Checkout-local overrides (per developer)
+
+Forge has two **optional**, **gitignored** overlays under `.forge/`.
+They appear on disk **only after you set them**. Bare get commands only print the
+merged effective value from package defaults.
+
+| Concern | Defaults (in `@izkac/forgekit`) | Local file (gitignored) | Get (print only) | Set (creates/updates file) |
+| ------- | ----------------------------- | ----------------------- | ---------------- | -------------------------- |
+| Subagent **billing** (`included` / `metered`) | `packages/cli/src/models.defaults.json` | `.forge/models.local.json` | `forge models` | `forge models included\|metered` |
+| Forge **pace** (review / verify ceremony) | `packages/cli/src/preferences.defaults.json` | `.forge/preferences.local.json` | `forge prefs` | `forge prefs auto\|thorough\|…` |
+
+```bash
+# Example: you ran forge models and only saw "included" —
+# that means the default lane is in effect. No models.local.json exists yet.
+forge models --json                 # localExists: false until you set
+forge models included               # now creates .forge/models.local.json
+
+forge prefs --session-set lite      # pin active session only; no local file
+```
+
+These are **per-checkout** (each developer’s clone), not committed to git — same
+idea as a personal `.env`.
+
+---
+
+## Pace (thoroughness)
+
+Forge ceremony (per-task review, final review, tier-3 verify, model bias, brainstorm
+depth) is controlled by a **pace** preset. Default is **`auto`**: resolve once at
+session start from risk signals, sticky for the session.
+
+| Pace | Intent |
+|------|--------|
+| `auto` | Pick thorough / standard / brisk / lite from signals (default) |
+| `thorough` | Always review **each task**; full-workspace tier 3 |
+| `standard` | Review once per **OpenSpec group**; full-workspace tier 3 |
+| `brisk` | Review high-risk tasks only; affected-workspace tier 3 |
+| `lite` | Skip reviews for low-risk; audit tier-2 only at verify |
+
+### Effort matrix (exact knobs)
+
+Defaults from `packages/cli/src/preferences.defaults.json`:
+
+| Knob | `thorough` | `standard` | `brisk` | `lite` |
+|------|------------|------------|---------|--------|
+| **review.perTask** | always | per-group | high-risk-only | never\* |
+| **review.final** | always | always | high-risk-only | never\* |
+| **review.depth** | full | full | spec-only | spec-only |
+| **review.maxRounds** | 3 | 2 | 1 | 0 |
+| **verify.tier3** | full-workspace | full-workspace | affected-only | audit-tier2-only |
+| **models.bias** | default | default | prefer-fast | prefer-fast |
+| **brainstorm.depth** | full | full | short (≤2–3 options) | minimal |
+
+\*Hard floor: money / auth / contracts / migrations / secrets still get per-task review (and final if the session touched high-risk), even under `brisk` / `lite` / mid-group `standard`.
+
+**`thorough` vs `standard`:** thorough reviews every task; standard reviews once per OpenSpec `tasks.md` group (`##` section), except high-risk tasks which still get an immediate per-task review.
+
+**`auto`** is not a preset — it picks one of the four once at session start (sticky):
+
+1. money / payment / auth / secret / migration / contract / gdpr → **thorough**
+2. ecosystem / API / multi-file / shared package / worker / job queue / pipeline / etl / platform / orchestration / openspec → **standard**
+3. docs / typo / rename / scaffold / changelog → **lite**
+4. fix / tweak / toolbar / style / padding (explicitly small) → **brisk**
+5. else (including empty / unrecognized) → **standard** (fail closed)
+
+When `--tasks-total N` is set with **N ≥ 15** and resolved pace is still `brisk`/`lite` (not user-pinned), Forge escalates the session to **standard**.
+
+**Unchanged on all paces:** tier-1 TDD + tier-2 evidence, no autonomous commit, OpenSpec when in Forge. Runtime integrity (below) applies at every pace.
+
+Agent rules for each knob: [pace.md](../references/pace.md).
+
+Prefs are gitignored (`.forge/preferences.local.json`), same pattern as `models.local.json`.
+
+### OpenSpec doctor
+
+`forge doctor` checks `openspec/config.yaml` and that `openspec` is on PATH.
+If the CLI is missing, it warns and offers `npm install -g @fission-ai/openspec`
+(`--install` to attempt). `forge new` runs doctor warn-only so a missing CLI does
+not block session creation.
+
+---
+
+## Runtime integrity
+
+Forge’s job is to ship **working product paths**, not green checkboxes over
+orphan libraries. Integrity rules live in
+[runtime-integrity.md](../references/runtime-integrity.md) and are
+enforced by both skill prompts and the CLI.
+
+### The problem it prevents
+
+Without integrity, a large change can look “done” while the product is hollow:
+
+- Libraries (matcher, BI exporter, …) are unit-tested and marked complete
+- A worker job logs and marks `succeeded` (or a thin concat job writes a `.sav`)
+- The UI can enqueue kinds nobody handles, or read collections nobody writes
+- OpenSpec shows 57/57 — but upload → analyze → ratify → run never works
+
+Integrity upgrades Forge from “no false job success” to **product-loop acceptance**.
+
+### Rules (plain language)
+
+1. **No stubs / false success** — a handler that only logs and succeeds is forbidden.
+2. **Runtime owner required** — a library alone does not satisfy a capability; name the production caller (job, endpoint, CLI).
+3. **Tests must fail on a no-op** — asserting “job status became succeeded” is not enough.
+4. **Specs beat narrow tasks** — capability specs win when they conflict with a thin task reading.
+5. **E2E = product loop** — produce → consume → decision changes output. A single job slice (ingest → Parquet) is **not** platform E2E.
+6. **Job-kind closure** — every product-surface job kind is wired end-to-end **or deleted** before complete. “Fail closed” is only a temporary `BLOCKED` state.
+7. **Consumer–producer** — if UI/API reads it, production must write it (proven in evidence).
+8. **Deferrals are tracked** — “wiring later” only via `forge defer`; unresolved deferrals block `done`.
+
+### Mechanics
+
+| Tool | Purpose |
+|------|---------|
+| `forge spine init\|check` | **Mandatory every change.** `spine.json`: rows **or** `notApplicable`. Not keyword-gated. |
+| `forge defer add\|resolve\|list` | Deferred wiring as tracked debt in the session |
+| `forge integrity-check` | Combined gate — also run automatically by `forge phase done\|finish` |
+
+Defaults (`integrity.forbidStubs`, `specsBeatNarrowTasks`, `requireE2E`) live in
+`preferences.defaults.json` and appear in `forge status`.
+
+Escape hatch: `forge phase done --allow-incomplete "<reason>"` records an honest
+exception in the session — it does not silently checkbox past gaps.
+
+### What runs automatically every session
+
+You do **not** paste a long definition-of-done prompt. After
+`forgekit install --skills forge`, every Forge session gets:
+
+| Automatic (CLI / hooks) | Agent-driven (skill phases — required) |
+| ----------------------- | -------------------------------------- |
+| Integrity reminder on every session/prompt hook | Plan: **`forge spine init` every change** — fill rows or `notApplicable` |
+| Pace `auto` fail-closed to **standard**; task-count escalation at ≥15 | Implement: update spine rows; `forge defer add` if wiring is deferred |
+| `forge phase done\|finish` requires valid spine + writes L2 scorecard | Verify: `## Product loop` when spine has rows (sync-only → prefer `notApplicable`) |
+| `forge status` surfaces `integrity.*` defaults | After done: answer L3 ship-check in `scorecard.md` |
+
+**Gates are automatic. Filling evidence is part of the normal phase flow.**
+Skipping those steps fails at `forge phase done`, not silently.
+
+### Worked example (jobs / workers change)
+
+**Plan**
+
+```bash
+forge spine init
+# edit openspec/changes/<name>/spine.json — one row per capability
+```
+
+```json
+{
+  "change": "etl-surveydb-pipeline-closure",
+  "notApplicable": null,
+  "rows": [
+    {
+      "capability": "REQ-GOV-01 matching",
+      "library": "services/etl-core/src/etl_core/matcher.py",
+      "runtimeOwner": "worker job analyze_study",
+      "writes": "study_proposals",
+      "reads": "N/A",
+      "uiConsumer": "Proposals page",
+      "evidence": "tasks/12-analyze/test-evidence.md"
+    },
+    {
+      "capability": "REQ-OUT-BI star schema",
+      "library": "services/etl-core/src/etl_core/bi_star.py",
+      "runtimeOwner": "worker job harmonization_run",
+      "writes": "runs/<id>/bi/*.parquet",
+      "reads": "decisions tip + weight_map tips",
+      "uiConsumer": "Runs artifact download",
+      "evidence": "verify-evidence.md#product-loop"
+    }
+  ]
+}
+```
+
+Docs-only / no-runtime changes may set `"notApplicable": "docs-only change"` instead of rows.
+
+**If wiring must wait for a later task**
+
+```bash
+forge defer add --task 9.7 --reason "analyze_study handler lands in 9.7"
+# … when 9.7 is done:
+forge defer resolve --task 9.7
+```
+
+**Verify evidence** (required when spine has rows):
+
+```markdown
+# Verify evidence — tier 3
+
+- **Command:** `pytest …` / `npm test …`
+- **Exit code:** 0
+
+## Product loop
+
+Fixture: OP1086 three sources
+
+1. ingest_source ×3 → study_sources + Parquet
+2. analyze_study → study_proposals (match / loop)
+3. ratify subset via API → decisions tip at revision R
+4. harmonization_run @R → .sav + Master QML + BI
+5. Assert: output at R differs from unratified baseline
+```
+
+Or an explicit `BLOCKED: …` line — then `forge phase done` refuses until unblocked
+or the user passes `--allow-incomplete`.
+
+**Finish**
+
+```bash
+forge integrity-check   # optional preview
+forge phase done        # same checks; exit 1 if incomplete
+```
+
+---
+
+## Subagent model
+
+Each implementation task:
+
+1. Coordinator writes `tasks/<nn>-<slug>/brief.md` (task text + file paths + constraints — **no chat history**).
+2. **Implementer** subagent — must follow `skills/test-driven-development` first.
+3. **Task reviewer** subagent (spec then quality) — unless pace skips low-risk tasks.
+4. Mark task complete (`tasks.md` checkbox or session progress).
+5. After all tasks: **verify** (tier 3 scope from pace) → **final reviewer** (unless pace skips) → finish.
+
+Test tiers: [test-strategy.md](../references/test-strategy.md) — scoped TDD per task, narrow evidence per task, full workspace **once** at verify when pace requires it (not every task).
+
+### Model selection (capability × billing)
+
+Subagents resolve models through **two axes** so Cursor / Claude Code / Codex stay on **subscription/included** pools by default:
+
+| Axis | Values | Default |
+| ---- | ------ | ------- |
+| Capability | `fast` · `standard` · `capable` | role-based |
+| Billing | `included` · `metered` | **`included`** |
+
+```bash
+forge resolve-model --tier standard   # JSON: { model, omitModel, billing, … }
+forge models                          # print effective billing (no file write)
+forge models metered                  # WRITE .forge/models.local.json
+```
+
+- Defaults: `packages/cli/src/models.defaults.json` (Cursor `included` = `inherit` → omit Task `model`).
+- Local overlay is optional — see **Checkout-local overrides** above.
+- **Never invent** host model slugs; honor `omitModel` / `model` from the resolver.
+- Escalate **capability** within `included` on `BLOCKED`; switch to `metered` only on explicit user request.
+- Keep the **parent** session on Auto/Composer (Cursor) or Max (Claude Code) — `inherit` follows the parent.
+
+Guardrails in every subagent brief (honor the **project’s** agent docs too):
+
+- No autonomous `git commit` / push unless the user asks
+- Implementer runs tier 1 (scoped) + tier 2 (narrow) tests; coordinator saves `tasks/<nn>-<slug>/test-evidence.md` before marking task done
+- Trace downstream consumers when contracts change
+
+Prompt templates: [subagents/](../subagents/)
+
+---
+
+## Bundled skills (self-contained)
+
+Forge vendors adapted Superpowers skills (MIT) under `skills/forge/skills/`.
+See [skills/NOTICE.md](../skills/NOTICE.md).
+
+| Skill | Purpose |
+| ----- | ------- |
+| brainstorming | Brainstorm phase |
+| test-driven-development | Implement — per task |
+| subagent-driven-development | Implement — orchestration |
+| systematic-debugging | Blockers during implement |
+| verification-before-completion | Verify phase |
+| requesting-code-review | Review phase |
+
+The bundled skills are a **maintained fork** of Superpowers (MIT — see `skills/NOTICE.md`), restructured for Forge (single task reviewer, tiered testing, trimmed prose). Do not re-vendor from upstream; edit `skills/forge/` in this repo and run `forgekit install --skills forge --force`.
+
+## Relationship to OpenSpec
+
+| Piece | Source | Policy |
+| ----- | ------ | ------ |
+| Brainstorm, TDD, subagents, verify, review | **skills/forge/skills/** (bundled) | Self-contained; Superpowers plugin not required |
+| Planning sink | OpenSpec or built-in specs engine | Engine per project (`.forge/config.json`); no throwaway or direct modes for new work |
+| OpenSpec skills | Vendor (`openspec-*`, `opsx:*`) | **Do not hand-edit** — run `forge overlay` after upgrade |
+| OpenSpec implement | Forge **`/forge:apply`** | Full subagent TDD + verify + review; survives OpenSpec upgrades |
+| Archive follow-up | Optional ADRs (`forge init --adr`) | When `.forge/config.json` has `adr.enabled`, run **archive-to-adr** (path from `adr.dir`, default `docs/adr`) |
+
+---
+
+## Agent surfaces
+
+Same workflow across Cursor, Claude Code, and Codex CLI. Install the skill once
+per machine with `forgekit install`; wire project commands/hooks with `forge init`.
+
+| Agent | Skill (after install) | Project wiring (`forge init`) | Session hooks |
+| ----- | --------------------- | ----------------------------- | ------------- |
+| **Cursor** | `~/.cursor/skills/forge/` | commands, `forge.mdc`, SessionStart hook | SessionStart → active session reminder |
+| **Claude Code** | `~/.claude/skills/forge/` | commands, `forge.md`, SessionStart + prompt hooks | SessionStart + substantial-work UserPromptSubmit + `/forge` UserPromptSubmit |
+| **Codex CLI** | `~/.codex/skills/forge/` | thin rule | *(none — read skill on substantial work)* |
+
+### Slash commands (Cursor + Claude Code)
+
+| Command | Purpose |
+| ------- | ------- |
+| `/forge` | Start or resume current phase |
+| `/forge:brainstorm` | Brainstorm only |
+| `/forge:plan` | Tracked-change propose (engine from `.forge/config.json`) |
+| `/forge:apply` | Tracked-change implement + verify + review (preferred) |
+| `/forge:build` | Implement phase (`tasks.md` from either engine) |
+| `/forge:status` | Session progress |
+| `/forge:skip` | Explicit skip for this task |
+
+### Codex CLI
+
+No slash commands. On substantial work: read the **`forge`** skill, check
+`forge status`, bootstrap with `forge new <slug>` when needed.
+After brainstorm, proceed directly to the configured engine's propose flow — see
+[plan-routing.md](../references/plan-routing.md).
+User can say “skip forge” or `/forge:skip` to opt out.
+
+---
+
+## What we deliberately dropped from Superpowers
+
+- `docs/superpowers/plans/` and `docs/superpowers/specs/` — use OpenSpec / `specs/changes/` + `.forge` (the built-in specs engine covers the no-OpenSpec case with an OpenSpec-compatible layout)
+- Mandatory git worktree per brainstorm — optional
+- Autonomous commits in subagent prompts — forbidden unless the user asks

package/vendor/skills/forge/references/forge-layout.md

@@ -43,7 +43,7 @@ Optional `cursorChatId` on `session.json` when available — not required.
 
 Bare `forge models` / `forge:prefs` **print** effective values from committed
 defaults and do **not** create the `*.local.json` files. See [pace.md](./pace.md) and
-[docs/forge.md](../../../docs/forge.md) § Checkout-local overrides.
+[docs/forge.md](../docs/forge.md) § Checkout-local overrides.
 
 ## session.json fields
 

package/vendor/skills/forge/references/pace.md

@@ -15,7 +15,7 @@ forge doctor                        # OpenSpec project + CLI
 
 Billing lane (orthogonal): `forge models` prints only;
 `forge models included|metered` writes `.forge/models.local.json`.
-See [docs/forge.md](../../../docs/forge.md) § Checkout-local overrides.
+See [docs/forge.md](../docs/forge.md) § Checkout-local overrides.
 
 ## Announce
 

package/vendor/skills/thorough-code-review/SKILL.md

@@ -231,7 +231,7 @@ When reviewing a project that documents accepted risks:
 
 ## Model selection for subagents
 
-**Choose the model tier per dispatch — never default to the most capable (priciest) model.** Match the tier to the judgment the role actually needs. Map roles to Forge capability tiers (`fast` / `standard` / `capable`) and resolve via `forge resolve-model --tier <…>` so billing stays on the **`included`** (subscription) lane unless the user explicitly asks for metered/API models — see forgekit `docs/forge.md` § Subagent model.
+**Choose the model tier per dispatch — never default to the most capable (priciest) model.** Match the tier to the judgment the role actually needs. Map roles to Forge capability tiers (`fast` / `standard` / `capable`) and resolve via `forge resolve-model --tier <…>` so billing stays on the **`included`** (subscription) lane unless the user explicitly asks for metered/API models — see forge skill [docs/forge.md](../forge/docs/forge.md) § Subagent model.
 
 | Role | Tier | Why |
 | ---- | ---- | --- |

package/vendor/templates/project/claude/commands/forge-apply.md

@@ -7,7 +7,7 @@ tags: [workflow, forge, openspec]
 
 **Forge-owned command.** Use this instead of bare `/opsx:apply` for disciplined implementation of a tracked change (OpenSpec or built-in specs engine — `.forge/config.json` → `plan.engine`).
 
-Read the Forge skill (`~/.claude/skills/forge/SKILL.md`) and forgekit `docs/forge.md`.
+Read the Forge skill (`~/.claude/skills/forge/SKILL.md`) and `~/.claude/skills/forge/docs/forge.md`.
 
 **Input**: Optionally specify a change name (e.g., `/forge:apply add-auth`). If omitted, infer from context or active Forge session.
 

package/vendor/templates/project/claude/commands/forge-status.md

@@ -13,4 +13,4 @@ forge status
 
 Summarize `phase`, `planType`, `openspecChange`, and task progress for the user.
 
-Reference: forgekit `docs/forge.md`
+Reference: `~/.claude/skills/forge/docs/forge.md`

package/vendor/templates/project/claude/commands/forge.md

@@ -7,7 +7,7 @@ tags: [workflow, forge, openspec]
 
 Run the **Forge** workflow for substantial work.
 
-Read and follow the Forge skill (`~/.claude/skills/forge/SKILL.md`) and forgekit `docs/forge.md`.
+Read and follow the Forge skill (`~/.claude/skills/forge/SKILL.md`) and `~/.claude/skills/forge/docs/forge.md`.
 
 1. Triage — substantial work? (skip only if user said `/forge:skip`)
 2. Resume from `.forge/active.json` or `forge new <slug>`

package/vendor/templates/project/claude/rules/forge.md

@@ -1,6 +1,6 @@
 # Forge (thin rule)
 
-Full workflow: forgekit `docs/forge.md` · Skill: user-installed **Forge** (`~/.claude/skills/forge/SKILL.md` after `forge install`).
+Full workflow: `~/.claude/skills/forge/docs/forge.md` · Skill: user-installed **Forge** (`~/.claude/skills/forge/SKILL.md` after `forge install`).
 
 **Default:** triage before implementation. Substantial work → **Forge**
 (brainstorm → OpenSpec → subagent TDD implement → review).

package/vendor/templates/project/codex/rules/forge.md

@@ -1,6 +1,6 @@
 # Forge (thin rule)
 
-Full workflow: forgekit `docs/forge.md` · Skill: user-installed **Forge** (`~/.codex/skills/forge/SKILL.md` after `forge install`).
+Full workflow: `~/.codex/skills/forge/docs/forge.md` · Skill: user-installed **Forge** (`~/.codex/skills/forge/SKILL.md` after `forge install`).
 
 **Default:** triage before implementation. Substantial work → **Forge**
 (brainstorm → OpenSpec → subagent TDD implement → review).

package/vendor/templates/project/cursor/commands/forge-apply.md

@@ -7,7 +7,7 @@ description: Forge — apply a tracked change with subagent TDD, verify, and rev
 
 **Forge-owned command.** Use this instead of bare `/opsx:apply` for disciplined implementation of a tracked change (OpenSpec or built-in specs engine — `.forge/config.json` → `plan.engine`).
 
-Read the Forge skill (`~/.cursor/skills/forge/SKILL.md`) and forgekit `docs/forge.md`.
+Read the Forge skill (`~/.cursor/skills/forge/SKILL.md`) and `~/.cursor/skills/forge/docs/forge.md`.
 
 **Input**: Optionally specify a change name (e.g., `/forge:apply add-auth`). If omitted, infer from context or active Forge session.
 

package/vendor/templates/project/cursor/commands/forge-status.md

@@ -13,4 +13,4 @@ forge status
 
 Summarize `phase`, `planType`, `openspecChange`, and task progress for the user.
 
-Reference: forgekit `docs/forge.md`
+Reference: `~/.cursor/skills/forge/docs/forge.md`

package/vendor/templates/project/cursor/commands/forge.md

@@ -7,7 +7,7 @@ description: Forge — start or resume disciplined development (brainstorm → p
 
 Run the **Forge** workflow for substantial work.
 
-Read and follow the Forge skill (`~/.cursor/skills/forge/SKILL.md`) and forgekit `docs/forge.md`.
+Read and follow the Forge skill (`~/.cursor/skills/forge/SKILL.md`) and `~/.cursor/skills/forge/docs/forge.md`.
 
 1. Triage — substantial work? (skip only if user said `/forge:skip`)
 2. Resume from `.forge/active.json` or `forge new <slug>`

package/vendor/templates/project/cursor/rules/forge.mdc

@@ -5,7 +5,7 @@ alwaysApply: true
 
 # Forge (thin rule)
 
-Full workflow: forgekit `docs/forge.md` · Skill: user-installed **Forge** (`~/.cursor/skills/forge/SKILL.md` after `forge install`).
+Full workflow: `~/.cursor/skills/forge/docs/forge.md` · Skill: user-installed **Forge** (`~/.cursor/skills/forge/SKILL.md` after `forge install`).
 
 **Default:** triage before implementation. Substantial work → **Forge**
 (brainstorm → OpenSpec → subagent TDD implement → review).