ai-runtime-kit 0.5.0

package/runtime/workflows/feature-development.md

@@ -0,0 +1,238 @@
+# Feature Development Workflow
+
+## Purpose
+
+Use this workflow to ship one small feature safely with AI assistance.
+
+> If the change is corrective (a bug fix), use
+> `.ai/runtime/workflows/bug-fix.md` instead. That workflow is a
+> strict superset of this one with three additional required spec
+> sections (Root Cause, Reproduction, Regression Test) and a
+> regression-test-first executor order.
+
+## Roles
+
+- ChatGPT: define, design, review, summarize
+- Claude Code: implement, refactor, verify
+
+## Spec Lifecycle
+
+Specs should use one of:
+
+```txt
+DRAFT
+APPROVED
+REJECTED
+SUPERSEDED
+```
+
+Rules:
+
+- New specs start as DRAFT.
+- Approved specs may generate plans/tasks.
+- Rejected specs must not generate executable tasks.
+- Superseded specs should reference the replacement spec.
+
+## Workflow
+
+### 0. Define PRD (optional — product-driven features)
+
+For features driven by product intent (new capabilities, UX
+changes, user-visible behavior shifts), draft a PRD first under:
+
+```txt
+.ai/project/prds/YYYY-MM-DD-<slug>/prd.md
+```
+
+Use `.ai/runtime/prds/_template.md` as the starting point. The
+PRD answers **what & why** — Problem, Target Users, Success
+Metrics, User Stories, Out of Scope, Open Questions,
+Stakeholders. Engineering details (architecture, data flow, code
+contracts) belong in the downstream spec, not the PRD.
+
+Skip this step when:
+
+- the change is corrective (use `bug-fix.md` instead — bug fixes
+  don't need PRDs),
+- the change is engineering-only (refactor, dependency bump, test
+  coverage, governance maintenance),
+- the scope is small enough that the spec alone communicates
+  intent.
+
+PRD lifecycle mirrors specs: `DRAFT → APPROVED → REJECTED →
+SUPERSEDED`. An APPROVED PRD authorizes spec drafting. The
+downstream spec MUST reference its PRD by path in §1 Goal so
+review can verify the spec satisfies the PRD.
+
+### 1. Define Spec
+
+Create a feature spec under:
+
+```txt
+.ai/project/specs/YYYY-MM-DD-feature-name/spec.md
+```
+
+If the spec is downstream of a PRD (Step 0), §1 Goal must cite
+the PRD path so reviewers can check that the spec covers the
+PRD's requirements without quietly expanding scope.
+
+Spec must include:
+
+- Goal
+- Scope
+- Requirements
+- Acceptance Criteria
+- Test Checklist
+- Verification Commands
+- Rollback Plan
+
+### 2. Execute with Claude Code
+
+Claude Code must read:
+
+- `.ai/runtime/agents/executor.md`
+- `.ai/project/memory/core/tech-stack.md`
+- `.ai/runtime/workflows/feature-development.md`
+- `.ai/runtime/memory/engineering/principles.md`
+- related `.ai/project/contracts/**` files if the feature touches public APIs
+- relevant skill files from **both** `.ai/runtime/skills/**`
+  (kit-shipped, framework-generic) **and** `.ai/project/skills/**`
+  (project-shipped, project-specific). Project-side files take
+  precedence on path collision.
+- feature spec
+
+If the spec itself authors or modifies a kit-shipped skill under
+`.ai/runtime/skills/**`, follow `.ai/runtime/skills/README.md` and
+treat the spec as runtime-scoped governance per
+`.ai/runtime/SAFETY.md` § Runtime Tree Protection. Authoring a
+project-side skill at `.ai/project/skills/**` is not governance-
+protected (project owns its tree); it still follows the structural
+convention from `.ai/runtime/skills/README.md`.
+
+If the spec authors or modifies a kit-shipped rule under
+`.ai/runtime/rules/**`, follow `.ai/runtime/rules/README.md` and
+treat the spec as runtime-scoped governance per `.ai/runtime/SAFETY.md`
+§ Runtime Tree Protection. Authoring a project-side rule at
+`.ai/project/rules/**` is not governance-protected.
+
+When the executor touches files in a rule's scope (e.g. a `.ts`
+file when a TypeScript rule exists), it must load the relevant
+rules from **both** `.ai/runtime/rules/<language>/*.md` (kit) and
+`.ai/project/rules/<language>/*.md` (project) before writing code.
+Project-side rules take precedence on path collision.
+
+If the spec authors or modifies a kit-shipped hook under
+`.ai/runtime/hooks/**`, follow `.ai/runtime/hooks/README.md` and
+treat the spec as runtime-scoped governance per `.ai/runtime/SAFETY.md`
+§ Runtime Tree Protection. Authoring a project-side hook at
+`.ai/project/hooks/**` is not governance-protected.
+
+At each agent-pipeline transition (Architect → Planner → Executor
+→ Verifier → Reviewer), the active agent must load hooks attached
+to its phase from **both** `.ai/runtime/hooks/<phase>-<agent>/*/HOOK.md`
+(kit) and `.ai/project/hooks/<phase>-<agent>/*/HOOK.md` (project)
+whose `appliesWhen` matches the current spec, diff, or runtime
+mode. Project-side hooks take precedence on path collision. GATE
+and MUTATION hooks block the transition until their action
+completes; ADVISORY hooks log into the review file.
+
+Claude Code must return:
+
+- Changed files
+- Implementation summary
+- Test result
+- Build result
+- Unresolved risks
+
+### 3. Verify
+
+Verification should include:
+
+- `.ai/runtime/agents/verifier.md`
+- related `.ai/project/contracts/**`
+- existing tests
+- build integrity
+- backward compatibility
+
+Verification results should be saved under `.ai/project/verifications/` when:
+
+- verification fails
+- a contract violation is detected
+- a breaking change is proposed
+- the feature is a complex refactor
+- explicit audit trail is required
+
+For simple successful features, verification results may be recorded in the review file instead.
+
+At minimum, run:
+
+```bash
+npm run verify
+```
+
+Local verification must use `npm run verify` as the canonical verification command.
+If the project has lint/typecheck commands, run them too.
+
+### 4. Review
+
+Create review file under:
+
+```txt
+.ai/project/reviews/YYYY-MM-DD-feature-name-review.md
+```
+
+Review must include:
+
+- Summary
+- Blocking issues
+- Non-blocking issues
+- Suggested fixes
+- Verdict
+
+### 5. Fix
+
+If review finds issues, Claude Code must:
+
+- Read the review
+- Fix blocking issues
+- Re-run verification
+- Report final result
+
+### 6. Commit
+
+Use conventional commits:
+
+```txt
+feat: ...
+fix: ...
+test: ...
+refactor: ...
+docs: ...
+```
+
+## Definition of Done
+
+A feature is done only when:
+
+- Spec exists
+- Code is implemented
+- Tests pass
+- Build passes
+- Review exists
+- Changes are committed
+
+## Task Status Lifecycle
+
+Tasks should follow:
+
+```txt
+TODO → IN_PROGRESS → IN_REVIEW → DONE
+```
+
+If blocked:
+
+```txt
+TODO or IN_PROGRESS → BLOCKED
+```
+
+Task status must be updated when execution state changes.

