@ludecker/aaac 1.0.0

package/templates/cursor/aaac/fitness-functions.yaml

@@ -0,0 +1,34 @@
+# Architecture fitness functions — scored before execute, re-checked in verify.
+
+version: 1
+
+functions:
+  api_first:
+    description: Contracts and validation at boundaries; no ad-hoc API shapes
+    skill: integration
+    applies_to: [integration, feature, workflow, module, function]
+
+  layer_boundaries:
+    description: SSOT, import direction, module size budgets
+    skill: architecture
+    applies_to: [module, component, feature, domain, app]
+
+  component_quality:
+    description: Presentational components, reusable props, accessible markup
+    skill: component
+    applies_to: [component, module]
+
+  data_contracts:
+    description: Schema and model alignment at persistence boundaries
+    skill: schema
+    applies_to: [schema, model, migration]
+
+  performance:
+    description: Deterministic builds, no unnecessary fetch in UI layers
+    skill: architecture
+    applies_to: [module, component, feature, app]
+
+scoring:
+  pass: meets criteria
+  warning: minor gap — document in report, may proceed if user intent clear
+  fail: blocking — STOP before execute unless user explicitly accepts risk

package/templates/cursor/aaac/governance/gates.json

@@ -0,0 +1,39 @@
+{
+  "version": 1,
+  "description": "Governance gates — approval/checkpoints, not work phases. Composed into runtime after plan, before execute.",
+  "stacks": {
+    "pre_execute": [
+      "validate",
+      "impact_analysis",
+      "dependency_graph",
+      "fitness_functions",
+      "rollback"
+    ],
+    "pre_execute_minimal": [
+      "validate",
+      "impact_analysis",
+      "dependency_graph",
+      "fitness_functions"
+    ],
+    "release": ["validate"]
+  },
+  "gate_rules": {
+    "rollback": {
+      "required_when": ["object_maturity:protected", "impact.blast_radius:high"]
+    },
+    "human_approval": {
+      "trigger_when": [
+        "confidence below threshold",
+        "fitness fail on security or layer_boundaries",
+        "impact proceed false",
+        "rollback unverified",
+        "user intent contains requires approval"
+      ],
+      "run_fields": {
+        "status": "blocked",
+        "awaiting_approval": true,
+        "blocked_reason": "string"
+      }
+    }
+  }
+}

package/templates/cursor/aaac/graph.project.yaml

