@c0x12c/ai-toolkit 1.15.0

package/lib/resolver.test.js

@@ -0,0 +1,298 @@
+// Spartan AI Toolkit — Resolver Tests
+// Run: node --test toolkit/lib/resolver.test.js
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolve, detectCycles, resolveAliases, toPacks, validatePack, loadExternalPacks } from './resolver.js';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Helper: create a minimal manifest map
+function makeManifests(defs) {
+  const m = new Map();
+  for (const [name, opts] of Object.entries(defs)) {
+    m.set(name, {
+      name,
+      description: `${name} pack`,
+      priority: opts.priority ?? 999,
+      hidden: opts.hidden ?? false,
+      depends: opts.depends ?? [],
+      commands: opts.commands ?? [],
+      rules: opts.rules ?? [],
+      skills: opts.skills ?? [],
+      agents: opts.agents ?? [],
+      'claude-sections': opts.claudeSections ?? [],
+    });
+  }
+  return m;
+}
+
+const testManifests = makeManifests({
+  core: { priority: 0 },
+  database: { priority: 5, hidden: true },
+  'shared-backend': { priority: 6, hidden: true },
+  'backend-micronaut': { priority: 11, depends: ['database', 'shared-backend'], commands: ['kotlin-service'] },
+  'frontend-react': { priority: 20 },
+  product: { priority: 40 },
+  research: { priority: 60, depends: ['product'] },
+});
+
+describe('resolve', () => {
+  it('basic resolve — backend-micronaut includes deps + core', () => {
+    const result = resolve(['backend-micronaut'], testManifests);
+    assert.ok(result.includes('core'));
+    assert.ok(result.includes('database'));
+    assert.ok(result.includes('shared-backend'));
+    assert.ok(result.includes('backend-micronaut'));
+  });
+
+  it('no duplicates — two packs sharing a dep', () => {
+    // Both backend-micronaut and a hypothetical other pack could share database
+    const result = resolve(['backend-micronaut', 'database'], testManifests);
+    const counts = {};
+    for (const p of result) counts[p] = (counts[p] || 0) + 1;
+    for (const [name, count] of Object.entries(counts)) {
+      assert.equal(count, 1, `${name} appears ${count} times`);
+    }
+  });
+
+  it('priority ordering — resolved packs sorted by priority', () => {
+    const result = resolve(['backend-micronaut', 'research'], testManifests);
+    for (let i = 1; i < result.length; i++) {
+      const prevPriority = testManifests.get(result[i - 1])?.priority ?? 999;
+      const currPriority = testManifests.get(result[i])?.priority ?? 999;
+      assert.ok(prevPriority <= currPriority, `${result[i - 1]} (${prevPriority}) should come before ${result[i]} (${currPriority})`);
+    }
+  });
+
+  it('core always first — no matter what you pick', () => {
+    const result = resolve(['research'], testManifests);
+    assert.equal(result[0], 'core');
+  });
+
+  it('unknown pack — throws clear error', () => {
+    assert.throws(
+      () => resolve(['nonexistent'], testManifests),
+      { message: "Unknown pack: 'nonexistent'" }
+    );
+  });
+
+  it('research pulls product as dependency', () => {
+    const result = resolve(['research'], testManifests);
+    assert.ok(result.includes('product'));
+    assert.ok(result.includes('research'));
+  });
+});
+
+describe('detectCycles', () => {
+  it('no cycles — passes silently', () => {
+    assert.doesNotThrow(() => detectCycles(testManifests));
+  });
+
+  it('cycle detection — A depends on B, B depends on A', () => {
+    const cyclic = makeManifests({
+      core: { priority: 0 },
+      a: { priority: 1, depends: ['b'] },
+      b: { priority: 2, depends: ['a'] },
+    });
+    assert.throws(
+      () => detectCycles(cyclic),
+      /Cycle detected/
+    );
+  });
+});
+
+describe('resolveAliases', () => {
+  it('maps backend to backend-micronaut', () => {
+    const { resolved, warnings } = resolveAliases(['backend', 'product']);
+    assert.deepEqual(resolved, ['backend-micronaut', 'product']);
+    assert.equal(warnings.length, 1);
+    assert.ok(warnings[0].includes('backend-micronaut'));
+  });
+
+  it('maps frontend to frontend-react', () => {
+    const { resolved } = resolveAliases(['frontend']);
+    assert.deepEqual(resolved, ['frontend-react']);
+  });
+
+  it('passes through unknown names unchanged', () => {
+    const { resolved, warnings } = resolveAliases(['product', 'ops']);
+    assert.deepEqual(resolved, ['product', 'ops']);
+    assert.equal(warnings.length, 0);
+  });
+});
+
+describe('toPacks', () => {
+  it('converts manifests to PACKS format', () => {
+    const { PACKS, PACK_ORDER } = toPacks(testManifests);
+    assert.ok(PACKS.core);
+    assert.ok(PACKS['backend-micronaut']);
+    assert.equal(PACKS['backend-micronaut'].description, 'backend-micronaut pack');
+    assert.deepEqual(PACKS['backend-micronaut'].depends, ['database', 'shared-backend']);
+    assert.equal(PACK_ORDER[0], 'core');
+  });
+
+  it('PACK_ORDER sorted by priority', () => {
+    const { PACK_ORDER } = toPacks(testManifests);
+    assert.equal(PACK_ORDER[0], 'core');
+    const idx = (name) => PACK_ORDER.indexOf(name);
+    assert.ok(idx('database') < idx('backend-micronaut'));
+    assert.ok(idx('product') < idx('research'));
+  });
+});
+
+// ── Test fixtures for validatePack / loadExternalPacks ──────────
+const TMP = join(import.meta.dirname, '..', '.test-tmp-resolver');
+
+function setupExternal() {
+  rmSync(TMP, { recursive: true, force: true });
+  mkdirSync(TMP, { recursive: true });
+}
+
+function cleanupExternal() {
+  rmSync(TMP, { recursive: true, force: true });
+}
+
+describe('validatePack', () => {
+  it('passes for a valid manifest', () => {
+    const manifest = {
+      name: 'my-pack',
+      description: 'A test pack',
+      commands: [],
+      rules: [],
+      skills: [],
+      agents: [],
+    };
+    const result = validatePack(manifest, TMP, new Set());
+    assert.ok(result.valid, `errors: ${result.errors.join(', ')}`);
+    assert.equal(result.errors.length, 0);
+  });
+
+  it('fails when name is missing', () => {
+    const manifest = { description: 'No name' };
+    const result = validatePack(manifest, TMP, new Set());
+    assert.ok(!result.valid);
+    assert.ok(result.errors.some(e => e.includes('name')));
+  });
+
+  it('fails when description is missing', () => {
+    const manifest = { name: 'no-desc' };
+    const result = validatePack(manifest, TMP, new Set());
+    assert.ok(!result.valid);
+    assert.ok(result.errors.some(e => e.includes('description')));
+  });
+
+  it('fails when name collides with built-in pack', () => {
+    const manifest = { name: 'core', description: 'Fake core' };
+    const builtins = new Set(['core', 'backend-micronaut']);
+    const result = validatePack(manifest, TMP, builtins);
+    assert.ok(!result.valid);
+    assert.ok(result.errors.some(e => e.includes('collides')));
+  });
+
+  it('fails when name uses wrong format', () => {
+    const manifest = { name: 'My_Pack', description: 'Bad name' };
+    const result = validatePack(manifest, TMP, new Set());
+    assert.ok(!result.valid);
+    assert.ok(result.errors.some(e => e.includes('kebab-case')));
+  });
+
+  it('fails when dependency references unknown pack', () => {
+    const manifest = {
+      name: 'my-pack',
+      description: 'Has bad dep',
+      depends: ['nonexistent-pack'],
+    };
+    const builtins = new Set(['core']);
+    const result = validatePack(manifest, TMP, builtins);
+    assert.ok(!result.valid);
+    assert.ok(result.errors.some(e => e.includes('nonexistent-pack')));
+  });
+
+  it('allows dependency on built-in pack', () => {
+    const manifest = {
+      name: 'my-pack',
+      description: 'Depends on core',
+      depends: ['core'],
+    };
+    const builtins = new Set(['core']);
+    const result = validatePack(manifest, TMP, builtins);
+    assert.ok(result.valid, `errors: ${result.errors.join(', ')}`);
+  });
+
+  it('warns about missing command files', () => {
+    setupExternal();
+    try {
+      const packDir = join(TMP, 'my-pack');
+      mkdirSync(join(packDir, 'commands', 'spartan'), { recursive: true });
+      // command file does NOT exist
+      const manifest = {
+        name: 'my-pack',
+        description: 'Missing command',
+        commands: ['nonexistent-cmd'],
+      };
+      const result = validatePack(manifest, packDir, new Set());
+      assert.ok(result.warnings.some(w => w.includes('nonexistent-cmd')));
+    } finally {
+      cleanupExternal();
+    }
+  });
+});
+
+describe('loadExternalPacks', () => {
+  it('loads valid external pack from directory', () => {
+    setupExternal();
+    try {
+      const packDir = join(TMP, 'community');
+      mkdirSync(join(packDir, 'packs'), { recursive: true });
+      writeFileSync(join(packDir, 'packs', 'go-backend.yaml'), `
+name: go-backend
+description: "Go backend rules"
+category: Backend
+priority: 100
+commands: []
+rules: []
+skills: []
+agents: []
+claude-sections: []
+`);
+      const builtins = new Set(['core']);
+      const result = loadExternalPacks(packDir, builtins);
+      assert.ok(result.loaded.has('go-backend'));
+      assert.equal(result.errors.length, 0);
+    } finally {
+      cleanupExternal();
+    }
+  });
+
+  it('rejects external pack with name collision', () => {
+    setupExternal();
+    try {
+      const packDir = join(TMP, 'bad-community');
+      mkdirSync(join(packDir, 'packs'), { recursive: true });
+      writeFileSync(join(packDir, 'packs', 'core.yaml'), `
+name: core
+description: "Fake core"
+`);
+      const builtins = new Set(['core']);
+      const result = loadExternalPacks(packDir, builtins);
+      assert.ok(!result.loaded.has('core'));
+      assert.ok(result.errors.length > 0);
+    } finally {
+      cleanupExternal();
+    }
+  });
+
+  it('returns empty when directory has no packs/', () => {
+    setupExternal();
+    try {
+      const packDir = join(TMP, 'empty');
+      mkdirSync(packDir, { recursive: true });
+      const result = loadExternalPacks(packDir, new Set());
+      assert.equal(result.loaded.size, 0);
+      assert.equal(result.errors.length, 0);
+    } finally {
+      cleanupExternal();
+    }
+  });
+});