package/src/diff.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { listFilesUnder, KIT_RUNTIME_DIR } = require('./snapshot');
+
+function computeRuntimeDiff(projectRuntimeDir) {
+  const kitFiles = new Set(listFilesUnder(KIT_RUNTIME_DIR));
+  const projectFiles = new Set(listFilesUnder(projectRuntimeDir).filter((f) => f !== 'KIT_VERSION'));
+
+  const added = [];
+  const removed = [];
+  const replaced = [];
+  const unchanged = [];
+
+  for (const f of kitFiles) {
+    if (!projectFiles.has(f)) {
+      added.push(f);
+    } else {
+      const a = fs.readFileSync(path.join(KIT_RUNTIME_DIR, f));
+      const b = fs.readFileSync(path.join(projectRuntimeDir, f));
+      if (a.equals(b)) unchanged.push(f);
+      else replaced.push(f);
+    }
+  }
+  for (const f of projectFiles) {
+    if (!kitFiles.has(f)) removed.push(f);
+  }
+
+  added.sort();
+  removed.sort();
+  replaced.sort();
+  unchanged.sort();
+
+  return { added, removed, replaced, unchanged };
+}
+
+function printDiffSummary(diff) {
+  const { added, removed, replaced, unchanged } = diff;
+  console.log('Upgrade preview:');
+  console.log(`  ${added.length} file(s) to ADD`);
+  console.log(`  ${replaced.length} file(s) to REPLACE`);
+  console.log(`  ${removed.length} file(s) to DELETE`);
+  console.log(`  ${unchanged.length} file(s) UNCHANGED`);
+  console.log('');
+  if (added.length) {
+    console.log('ADD:');
+    for (const f of added) console.log(`  + ${f}`);
+    console.log('');
+  }
+  if (replaced.length) {
+    console.log('REPLACE:');
+    for (const f of replaced) console.log(`  ~ ${f}`);
+    console.log('');
+  }
+  if (removed.length) {
+    console.log('DELETE:');
+    for (const f of removed) console.log(`  - ${f}`);
+    console.log('');
+  }
+}
+
+function printPerFileDiff(diff, projectRuntimeDir, out = process.stdout) {
+  const writeLine = (line) => out.write(`${line}\n`);
+  for (const f of diff.replaced) {
+    const a = path.join(projectRuntimeDir, f);
+    const b = path.join(KIT_RUNTIME_DIR, f);
+    writeLine(`--- a/.ai/runtime/${f}`);
+    writeLine(`+++ b/.ai/runtime/${f} (kit)`);
+    const r = spawnSync('diff', ['-u', a, b], { encoding: 'utf8' });
+    if (r.stdout) {
+      const body = r.stdout.split('\n').slice(2).join('\n');
+      out.write(body);
+    }
+    writeLine('');
+  }
+}
+
+module.exports = { computeRuntimeDiff, printDiffSummary, printPerFileDiff };

