@izkac/forgekit 0.1.0

package/vendor/templates/adr/decisions.md

@@ -0,0 +1,141 @@
+# Architecture decision records (ADRs)
+
+> How this project captures **architectural** decisions. ADRs live next to OpenSpec
+> archives. Scaffolded by Forgekit (`forge init --adr` / `forgekit install` with ADRs on).
+
+ADR directory for this project: **`{{ADR_DIR}}`** (configured in `.forge/config.json`).
+
+---
+
+## 1. Why ADRs *and* OpenSpec archives?
+
+They overlap in “why we did something,” but they serve different lookups:
+
+| OpenSpec archive (verbose) | ADR (short) |
+| -------------------------- | ----------- |
+| `proposal.md`, `design.md`, `tasks.md`, specs | One file, one sharpened decision |
+| “Replay the implementation story” | “Why is X shaped this way?” |
+
+---
+
+## 2. When to write an ADR
+
+| Write an ADR when the change … | Skip the ADR when … |
+| ------------------------------ | ------------------- |
+| Establishes or moves a boundary | Bug fix / copy / docs-only |
+| Chooses among real alternatives | Refactor that changes no decision |
+| Adds a constraint future code must follow | Chore rename without semantics |
+| Picks a costly-to-swap vendor or protocol | Narrow feature inside a prior ADR |
+| Codifies a convention across the repo | Noise would drown readers |
+
+If you’re listing code edits, that belongs in `design.md`—not an ADR.
+
+---
+
+## 3. Format (`{{ADR_DIR}}/NNNN-short-topic.md`)
+
+```markdown
+# NNNN. <Short, decision-shaped title>
+
+- **Status**: Proposed | Accepted | Superseded by ADR-NNNN (…)
+- **Date**: YYYY-MM-DD
+- **Area**: <product or layer>
+- **Related**: openspec/changes/archive/<change>/, …
+
+## Context
+
+One paragraph: pressure or constraint forcing a decision.
+
+## Decision
+
+One imperative paragraph stating what this project commits to.
+
+## Alternatives considered
+
+- **Option A** — rejected because …
+- **Chosen** — …
+
+## Consequences
+
+### Positive
+### Negative
+### Neutral
+
+## References
+
+- Archive: openspec/changes/archive/<name>/
+```
+
+Keep ADRs terse (roughly tens to low hundreds of lines each).
+
+---
+
+## 4. Numbering
+
+- Sequential `NNNN`; never recycle numbers—supersede with a **new** ADR.
+- Prefer decision-shaped filenames: `0004-outbox-only-on-critical-path.md` not `0004-add-worker.md`.
+
+All ADRs sit under **`{{ADR_DIR}}/`** even when scoped to one area—the decision
+usually crosses layers.
+
+---
+
+## 5. Status index (`{{ADR_DIR}}/README.md`)
+
+Maintain the table of `#`, Title, Status, Date. Leave placeholder rows until real ADRs land.
+
+---
+
+## 6. Cross-link OpenSpec ↔ ADRs
+
+ADR **References** should point at the dated archive folder.
+
+Archived `proposal.md` should gain:
+
+```markdown
+## Decision record
+
+This change is recorded as ADR-NNNN ({{ADR_DIR}}/NNNN-short-topic.md).
+```
+
+Or, for non-architectural archives, the one-line stamp:
+
+```text
+No ADR — non-architectural change
+```
+
+Capability specs may cite ADRs as normative “why.”
+
+---
+
+## 7. ADRs in agent retrieval
+
+Short, focused ADRs embed well. **Do not** add `{{ADR_DIR}}/` to
+`.cursorindexignore` (or equivalent).
+
+---
+
+## 7a. Hooks: archive → ADR
+
+When ADR wiring is enabled, archive hooks remind agents to run **archive-to-adr**
+after `openspec archive` or a move into `openspec/changes/archive/YYYY-MM-DD-…`.
+
+Session-start backstops list archives whose `proposal.md` lacks `ADR-[0-9]` **and**
+lacks the `No ADR — non-architectural change` stamp.
+
+---
+
+## 8. Maintenance habit
+
+- On each meaningful archive: decide ADR vs stamp.
+- Periodically skim the index for stale status.
+- Supersede with new ADRs—don’t delete old ones.
+
+---
+
+## 9. TL;DR
+
+- ADRs **distill** decisions; OpenSpec archives keep the **full** story.
+- Use this file + `{{ADR_DIR}}/README.md` + `{{ADR_DIR}}/NNNN-*.md`.
+- Cross-link archives and ADRs both directions.
+- After archive: run **archive-to-adr** (or stamp “No ADR”).

