@ludecker/aaac 1.0.0

package/README.md

@@ -0,0 +1,60 @@
+# @ludecker/aaac
+
+**Agentic Architecture as Code (AAAC)** — a complete agentic architecture framework for Cursor.
+
+> Commands are the public API. Skills, agents, and orchestrators are private implementation.
+
+## Install
+
+No `npm` CLI required. Use `npx` or `pnpm dlx`:
+
+```bash
+npx @ludecker/aaac@latest init
+```
+
+```bash
+pnpm dlx @ludecker/aaac@latest init
+```
+
+Non-interactive:
+
+```bash
+npx @ludecker/aaac@latest init --yes --dir /path/to/your/repo
+```
+
+## What you get
+
+- `.cursor/aaac/` — ontology, graph, lifecycle, run model, generators config
+- `.cursor/skills/shared/` — full pipeline (discovery → execute → verify → report)
+- `.cursor/agents/` — 13 generic subagent specs
+- `.cursor/commands/` — ~130 generated slash commands
+- `docs/agentic_architecture.md` — user + maintainer guide
+
+Add project-specific **domains** under `.cursor/domains/<slug>/` (see maintainer appendix).
+
+## Regenerate
+
+After editing `ontology.json` or `graph.project.yaml`:
+
+```bash
+npx @ludecker/aaac@latest generate
+pnpm dlx @ludecker/aaac@latest generate
+```
+
+## Links
+
+- [Install guide](https://ludecker.com/guide/install-aaac)
+- [Package on npm](https://www.npmjs.com/package/@ludecker/aaac)
+- [Lüdecker](https://ludecker.com) — reference implementation
+
+## Publish (maintainers)
+
+Authenticate with a registry token in `.npmrc` (used by pnpm, not the `npm` CLI):
+
+```bash
+pnpm --filter @ludecker/aaac publish --access public --no-git-checks
+git tag aaac-v1.0.0
+git push origin aaac-v1.0.0
+```
+
+CI publishes on `aaac-v*` tags via `.github/workflows/publish-aaac.yml` (`NPM_TOKEN` secret).

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@ludecker/aaac",
+  "version": "1.0.0",
+  "description": "Agentic Architecture as Code (AAAC) — installable Cursor agent framework",
+  "type": "module",
+  "license": "MIT",
+  "author": "Hans-Erik Lydecker",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eriklydecker/ludecker.git",
+    "directory": "packages/aaac"
+  },
+  "homepage": "https://ludecker.com/guide/install-aaac",
+  "bugs": {
+    "url": "https://github.com/eriklydecker/ludecker/issues"
+  },
+  "keywords": [
+    "aaac",
+    "agentic-architecture",
+    "cursor",
+    "ai-agents",
+    "skills",
+    "commands"
+  ],
+  "bin": {
+    "aaac": "./src/cli.mjs"
+  },
+  "files": [
+    "src/",
+    "templates/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import readline from "readline";
+import path from "path";
+import { parseArgs } from "./lib/paths.mjs";
+import { installAaac, runGenerators } from "./lib/install.mjs";
+import { resolveCursorRoot } from "./lib/paths.mjs";
+
+function printHelp() {
+  console.log(`@ludecker/aaac — Agentic Architecture as Code
+
+Usage:
+  npx @ludecker/aaac@latest init [options]
+  pnpm dlx @ludecker/aaac@latest init [options]
+  aaac generate [options]
+
+Commands:
+  init      Copy AAAC kernel into .cursor/ and docs/ (default)
+  generate  Regenerate graph.yaml and commands from ontology
+
+Options:
+  --dir <path>   Target project directory (default: cwd)
+  --yes, -y      Non-interactive defaults
+  --force        Backup existing .cursor/ and replace
+
+Install (no npm CLI required):
+  npx @ludecker/aaac@latest init
+  pnpm dlx @ludecker/aaac@latest init
+
+Docs: https://ludecker.com/guide/install-aaac
+Package: https://www.npmjs.com/package/@ludecker/aaac
+`);
+}
+
+function ask(question, defaultValue) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const prompt = defaultValue
+    ? `${question} [${defaultValue}]: `
+    : `${question}: `;
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      const trimmed = answer.trim();
+      resolve(trimmed || defaultValue || "");
+    });
+  });
+}
+
+async function promptInitOptions(args) {
+  if (args.yes) {
+    const dir = args.dir ? path.resolve(args.dir) : process.cwd();
+    const base = path.basename(dir);
+    return {
+      targetDir: dir,
+      projectName: base || "my-project",
+      docsRoot: "docs",
+    };
+  }
+
+  const targetDir = args.dir
+    ? path.resolve(args.dir)
+    : await ask("Project directory", process.cwd());
+  const projectName = await ask(
+    "Project name",
+    path.basename(targetDir) || "my-project",
+  );
+  const docsRoot = await ask("Docs folder (relative to project)", "docs");
+
+  return { targetDir, projectName, docsRoot };
+}
+
+async function cmdInit(args) {
+  const options = await promptInitOptions(args);
+  console.log(`\nInstalling AAAC into ${options.targetDir}...\n`);
+
+  const { cursorDest, docsDest } = installAaac({
+    targetDir: options.targetDir,
+    projectName: options.projectName,
+    docsRoot: options.docsRoot,
+    force: args.force,
+  });
+
+  console.log(`
+AAAC installed.
+
+  .cursor/     → ${cursorDest}
+  docs/        → ${docsDest}
+
+Next steps:
+  1. Open the project in Cursor
+  2. Create ${options.docsRoot}/master_rules.md and ${options.docsRoot}/architecture.md if missing
+  3. Try /review-architecture or /check-architecture
+  4. Read ${options.docsRoot}/agentic_architecture.md — Part 2 for adding domains
+
+Regenerate after ontology changes:
+  pnpm dlx @ludecker/aaac@latest generate
+  npx @ludecker/aaac@latest generate
+`);
+}
+
+function cmdGenerate(args) {
+  const targetDir = args.dir ? path.resolve(args.dir) : process.cwd();
+  const cursorRoot = resolveCursorRoot(path.join(targetDir, ".cursor"));
+  console.log(`Regenerating AAAC graph at ${cursorRoot}...`);
+  runGenerators(cursorRoot);
+  console.log("Done.");
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--help") || argv.includes("-h")) {
+    printHelp();
+    return;
+  }
+
+  const args = parseArgs(process.argv);
+  const sub = argv.find((a) => !a.startsWith("-")) ?? "init";
+
+  if (sub === "init") {
+    await cmdInit(args);
+    return;
+  }
+  if (sub === "generate") {
+    cmdGenerate(args);
+    return;
+  }
+
+  console.error(`Unknown command: ${sub}`);
+  printHelp();
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(err.message ?? err);
+  process.exit(1);
+});