package/src/git.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+
+function gitStatusPorcelain(targetPath, cwd) {
+  const r = spawnSync('git', ['status', '--porcelain', '--', targetPath], {
+    cwd,
+    encoding: 'utf8',
+  });
+  if (r.status === 128) {
+    return { ok: false, error: 'not a git repository' };
+  }
+  if (r.status !== 0) {
+    return { ok: false, error: r.stderr.trim() || `git exited ${r.status}` };
+  }
+  const lines = r.stdout.split('\n').filter(Boolean);
+  return { ok: true, lines };
+}
+
+function isGitRepo(cwd) {
+  const r = spawnSync('git', ['rev-parse', '--git-dir'], { cwd, encoding: 'utf8' });
+  return r.status === 0;
+}
+
+// `git check-ignore` returns 0 if path is ignored, 1 if not, 128 if not a
+// git repo. Null on any non-deterministic result so callers stay silent
+// rather than misreporting.
+function isPathGitignored(targetPath, cwd) {
+  const r = spawnSync('git', ['check-ignore', '-q', '--', targetPath], {
+    cwd,
+    encoding: 'utf8',
+  });
+  if (r.status === 0) return true;
+  if (r.status === 1) return false;
+  return null;
+}
+
+module.exports = { gitStatusPorcelain, isGitRepo, isPathGitignored };

package/src/init.js