package/lib/worktree.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# Spartan worktree manager — reusable functions for isolated builds.
+# Modeled after gstack's lib/worktree.ts WorktreeManager class.
+#
+# Usage in build commands:
+#   source ~/.spartan/lib/worktree.sh  (if installed)
+#   spartan_worktree_create "my-feature"
+#   spartan_worktree_guard
+#   spartan_worktree_cleanup "my-feature"
+
+set -euo pipefail
+
+# Create an isolated worktree for a feature build.
+# Creates branch, symlinks planning dirs, copies .env.
+#
+# Args:
+#   $1 — slug (e.g., "user-auth-flow")
+#   $2 — branch prefix (default: "feature")
+#
+# Prints:
+#   WORKSPACE=<path>
+#   BRANCH=<name>
+spartan_worktree_create() {
+  local slug="$1"
+  local prefix="${2:-feature}"
+  local branch="$prefix/$slug"
+  local main_repo
+  main_repo="$(git rev-parse --show-toplevel)"
+  local workspace="$main_repo/.worktrees/$slug"
+
+  if [ -d "$workspace" ]; then
+    echo "RESUMING: $workspace"
+  else
+    git worktree add "$workspace" -b "$branch" 2>/dev/null || \
+      git worktree add "$workspace" "$branch"
+  fi
+
+  # Symlink planning directories so worktree shares them with main repo
+  for dir in .planning .memory .handoff .spartan; do
+    [ -d "$main_repo/$dir" ] && [ ! -e "$workspace/$dir" ] && \
+      ln -s "$main_repo/$dir" "$workspace/$dir"
+  done
+
+  # Copy .env (not symlinked — worktree may need different values)
+  [ -f "$main_repo/.env" ] && [ ! -f "$workspace/.env" ] && \
+    cp "$main_repo/.env" "$workspace/.env"
+
+  # Ensure .worktrees/ is gitignored
+  grep -qxF '.worktrees/' "$main_repo/.gitignore" 2>/dev/null || \
+    echo '.worktrees/' >> "$main_repo/.gitignore"
+
+  echo "WORKSPACE=$workspace"
+  echo "BRANCH=$branch"
+}
+
+# Guard: verify we're inside a worktree, not the main repo.
+# Returns 0 if OK, 1 if in main repo (should stop).
+spartan_worktree_guard() {
+  local main_repo
+  main_repo="$(git worktree list | head -1 | awk '{print $1}')"
+  local current
+  current="$(git rev-parse --show-toplevel)"
+
+  if [ "$main_repo" = "$current" ]; then
+    echo "ERROR: Working in main repo, not a worktree. Run spartan_worktree_create first."
+    return 1
+  else
+    echo "OK: Worktree at $current"
+    return 0
+  fi
+}
+
+# Remove a worktree after PR is merged.
+#
+# Args:
+#   $1 — slug used during create
+spartan_worktree_cleanup() {
+  local slug="$1"
+  local main_repo
+  main_repo="$(git worktree list | head -1 | awk '{print $1}')"
+
+  git -C "$main_repo" worktree remove ".worktrees/$slug" --force 2>/dev/null || true
+  git -C "$main_repo" worktree prune 2>/dev/null || true
+  echo "Cleaned up worktree: $slug"
+}
+
+# List all active worktrees.
+spartan_worktree_list() {
+  git worktree list 2>/dev/null
+}
+
+# Prune stale worktrees from previous runs.
+spartan_worktree_prune() {
+  local main_repo
+  main_repo="$(git rev-parse --show-toplevel)"
+  git worktree prune 2>/dev/null || true
+
+  local worktree_base="$main_repo/.worktrees"
+  if [ -d "$worktree_base" ]; then
+    # Remove empty directories left behind
+    find "$worktree_base" -maxdepth 1 -type d -empty -delete 2>/dev/null || true
+  fi
+  echo "Pruned stale worktrees"
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@c0x12c/ai-toolkit",
+  "version": "1.15.0",
+  "description": "Engineering discipline layer for AI coding agents — commands, rules, skills, agents, and packs for Claude Code",
+  "type": "module",
+  "bin": {
+    "ai-toolkit": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "commands/",
+    "skills/",
+    "rules/",
+    "agents/",
+    "claude-md/",
+    "frameworks/",
+    "templates/",
+    "packs/",
+    "VERSION",
+    ".claude-plugin/"
+  ],
+  "keywords": [
+    "claude-code",
+    "ai-toolkit",
+    "cursor",
+    "windsurf",
+    "codex",
+    "copilot",
+    "engineering",
+    "agent-skills"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/c0x12c/ai-toolkit"
+  },
+  "scripts": {
+    "test": "node --test lib/resolver.test.js lib/assembler.test.js lib/detector.test.js",
+    "gen:codex": "node scripts/gen-codex-skills.js",
+    "check:codex": "node scripts/check-codex-skills.js",
+    "prepublishOnly": "node scripts/compile-packs.js && node scripts/gen-codex-skills.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.1"
+  }
+}

