@izkac/forgekit 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izkac/forgekit",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Forgekit CLIs — forgekit (install), forge (workflow), review (code review)",
   "type": "module",
   "bin": {

package/src/init.mjs

@@ -100,7 +100,8 @@ Options:
   --no-adr          Disable ADRs for this project
   --adr-dir <path>  ADR directory (default: ${DEFAULT_ADR_DIR} or ~/.forgekit preference)
   --overlay         Also run \`forge overlay\` (OpenSpec vendor patches)
-  --force, -f       Overwrite existing template files
+  --force, -f       Force re-scaffold of ADR/specs docs (managed command,
+                    rule, and hook files always refresh to the latest template)
   --cwd <path>      Project root (default: cwd)
   --help
 
@@ -124,16 +125,22 @@ export function resolveTemplatesRoot() {
 }
 
 /**
+ * Copy a forgekit-managed template file. These are regenerated pointers
+ * (forge-* commands/rules/hooks) with no user-owned content, so re-running
+ * `forge init` refreshes them in place — that's how template fixes propagate.
  * @param {string} src
  * @param {string} dest
- * @param {{ force?: boolean }} opts
+ * @param {{ force?: boolean }} _opts
  */
-function copyFile(src, dest, opts) {
+function copyFile(src, dest, _opts) {
   fs.mkdirSync(path.dirname(dest), { recursive: true });
-  if (fs.existsSync(dest) && !opts.force) {
-    return 'skipped';
+  const next = fs.readFileSync(src);
+  if (fs.existsSync(dest)) {
+    if (fs.readFileSync(dest).equals(next)) return 'unchanged';
+    fs.writeFileSync(dest, next);
+    return 'updated';
   }
-  fs.copyFileSync(src, dest);
+  fs.writeFileSync(dest, next);
   return 'written';
 }
 
@@ -469,17 +476,18 @@ async function promptOpenSpecSetup() {
 
 /**
  * Resolve the planning engine for `forge init`, offering OpenSpec setup when needed.
- * @param {{ cwd: string, openspec: boolean | null }} opts
+ * @param {{ cwd: string, openspec: boolean | null, agents?: string[] }} opts
  * @returns {Promise<string>} 'openspec' | 'specs'
  */
 async function resolveInitPlanEngine(opts) {
   const configured = hasOpenSpecConfig(opts.cwd);
+  const tools = opts.agents;
 
   if (opts.openspec === false) return 'specs';
 
   if (opts.openspec === true) {
     if (!configured && process.stdin.isTTY) {
-      const setup = setupOpenSpec(opts.cwd);
+      const setup = setupOpenSpec(opts.cwd, { tools });
       for (const s of setup.steps) {
         process.stdout.write(`  [${s.ok ? 'ok' : 'FAIL'}] ${s.step}${s.detail ? ` — ${s.detail}` : ''}\n`);
       }
@@ -505,7 +513,7 @@ async function resolveInitPlanEngine(opts) {
   const accepted = await promptOpenSpecSetup();
   if (!accepted) return 'specs';
 
-  const setup = setupOpenSpec(opts.cwd);
+  const setup = setupOpenSpec(opts.cwd, { tools });
   for (const s of setup.steps) {
     process.stdout.write(`  [${s.ok ? 'ok' : 'FAIL'}] ${s.step}${s.detail ? ` — ${s.detail}` : ''}\n`);
   }
@@ -564,6 +572,7 @@ async function main(argv = process.argv.slice(2)) {
   const planEngine = await resolveInitPlanEngine({
     cwd: opts.cwd,
     openspec: opts.openspec,
+    agents: selected,
   });
 
   let adr = opts.adr;

package/src/init.test.mjs

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { parseArgs, initProject, rememberedAgents } from './init.mjs';
+import { parseArgs, initProject, rememberedAgents, resolveTemplatesRoot } from './init.mjs';
 import { installSkillsToAgents } from './install.mjs';
 import { saveUserConfig } from './config.mjs';
 
@@ -35,6 +35,37 @@ test('rememberedAgents unions install config, installed skills, and project wiri
   }
 });
 
+test('re-running init refreshes stale managed rule files in place', () => {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'forgekit-refresh-'));
+  try {
+    initProject(['claude'], { cwd, adr: false, planEngine: null });
+    const rule = path.join(cwd, '.claude', 'rules', 'forge.md');
+    // Simulate an older install with a stale reference.
+    fs.writeFileSync(rule, 'Full workflow: forgekit `docs/forge.md`\n', 'utf8');
+
+    const report = initProject(['claude'], { cwd, adr: false, planEngine: null });
+    const updated = fs.readFileSync(rule, 'utf8');
+    assert.ok(!updated.includes('forgekit `docs/forge.md`'), 'stale ref replaced');
+    assert.ok(updated.includes('~/.claude/skills/forge/docs/forge.md'), 'points to global skill doc');
+    assert.ok(
+      report.files.some((f) => f.file.includes('forge.md') && f.status === 'updated'),
+      'reports the refresh as updated',
+    );
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('thin-rule templates are engine-neutral (no hardcoded OpenSpec-only flow)', () => {
+  const root = resolveTemplatesRoot();
+  for (const rel of ['claude/rules/forge.md', 'cursor/rules/forge.mdc', 'codex/rules/forge.md']) {
+    const body = fs.readFileSync(path.join(root, ...rel.split('/')), 'utf8');
+    assert.ok(!/Forge = OpenSpec/.test(body), `${rel} still says "Forge = OpenSpec"`);
+    assert.ok(body.includes('forge change new'), `${rel} missing built-in specs command`);
+    assert.ok(body.includes('/opsx:propose'), `${rel} missing OpenSpec command`);
+  }
+});
+
 test('initProject wires templated envs and marks the rest skill-only', () => {
   const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'forgekit-init-'));
   try {

package/src/plan-engine.mjs

@@ -204,12 +204,28 @@ export function checkOpenSpecCliQuick(runCommand) {
   return { ok: false, version: null };
 }
 
+/**
+ * Map forgekit environment ids → OpenSpec tool ids (mostly identity).
+ * @type {Record<string, string>}
+ */
+const OPENSPEC_TOOL_ID = { copilot: 'github-copilot' };
+
+/**
+ * @param {string[]} agentIds forgekit environment ids
+ * @returns {string[]} OpenSpec tool ids
+ */
+export function toOpenSpecToolIds(agentIds) {
+  return agentIds.map((id) => OPENSPEC_TOOL_ID[id] ?? id);
+}
+
 /**
  * Install the OpenSpec CLI (if missing) and run `openspec init` in the project.
- * Interactive: inherits stdio so `openspec init` can prompt.
+ * Interactive: inherits stdio so `openspec init` can prompt — unless `tools`
+ * is given, in which case those tools are configured non-interactively
+ * (`openspec init --tools <ids>`), skipping OpenSpec's own tool picker.
  *
  * @param {string} cwd
- * @param {{ runCommand?: Function, interactive?: boolean }} [opts]
+ * @param {{ runCommand?: Function, interactive?: boolean, tools?: string[] }} [opts]
  * @returns {{ ok: boolean, steps: { step: string, ok: boolean, detail?: string }[] }}
  */
 export function setupOpenSpec(cwd, opts = {}) {
@@ -249,10 +265,12 @@ export function setupOpenSpec(cwd, opts = {}) {
     return { ok: true, steps };
   }
 
-  const init = runInherit('openspec', ['init']);
+  const tools = opts.tools?.length ? toOpenSpecToolIds(opts.tools) : null;
+  const initArgs = tools ? ['init', '--tools', tools.join(',')] : ['init'];
+  const init = runInherit('openspec', initArgs);
   const initOk = init.status === 0;
   steps.push({
-    step: 'openspec init',
+    step: `openspec ${initArgs.join(' ')}`,
     ok: initOk,
     detail: initOk ? undefined : String(init.error ?? `exit ${init.status}`),
   });

package/src/plan-engine.test.mjs

@@ -12,6 +12,7 @@ import {
   saveUserPlanEngine,
   scaffoldSpecs,
   setupOpenSpec,
+  toOpenSpecToolIds,
   writeProjectPlanConfig,
 } from './plan-engine.mjs';
 import { loadProjectConfig, loadUserConfig, saveUserConfig } from './adr.mjs';
@@ -148,6 +149,43 @@ test('setupOpenSpec runs install + init via injected runner', () => {
   }
 });
 
+test('toOpenSpecToolIds maps copilot → github-copilot, else identity', () => {
+  assert.deepEqual(
+    toOpenSpecToolIds(['claude', 'cursor', 'codex', 'opencode', 'copilot', 'gemini', 'windsurf']),
+    ['claude', 'cursor', 'codex', 'opencode', 'github-copilot', 'gemini', 'windsurf'],
+  );
+});
+
+test('setupOpenSpec passes selected tools to `openspec init --tools`', () => {
+  const cwd = tmpdir('forgekit-openspec-tools-');
+  try {
+    /** @type {string[]} */
+    const calls = [];
+    const runCommand = (cmd, args) => {
+      const line = [cmd, ...args].join(' ');
+      calls.push(line);
+      if (line === 'openspec --version') return { status: 0, stdout: '1.0.0' };
+      if (line.startsWith('openspec init')) {
+        fs.mkdirSync(path.join(cwd, 'openspec'), { recursive: true });
+        fs.writeFileSync(path.join(cwd, 'openspec', 'config.yaml'), 'x: 1\n', 'utf8');
+        return { status: 0, stdout: '' };
+      }
+      return { status: 1, stdout: '' };
+    };
+    const result = setupOpenSpec(cwd, {
+      runCommand,
+      tools: ['claude', 'cursor', 'codex', 'copilot'],
+    });
+    assert.equal(result.ok, true);
+    assert.ok(
+      calls.includes('openspec init --tools claude,cursor,codex,github-copilot'),
+      `expected --tools call, got: ${calls.join(' | ')}`,
+    );
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
 test('setupOpenSpec reports failure when install fails', () => {
   const cwd = tmpdir('forgekit-openspec-fail-');
   try {

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

@@ -2,7 +2,7 @@
 name: /forge
 description: Forge — start or resume disciplined development (brainstorm → plan → build → review)
 category: Workflow
-tags: [workflow, forge, openspec]
+tags: [workflow, forge, planning]
 ---
 
 Run the **Forge** workflow for substantial work.

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

@@ -1,16 +1,20 @@
-# Forge (thin rule)
-
-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).
-
-**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.
+# Forge (thin rule)
+
+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 → plan → subagent TDD implement → review).
+
+**Planning engine:** this project's engine is recorded in `.forge/config.json` (`plan.engine`). After brainstorm, create the change spec directly — do not ask for a plan mode:
+- OpenSpec → `/opsx:propose`
+- built-in specs → `forge change new <slug>`
+
+Work too small to spec 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 planning-engine skills — Forge orchestrates them. Workflow skills are bundled under the Forge skill's `skills/` folder.

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

@@ -1,10 +1,12 @@
-# Forge (thin rule)
-
-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).
-
-**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`
+# Forge (thin rule)
+
+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 → plan → subagent TDD implement → review).
+
+**Planning engine:** recorded in `.forge/config.json` (`plan.engine`). After brainstorm, create the change directly — OpenSpec → `/opsx:propose`, built-in specs → `forge change new <slug>`. Skip with `/forge:skip` or when work is trivial.
+
+Scratch: `.forge/` · CLI: `forge new|status|prefs|models|phase|doctor`
+
+Do not edit vendor planning-engine skills — Forge orchestrates them.

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

@@ -1,21 +1,25 @@
----
-description: Forge triage and workflow (thin rule)
-alwaysApply: true
----
-
-# Forge (thin rule)
-
-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).
-
-**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.
+---
+description: Forge triage and workflow (thin rule)
+alwaysApply: true
+---
+
+# Forge (thin rule)
+
+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 → plan → subagent TDD implement → review).
+
+**Planning engine:** this project's engine is recorded in `.forge/config.json` (`plan.engine`). After brainstorm, create the change spec directly — do not ask for a plan mode:
+- OpenSpec → `/opsx:propose`
+- built-in specs → `forge change new <slug>`
+
+Work too small to spec 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 planning-engine skills — Forge orchestrates them. Workflow skills are bundled under the Forge skill's `skills/` folder.