@ludecker/aaac 1.0.0

package/src/lib/copy.mjs

@@ -0,0 +1,36 @@
+import fs from "fs";
+import path from "path";
+
+export function copyDirRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+export function substituteInTree(dir, replacements) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      substituteInTree(full, replacements);
+      continue;
+    }
+    if (!/\.(md|json|yaml|yml|mdc)$/i.test(entry.name)) continue;
+    let text = fs.readFileSync(full, "utf8");
+    let changed = false;
+    for (const [key, value] of Object.entries(replacements)) {
+      const token = `{{${key}}}`;
+      if (text.includes(token)) {
+        text = text.split(token).join(value);
+        changed = true;
+      }
+    }
+    if (changed) fs.writeFileSync(full, text);
+  }
+}

package/src/lib/install.mjs

@@ -0,0 +1,76 @@
+import fs from "fs";
+import path from "path";
+import { spawnSync } from "child_process";
+import { copyDirRecursive, substituteInTree } from "./copy.mjs";
+import {
+  ensureDir,
+  packageGeneratorsDir,
+  packageTemplatesDir,
+} from "./paths.mjs";
+
+export function runGenerators(cursorRoot) {
+  const generatorsDir = packageGeneratorsDir();
+  const graph = spawnSync(
+    process.execPath,
+    [path.join(generatorsDir, "generate-graph.mjs"), "--root", cursorRoot],
+    { stdio: "inherit" },
+  );
+  if (graph.status !== 0) {
+    throw new Error("generate-graph.mjs failed");
+  }
+  const commands = spawnSync(
+    process.execPath,
+    [path.join(generatorsDir, "generate-commands.mjs"), "--root", cursorRoot],
+    { stdio: "inherit" },
+  );
+  if (commands.status !== 0) {
+    throw new Error("generate-commands.mjs failed");
+  }
+}
+
+export function installAaac({
+  targetDir,
+  projectName,
+  docsRoot,
+  force = false,
+}) {
+  const resolvedTarget = path.resolve(targetDir);
+  const cursorDest = path.join(resolvedTarget, ".cursor");
+  const aaacDest = path.join(cursorDest, "aaac");
+  const templates = packageTemplatesDir();
+
+  if (fs.existsSync(aaacDest) && !force) {
+    throw new Error(
+      `.cursor/aaac already exists at ${aaacDest}. Use --force to backup and replace.`,
+    );
+  }
+
+  if (fs.existsSync(cursorDest) && force) {
+    const backup = `${cursorDest}.aaac-backup-${Date.now()}`;
+    fs.renameSync(cursorDest, backup);
+    console.log(`Backed up existing .cursor to ${backup}`);
+  }
+
+  const cursorSrc = path.join(templates, "cursor");
+  copyDirRecursive(cursorSrc, cursorDest);
+  ensureDir(path.join(cursorDest, "commands"));
+  ensureDir(path.join(aaacDest, "state", "runs"));
+
+  const docsDest = path.join(resolvedTarget, docsRoot);
+  ensureDir(docsDest);
+  const docsSrc = path.join(templates, "docs");
+  for (const file of fs.readdirSync(docsSrc)) {
+    fs.copyFileSync(path.join(docsSrc, file), path.join(docsDest, file));
+  }
+
+  const replacements = {
+    PROJECT_NAME: projectName,
+    DOCS_ROOT: docsRoot.replace(/\/$/, ""),
+  };
+  substituteInTree(cursorDest, replacements);
+  substituteInTree(docsDest, replacements);
+
+  runGenerators(cursorDest);
+
+  return { cursorDest, docsDest };
+}

package/src/lib/paths.mjs

@@ -0,0 +1,54 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const packageRoot = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+);
+
+export function parseArgs(argv) {
+  const args = { root: null, yes: false, dir: null, force: false };
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--root" && argv[i + 1]) {
+      args.root = argv[++i];
+    } else if (arg === "--dir" && argv[i + 1]) {
+      args.dir = argv[++i];
+    } else if (arg === "--yes" || arg === "-y") {
+      args.yes = true;
+    } else if (arg === "--force") {
+      args.force = true;
+    }
+  }
+  return args;
+}
+
+/** Resolve `.cursor` root (parent of `aaac/`). */
+export function resolveCursorRoot(rootArg) {
+  if (rootArg) {
+    const resolved = path.resolve(rootArg);
+    if (path.basename(resolved) === "aaac") {
+      return path.dirname(resolved);
+    }
+    return resolved;
+  }
+  return path.resolve(process.cwd(), ".cursor");
+}
+
+export function aaacDir(cursorRoot) {
+  return path.join(cursorRoot, "aaac");
+}
+
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+export function packageTemplatesDir() {
+  return path.join(packageRoot, "templates");
+}
+
+export function packageGeneratorsDir() {
+  return path.join(packageRoot, "src", "generators");
+}