@@ -0,0 +1,166 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseArgs } = require('node:util');
+
+const { copyKitRuntimeTo, dirHasFiles, removeDir } = require('./snapshot');
+const { writeProjectKitVersion, KIT_VERSION } = require('./version');
+const { projectStateMd, projectTaskStatusMd, agentEntryClaudeMd } = require('./templates');
+const { isPathGitignored } = require('./git');
+
+const PROJECT_SKELETON_DIRS = [
+  'prds',
+  'specs',
+  'plans',
+  'tasks',
+  'reviews',
+  'verifications',
+  'adr',
+  'contracts',
+  'memory',
+  'rules',
+  'skills',
+  'hooks',
+];
+
+function run(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: {
+        cwd: { type: 'string' },
+        migrate: { type: 'boolean', default: false },
+        'no-agent-entry': { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      strict: true,
+      allowPositionals: false,
+    });
+  } catch (e) {
+    console.error(`init: ${e.message}`);
+    console.error('Try: ai-runtime-kit init --help');
+    process.exit(1);
+  }
+
+  if (parsed.values.help) {
+    printHelp();
+    return;
+  }
+
+  const cwd = path.resolve(parsed.values.cwd ?? process.cwd());
+  const aiDir = path.join(cwd, '.ai');
+  const runtimeDir = path.join(aiDir, 'runtime');
+  const projectDir = path.join(aiDir, 'project');
+  const claudeMdPath = path.join(cwd, 'CLAUDE.md');
+
+  // Detect "real" presence — empty-only directory tree counts as
+  // absent so `init --migrate` post `git rm` doesn't have to be
+  // chased with a manual `rm -rf` (kit v0.3.0 fix).
+  const runtimeHasFiles = dirHasFiles(runtimeDir);
+  const projectHasFiles = dirHasFiles(projectDir);
+  const runtimeEmptyButPresent = fs.existsSync(runtimeDir) && !runtimeHasFiles;
+  const projectEmptyButPresent = fs.existsSync(projectDir) && !projectHasFiles;
+  const claudeMdExists = fs.existsSync(claudeMdPath);
+  const writeAgentEntry = !parsed.values['no-agent-entry'];
+
+  if (!parsed.values.migrate) {
+    if (runtimeHasFiles || projectHasFiles) {
+      console.error('init: .ai/runtime/ or .ai/project/ already exists.');
+      console.error('If you intended to bootstrap an existing-.ai/project/ repo, pass --migrate.');
+      console.error('To upgrade an installed runtime, use: ai-runtime-kit upgrade');
+      process.exit(1);
+    }
+    if (writeAgentEntry && claudeMdExists) {
+      console.error('init: CLAUDE.md already exists at the project root.');
+      console.error('Pass --no-agent-entry to skip CLAUDE.md generation, or --migrate to keep the existing file.');
+      process.exit(1);
+    }
+  } else {
+    if (runtimeHasFiles) {
+      console.error('init --migrate: .ai/runtime/ already has content; refusing to overwrite.');
+      console.error('Move it aside or use: ai-runtime-kit upgrade');
+      process.exit(1);
+    }
+    // In --migrate mode .ai/project/ MAY already exist with content;
+    // we only lay down .ai/runtime/ and skip any pre-existing
+    // project skeleton files.
+  }
+
+  // Empty parent dirs (e.g. left by `git rm -r .ai/runtime/`) are
+  // removed here so copyKitRuntimeTo can re-create the tree cleanly.
+  if (runtimeEmptyButPresent) {
+    removeDir(runtimeDir);
+  }
+  // For --migrate (or fresh init), only remove an empty .ai/project/
+  // if it has no content — otherwise it stays untouched.
+  if (!parsed.values.migrate && projectEmptyButPresent) {
+    removeDir(projectDir);
+  }
+
+  fs.mkdirSync(aiDir, { recursive: true });
+  copyKitRuntimeTo(runtimeDir);
+  writeProjectKitVersion(cwd, KIT_VERSION);
+
+  if (!projectHasFiles) {
+    fs.mkdirSync(projectDir, { recursive: true });
+    for (const d of PROJECT_SKELETON_DIRS) {
+      fs.mkdirSync(path.join(projectDir, d), { recursive: true });
+    }
+    fs.writeFileSync(path.join(projectDir, 'STATE.md'), projectStateMd());
+    fs.writeFileSync(path.join(projectDir, 'tasks', 'TASK_STATUS.md'), projectTaskStatusMd());
+  }
+
+  let agentEntryWritten = false;
+  if (writeAgentEntry && !claudeMdExists) {
+    fs.writeFileSync(claudeMdPath, agentEntryClaudeMd());
+    agentEntryWritten = true;
+  }
+
+  console.log(`ai-runtime-kit ${KIT_VERSION}: initialized .ai/ at ${cwd}`);
+  console.log('  - .ai/runtime/  (kit-managed; do not hand-edit)');
+  if (!projectHasFiles) {
+    console.log('  - .ai/project/  (project-owned; STATE.md and tasks/TASK_STATUS.md scaffolded)');
+  } else {
+    console.log('  - .ai/project/  (pre-existing; not modified)');
+  }
+  console.log(`  - .ai/runtime/KIT_VERSION = ${KIT_VERSION}`);
+  if (agentEntryWritten) {
+    console.log('  - CLAUDE.md     (agent entry; project-owned, never touched by upgrade)');
+  } else if (claudeMdExists) {
+    console.log('  - CLAUDE.md     (pre-existing; not modified)');
+  } else {
+    console.log('  - CLAUDE.md     (skipped via --no-agent-entry)');
+  }
+
+  if (isPathGitignored('.ai/runtime', cwd) === true) {
+    console.log('');
+    console.log('Note: .ai/runtime/ is gitignored. Clones of this repo will not');
+    console.log('      contain the runtime tree; they will need to run');
+    console.log('      `ai-runtime-kit init` or `upgrade` to regenerate it.');
+  }
+}
+
+function printHelp() {
+  console.log(`ai-runtime-kit init [options]
+
+Lay down .ai/runtime/, a .ai/project/ skeleton (if absent), and a
+project-root CLAUDE.md (if absent) in the current directory.
+
+Options:
+  --cwd <dir>         Target directory (default: process.cwd())
+  --migrate           Allow pre-existing .ai/project/ and/or
+                      CLAUDE.md (for bootstrapping an existing repo
+                      into kit-consumer mode). Still refuses if
+                      .ai/runtime/ already exists.
+  --no-agent-entry    Skip CLAUDE.md generation entirely.
+  -h, --help          Show this help.
+
+Refuses (without --migrate) if .ai/runtime/, .ai/project/, or
+CLAUDE.md already exists. To upgrade an installed runtime, use the
+upgrade command instead. CLAUDE.md is project-owned and never
+modified by upgrade.`);
+}
+
+module.exports = { run, printHelp };