@@ -0,0 +1,161 @@
+orchestrators:
+  update-doc:
+    path: skills/shared/documentation/orchestrator
+    requires: [discovery, documentation, reporting]
+    readonly: true
+
+  review-incident:
+    path: skills/shared/investigation/orchestrator
+    requires: [discovery, investigation, reporting]
+    optional: [execution]
+
+  review-module:
+    path: skills/shared/architecture/orchestrator
+    requires: [discovery, architecture, reporting]
+    readonly: true
+
+  verb-check:
+    path: skills/shared/verbs/check/orchestrator
+    requires: [check, reporting]
+    readonly: true
+
+  test-function:
+    path: skills/shared/testing/orchestrator
+    requires: [discovery, testing, verification, reporting]
+
+  release-app:
+    path: skills/shared/platform-release/orchestrator
+    requires: [testing, verification, execution, reporting]
+
+  verb-create:
+    path: skills/shared/verbs/create/orchestrator
+    requires: [discovery, investigation-lite, planning, validation, impact-analysis, dependency-graph, fitness-functions, rollback, execution, testing, verification, reporting, module-authoring]
+
+  verb-update:
+    path: skills/shared/verbs/update/orchestrator
+    requires: [discovery, investigation-lite, planning, validation, impact-analysis, dependency-graph, fitness-functions, rollback, execution, testing, verification, reporting]
+
+  verb-fix:
+    path: skills/shared/verbs/fix/orchestrator
+    requires: [discovery, investigation, root-cause, planning, validation, impact-analysis, dependency-graph, fitness-functions, rollback, execution, testing, verification, reporting]
+
+  verb-review:
+    path: skills/shared/verbs/review/orchestrator
+    requires: [discovery, architecture, reporting]
+    readonly: true
+
+  verb-test:
+    path: skills/shared/verbs/test/orchestrator
+    requires: [discovery, planning, testing, verification, reporting]
+
+  verb-release:
+    path: skills/shared/verbs/release/orchestrator
+    requires: [testing, verification, execution, reporting]
+
+  verb-remove:
+    path: skills/shared/verbs/remove/orchestrator
+    requires: [discovery, remove, execution, testing, verification, reporting]
+
+{{INJECT_OBJECT_BLOCKS}}
+
+skills:
+  discovery:
+    path: skills/shared/discovery
+    agents: [discovery-inventory, discovery-boundaries, discovery-ssot]
+  planning:
+    path: skills/shared/planning
+    agents: [plan-layer-map, plan-state-machines]
+  execution:
+    path: skills/shared/execution
+    depends: [governance/implementation]
+  testing:
+    path: skills/shared/testing
+    agents: [unit-test-run, fallow-check-changed]
+  verification:
+    path: skills/shared/verification
+  reporting:
+    path: skills/shared/reporting
+  architecture:
+    path: skills/shared/architecture
+    agents: [boundary-review, dependency-analysis, system-decomposition]
+  documentation:
+    path: skills/shared/documentation
+  investigation:
+    path: skills/shared/investigation
+  investigation-lite:
+    path: skills/shared/investigation-lite
+  root-cause:
+    path: skills/shared/root-cause
+  validation:
+    path: skills/shared/validation
+  impact-analysis:
+    path: skills/shared/impact-analysis
+    agents: [impact-analysis]
+  dependency-graph:
+    path: skills/shared/dependency-graph
+    agents: [dependency-analysis]
+  fitness-functions:
+    path: skills/shared/fitness-functions
+  rollback:
+    path: skills/shared/rollback
+  run:
+    path: skills/shared/run
+  check:
+    path: skills/shared/check
+    agents: [discovery-inventory, discovery-ssot, check-capability-trace]
+  component:
+    path: skills/shared/component
+  model:
+    path: skills/shared/model
+  migration:
+    path: skills/shared/migration
+  domain:
+    path: skills/shared/domain
+  schema:
+    path: skills/shared/schema
+  workflow:
+    path: skills/shared/workflow
+  integration:
+    path: skills/shared/integration
+  remove:
+    path: skills/shared/remove
+  module-authoring:
+    path: skills/shared/module-authoring
+  platform-release:
+    path: skills/shared/platform-release
+  governance/implementation:
+    path: skills/shared/governance/implementation
+
+agents:
+  discovery-inventory:
+    path: agents/discovery-inventory.md
+  discovery-boundaries:
+    path: agents/discovery-boundaries.md
+  discovery-ssot:
+    path: agents/discovery-ssot.md
+  plan-layer-map:
+    path: agents/plan-layer-map.md
+  plan-state-machines:
+    path: agents/plan-state-machines.md
+  boundary-review:
+    path: agents/boundary-review.md
+  dependency-analysis:
+    path: agents/dependency-analysis.md
+  system-decomposition:
+    path: agents/system-decomposition.md
+  unit-test-run:
+    path: agents/unit-test-run.md
+  fallow-check-changed:
+    path: agents/fallow-check-changed.md
+  check-capability-trace:
+    path: agents/check-capability-trace.md
+  impact-analysis:
+    path: agents/impact-analysis.md
+  release-git:
+    path: agents/release-git.md
+    wave: 1
+    blocking: true
+
+policies:
+  - policies/master-rules.md
+  - policies/implementation.md

package/templates/cursor/aaac/layers.md