package/templates/cursor/aaac/capabilities/registry.json

@@ -0,0 +1,106 @@
+{
+  "version": 2,
+  "capabilities": {
+    "ui-design": {
+      "description": "Design tokens, component CSS, presentational UI",
+      "providers": [
+        { "id": "component", "type": "skill", "path": "skills/shared/component" }
+      ]
+    },
+    "ux-design": {
+      "description": "User flows, readability, navigation clarity",
+      "providers": [
+        { "id": "workflow", "type": "skill", "path": "skills/shared/workflow" }
+      ]
+    },
+    "api-design": {
+      "description": "Contracts and validation at boundaries",
+      "providers": [
+        { "id": "integration", "type": "skill", "path": "skills/shared/integration" }
+      ]
+    },
+    "database-design": {
+      "description": "Schema, migrations, persistence contracts",
+      "providers": [
+        { "id": "schema", "type": "skill", "path": "skills/shared/schema" },
+        { "id": "migration", "type": "skill", "path": "skills/shared/migration" }
+      ]
+    },
+    "security": {
+      "description": "Auth, secrets, access control — extend with project skills",
+      "providers": [
+        { "id": "architecture", "type": "skill", "path": "skills/shared/architecture" }
+      ]
+    },
+    "infrastructure": {
+      "description": "Deploy, hosting, environment",
+      "providers": [
+        { "id": "platform-release", "type": "skill", "path": "skills/shared/platform-release" }
+      ]
+    },
+    "layer-boundaries": {
+      "description": "SSOT, import direction, module layers",
+      "providers": [
+        { "id": "architecture", "type": "skill", "path": "skills/shared/architecture" }
+      ]
+    },
+    "component-model": {
+      "description": "Presentational UI components",
+      "providers": [
+        { "id": "component", "type": "skill", "path": "skills/shared/component" }
+      ]
+    },
+    "schema-model": {
+      "description": "Database schema contracts",
+      "providers": [
+        { "id": "schema", "type": "skill", "path": "skills/shared/schema" }
+      ]
+    },
+    "data-model": {
+      "description": "Entity and type shapes in code",
+      "providers": [
+        { "id": "model", "type": "skill", "path": "skills/shared/model" }
+      ]
+    },
+    "migration-model": {
+      "description": "Migration scripts and apply procedure",
+      "providers": [
+        { "id": "migration", "type": "skill", "path": "skills/shared/migration" }
+      ]
+    },
+    "workflow-model": {
+      "description": "Multi-step processes and state machines",
+      "providers": [
+        { "id": "workflow", "type": "skill", "path": "skills/shared/workflow" }
+      ]
+    },
+    "integration-model": {
+      "description": "API routes, webhooks, MCP adapters",
+      "providers": [
+        { "id": "integration", "type": "skill", "path": "skills/shared/integration" }
+      ]
+    },
+    "domain-model": {
+      "description": "Bounded context structure",
+      "providers": [
+        { "id": "domain", "type": "skill", "path": "skills/shared/domain" }
+      ]
+    },
+    "documentation": {
+      "description": "Architecture and runbook docs",
+      "providers": [
+        { "id": "documentation", "type": "skill", "path": "skills/shared/documentation" }
+      ]
+    },
+    "module-authoring": {
+      "description": "Bootstrap new domain modules",
+      "providers": [
+        { "id": "module-authoring", "type": "skill", "path": "skills/shared/module-authoring" }
+      ]
+    }
+  },
+  "resolution": {
+    "graph_skill_keys": "providers where type=skill → id maps to graph skills key",
+    "run_record": "all providers including type=mcp recorded on Run.capabilities_resolved and decisions"
+  }
+}

package/templates/cursor/aaac/contract-schema.md