package/packs/backend-micronaut.yaml

@@ -0,0 +1,35 @@
+name: backend-micronaut
+description: "Kotlin + Micronaut backend"
+category: Backend
+priority: 11
+hidden: false
+depends:
+  - database
+  - shared-backend
+
+commands:
+  - kotlin-service
+  - review
+  - testcontainer
+
+rules:
+  - backend-micronaut/KOTLIN.md
+  - backend-micronaut/CONTROLLERS.md
+  - backend-micronaut/SERVICES_AND_BEANS.md
+  - backend-micronaut/API_DESIGN.md
+  - backend-micronaut/RETROFIT_PLACEMENT.md
+  - backend-micronaut/BATCH_PROCESSING.md
+
+skills:
+  - api-endpoint-creator
+  - backend-api-design
+  - kotlin-best-practices
+  - testing-strategies
+  - security-checklist
+
+agents:
+  - micronaut-backend-expert.md
+  - solution-architect-cto.md
+
+claude-sections:
+  - 11-backend-micronaut.md

package/packs/backend-nodejs.yaml

@@ -0,0 +1,15 @@
+name: backend-nodejs
+description: "Node.js backend (coming soon)"
+category: Backend
+priority: 12
+hidden: false
+coming-soon: true
+depends:
+  - database
+  - shared-backend
+
+commands: []
+rules: []
+skills: []
+agents: []
+claude-sections: []