@@ -0,0 +1,93 @@
+# AAAC — responsibility layers
+
+AAAC is organized by **responsibility**, not by file type. Paths below map logical layers to current repo locations.
+
+## Layer model
+
+```text
+User Layer
+├─ Commands                    .cursor/commands/
+
+Control Layer
+├─ Ontology                    .cursor/aaac/ontology.json, ontology.md
+├─ Dispatch                    .cursor/aaac/dispatch.md
+├─ Graph                       .cursor/aaac/graph.yaml
+
+Lifecycle Layer (work)
+├─ Work phase definitions      .cursor/aaac/lifecycle/phases.json
+├─ Verb work lifecycles        .cursor/aaac/lifecycle/lifecycle.json
+
+Governance Layer (gates + rules)
+├─ Gate stacks                 .cursor/aaac/governance/gates.json
+├─ Policies                    .cursor/policies/
+├─ Rules                       .cursor/rules/
+├─ Dependencies                .cursor/aaac/dependencies.yaml
+├─ Fitness functions           .cursor/aaac/fitness-functions.yaml
+
+Run Layer (primary execution object)
+├─ Run schema                  .cursor/aaac/run/schema.json
+├─ Run protocol                .cursor/aaac/run/RUN.md
+├─ Run storage                 .cursor/aaac/state/runs/{run_id}/run.json
+├─ Observability on Run        run.decisions, run.log, run.checkpoints
+
+Execution Layer
+├─ Domain orchestrators        .cursor/domains/<slug>/update/orchestrator/
+├─ Verb orchestrators          .cursor/skills/shared/verbs/*/orchestrator/
+├─ Shared pipeline skills      .cursor/skills/shared/
+├─ Capability registry         .cursor/aaac/capabilities/registry.json
+├─ Agent specs                 .cursor/agents/
+
+Knowledge Layer
+├─ Documentation               docs/agentic_architecture.md, docs/architecture.md, …
+
+Contracts Layer (cross-cutting)
+├─ Schema                      .cursor/aaac/contract-schema.md
+├─ Command contracts           .cursor/aaac/contracts/commands/
+├─ Skill contracts             .cursor/aaac/contracts/skills/
+```
+
+## Responsibilities
+
+| Component | Layer | Responsibility |
+|-----------|-------|----------------|
+| Commands | User | User-facing API |
+| Ontology | Control | Vocabulary and classification |
+| Dispatch | Control | Command resolution and escalation |
+| Graph | Control | Execution routing |
+| Lifecycle | Lifecycle | **Work** phase configuration |
+| Gate stacks | Governance | **Approval** checkpoints |
+| Run | Run | Primary execution object; state + observability |
+| Domain orchestrators | Execution | Domain coordination |
+| Shared pipeline skills | Execution | Phase execution |
+| Capability registry | Execution | object → capability → provider |
+| Agent specs | Execution | Agent behavior |
+| Policies | Governance | Mandatory governance |
+| Contracts | Contracts | Input/output invariants |
+| Documentation | Knowledge | System knowledge |
+
+## Questions each layer answers
+
+| Layer | Question |
+|-------|----------|
+| User | What does the user want? |
+| Control | What command, object, orchestrator? |
+| Lifecycle | What **work** happens, in what order? |
+| Governance | What **gates** must pass? What rules apply? |
+| Run | Where are we? Why? What was decided? |
+| Execution | Who does the work? |
+| Contracts | What must be true in/out? |
+| Knowledge | What does the system mean? |
+
+## Load order (mutating commands)
+
+```text
+Policies → Ontology → Graph → Create Run
+→ Lifecycle (work) + Gates (composed into Run.pending)
+→ Orchestrator → Capabilities resolved (recorded on Run)
+→ Execute phases → Update Run → Report
+```
+
+## Deprecated
+
+- `state/execution-state.yaml` — superseded by `run/schema.json`
+- `observability/decision-log.md`, `execution-log.md` — superseded by Run fields

package/templates/cursor/aaac/lifecycle/lifecycle.json

@@ -0,0 +1,78 @@
+{
+  "version": 2,
+  "description": "Work lifecycle only. Gates are in governance/gates.json. Runtime = work through plan → gate stack → execute through report.",
+  "verbs": {
+    "create": {
+      "work_phases": [
+        "discover",
+        "investigate_lite",
+        "plan",
+        "execute",
+        "verify",
+        "report"
+      ],
+      "gate_stack": "pre_execute"
+    },
+    "update": {
+      "work_phases": [
+        "discover",
+        "investigate_lite",
+        "plan",
+        "execute",
+        "verify",
+        "report"
+      ],
+      "gate_stack": "pre_execute"
+    },
+    "fix": {
+      "work_phases": [
+        "discover",
+        "investigate",
+        "root_cause",
+        "plan",
+        "execute",
+        "verify",
+        "report"
+      ],
+      "gate_stack": "pre_execute"
+    },
+    "review": {
+      "work_phases": ["discover", "plan", "report"],
+      "gate_stack": null
+    },
+    "check": {
+      "work_phases": ["discover", "report"],
+      "gate_stack": "pre_execute_minimal"
+    },
+    "test": {
+      "work_phases": ["discover", "plan", "verify", "report"],
+      "gate_stack": null
+    },
+    "release": {
+      "work_phases": ["execute", "verify", "report"],
+      "gate_stack": "release"
+    },
+    "remove": {
+      "work_phases": [
+        "discover",
+        "investigate_lite",
+        "plan",
+        "execute",
+        "verify",
+        "report"
+      ],
+      "gate_stack": "pre_execute"
+    }
+  },
+  "investigation_depth": {
+    "create": "lite",
+    "update": "lite",
+    "fix": "deep",
+    "remove": "lite"
+  },
+  "runtime_compose": "work_phases before execute + gate_stack + work_phases from execute onward",
+  "escalation": {
+    "on_gate_fail": "STOP_REQUEST_CLARIFICATION",
+    "on_human_approval_required": "blocked"
+  }
+}

