@izkac/forgekit 0.1.0

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

@@ -0,0 +1,75 @@
+---
+name: /forge:apply
+id: forge-apply
+category: Workflow
+description: Forge — apply a tracked change with subagent TDD, verify, and review
+---
+
+**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`.
+
+**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 ~/.cursor/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 ~/.cursor/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 ~/.cursor/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](~/.cursor/skills/forge/phases/finish.md).
+
+**Skip Forge for this task only:** `/forge:skip` (runs work without brainstorm/plan/verify chain).

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

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

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

@@ -0,0 +1,17 @@
+---
+name: /forge:build
+id: forge-build
+category: Workflow
+description: Forge — implement phase (subagent-driven + TDD)
+---
+
+Implement phase. Follow ~/.cursor/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/cursor/commands/forge-plan.md

@@ -0,0 +1,15 @@
+---
+name: /forge:plan
+id: forge-plan
+category: Workflow
+description: Forge — plan phase (tracked change propose)
+---
+
+Plan phase. Follow ~/.cursor/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](~/.cursor/skills/forge/phases/plan-openspec.md)
+- `specs` → author `specs/changes/<name>/{proposal,tasks}.md` per [plan-specs.md](~/.cursor/skills/forge/phases/plan-specs.md)
+
+Get user approval on the change artefacts before `/forge:build` or `/forge:apply`.

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

@@ -0,0 +1,14 @@
+---
+name: /forge:skip
+id: forge-skip
+category: Workflow
+description: Explicitly skip Forge for this task
+---
+
+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/cursor/commands/forge-status.md

@@ -0,0 +1,16 @@
+---
+name: /forge:status
+id: forge-status
+category: Workflow
+description: Forge — show active session progress
+---
+
+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/cursor/commands/forge.md

@@ -0,0 +1,16 @@
+---
+name: /forge
+id: forge
+category: Workflow
+description: Forge — start or resume disciplined development (brainstorm → plan → build → review)
+---
+
+Run the **Forge** workflow for substantial work.
+
+Read and follow the Forge skill (`~/.cursor/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/cursor/hooks/forge-session-start.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Cursor sessionStart: remind when a Forge session is active (.forge/active.json).
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+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;
+}
+
+const root = gitRoot();
+if (!root) process.exit(0);
+
+if (!fs.existsSync(path.join(root, '.forge', 'active.json'))) process.exit(0);
+
+const reminder = spawnSync('forge', ['reminder', '--format', 'cursor'], {
+  cwd: root,
+  encoding: 'utf8',
+  shell: process.platform === 'win32',
+  stdio: ['ignore', 'inherit', 'ignore'],
+});
+process.exit(reminder.status === 0 ? 0 : 0);

package/vendor/templates/project/cursor/hooks/forge-session-start.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# Thin wrapper — prefer the Node implementation on Windows-friendly hosts.
+exec node "$(dirname "$0")/forge-session-start.mjs" "$@"

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

@@ -0,0 +1,21 @@
+---
+description: Forge triage and workflow (thin rule)
+alwaysApply: true
+---
+
+# Forge (thin rule)
+
+Full workflow: forgekit `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).
+
+**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.