package/packs/backend-python.yaml

@@ -0,0 +1,15 @@
+name: backend-python
+description: "Python backend (coming soon)"
+category: Backend
+priority: 13
+hidden: false
+coming-soon: true
+depends:
+  - database
+  - shared-backend
+
+commands: []
+rules: []
+skills: []
+agents: []
+claude-sections: []

package/packs/core.yaml

@@ -0,0 +1,37 @@
+name: core
+description: "Core workflow (always installed)"
+category: Core
+priority: 0
+hidden: false
+
+commands:
+  - spec
+  - plan
+  - build
+  - debug
+  - onboard
+  - daily
+  - context-save
+  - update
+  - pr-ready
+  - init-project
+  - init-rules
+  - scan-rules
+  - lint-rules
+  - careful
+  - freeze
+  - unfreeze
+  - guard
+  - sessions
+  - contribute
+  - gate-review
+
+rules:
+  - core/NAMING_CONVENTIONS.md
+  - core/TIMEZONE.md
+  - core/SKILL_AUTHORING.md
+
+skills: []
+agents:
+  - phase-reviewer.md
+claude-sections: []

package/packs/database.yaml

@@ -0,0 +1,21 @@
+name: database
+description: "Database patterns, migrations, Exposed ORM"
+category: Backend
+priority: 5
+hidden: true
+
+commands:
+  - migration
+
+rules:
+  - database/SCHEMA.md
+  - database/ORM_AND_REPO.md
+  - database/TRANSACTIONS.md
+
+skills:
+  - database-patterns
+  - database-table-creator
+
+agents: []
+claude-sections:
+  - 05-database.md