package/src/prompt.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const readline = require('node:readline/promises');
+
+async function confirm(question, { defaultYes = false } = {}) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const suffix = defaultYes ? '(Y/n)' : '(y/N)';
+    const answer = (await rl.question(`${question} ${suffix} `)).trim().toLowerCase();
+    if (!answer) return defaultYes;
+    return answer === 'y' || answer === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+module.exports = { confirm };

package/src/snapshot.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const KIT_RUNTIME_DIR = path.resolve(__dirname, '..', 'runtime');
+
+function copyKitRuntimeTo(targetRuntimeDir) {
+  if (fs.existsSync(targetRuntimeDir)) {
+    throw new Error(`copyKitRuntimeTo: target already exists: ${targetRuntimeDir}`);
+  }
+  fs.cpSync(KIT_RUNTIME_DIR, targetRuntimeDir, { recursive: true });
+}
+
+function listKitRuntimeFiles() {
+  const out = [];
+  walk(KIT_RUNTIME_DIR, '');
+  function walk(absDir, relDir) {
+    const entries = fs.readdirSync(absDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(path.join(absDir, entry.name), rel);
+      } else {
+        out.push(rel);
+      }
+    }
+  }
+  return out.sort();
+}
+
+function listFilesUnder(absDir) {
+  if (!fs.existsSync(absDir)) return [];
+  const out = [];
+  walk(absDir, '');
+  function walk(dir, relDir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(path.join(dir, entry.name), rel);
+      } else {
+        out.push(rel);
+      }
+    }
+  }
+  return out.sort();
+}
+
+function removeDir(absDir) {
+  if (fs.existsSync(absDir)) {
+    fs.rmSync(absDir, { recursive: true, force: true });
+  }
+}
+
+// True iff absDir exists AND contains at least one regular file
+// anywhere in its subtree. Empty parent directories (e.g. left over
+// from `git rm -r` which doesn't remove the parent dirs) return
+// false — they're not real content.
+function dirHasFiles(absDir) {
+  if (!fs.existsSync(absDir)) return false;
+  const stack = [absDir];
+  while (stack.length) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        stack.push(path.join(current, entry.name));
+      } else {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+module.exports = {
+  KIT_RUNTIME_DIR,
+  copyKitRuntimeTo,
+  listKitRuntimeFiles,
+  listFilesUnder,
+  removeDir,
+  dirHasFiles,
+};