akili-specs 2.1.0

package/assets/jc-fox-mark.svg

@@ -0,0 +1,10 @@
+<svg width="640" height="180" viewBox="0 0 640 180" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="640" height="180" rx="24" fill="#0F172A"/>
+  <path d="M88 118L118 58L144 88L172 54L206 118H88Z" fill="#F59E0B"/>
+  <path d="M132 88L152 108L172 88" stroke="#0F172A" stroke-width="8" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="138" cy="92" r="4" fill="#0F172A"/>
+  <circle cx="166" cy="92" r="4" fill="#0F172A"/>
+  <text x="220" y="121" fill="#E5E7EB" font-family="Inter, Arial, sans-serif" font-size="104" font-weight="700" letter-spacing="2">SD</text>
+  <text x="387" y="121" fill="#38BDF8" font-family="Inter, Arial, sans-serif" font-size="104" font-weight="700" letter-spacing="2">D</text>
+  <text x="219" y="42" fill="#94A3B8" font-family="Inter, Arial, sans-serif" font-size="16" letter-spacing="3.2">JC METHODOLOGY</text>
+</svg>

package/bin/akili.js

@@ -0,0 +1,574 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { parseArgs } = require("util");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const SOURCE_CLAUDE = path.join(PACKAGE_ROOT, ".claude");
+const SOURCE_COMMANDS = path.join(SOURCE_CLAUDE, "commands");
+const SOURCE_SKILLS = path.join(SOURCE_CLAUDE, "skills");
+const SOURCE_TEMPLATES = path.join(SOURCE_CLAUDE, "templates");
+const AGENT_TEMPLATES = ["leader.md", "implementer.md", "reviewer.md"];
+const RESOURCE_SCRIPTS = ["gsc_verify.py", "parse_tests.js"];
+const SOURCE_SCRIPTS = path.join(PACKAGE_ROOT, "scripts");
+const SOURCE_MCP_EXAMPLE = path.join(PACKAGE_ROOT, ".mcp.json.example");
+const BANNER = ` █████╗ ██╗  ██╗██╗██╗     ██╗
+██╔══██╗██║ ██╔╝██║██║     ██║
+███████║█████╔╝ ██║██║     ██║
+██╔══██║██╔═██╗ ██║██║     ██║
+██║  ██║██║  ██╗██║███████╗██║
+╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚══════╝╚═╝`;
+
+// ANSI Colors
+const colors = {
+  reset: "\x1b[0m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+};
+
+function formatPath(p) {
+  // Normalize paths for display to prefer forward slashes, even on Windows, for consistency in docs/CLI
+  return p.split(path.sep).join("/");
+}
+
+// Default paths per OS
+const defaultPaths = {
+  claude: path.join(os.homedir(), ".claude"),
+  opencode: path.join(os.homedir(), ".config", "opencode"),
+  antigravity: path.join(os.homedir(), ".gemini"),
+};
+
+// Tool Registry defining target directories mapping per tool
+const TOOL_REGISTRY = {
+  claude: (rootPath) => ({
+    commands: [path.join(rootPath, "commands")],
+    skills: path.join(rootPath, "skills"),
+    resources: path.join(rootPath, "akili"),
+  }),
+  opencode: (rootPath) => ({
+    commands: [path.join(rootPath, "commands")],
+    skills: path.join(rootPath, "skills"),
+    resources: path.join(rootPath, "akili"),
+  }),
+  antigravity: (rootPath) => ({
+    commands: [
+      path.join(rootPath, "antigravity", "global_workflows"),
+      path.join(rootPath, "antigravity-cli", "global_workflows"),
+      path.join(rootPath, "antigravity-cli", "workflows"),
+    ],
+    skills: path.join(rootPath, "config", "skills"),
+    resources: path.join(rootPath, "config", "akili"),
+  }),
+};
+
+function printHelp() {
+  console.log(`AKILI-SPECS Methodology CLI
+
+Usage:
+  akili <command> [options]
+
+Commands:
+  install   Install commands, skills, and helper resources
+  update    Reinstall commands, skills, and helper resources
+  doctor    Check whether expected files are installed
+  list      List packaged commands, skills, and helper resources
+  help      Show this help
+
+Options:
+  --tool <name>        Install target: claude, opencode, antigravity, both, or all. Default: claude
+  --target <path>      Target config directory for selected single tool
+  --claude-target      Claude config directory. Default: ~/.claude
+  --opencode-target    OpenCode config directory. Default: ~/.config/opencode
+  --antigravity-target Antigravity config directory. Default: ~/.gemini
+  --force              Overwrite existing files
+  --dry-run            Show what would happen without writing files
+  --commands-only      Install or check only commands
+  --skills-only        Install or check only skills
+  --fix                Automatically fix missing files during doctor command
+  --local, -l          Install locally to the current project instead of globally
+
+Examples:
+  akili init
+  akili install
+  akili install --local
+  akili install --tool opencode
+  akili install --tool both --dry-run
+  akili install --tool claude --target ./.claude
+  akili update --tool both --force
+  akili doctor --tool all --fix
+  akili list
+`);
+}
+
+function printBanner() {
+  console.log(colors.cyan + BANNER + colors.reset);
+}
+
+function fail(message) {
+  console.error(`${colors.red}ERROR: ${message}${colors.reset}`);
+  process.exit(1);
+}
+
+function resolveUserPath(input) {
+  // Works for both ~/path (Unix) and ~\\path (Windows)
+  return path.resolve(input.replace(/^~(?=$|\/|\\)/, os.homedir()));
+}
+
+function getArgs() {
+  const options = {
+    tool: { type: "string", default: "claude" },
+    target: { type: "string" },
+    "claude-target": { type: "string", default: defaultPaths.claude },
+    "opencode-target": { type: "string", default: defaultPaths.opencode },
+    "antigravity-target": { type: "string", default: defaultPaths.antigravity },
+    force: { type: "boolean", default: false },
+    "dry-run": { type: "boolean", default: false },
+    "commands-only": { type: "boolean", default: false },
+    "skills-only": { type: "boolean", default: false },
+    fix: { type: "boolean", default: false },
+    local: { type: "boolean", short: "l", default: false },
+    help: { type: "boolean", short: "h", default: false },
+  };
+
+  try {
+    const { values, positionals } = parseArgs({
+      options,
+      strict: true,
+      allowPositionals: true,
+    });
+
+    let command = positionals[0] || "help";
+    if (values.help) command = "help";
+
+    if (values["commands-only"] && values["skills-only"]) {
+      fail("Use only one of --commands-only or --skills-only");
+    }
+
+    if (!["claude", "opencode", "antigravity", "both", "all"].includes(values.tool)) {
+      fail("--tool must be one of: claude, opencode, antigravity, both, all");
+    }
+
+    if (values.target && (values.tool === "both" || values.tool === "all")) {
+      fail("--target can only be used with a single tool target.");
+    }
+
+    // Resolve paths
+    const baseClaude = values.local ? path.join(process.cwd(), ".claude") : defaultPaths.claude;
+    const baseOpencode = values.local ? path.join(process.cwd(), ".config", "opencode") : defaultPaths.opencode;
+    const baseAntigravity = values.local ? path.join(process.cwd(), ".gemini") : defaultPaths.antigravity;
+
+    const args = {
+      command,
+      tool: values.tool,
+      force: values.force,
+      dryRun: values["dry-run"],
+      commandsOnly: values["commands-only"],
+      skillsOnly: values["skills-only"],
+      fix: values.fix,
+      local: values.local,
+      claudeTarget: resolveUserPath(values.target && values.tool === "claude" ? values.target : (values["claude-target"] !== defaultPaths.claude ? values["claude-target"] : baseClaude)),
+      opencodeTarget: resolveUserPath(values.target && values.tool === "opencode" ? values.target : (values["opencode-target"] !== defaultPaths.opencode ? values["opencode-target"] : baseOpencode)),
+      antigravityTarget: resolveUserPath(values.target && values.tool === "antigravity" ? values.target : (values["antigravity-target"] !== defaultPaths.antigravity ? values["antigravity-target"] : baseAntigravity)),
+    };
+
+    return args;
+  } catch (err) {
+    fail(err.message);
+  }
+}
+
+function ensureDirectory(dir, dryRun) {
+  if (fs.existsSync(dir)) return;
+  if (dryRun) {
+    console.log(`  ${colors.yellow}would create dir${colors.reset} ${dir}`);
+    return;
+  }
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function listEntries(dir, filter) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter(filter)
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function listCommands() {
+  return listEntries(SOURCE_COMMANDS, (entry) => entry.isFile() && entry.name.endsWith(".md"));
+}
+
+function listSkills() {
+  return listEntries(SOURCE_SKILLS, (entry) => entry.isDirectory());
+}
+
+function selectedTools(args) {
+  if (args.tool === "both") return ["claude", "opencode"];
+  if (args.tool === "all") return ["claude", "opencode", "antigravity"];
+  return [args.tool];
+}
+
+function shouldInclude(type, args) {
+  if (args.commandsOnly) return type === "commands";
+  if (args.skillsOnly) return type === "skills";
+  return true;
+}
+
+function copySingleFile(sourcePath, targetPath, args) {
+  ensureDirectory(path.dirname(targetPath), args.dryRun);
+
+  if (fs.existsSync(targetPath) && !args.force) {
+    console.log(`  ${colors.yellow}skip existing${colors.reset} ${targetPath}`);
+    return { installed: 0, skipped: 1 };
+  }
+
+  const action = fs.existsSync(targetPath) ? "overwrite" : "install";
+  console.log(`  ${colors.green}${args.dryRun ? "would " : ""}${action}${colors.reset} ${targetPath}`);
+
+  if (!args.dryRun) {
+    fs.copyFileSync(sourcePath, targetPath);
+  }
+
+  return { installed: 1, skipped: 0 };
+}
+
+function copyDirectoryContents(sourceDir, targetDir, args) {
+  ensureDirectory(targetDir, args.dryRun);
+
+  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+  let installed = 0;
+  let skipped = 0;
+
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+
+    if (fs.existsSync(targetPath) && !args.force) {
+      console.log(`  ${colors.yellow}skip existing${colors.reset} ${targetPath}`);
+      skipped += 1;
+      continue;
+    }
+
+    const action = fs.existsSync(targetPath) ? "overwrite" : "install";
+    console.log(`  ${colors.green}${args.dryRun ? "would " : ""}${action}${colors.reset} ${targetPath}`);
+
+    if (!args.dryRun) {
+      fs.cpSync(sourcePath, targetPath, {
+        recursive: true,
+        force: true,
+        errorOnExist: false,
+      });
+    }
+    installed += 1;
+  }
+
+  return { installed, skipped };
+}
+
+function getToolRegistryInfo(tool, args) {
+  const rootPath =
+    tool === "claude"
+      ? args.claudeTarget
+      : tool === "opencode"
+      ? args.opencodeTarget
+      : args.antigravityTarget;
+  return { rootPath, paths: TOOL_REGISTRY[tool](rootPath) };
+}
+
+function installTool(tool, args) {
+  const { rootPath, paths } = getToolRegistryInfo(tool, args);
+
+  let installed = 0;
+  let skipped = 0;
+
+  console.log(`\n${colors.cyan}${tool.toUpperCase()} target: ${rootPath}${colors.reset}`);
+
+  if (shouldInclude("commands", args)) {
+    for (const targetCommands of paths.commands) {
+      const result = copyDirectoryContents(SOURCE_COMMANDS, targetCommands, args);
+      installed += result.installed;
+      skipped += result.skipped;
+    }
+  }
+
+  if (shouldInclude("skills", args)) {
+    const result = copyDirectoryContents(SOURCE_SKILLS, paths.skills, args);
+    installed += result.installed;
+    skipped += result.skipped;
+  }
+
+  if (shouldInclude("resources", args)) {
+    for (const scriptName of RESOURCE_SCRIPTS) {
+      const result = copySingleFile(
+        path.join(SOURCE_SCRIPTS, scriptName),
+        path.join(paths.resources, "scripts", scriptName),
+        args
+      );
+      installed += result.installed;
+      skipped += result.skipped;
+    }
+
+    for (const templateName of AGENT_TEMPLATES) {
+      const result = copySingleFile(
+        path.join(SOURCE_TEMPLATES, templateName),
+        path.join(paths.resources, "templates", templateName),
+        args
+      );
+      installed += result.installed;
+      skipped += result.skipped;
+    }
+
+    const mcpResult = copySingleFile(
+      SOURCE_MCP_EXAMPLE,
+      path.join(paths.resources, ".mcp.json.example"),
+      args
+    );
+    installed += mcpResult.installed;
+    skipped += mcpResult.skipped;
+  }
+
+  return { installed, skipped };
+}
+
+function runInstall(args) {
+  let installed = 0;
+  let skipped = 0;
+
+  for (const tool of selectedTools(args)) {
+    const result = installTool(tool, args);
+    installed += result.installed;
+    skipped += result.skipped;
+  }
+
+  console.log(`\nDone. Installed: ${installed} | Skipped: ${skipped}`);
+  if (skipped > 0 && !args.force) {
+    console.log(`Use ${colors.yellow}--force${colors.reset} to overwrite existing files.`);
+  }
+
+  if (selectedTools(args).includes("opencode") && !args.dryRun) {
+    console.log(`Restart ${colors.cyan}OpenCode${colors.reset} for installed commands and skills to be loaded.`);
+  }
+}
+
+function runList() {
+  const commands = listCommands();
+  const skills = listSkills();
+  console.log(`\n${colors.cyan}Commands:${colors.reset}`);
+  commands.forEach((name) => console.log(`  ${name.replace(/\.md$/, "")}`));
+
+  console.log(`\n${colors.cyan}Skills:${colors.reset}`);
+  skills.forEach((name) => console.log(`  ${name}`));
+
+  console.log(`\n${colors.cyan}Resources:${colors.reset}`);
+  RESOURCE_SCRIPTS.forEach((name) => console.log(`  ${formatPath(path.join("scripts", name))}`));
+  AGENT_TEMPLATES.forEach((name) => console.log(`  ${formatPath(path.join("templates", name))}`));
+  console.log("  .mcp.json.example");
+}
+
+function hasInstalledCommand(targetCommandsList, name) {
+  for (const targetCommands of targetCommandsList) {
+    if (fs.existsSync(path.join(targetCommands, name))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function doctorTool(tool, args) {
+  const { rootPath, paths } = getToolRegistryInfo(tool, args);
+  let missing = 0;
+  let fixed = 0;
+
+  console.log(`\n${colors.cyan}Checking ${tool.toUpperCase()}: ${rootPath}${colors.reset}`);
+
+  if (shouldInclude("commands", args)) {
+    console.log(`\n${colors.yellow}Commands:${colors.reset}`);
+    for (const command of listCommands()) {
+      const ok = hasInstalledCommand(paths.commands, command);
+      if (ok) {
+        console.log(`  ${colors.green}OK${colors.reset} ${command}`);
+      } else {
+        if (args.fix) {
+          const targetPath = path.join(paths.commands[0], command);
+          copySingleFile(path.join(SOURCE_COMMANDS, command), targetPath, { force: true, dryRun: false });
+          console.log(`  ${colors.cyan}FIXED${colors.reset} ${command}`);
+          fixed += 1;
+        } else {
+          console.log(`  ${colors.red}MISSING${colors.reset} ${command}`);
+          missing += 1;
+        }
+      }
+    }
+  }
+
+  if (shouldInclude("skills", args)) {
+    console.log(`\n${colors.yellow}Skills:${colors.reset}`);
+    for (const skill of listSkills()) {
+      const ok = fs.existsSync(path.join(paths.skills, skill, "SKILL.md"));
+      if (ok) {
+        console.log(`  ${colors.green}OK${colors.reset} ${skill}`);
+      } else {
+        if (args.fix) {
+          copyDirectoryContents(path.join(SOURCE_SKILLS, skill), path.join(paths.skills, skill), { force: true, dryRun: false });
+          console.log(`  ${colors.cyan}FIXED${colors.reset} ${skill}`);
+          fixed += 1;
+        } else {
+          console.log(`  ${colors.red}MISSING${colors.reset} ${skill}`);
+          missing += 1;
+        }
+      }
+    }
+  }
+
+  if (shouldInclude("resources", args)) {
+    console.log(`\n${colors.yellow}Resources:${colors.reset}`);
+    const resourceChecks = [
+      { src: path.join(SOURCE_SCRIPTS, "gsc_verify.py"), dest: path.join(paths.resources, "scripts", "gsc_verify.py") },
+      { src: path.join(SOURCE_SCRIPTS, "parse_tests.js"), dest: path.join(paths.resources, "scripts", "parse_tests.js") },
+      { src: SOURCE_MCP_EXAMPLE, dest: path.join(paths.resources, ".mcp.json.example") },
+      ...AGENT_TEMPLATES.map((name) => ({
+        src: path.join(SOURCE_TEMPLATES, name),
+        dest: path.join(paths.resources, "templates", name),
+      })),
+    ];
+
+    for (const check of resourceChecks) {
+      const ok = fs.existsSync(check.dest);
+      if (ok) {
+        console.log(`  ${colors.green}OK${colors.reset} ${check.dest}`);
+      } else {
+         if (args.fix) {
+          copySingleFile(check.src, check.dest, { force: true, dryRun: false });
+          console.log(`  ${colors.cyan}FIXED${colors.reset} ${check.dest}`);
+          fixed += 1;
+        } else {
+          console.log(`  ${colors.red}MISSING${colors.reset} ${check.dest}`);
+          missing += 1;
+        }
+      }
+    }
+  }
+
+  return { missing, fixed };
+}
+
+function runDoctor(args) {
+  let missingTotal = 0;
+  let fixedTotal = 0;
+  
+  for (const tool of selectedTools(args)) {
+    const { missing, fixed } = doctorTool(tool, args);
+    missingTotal += missing;
+    fixedTotal += fixed;
+  }
+
+  console.log(`\nDone. Missing: ${missingTotal} | Fixed: ${fixedTotal}`);
+  if (missingTotal > 0) {
+    console.log(`Run ${colors.cyan}akili doctor --fix${colors.reset} to auto-repair missing files.`);
+    process.exitCode = 1;
+  }
+}
+
+const readline = require("readline/promises");
+
+async function runInteractiveInit() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  console.log(`\n${colors.cyan}Welcome to the AKILI-SPECS Setup!${colors.reset}`);
+  console.log("Let's configure your AI-assisted development environment.\n");
+
+  const toolAnswer = await rl.question(
+    `Which tool do you want to install AKILI-SPECS for?\n` +
+    `  1) Claude Code\n` +
+    `  2) OpenCode\n` +
+    `  3) Google Antigravity\n` +
+    `  4) Both (Claude Code + OpenCode)\n` +
+    `  5) All three\n` +
+    `${colors.cyan}>${colors.reset} `
+  );
+
+  let tool = "claude";
+  if (toolAnswer.trim() === "2") tool = "opencode";
+  else if (toolAnswer.trim() === "3") tool = "antigravity";
+  else if (toolAnswer.trim() === "4") tool = "both";
+  else if (toolAnswer.trim() === "5") tool = "all";
+
+  console.log("");
+  const scopeAnswer = await rl.question(
+    `Do you want to install it globally or locally for this specific project?\n` +
+    `  1) Globally (available in all your projects)\n` +
+    `  2) Locally (only for this project workspace)\n` +
+    `${colors.cyan}>${colors.reset} `
+  );
+
+  const isLocal = scopeAnswer.trim() === "2";
+  rl.close();
+
+  const args = {
+    command: "install",
+    tool: tool,
+    force: false,
+    dryRun: false,
+    commandsOnly: false,
+    skillsOnly: false,
+    fix: false,
+    local: isLocal,
+  };
+
+  if (isLocal) {
+    const cwd = process.cwd();
+    args.claudeTarget = path.join(cwd, ".claude");
+    args.opencodeTarget = path.join(cwd, ".config", "opencode");
+    args.antigravityTarget = path.join(cwd, ".gemini");
+    console.log(`\n${colors.yellow}Setting up local project installation...${colors.reset}`);
+  } else {
+    args.claudeTarget = defaultPaths.claude;
+    args.opencodeTarget = defaultPaths.opencode;
+    args.antigravityTarget = defaultPaths.antigravity;
+    console.log(`\n${colors.yellow}Setting up global installation...${colors.reset}`);
+  }
+
+  runInstall(args);
+}
+
+async function main() {
+  const args = getArgs();
+  
+  if (args.command !== "help" && args.command !== "list" && args.command !== "init") {
+    printBanner();
+  }
+
+  if (process.argv.length === 2 || args.command === "init") {
+    printBanner();
+    await runInteractiveInit();
+    return;
+  }
+
+  switch (args.command) {
+    case "install":
+    case "update":
+      runInstall(args);
+      break;
+    case "doctor":
+      runDoctor(args);
+      break;
+    case "list":
+      runList();
+      break;
+    case "help":
+      printHelp();
+      break;
+    default:
+      fail(`Unknown command: ${args.command}`);
+  }
+}
+
+main();

package/docs/README.md

@@ -0,0 +1,48 @@
+# AKILI Documentation
+
+AKILI is the documented form of the AKILI-SPECS methodology: a constitution-first, spec-driven workflow for Claude Code and OpenCode.
+
+Use this documentation when you want the human-facing reference. The installable source prompts and skills remain under `.claude/commands/` and `.claude/skills/`.
+
+## Start Here
+
+- [Flow](flow.md) - end-to-end methodology lifecycle from constitution to archive
+- [Model Routing](model-routing.md) - capability-tier model selection per AKILI-SPECS phase for Claude Code and OpenCode
+- [CLI](cli.md) - `akili` terminal reference for install, update, list, and doctor
+- [Commands](commands/README.md) - slash command reference
+- [Skills](skills/README.md) - packaged skill inventory and usage guidance
+- [OpenSpec comparison](openspec-comparison.md) - what AKILI borrows from OpenSpec and where it differs
+- [Release checklist](release-checklist.md) - controlled npm release process
+
+## Quick Flow
+
+```text
+/akili-constitution
+/akili-propose <change-name-or-spec-path>
+/akili-specify <spec-path>
+/akili-execute <spec-path>
+/akili-test <spec-path>
+/akili-validate <spec-path>
+/akili-archive <spec-path>
+```
+
+Use `/akili-seo <site-domain>` independently when you need Google Search Console setup and SEO audit reports.
+
+## Documentation Map
+
+| Topic | File | Use When |
+|---|---|---|
+| Flow | [flow.md](flow.md) | You need the lifecycle, artifacts, review gates, and project modes |
+| Model Routing | [model-routing.md](model-routing.md) | You need to choose which model runs each AKILI-SPECS phase across Claude Code and OpenCode |
+| CLI | [cli.md](cli.md) | You need install/update/list/doctor options or install paths |
+| Commands | [commands/README.md](commands/README.md) | You need command purpose, inputs, outputs, and sequencing |
+| Skills | [skills/README.md](skills/README.md) | You need to know which packaged skill supports which work |
+| OpenSpec comparison | [openspec-comparison.md](openspec-comparison.md) | You want to understand the relationship to OpenSpec patterns |
+
+## Source Of Truth
+
+- Command implementation prompts: `.claude/commands/*.md`
+- Skill implementation prompts: `.claude/skills/*/SKILL.md`
+- Multi-agent harness templates: `.claude/templates/{leader,implementer,reviewer}.md` (deployed into each project's `.agents/` by `/akili-constitution`)
+- CLI implementation: `bin/akili.js`
+- Release automation: `scripts/release.js` and `scripts/release-status.js`