package/templates/cursor/aaac/lifecycle/phases.json

@@ -0,0 +1,19 @@
+{
+  "version": 2,
+  "description": "Phase id to skill mapping. gate:true phases are governance gates, not lifecycle work.",
+  "phases": {
+    "discover": { "skill": "discovery", "readonly": true },
+    "investigate_lite": { "skill": "investigation-lite", "readonly": true },
+    "investigate": { "skill": "investigation", "readonly": true },
+    "root_cause": { "skill": "root-cause", "readonly": true },
+    "plan": { "skill": "planning" },
+    "validate": { "skill": "validation", "gate": true },
+    "impact_analysis": { "skill": "impact-analysis", "gate": true },
+    "dependency_graph": { "skill": "dependency-graph", "gate": true },
+    "fitness_functions": { "skill": "fitness-functions", "gate": true },
+    "rollback": { "skill": "rollback", "gate": true },
+    "execute": { "skill": "execution" },
+    "verify": { "skills": ["testing", "verification"] },
+    "report": { "skill": "reporting" }
+  }
+}

package/templates/cursor/aaac/ontology.json

@@ -0,0 +1,219 @@
+{
+  "verbs": {
+    "create": "create something new",
+    "update": "modify existing thing",
+    "fix": "repair something broken",
+    "review": "analyze and give feedback",
+    "check": "validate or inspect",
+    "test": "verify behavior",
+    "release": "deploy or ship",
+    "remove": "delete or retire"
+  },
+  "layers": {
+    "code": {
+      "order": 1,
+      "objects": ["function", "component", "module"],
+      "description": "Variables up through bounded code units"
+    },
+    "data": {
+      "order": 2,
+      "objects": ["schema", "model", "migration"],
+      "description": "Persistence shape and change"
+    },
+    "product": {
+      "order": 3,
+      "objects": ["feature", "workflow", "integration"],
+      "description": "User-visible capability and cross-system flow"
+    },
+    "system": {
+      "order": 4,
+      "objects": ["app", "domain", "architecture"],
+      "description": "Application, bounded context, and system structure"
+    }
+  },
+  "objects": {
+    "function": {
+      "layer": "code",
+      "description": "Function, method, or hook — specific behavior",
+      "maturity": "evolving"
+    },
+    "component": {
+      "layer": "code",
+      "description": "UI component, view, or composable unit",
+      "maturity": "evolving"
+    },
+    "module": {
+      "layer": "code",
+      "description": "Bounded domain package (service, library, plugin)",
+      "maturity": "critical"
+    },
+    "schema": {
+      "layer": "data",
+      "description": "Tables, RLS, database contracts",
+      "maturity": "protected"
+    },
+    "model": {
+      "layer": "data",
+      "description": "Entity, type, or shared data shape in code",
+      "maturity": "critical"
+    },
+    "migration": {
+      "layer": "data",
+      "description": "Schema migration or data change script",
+      "maturity": "protected"
+    },
+    "feature": {
+      "layer": "product",
+      "description": "User-facing capability",
+      "maturity": "stable"
+    },
+    "workflow": {
+      "layer": "product",
+      "description": "Multi-step business process or state machine",
+      "maturity": "stable"
+    },
+    "integration": {
+      "layer": "product",
+      "description": "API, endpoint, webhook, MCP, or external adapter",
+      "maturity": "critical"
+    },
+    "app": {
+      "layer": "system",
+      "description": "Whole application deployable unit",
+      "maturity": "critical"
+    },
+    "domain": {
+      "layer": "system",
+      "description": "Bounded context / product domain",
+      "maturity": "critical"
+    },
+    "architecture": {
+      "layer": "system",
+      "description": "Boundaries, capabilities, architecture docs",
+      "maturity": "protected"
+    }
+  },
+  "verb_lifecycle_ref": "aaac/lifecycle/lifecycle.json",
+  "object_capabilities": {
+    "function": [],
+    "component": ["component-model", "layer-boundaries", "ui-design"],
+    "module": ["layer-boundaries"],
+    "schema": ["schema-model", "database-design", "security"],
+    "model": ["data-model", "schema-model"],
+    "migration": ["migration-model", "schema-model", "database-design", "security"],
+    "feature": ["workflow-model", "ux-design"],
+    "workflow": ["workflow-model", "ux-design"],
+    "integration": ["integration-model", "api-design"],
+    "app": ["layer-boundaries", "infrastructure"],
+    "domain": ["domain-model", "layer-boundaries"],
+    "architecture": ["layer-boundaries", "documentation"]
+  },
+  "object_capability_verbs": {
+    "module": {
+      "create": ["module-authoring"],
+      "review": ["layer-boundaries"]
+    },
+    "feature": {
+      "create": ["module-authoring"]
+    }
+  },
+  "confidence": {
+    "architecture": 0.9,
+    "requirements": 0.8,
+    "scope": 0.8
+  },
+  "object_maturity": {
+    "function": "evolving",
+    "component": "evolving",
+    "module": "critical",
+    "schema": "protected",
+    "model": "critical",
+    "migration": "protected",
+    "feature": "stable",
+    "workflow": "stable",
+    "integration": "critical",
+    "app": "critical",
+    "domain": "critical",
+    "architecture": "protected"
+  },
+  "maturity_rules": {
+    "protected": {
+      "requires_phases": ["impact_analysis", "dependency_graph", "rollback"],
+      "investigation": "lite_on_create_update_deep_on_fix"
+    },
+    "critical": {
+      "requires_phases": ["impact_analysis", "dependency_graph"],
+      "investigation": "lite_on_create_update_deep_on_fix"
+    },
+    "stable": {
+      "requires_phases": ["impact_analysis"],
+      "investigation": "lite_on_create_update_deep_on_fix"
+    },
+    "evolving": {
+      "requires_phases": [],
+      "investigation": "lite_on_create_update_deep_on_fix"
+    }
+  },
+  "invalid_pairs": [
+    ["release", "function"],
+    ["release", "component"],
+    ["release", "module"],
+    ["release", "schema"],
+    ["release", "model"],
+    ["release", "migration"],
+    ["release", "workflow"],
+    ["release", "architecture"],
+    ["release", "domain"]
+  ],
+  "domain_optional_suffixes": ["-function"],
+  "command_overrides": {
+    "fix-bug": { "orchestrator": "verb-fix", "object": "feature" },
+    "update-architecture": { "orchestrator": "update-doc" },
+    "review-module": { "orchestrator": "review-module" },
+    "review-incident": { "orchestrator": "review-incident" },
+    "test-function": { "orchestrator": "test-function" },
+    "release-app": { "orchestrator": "release-app" },
+    "module-update": { "alias": "update-module" },
+    "update-doc": { "alias": "update-architecture" },
+    "architecture": { "alias": "update-architecture" },
+    "swarm-check": { "alias": "review-incident" },
+    "refactor": { "alias": "review-module" }
+  },
+  "command_aliases": {
+    "update-api": "update-integration",
+    "create-api": "create-integration",
+    "fix-api": "fix-integration",
+    "check-api": "check-integration",
+    "test-api": "test-integration",
+    "review-api": "review-integration",
+    "remove-api": "remove-integration",
+    "update-spec": "update-architecture",
+    "create-spec": "create-architecture",
+    "review-spec": "review-architecture",
+    "fix-hook": "fix-function",
+    "create-hook": "create-function",
+    "review-hook": "review-function",
+    "check-hook": "check-function",
+    "create-endpoint": "create-integration",
+    "update-endpoint": "update-integration",
+    "fix-webhook": "fix-integration",
+    "fix-query": "fix-model",
+    "create-plugin": "create-module",
+    "review-service": "review-module",
+    "check-boundary": "check-architecture",
+    "review-graph": "review-architecture",
+    "check-inventory": "check-module",
+    "create-skill": "create-module",
+    "update-agent": "update-module",
+    "review-dashboard": "review-component",
+    "fix-pipeline": "fix-workflow",
+    "release-pipeline": "release-app",
+    "create-policy": "create-architecture",
+    "update-policy": "update-architecture",
+    "review-runbook": "review-architecture",
+    "create-form": "create-component",
+    "update-page": "update-component",
+    "review-flow": "review-workflow",
+    "update-flow": "update-workflow"
+  }
+}