@@ -0,0 +1,66 @@
+# AAAC contract schema
+
+Command vocabulary: [ontology.json](ontology.json).  
+Capability routing: [capabilities/registry.json](capabilities/registry.json).  
+Lifecycle phases: [lifecycle/lifecycle.json](lifecycle/lifecycle.json).
+
+## Layer placement
+
+| Contract type | Location |
+|---------------|----------|
+| Command | `contracts/commands/<command>.yaml` |
+| Skill / phase | `contracts/skills/<skill>.yaml` |
+| Orchestrator plugin | `contract.yaml` beside orchestrator `SKILL.md` |
+
+## Command contract (required fields)
+
+```yaml
+name: string
+purpose: string
+inputs:
+  domain: { required: boolean }
+  intent: { required: boolean }
+outputs:
+  plan: { type: markdown, required: boolean }
+  report: { type: markdown, required: true }
+lifecycle_verb: create | update | fix | …
+success_criteria: []
+failure_conditions: []
+```
+
+## Skill contract (required fields)
+
+```yaml
+name: string
+purpose: string
+outputs:
+  <artifact>:
+    type: list | object | markdown | enum
+    required: boolean | required_when
+readonly: boolean   # when applicable
+gate: boolean       # when phase blocks execute
+```
+
+Contracts prevent skills from drifting. Verification checks orchestrator `contract.yaml` **and** `contracts/skills/*.yaml` outputs.
+
+## Orchestrator plugin fields
+
+See previous schema — `name`, `purpose`, `inputs`, `outputs`, `success_criteria`, `failure_conditions`, `dependencies`, `verification`.
+
+## Graph sections
+
+| Section | Purpose |
+|---------|---------|
+| `object_capabilities` | Capability ids per object (ontology SSOT) |
+| `object_skills` | Resolved providers from capability registry (generated) |
+| `verb_work_phases` | Work phases from lifecycle.json (generated) |
+| `verb_gate_stack` | Gate stack id per verb (generated) |
+| `governance_gate_stacks` | From governance/gates.json (generated) |
+| `verb_runtime` | Composed work + gates (generated) |
+| `lifecycle` / `governance_gates` / `run` / `capabilities` | Layer SSOT paths |
+
+## Validation
+
+- Every gate skill must have a contract in `contracts/skills/`
+- Resolver commands (`update-module`, `fix-bug`, `create-feature`) must have command contracts
+- Domain orchestrators must list `sync_inventory` in verification when `execute` runs

package/templates/cursor/aaac/contracts/commands/create-module.yaml

@@ -0,0 +1,28 @@
+name: create-module
+purpose: Create a new bounded module in a domain
+inputs:
+  domain:
+    required: true
+  intent:
+    required: true
+outputs:
+  plan:
+    type: markdown
+    required: true
+  implementation:
+    type: code_changes
+    required: true
+  verification:
+    type: markdown
+    required: true
+  report:
+    type: markdown
+    required: true
+lifecycle_verb: create
+success_criteria:
+  - validation confidence gates passed
+  - fitness security and layer_boundaries pass
+  - inventory synced when domain slug present
+failure_conditions:
+  - confidence below threshold without user risk acceptance
+  - execute without rollback on protected object

package/templates/cursor/aaac/contracts/commands/fix-bug.yaml

@@ -0,0 +1,32 @@
+name: fix-bug
+purpose: Repair broken behavior in a domain
+inputs:
+  domain:
+    required: false
+  intent:
+    required: true
+outputs:
+  findings:
+    type: markdown
+    required: true
+  root_cause:
+    type: markdown
+    required: true
+  plan:
+    type: markdown
+    required: true
+  implementation:
+    type: code_changes
+  verification:
+    type: markdown
+    required: true
+  report:
+    type: markdown
+    required: true
+lifecycle_verb: fix
+success_criteria:
+  - deep investigation and root_cause before plan
+  - impact_analysis proceed yes or rollback defined
+failure_conditions:
+  - root_cause confidence below 0.7
+  - symptom patch without root cause frame

package/templates/cursor/aaac/contracts/commands/update-module.yaml

@@ -0,0 +1,28 @@
+name: update-module
+purpose: Modify an existing domain module
+inputs:
+  domain:
+    required: true
+    enum: [cms, ui, database]
+  intent:
+    required: true
+outputs:
+  plan:
+    type: markdown
+    required: true
+  implementation:
+    type: code_changes
+  verification:
+    type: markdown
+    required: true
+  report:
+    type: markdown
+    required: true
+lifecycle_verb: update
+success_criteria:
+  - investigation_lite completed
+  - validation passed
+  - inventory Section 3 synced after execute
+failure_conditions:
+  - skip investigation_lite
+  - execute without validate gate pass

package/templates/cursor/aaac/contracts/skills/impact-analysis.yaml

@@ -0,0 +1,17 @@
+name: impact-analysis
+purpose: Pre-execute blast radius and risk analysis
+outputs:
+  affected:
+    type: list
+    required: true
+  risk:
+    type: list
+    required: true
+  blast_radius:
+    type: enum
+    values: [low, medium, high]
+    required: true
+  proceed:
+    type: boolean
+    required: true
+gate: true