package/src/generators/generate-commands.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * Regenerates .cursor/commands/<verb>-<object>.md from ontology.json
+ * Prunes stale command files. manual_commands from aaac/project.config.json
+ */
+import fs from "fs";
+import path from "path";
+import { aaacDir, parseArgs, resolveCursorRoot } from "../lib/paths.mjs";
+
+const args = parseArgs(process.argv);
+const cursorRoot = resolveCursorRoot(args.root);
+const aaac = aaacDir(cursorRoot);
+const commandsDir = path.join(cursorRoot, "commands");
+fs.mkdirSync(commandsDir, { recursive: true });
+
+const data = JSON.parse(
+  fs.readFileSync(path.join(aaac, "ontology.json"), "utf8"),
+);
+
+const projectConfigPath = path.join(aaac, "project.config.json");
+const projectConfig = fs.existsSync(projectConfigPath)
+  ? JSON.parse(fs.readFileSync(projectConfigPath, "utf8"))
+  : { manual_commands: [] };
+
+const {
+  verbs,
+  objects,
+  invalid_pairs,
+  command_overrides,
+  command_aliases,
+} = data;
+
+const invalid = new Set(invalid_pairs.map(([v, o]) => `${v}-${o}`));
+
+const KEEP_EXTRA = new Set(projectConfig.manual_commands ?? []);
+
+const EXCEPTION_CMD = {
+  "fix-bug": {
+    layer: "product",
+    description: "defect repair (resolver; not in 12-object matrix)",
+  },
+  "review-incident": {
+    layer: "system",
+    description: "production incident investigation",
+  },
+};
+
+function objectMeta(object, cmd) {
+  if (EXCEPTION_CMD[cmd]) return EXCEPTION_CMD[cmd];
+  const o = objects[object];
+  if (!o) return { layer: null, description: object };
+  if (typeof o === "string") return { layer: null, description: o };
+  return { layer: o.layer ?? null, description: o.description ?? object };
+}
+
+function cap(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function orchestratorHint(cmd, entry) {
+  if (entry?.alias) return `alias → \`${entry.alias}\``;
+  if (entry?.resolver) {
+    const fallback =
+      cmd === "fix-bug"
+        ? " — unknown slug → `verb-fix` + object `feature`"
+        : "";
+    return `resolver \`${entry.resolver}\`${fallback}`;
+  }
+  const verb = cmd.split("-")[0];
+  const orch = entry?.orchestrator;
+  const dedicated = new Set([
+    "update-doc",
+    "review-module",
+    "review-incident",
+    "test-function",
+    "release-app",
+    "write-article",
+  ]);
+  if (cmd === "update-architecture" || (orch && dedicated.has(orch))) {
+    const id = cmd === "update-architecture" ? "update-doc" : orch;
+    return `orchestrator \`${id}\` (see graph \`orchestrators.${id}.path\`)`;
+  }
+  const object = cmd.split("-").slice(1).join("-");
+  return `[skills/shared/verbs/${verb}/orchestrator/SKILL.md](../skills/shared/verbs/${verb}/orchestrator/SKILL.md) (object: \`${object}\`)`;
+}
+
+function domainLine(cmd) {
+  if (cmd === "review-incident" || cmd.endsWith("-function")) {
+    return "Domain optional.";
+  }
+  if (cmd.endsWith("-domain") || cmd.endsWith("-module")) {
+    return "Domain slug required (bounded context).";
+  }
+  return "Domain slug recommended.";
+}
+
+function writeCmd(cmd, entry = null) {
+  const parts = cmd.split("-");
+  const verb = parts[0];
+  let object = parts.slice(1).join("-");
+  const vDesc = verbs[verb] ?? verb;
+  if (entry?.alias) {
+    const canonParts = entry.alias.split("-");
+    object = canonParts.slice(1).join("-");
+  }
+  const { layer, description } = objectMeta(object, entry?.alias ?? cmd);
+  const aliasNote = entry?.alias
+    ? ` (alias \`${cmd}\` → \`${entry.alias}\`)`
+    : "";
+  const domainArg =
+    cmd === "review-incident" || cmd.endsWith("-function") ? "" : " <domain>";
+  const layerLine = layer ? `**Layer:** ${layer}  \n` : "";
+  const body = `# ${cmd}
+
+AAAC: \`/${cmd}${domainArg} "<intent>"\`
+
+${layerLine}**${cap(vDesc)}** a **${object}**${aliasNote} — ${description}.
+
+## Dispatch
+
+1. [.cursor/aaac/dispatch.md](../aaac/dispatch.md)
+2. [.cursor/aaac/graph.yaml](../aaac/graph.yaml) — **\`${cmd}\`**
+3. ${orchestratorHint(cmd, entry ?? {})}
+
+${domainLine(cmd)}
+`;
+  fs.writeFileSync(path.join(commandsDir, `${cmd}.md`), body);
+}
+
+const written = new Set();
+
+for (const [cmd, entry] of Object.entries(command_overrides)) {
+  writeCmd(cmd, entry);
+  written.add(cmd);
+}
+
+for (const [alias, canonical] of Object.entries(command_aliases ?? {})) {
+  if (written.has(alias)) continue;
+  writeCmd(alias, { alias: canonical });
+  written.add(alias);
+}
+
+for (const verb of Object.keys(verbs)) {
+  for (const object of Object.keys(objects)) {
+    const cmd = `${verb}-${object}`;
+    if (invalid.has(cmd) || written.has(cmd)) continue;
+    writeCmd(cmd, { orchestrator: `verb-${verb}`, object });
+    written.add(cmd);
+  }
+}
+
+let pruned = 0;
+if (fs.existsSync(commandsDir)) {
+  for (const file of fs.readdirSync(commandsDir)) {
+    if (!file.endsWith(".md") || KEEP_EXTRA.has(file)) continue;
+    if (!written.has(file.replace(/\.md$/, ""))) {
+      fs.unlinkSync(path.join(commandsDir, file));
+      pruned++;
+    }
+  }
+} else {
+  fs.mkdirSync(commandsDir, { recursive: true });
+}
+
+console.log(`Wrote ${written.size} command files, pruned ${pruned} stale.`);

package/src/generators/generate-graph-commands.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/** Prints graph.yaml `commands:` block from ontology.json */
+import fs from "fs";
+import path from "path";
+import { aaacDir, parseArgs, resolveCursorRoot } from "../lib/paths.mjs";
+
+const args = parseArgs(process.argv);
+const cursorRoot = resolveCursorRoot(args.root);
+const aaac = aaacDir(cursorRoot);
+
+const data = JSON.parse(
+  fs.readFileSync(path.join(aaac, "ontology.json"), "utf8"),
+);
+const { verbs, objects, invalid_pairs, command_overrides, command_aliases } =
+  data;
+const invalid = new Set(invalid_pairs.map(([v, o]) => `${v}-${o}`));
+
+const lines = ["commands:"];
+const done = new Set();
+
+function emit(cmd, entry) {
+  done.add(cmd);
+  if (entry.alias) {
+    lines.push(`  ${cmd}:`);
+    lines.push(`    alias: ${entry.alias}`);
+    return;
+  }
+  if (entry.resolver) {
+    lines.push(`  ${cmd}:`);
+    lines.push(`    resolver: ${entry.resolver}`);
+    return;
+  }
+  if (entry.orchestrator) {
+    lines.push(`  ${cmd}:`);
+    lines.push(`    orchestrator: ${entry.orchestrator}`);
+    if (entry.object) lines.push(`    object: ${entry.object}`);
+  }
+}
+
+for (const [cmd, entry] of Object.entries(command_overrides)) {
+  emit(cmd, entry);
+}
+
+for (const verb of Object.keys(verbs)) {
+  for (const object of Object.keys(objects)) {
+    const cmd = `${verb}-${object}`;
+    if (invalid.has(cmd) || done.has(cmd)) continue;
+    done.add(cmd);
+    const orch = verb === "check" ? "verb-check" : `verb-${verb}`;
+    lines.push(`  ${cmd}:`);
+    lines.push(`    orchestrator: ${orch}`);
+    lines.push(`    object: ${object}`);
+  }
+}
+
+for (const [alias, canonical] of Object.entries(command_aliases ?? {})) {
+  if (done.has(alias) || alias === canonical) continue;
+  done.add(alias);
+  lines.push(`  ${alias}:`);
+  lines.push(`    alias: ${canonical}`);
+}
+
+console.log(lines.join("\n"));

package/src/generators/generate-graph.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+/** Writes .cursor/aaac/graph.yaml from ontology + lifecycle + graph.project.yaml */
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+import {
+  aaacDir,
+  parseArgs,
+  resolveCursorRoot,
+  packageGeneratorsDir,
+} from "../lib/paths.mjs";
+
+const INJECT_MARKER = "{{INJECT_OBJECT_BLOCKS}}";
+
+const args = parseArgs(process.argv);
+const cursorRoot = resolveCursorRoot(args.root);
+const aaac = aaacDir(cursorRoot);
+const generatorsDir = packageGeneratorsDir();
+
+const commandsBlock = execSync(
+  `node "${path.join(generatorsDir, "generate-graph-commands.mjs")}" --root "${cursorRoot}"`,
+  { encoding: "utf8" },
+);
+
+const data = JSON.parse(
+  fs.readFileSync(path.join(aaac, "ontology.json"), "utf8"),
+);
+
+const lifecycle = JSON.parse(
+  fs.readFileSync(path.join(aaac, "lifecycle/lifecycle.json"), "utf8"),
+);
+
+const gates = JSON.parse(
+  fs.readFileSync(path.join(aaac, "governance/gates.json"), "utf8"),
+);
+
+const capabilityRegistry = JSON.parse(
+  fs.readFileSync(path.join(aaac, "capabilities/registry.json"), "utf8"),
+);
+
+const projectTail = fs.readFileSync(
+  path.join(aaac, "graph.project.yaml"),
+  "utf8",
+);
+
+function providerSkillId(provider) {
+  if (typeof provider === "string") return provider;
+  if (provider.type === "skill") return provider.id;
+  return null;
+}
+
+function resolveCapabilities(capIds) {
+  const skills = new Set();
+  for (const id of capIds ?? []) {
+    const cap = capabilityRegistry.capabilities[id];
+    if (!cap) throw new Error(`Unknown capability in ontology: ${id}`);
+    for (const provider of cap.providers) {
+      const skillId = providerSkillId(provider);
+      if (skillId) skills.add(skillId);
+    }
+  }
+  return [...skills];
+}
+
+function composeRuntimePhases(verbDef) {
+  const work = verbDef.work_phases ?? [];
+  if (!verbDef.gate_stack) return work;
+  const gatePhases = gates.stacks[verbDef.gate_stack] ?? [];
+  const executeIdx = work.indexOf("execute");
+  if (executeIdx === -1) {
+    const reportIdx = work.indexOf("report");
+    if (reportIdx <= 0) {
+      return work.length <= 1
+        ? [...work, ...gatePhases]
+        : [...work.slice(0, -1), ...gatePhases, work[work.length - 1]];
+    }
+    return [...work.slice(0, reportIdx), ...gatePhases, ...work.slice(reportIdx)];
+  }
+  return [...work.slice(0, executeIdx), ...gatePhases, ...work.slice(executeIdx)];
+}
+
+const resolvedObjectSkills = Object.fromEntries(
+  Object.entries(data.object_capabilities ?? {}).map(([object, caps]) => [
+    object,
+    resolveCapabilities(caps),
+  ]),
+);
+
+const resolvedObjectSkillVerbs = Object.fromEntries(
+  Object.entries(data.object_capability_verbs ?? {}).map(([object, verbs]) => [
+    object,
+    Object.fromEntries(
+      Object.entries(verbs).map(([verb, caps]) => [
+        verb,
+        resolveCapabilities(caps),
+      ]),
+    ),
+  ]),
+);
+
+const objectCapabilitiesBlock = Object.entries(data.object_capabilities ?? {})
+  .map(([object, caps]) =>
+    caps.length ? `  ${object}: [${caps.join(", ")}]` : `  ${object}: []`,
+  )
+  .join("\n");
+
+const objectSkillsBlock = Object.entries(resolvedObjectSkills)
+  .map(([object, skills]) =>
+    skills.length ? `  ${object}: [${skills.join(", ")}]` : `  ${object}: []`,
+  )
+  .join("\n");
+
+const objectSkillVerbsBlock = Object.entries(resolvedObjectSkillVerbs)
+  .map(([object, verbs]) => {
+    const inner = Object.entries(verbs)
+      .map(([verb, skills]) =>
+        skills.length
+          ? `    ${verb}: [${skills.join(", ")}]`
+          : `    ${verb}: []`,
+      )
+      .join("\n");
+    return `  ${object}:\n${inner}`;
+  })
+  .join("\n");
+
+const verbWorkPhasesBlock = Object.entries(lifecycle.verbs ?? {})
+  .map(
+    ([verb, def]) => `  ${verb}: [${(def.work_phases ?? []).join(", ")}]`,
+  )
+  .join("\n");
+
+const verbGateStackBlock = Object.entries(lifecycle.verbs ?? {})
+  .map(
+    ([verb, def]) =>
+      `  ${verb}: ${def.gate_stack ?? "null"}`,
+  )
+  .join("\n");
+
+const verbRuntimeBlock = Object.entries(lifecycle.verbs ?? {})
+  .map(([verb, def]) => {
+    const phases = Array.isArray(def) ? def : composeRuntimePhases(def);
+    return `  ${verb}: [${phases.join(", ")}]`;
+  })
+  .join("\n");
+
+const governanceGateStacksBlock = Object.entries(gates.stacks ?? {})
+  .map(([name, phases]) => `  ${name}: [${phases.join(", ")}]`)
+  .join("\n");
+
+const layerComment = Object.entries(data.layers ?? {})
+  .sort((a, b) => a[1].order - b[1].order)
+  .map(([name, L]) => `#   ${name}: ${L.objects.join(", ")}`)
+  .join("\n");
+
+const confidenceBlock = Object.entries(data.confidence ?? {})
+  .map(([k, v]) => `  ${k}: ${v}`)
+  .join("\n");
+
+const objectMaturityBlock = Object.entries(data.object_maturity ?? {})
+  .map(([object, level]) => `  ${object}: ${level}`)
+  .join("\n");
+
+const maturityRulesBlock = Object.entries(data.maturity_rules ?? {})
+  .map(([level, rule]) => {
+    const phases = (rule.requires_phases ?? [])
+      .map((p) => `      - ${p}`)
+      .join("\n");
+    return `  ${level}:\n    requires_phases:\n${phases || "      []"}\n    investigation: ${rule.investigation ?? "lite_on_create_update_deep_on_fix"}`;
+  })
+  .join("\n");
+
+const injectBlock = `object_capabilities:
+${objectCapabilitiesBlock}
+
+object_skills:
+${objectSkillsBlock}
+
+object_skill_verbs:
+${objectSkillVerbsBlock}
+`;
+
+const header = `version: 1
+
+# AAAC execution graph — SSOT for command → orchestrator → skills → agents.
+# Regenerate: pnpm aaac:generate (or npx @ludecker/aaac generate)
+# Path convention: agents/, policies/, skills/, domains/ are relative to .cursor/
+# Ontology: .cursor/aaac/ontology.json — layers (code → data → product → system):
+${layerComment}
+
+verbs: [${Object.keys(data.verbs).join(", ")}]
+objects: [${Object.keys(data.objects).join(", ")}]
+
+invalid_pairs:
+${data.invalid_pairs.map(([v, o]) => `  - [${v}, ${o}]`).join("\n")}
+
+verb_work_phases:
+${verbWorkPhasesBlock}
+
+verb_gate_stack:
+${verbGateStackBlock}
+
+governance_gate_stacks:
+${governanceGateStacksBlock}
+
+# Composed runtime: work through plan + gate stack + execute onward (see lifecycle.json runtime_compose)
+verb_runtime:
+${verbRuntimeBlock}
+
+confidence:
+${confidenceBlock}
+
+object_maturity:
+${objectMaturityBlock}
+
+maturity_rules:
+${maturityRulesBlock}
+
+# Layer SSOT refs (see aaac/layers.md)
+lifecycle: aaac/lifecycle/lifecycle.json
+lifecycle_phases: aaac/lifecycle/phases.json
+governance_gates: aaac/governance/gates.json
+run: aaac/run/schema.json
+capabilities: aaac/capabilities/registry.json
+dependencies: aaac/dependencies.yaml
+fitness_functions: aaac/fitness-functions.yaml
+state: aaac/state/runs/
+observability: aaac/run/schema.json
+contracts: aaac/contracts/
+
+`;
+
+let tail = projectTail.trim();
+if (tail.includes(INJECT_MARKER)) {
+  tail = tail.replace(INJECT_MARKER, injectBlock.trim());
+} else {
+  tail = `${tail}\n\n${injectBlock.trim()}`;
+}
+
+const out = `${header}${commandsBlock}\n\n${tail}\n`;
+fs.writeFileSync(path.join(aaac, "graph.yaml"), out);
+console.log("Wrote graph.yaml");