package/packs/frontend-react.yaml

@@ -0,0 +1,24 @@
+name: frontend-react
+description: "React + Next.js frontend"
+category: Frontend
+priority: 20
+hidden: false
+
+commands:
+  - next-app
+  - next-feature
+  - fe-review
+  - figma-to-code
+  - e2e
+  - qa
+
+rules:
+  - frontend-react/FRONTEND.md
+
+skills:
+  - browser-qa
+
+agents: []
+
+claude-sections:
+  - 20-frontend-react.md

package/packs/infrastructure.yaml

@@ -0,0 +1,40 @@
+name: infrastructure
+description: "Terraform + AWS infrastructure"
+category: Ops
+priority: 30
+hidden: false
+depends: []
+
+commands:
+  - tf-scaffold
+  - tf-module
+  - tf-review
+  - tf-plan
+  - tf-deploy
+  - tf-import
+  - tf-drift
+  - tf-cost
+  - tf-security
+
+rules:
+  - infrastructure/STRUCTURE.md
+  - infrastructure/MODULES.md
+  - infrastructure/STATE_AND_BACKEND.md
+  - infrastructure/NAMING.md
+  - infrastructure/SECURITY.md
+  - infrastructure/VARIABLES.md
+  - infrastructure/PROVIDERS.md
+
+skills:
+  - terraform-service-scaffold
+  - terraform-module-creator
+  - terraform-review
+  - terraform-security-audit
+  - terraform-best-practices
+
+agents:
+  - infrastructure-expert.md
+  - sre-architect.md
+
+claude-sections:
+  - 30-infrastructure.md

package/packs/ops.yaml

@@ -0,0 +1,16 @@
+name: ops
+description: "Deploy & infrastructure"
+category: Ship
+priority: 50
+hidden: false
+
+commands:
+  - deploy
+  - env-setup
+
+rules: []
+skills: []
+agents: []
+
+claude-sections:
+  - 50-ops.md