package/templates/cursor/aaac/contracts/skills/investigation-lite.yaml

@@ -0,0 +1,17 @@
+name: investigation-lite
+purpose: Lightweight pre-change investigation for create and update
+outputs:
+  exists:
+    type: list
+    required: true
+  depends_on:
+    type: list
+    required: true
+  constraints:
+    type: list
+    required: true
+  confidence:
+    type: object
+    required: true
+    fields: [architecture, requirements, scope]
+readonly: true

package/templates/cursor/aaac/contracts/skills/investigation.yaml

@@ -0,0 +1,17 @@
+name: investigation
+purpose: Deep investigation for fix paths and incidents
+outputs:
+  findings:
+    type: list
+    required: true
+  risks:
+    type: list
+    required: true
+  recommendations:
+    type: list
+    required: true
+  confidence:
+    type: object
+    required: true
+    fields: [architecture, requirements, scope]
+readonly: true

package/templates/cursor/aaac/contracts/skills/validation.yaml

@@ -0,0 +1,14 @@
+name: validation
+purpose: Confidence gates before execute
+outputs:
+  validation:
+    type: enum
+    values: [pass, fail]
+    required: true
+  scores:
+    type: object
+    required: true
+  clarification_questions:
+    type: list
+    required_when: validation fail
+gate: true

package/templates/cursor/aaac/dependencies.yaml

@@ -0,0 +1,14 @@
+# Domain dependency graph — populate when you add bounded contexts.
+# SSOT for dependency-graph skill.
+
+version: 1
+
+domains: {}
+
+objects: {}
+
+risk_tags:
+  migrations: [migration, schema]
+  breaking_contracts: [integration, model, schema, migration]
+  auth: [integration, schema]
+  deployment: [app, integration]

package/templates/cursor/aaac/dispatch.md