package/vendor/templates/adr/hooks/check-pending-adrs.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * Pending-ADR backstop: list archived proposals missing ADR link and No-ADR stamp.
+ * Honors .forge/config.json adr.enabled === false.
+ *
+ * Usage: node check-pending-adrs.mjs [repoRoot]
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+function gitRoot() {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+  });
+  if (r.status !== 0) return null;
+  return String(r.stdout || '').trim() || null;
+}
+
+function loadConfig(cwd) {
+  const p = path.join(cwd, '.forge', 'config.json');
+  if (!fs.existsSync(p)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function listProposals(cwd, archiveRoot) {
+  const dir = path.join(cwd, ...archiveRoot.split('/'));
+  if (!fs.existsSync(dir)) return [];
+  /** @type {string[]} */
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    const proposal = path.join(dir, name, 'proposal.md');
+    if (fs.existsSync(proposal)) out.push(proposal);
+  }
+  return out;
+}
+
+const cwd = process.argv[2] || gitRoot();
+if (!cwd) process.exit(0);
+
+const cfg = loadConfig(cwd);
+if (cfg.adr && cfg.adr.enabled === false) process.exit(0);
+
+const archives = [
+  'openspec/changes/archive',
+  `${(cfg.plan && typeof cfg.plan === 'object' && cfg.plan.dir) || 'specs'}/changes/archive`,
+];
+/** @type {string[]} */
+const pending = [];
+for (const root of archives) {
+  for (const proposal of listProposals(cwd, root)) {
+    const body = fs.readFileSync(proposal, 'utf8');
+    if (/ADR-[0-9]/.test(body)) continue;
+    if (body.includes('No ADR — non-architectural change')) continue;
+    pending.push(path.relative(cwd, proposal).replace(/\\/g, '/'));
+  }
+}
+
+if (pending.length === 0) process.exit(0);
+
+const shown = pending.slice(0, 10).join('\n');
+process.stdout.write(
+  `Archived changes whose proposal.md does not reference an ADR yet:\n\n${shown}\n\n` +
+    `If any had architectural impact, run the archive-to-adr skill.\n` +
+    `Otherwise add a one-line stamp to each proposal.md:\n` +
+    `  'No ADR — non-architectural change'\n`,
+);
+process.exit(0);

package/vendor/templates/adr/hooks/check-pending-adrs.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# Thin wrapper around the Node implementation.
+exec node "$(dirname "$0")/check-pending-adrs.mjs" "$@"

package/vendor/templates/adr/hooks/openspec-archive-agent-message.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * Agent reminder after a successful change archive (stdout only).
+ * Usage: node openspec-archive-agent-message.mjs <change-slug>
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const changeName = process.argv[2];
+if (!changeName) {
+  process.stderr.write('Usage: openspec-archive-agent-message.mjs <change-slug>\n');
+  process.exit(1);
+}
+
+let adrDir = 'docs/adr';
+let decisionsDoc = 'docs/decisions.md';
+let archiveRoot = 'openspec/changes/archive';
+let adrEnabled = true;
+
+const cfgPath = path.join(process.cwd(), '.forge', 'config.json');
+if (fs.existsSync(cfgPath)) {
+  try {
+    const c = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    if (c.plan?.engine === 'specs') {
+      archiveRoot = `${c.plan.dir || 'specs'}/changes/archive`;
+    }
+    if (c.adr?.enabled === false) adrEnabled = false;
+    if (c.adr?.dir) adrDir = c.adr.dir;
+    if (c.adr?.decisionsDoc) decisionsDoc = c.adr.decisionsDoc;
+  } catch {
+    // keep defaults
+  }
+}
+
+if (!adrEnabled) {
+  process.stdout.write(
+    `Change '${changeName}' was archived. ADRs are disabled for this project\n` +
+      `(\`.forge/config.json\` → adr.enabled: false). No archive-to-adr follow-up.\n\n` +
+      `Suggested commit (display only — do NOT commit unless the user asks):\n\n` +
+      `openspec: archive ${changeName}\n`,
+  );
+  process.exit(0);
+}
+
+process.stdout.write(
+  `Change '${changeName}' was just archived.\n\n` +
+    `1. archive-to-adr: locate ${archiveRoot}/YYYY-MM-DD-${changeName}/, open proposal.md, and evaluate an ADR (${decisionsDoc}). If yes: ${adrDir}/NNNN-<topic>.md, update ${adrDir}/README.md, add a ## Decision record to proposal.md. If no: add one line to proposal.md: No ADR — non-architectural change.\n\n` +
+    `2. Suggested commit (display only — do NOT run git commit / push / gh pr create unless the user explicitly asks):\n\n` +
+    `openspec: archive ${changeName}\n`,
+);
+process.exit(0);

package/vendor/templates/adr/hooks/openspec-archive-agent-message.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# Thin wrapper around the Node implementation.
+exec node "$(dirname "$0")/openspec-archive-agent-message.mjs" "$@"

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

@@ -0,0 +1,75 @@
+---
+name: /forge:apply
+description: Forge — apply a tracked change with subagent TDD, verify, and review
+category: Workflow
+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`.
+
+**Input**: Optionally specify a change name (e.g., `/forge:apply add-auth`). If omitted, infer from context or active Forge session.
+
+## 0. Forge session
+
+1. Announce: "Using Forge apply."
+2. Resume `.forge/active.json` or bootstrap: `forge new <slug>`
+3. Set phase (use the project's engine as plan-type):
+   ```bash
+   forge phase implement --plan-type openspec|specs --openspec "<change>"
+   ```
+
+## 1–5. Load the change
+
+**OpenSpec engine** — vendor CLI, follow `openspec-apply-change` (same as `/opsx:apply` steps 1–5):
+
+1. **Select the change** — announce "Using change: \<name\>"
+2. `openspec status --change "<name>" --json`
+3. `openspec instructions apply --change "<name>" --json`
+4. Read all `contextFiles` from CLI output
+5. Show progress (N/M tasks, schema, remaining tasks)
+
+Handle blocked / all_done states per vendor skill before implementing.
+
+**Specs engine** — no CLI:
+
+1. **Select the change** under `specs/changes/<name>/` — announce "Using change: \<name\>"
+2. Read `proposal.md`, `design.md` (if present), `tasks.md`
+3. Show progress (N/M checkboxes, remaining tasks)
+
+## 6. Implement (Forge — REQUIRED)
+
+Follow ~/.claude/skills/forge/phases/implement.md`:
+
+- **Do not** implement all tasks inline in coordinator context
+- Per pending task: brief → **implementer** subagent (TDD first) → **spec reviewer** → **quality reviewer** → mark `- [x]` in `tasks.md`
+- Bundled skills: `skills/subagent-driven-development` + `skills/test-driven-development`
+
+Pause on unclear tasks, design issues, errors, or user interrupt.
+
+## 7. Verify (Forge — REQUIRED when all tasks done)
+
+Follow ~/.claude/skills/forge/phases/verify.md`:
+
+```bash
+forge phase verify
+```
+
+Run affected workspace tests — **audit per-task `test-evidence.md`**; do not re-run the same commands if subagents already recorded passing runs (see verify phase).
+
+## 8. Review (Forge — REQUIRED)
+
+Follow ~/.claude/skills/forge/phases/review.md`:
+
+```bash
+forge phase review
+```
+
+Final reviewer; save to `.forge/sessions/<id>/reviews/final-review.md`.
+
+## 9. Finish
+
+When verify + review pass: suggest archive — `/opsx:archive` (OpenSpec) or the dated move into `specs/changes/archive/` (specs) — per [finish phase](~/.claude/skills/forge/phases/finish.md).
+
+**Skip Forge for this task only:** `/forge:skip` (runs work without brainstorm/plan/verify chain).

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

@@ -0,0 +1,7 @@
+---
+description: Forge — brainstorm phase only
+---
+
+Brainstorm phase only. Follow ~/.claude/skills/forge/phases/brainstorm.md`.
+
+Invoke bundled **skills/brainstorming**. Save notes to `.forge/sessions/<id>/brainstorm/`. Terminal state: **OpenSpec propose** (`/opsx:propose`) — do not implement until artefacts are approved.

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

@@ -0,0 +1,17 @@
+---
+name: /forge:build
+description: Forge — implement phase (subagent-driven + TDD)
+category: Workflow
+tags: [workflow, forge, openspec]
+---
+
+Implement phase. Follow ~/.claude/skills/forge/phases/implement.md`.
+
+**REQUIRED:** forge `skills/subagent-driven-development` + `skills/test-driven-development` per task.
+
+- OpenSpec plan → **`/forge:apply`** (preferred) or `openspec-apply-change` / `/opsx:apply` wrapped in subagent loop
+- Specs plan (`planType: specs`) → **`/forge:apply`** — tasks from `specs/changes/<name>/tasks.md`, no vendor CLI steps
+- Throwaway plan → tasks from `.forge/.../plan.md`
+- Direct → brief from `.forge/.../brainstorm/notes.md` + `decisions.md`
+
+Then verify and review phases.

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

@@ -0,0 +1,12 @@
+---
+description: Forge — plan phase (tracked change propose)
+---
+
+Plan phase. Follow ~/.claude/skills/forge/references/plan-routing.md`.
+
+**Engine from `.forge/config.json` → `plan.engine`** — do not ask for a plan mode:
+
+- `openspec` → run `/opsx:propose <prefix>-<slug>` or the `openspec-propose` skill per [plan-openspec.md](~/.claude/skills/forge/phases/plan-openspec.md)
+- `specs` → author `specs/changes/<name>/{proposal,tasks}.md` per [plan-specs.md](~/.claude/skills/forge/phases/plan-specs.md)
+
+Get user approval on the change artefacts before `/forge:build` or `/forge:apply`.

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

@@ -0,0 +1,14 @@
+---
+name: /forge:skip
+description: Explicitly skip Forge for this task
+category: Workflow
+tags: [workflow, forge]
+---
+
+User opted out of Forge for **this task only**.
+
+1. If active session exists: `forge phase skipped`
+2. Do **not** brainstorm or plan
+3. Execute the request under normal project rules
+
+Triage defaults to Forge; `/forge:skip` is the explicit override.

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

@@ -0,0 +1,16 @@
+---
+name: /forge:status
+description: Forge — show active session progress
+category: Workflow
+tags: [workflow, forge]
+---
+
+Show Forge session status:
+
+```bash
+forge status
+```
+
+Summarize `phase`, `planType`, `openspecChange`, and task progress for the user.
+
+Reference: forgekit `docs/forge.md`

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

@@ -0,0 +1,16 @@
+---
+name: /forge
+description: Forge — start or resume disciplined development (brainstorm → plan → build → review)
+category: Workflow
+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`.
+
+1. Triage — substantial work? (skip only if user said `/forge:skip`)
+2. Resume from `.forge/active.json` or `forge new <slug>`
+3. Continue from current `phase` in `session.json`
+
+Subcommands: `/forge:brainstorm`, `/forge:plan`, `/forge:apply`, `/forge:build`, `/forge:status`, `/forge:skip`

package/vendor/templates/project/claude/hooks/forge-prompt-hook.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit: when the user invokes /forge or /forge:*, inject session context.
+ * Requires `forge` on PATH.
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const REPO_ROOT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const ACTIVE_FILE = path.join(REPO_ROOT, '.forge', 'active.json');
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    if (process.stdin.isTTY) return resolve('');
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(data));
+    setTimeout(() => resolve(data), 1500);
+  });
+}
+
+function extractPrompt(raw) {
+  if (!raw) return '';
+  try {
+    const j = JSON.parse(raw);
+    return (
+      (typeof j?.prompt === 'string' && j.prompt) ||
+      (typeof j?.user_prompt === 'string' && j.user_prompt) ||
+      (typeof j?.message === 'string' && j.message) ||
+      ''
+    );
+  } catch {
+    return raw;
+  }
+}
+
+function isForgeInvocation(prompt) {
+  return /^\s*\/forge(?::|\s|$)/i.test(prompt);
+}
+
+function emit(message) {
+  process.stdout.write(`<system-reminder>\n${message}\n</system-reminder>\n`);
+}
+
+const raw = await readStdin();
+const prompt = extractPrompt(raw);
+
+if (!isForgeInvocation(prompt)) {
+  process.exit(0);
+}
+
+if (!fs.existsSync(ACTIVE_FILE)) {
+  emit(
+    '[forge] No active session. Bootstrap with `forge new <slug>` then follow the Forge skill.',
+  );
+  process.exit(0);
+}
+
+const r = spawnSync('forge', ['reminder', '--format', 'plain', '--prompt', prompt], {
+  encoding: 'utf8',
+  cwd: REPO_ROOT,
+  shell: true,
+});
+
+if (r.status === 0 && r.stdout.trim()) {
+  emit(r.stdout.trim());
+}