@@ -0,0 +1,135 @@
+# AAAC command dispatch (shared by all slash commands)
+
+Agents running any AAAC command **must** follow this sequence.
+
+**Path convention:** In [graph.yaml](graph.yaml), paths under `agents/`, `policies/`, `skills/`, and `domains/` are relative to **`.cursor/`**.
+
+**Primary execution object:** Every command runs inside a **Run** — see [run/RUN.md](run/RUN.md) and [run/schema.json](run/schema.json).
+
+## 1. Parse input
+
+From `$ARGUMENTS` and the user message:
+
+| Slot | Rule |
+|------|------|
+| Command | Filename without `.md` (e.g. `update-module`) |
+| Domain | See [ontology.md](ontology.md); optional for `review-incident` and `*-function` |
+| Intent | Quoted string `"…"` or remainder after domain |
+| Verb | First segment of command (e.g. `update-module` → verb `update`) |
+
+If intent contains `Sync inventory only` (case-insensitive), orchestrator runs **sync_inventory** phase only (no execution).
+
+**Resume:** If user references `run_{id}`, load `state/runs/{run_id}/run.json` and continue from `phase`.
+
+**Aliases:** `commands.<name>.alias` → resolve canonical command (e.g. `update-api` → `update-integration`) and continue.
+
+Legacy names (`module-update`, `architecture`, `swarm-check`, …) are aliases in [graph.yaml](graph.yaml).
+
+## 2. Load graph
+
+Read [graph.yaml](graph.yaml) and [ontology.json](ontology.json).
+
+- Reject unknown commands; suggest nearest alias if typo matches `command_aliases`
+- Reject `invalid_pairs` with valid alternative (e.g. `release-module` → `release-app`)
+- Resolve `commands.<name>` → orchestrator, `object`, `alias`, or `resolver` + slug map
+- **Resolver fallback:** if slug missing from resolver `map`, use resolver `default` orchestrator and `default_object` when set
+- **Object** comes from graph `object` field — load skills from `object_skills.<object>` and `object_skill_verbs.<object>.<verb>` per [verbs/_object-skills.md](../skills/shared/verbs/_object-skills.md)
+- **Lifecycle (work):** [lifecycle/lifecycle.json](lifecycle/lifecycle.json) `verbs.*.work_phases`
+- **Gates (approval):** [governance/gates.json](governance/gates.json) — composed into runtime per `verb_runtime` in graph
+- **Maturity:** read `object_maturity.<object>` and apply `maturity_rules.<level>` (may require extra gate phases)
+- **Capabilities:** resolve `object_capabilities.<object>` via [capabilities/registry.json](capabilities/registry.json) — record all providers (skill + mcp) on Run
+- **Dependencies:** [dependencies.yaml](dependencies.yaml)
+- **Fitness:** [fitness-functions.yaml](fitness-functions.yaml)
+- **Contracts:** validate against [contracts/commands/](contracts/commands/) and [contracts/skills/](contracts/skills/)
+
+## 2.5 Create or resume Run
+
+Before loading orchestrator:
+
+1. **Create** `state/runs/{run_id}/run.json` per [run/schema.json](run/schema.json)
+2. Set `pending` from `verb_runtime.<verb>` in graph (work + gates composed)
+3. Set `status: running`, first `phase`, `phase_kind: work`
+4. Record resolved orchestrator, object, domain, intent on Run
+
+All state and observability live on the Run — **no** standalone execution-state or markdown logs.
+
+## 3. Load orchestrator
+
+- Read `orchestrators.<id>.path` → `SKILL.md` + `contract.yaml` if present
+- Read `inventory` when set on orchestrator
+- Load every skill in `requires` (+ `optional` when fix/create modes need it)
+- Load object skills from graph `object_skills` / `object_skill_verbs` for the command verb + object
+- Load [.cursor/policies/](../policies/) — all skills inherit:
+  - [master-rules.md](../policies/master-rules.md)
+  - [implementation.md](../policies/implementation.md)
+  - [mcp-and-deploy.md](../policies/mcp-and-deploy.md)
+- Read [verbs/_dispatch-utils.md](../skills/shared/verbs/_dispatch-utils.md) for inventory + investigation rules
+- Read [run/SKILL.md](../skills/shared/run/SKILL.md) for Run update protocol
+
+## 4. Execute phases (Run-driven)
+
+Run phases **in order** from Run `pending` (matches `verb_runtime`). Map phase id → skill via [lifecycle/phases.json](lifecycle/phases.json).
+
+**After every phase** — update Run per [run/RUN.md](run/RUN.md):
+
+- Append `log[]`, move phase to `completed`, write checkpoint, store artifacts
+- Record routing and capability resolution in `decisions[]`
+- Persist `run.json`
+
+### Work vs gate
+
+| `phase_kind` | Phases | Purpose |
+|--------------|--------|---------|
+| `work` | discover … plan, execute … report | Do the work |
+| `gate` | validate, impact_analysis, dependency_graph, fitness_functions, rollback | Approval / checkpoints |
+
+Gates run after `plan`, before `execute` (or before `report` when verb has no execute).
+
+### Gate rules
+
+| Gate | Skill |
+|------|-------|
+| **validate** | [validation/SKILL.md](../skills/shared/validation/SKILL.md) |
+| **impact_analysis** | [impact-analysis/SKILL.md](../skills/shared/impact-analysis/SKILL.md) |
+| **dependency_graph** | [dependency-graph/SKILL.md](../skills/shared/dependency-graph/SKILL.md) |
+| **fitness_functions** | [fitness-functions/SKILL.md](../skills/shared/fitness-functions/SKILL.md) |
+| **rollback** | [rollback/SKILL.md](../skills/shared/rollback/SKILL.md) when maturity or blast radius requires |
+
+### Human approval at gate boundaries
+
+When a gate fails or confidence is below threshold:
+
+```yaml
+status: blocked
+awaiting_approval: true
+blocked_reason: "<specific reason>"
+```
+
+```text
+STOP — awaiting approval
+Reason: {blocked_reason}
+Run: {run_id}
+```
+
+Do **not** proceed until user approves in chat. On approval: log decision, set `status: running`, `awaiting_approval: false`, retry gate or continue.
+
+**Code changes:** [governance/implementation/SKILL.md](../skills/shared/governance/implementation/SKILL.md) is mandatory for `execute`.
+
+**Investigation depth:**
+
+| Verb | Investigation |
+|------|----------------|
+| create | [investigation-lite](../skills/shared/investigation-lite/SKILL.md) |
+| update | [investigation-lite](../skills/shared/investigation-lite/SKILL.md) |
+| fix | [investigation](../skills/shared/investigation/SKILL.md) → [root-cause](../skills/shared/root-cause/SKILL.md) |
+
+## 5. Report
+
+[reporting/SKILL.md](../skills/shared/reporting/SKILL.md) — plain language first; include confidence, impact, fitness, rollback from Run artifacts. Set Run `status: completed`.
+
+## Regenerating
+
+```bash
+node .cursor/aaac/generate-graph.mjs
+node .cursor/aaac/generate-commands.mjs
+```