package/vendor/templates/project/claude/hooks/forge-session-start.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Claude Code SessionStart: inject active Forge session when present.
+ * Requires `forge` on PATH (npm link @izkac/forgekit or global install).
+ */
+
+import { spawnSync } from 'node:child_process';
+
+const REPO_ROOT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+const r = spawnSync('forge', ['reminder', '--format', 'claude-session-start'], {
+  encoding: 'utf8',
+  cwd: REPO_ROOT,
+  shell: true,
+});
+
+if (r.status === 0 && r.stdout.trim()) {
+  process.stdout.write(r.stdout);
+}

package/vendor/templates/project/claude/hooks/forge-triage-hook.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit: auto-triage substantial work into Forge (Claude Code).
+ * Requires `forge` on PATH.
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const REPO_ROOT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const ACTIVE_FILE = path.join(REPO_ROOT, '.forge', 'active.json');
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    if (process.stdin.isTTY) return resolve('');
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(data));
+    setTimeout(() => resolve(data), 1500);
+  });
+}
+
+function extractPrompt(raw) {
+  if (!raw) return '';
+  try {
+    const j = JSON.parse(raw);
+    return (
+      (typeof j?.prompt === 'string' && j.prompt) ||
+      (typeof j?.user_prompt === 'string' && j.user_prompt) ||
+      (typeof j?.message === 'string' && j.message) ||
+      ''
+    );
+  } catch {
+    return raw;
+  }
+}
+
+function emit(message) {
+  process.stdout.write(`<system-reminder>\n${message}\n</system-reminder>\n`);
+}
+
+function runForge(args) {
+  return spawnSync('forge', args, {
+    encoding: 'utf8',
+    cwd: REPO_ROOT,
+    shell: true,
+  });
+}
+
+const raw = await readStdin();
+const prompt = extractPrompt(raw);
+if (!prompt) process.exit(0);
+
+const check = runForge(['triage', '--check', prompt]);
+if (check.status !== 0) process.exit(0);
+
+const hasSession = fs.existsSync(ACTIVE_FILE);
+const args = ['triage', '--message'];
+if (hasSession) args.push('--has-session');
+args.push(prompt);
+
+const msg = runForge(args);
+if (msg.status === 0 && msg.stdout.trim()) {
+  if (hasSession) {
+    const rem = runForge(['reminder', '--format', 'plain']);
+    if (rem.status === 0 && rem.stdout.trim()) {
+      emit(`${msg.stdout.trim()}\n\nActive session:\n${rem.stdout.trim()}`);
+      process.exit(0);
+    }
+  }
+  emit(msg.stdout.trim());
+}

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

@@ -0,0 +1,16 @@
+# Forge (thin rule)
+
+Full workflow: forgekit `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).
+
+**Forge = OpenSpec:** after brainstorm, proceed directly to `/opsx:propose` — do not ask for a plan mode. Work too small for OpenSpec should skip Forge (`/forge:skip` or direct execution).
+
+**Skip Forge** only when work is trivial OR user sends **`/forge:skip`**.
+
+Scratch sessions: `.forge/sessions/` (14-day retention). Active pointer: `.forge/active.json`.
+
+CLI: `forge new`, `forge status`, `forge prefs`, `forge models`, `forge phase`, `forge doctor`.
+
+Do not edit vendor OpenSpec skills — Forge orchestrates them. Workflow skills are bundled under the Forge skill’s `skills/` folder.

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

@@ -0,0 +1,10 @@
+# Forge (thin rule)
+
+Full workflow: forgekit `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).
+
+**Forge = OpenSpec:** after brainstorm, proceed directly to OpenSpec propose. Skip with `/forge:skip` or when work is trivial.
+
+Scratch: `.forge/` · CLI: `forge new|status|prefs|models|phase|doctor`