@ludecker/aaac 1.0.0 → 1.1.1

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

@@ -2,44 +2,44 @@
   "version": 2,
   "capabilities": {
     "ui-design": {
-      "description": "Design tokens, component CSS, presentational UI",
+      "description": "Design tokens, component CSS, Figma alignment",
       "providers": [
-        { "id": "component", "type": "skill", "path": "skills/shared/component" }
+        { "id": "ludecker-design-system", "type": "skill", "path": "skills/ludecker/design-system" }
       ]
     },
     "ux-design": {
-      "description": "User flows, readability, navigation clarity",
+      "description": "Editorial readability, publish flow, navigation clarity",
       "providers": [
-        { "id": "workflow", "type": "skill", "path": "skills/shared/workflow" }
+        { "id": "ludecker-user-experience", "type": "skill", "path": "skills/ludecker/user-experience" }
       ]
     },
     "api-design": {
       "description": "Contracts and validation at boundaries",
       "providers": [
-        { "id": "integration", "type": "skill", "path": "skills/shared/integration" }
+        { "id": "ludecker-api-first", "type": "skill", "path": "skills/ludecker/api-first" }
       ]
     },
     "database-design": {
-      "description": "Schema, migrations, persistence contracts",
+      "description": "Schema, migrations, RLS, type mirrors",
       "providers": [
-        { "id": "schema", "type": "skill", "path": "skills/shared/schema" },
-        { "id": "migration", "type": "skill", "path": "skills/shared/migration" }
+        { "id": "ludecker-database-schema", "type": "skill", "path": "skills/ludecker/database-schema" },
+        { "id": "supabase-mcp", "type": "mcp", "optional": true, "note": "Apply migrations and RLS via Supabase MCP" }
       ]
     },
     "security": {
-      "description": "Auth, secrets, access control — extend with project skills",
+      "description": "Auth, RLS, secrets, CMS gates",
       "providers": [
-        { "id": "architecture", "type": "skill", "path": "skills/shared/architecture" }
+        { "id": "ludecker-security", "type": "skill", "path": "skills/ludecker/security" }
       ]
     },
     "infrastructure": {
-      "description": "Deploy, hosting, environment",
+      "description": "Deploy, Render, env, hosting",
       "providers": [
-        { "id": "platform-release", "type": "skill", "path": "skills/shared/platform-release" }
+        { "id": "ludecker-infrastructure", "type": "skill", "path": "skills/ludecker/infrastructure" }
       ]
     },
     "layer-boundaries": {
-      "description": "SSOT, import direction, module layers",
+      "description": "SSOT, import direction, monorepo layers",
       "providers": [
         { "id": "architecture", "type": "skill", "path": "skills/shared/architecture" }
       ]
@@ -65,7 +65,8 @@
     "migration-model": {
       "description": "Migration scripts and apply procedure",
       "providers": [
-        { "id": "migration", "type": "skill", "path": "skills/shared/migration" }
+        { "id": "migration", "type": "skill", "path": "skills/shared/migration" },
+        { "id": "supabase-mcp", "type": "mcp", "optional": true }
       ]
     },
     "workflow-model": {
@@ -101,6 +102,7 @@
   },
   "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"
+    "run_record": "all providers including type=mcp recorded on Run.capabilities_resolved and decisions",
+    "lifecycle": "cross-run state in state/capability-stats.json; promotion thresholds in promotion-rules.json; updated by capability-evidence.mjs after each completed Run"
   }
 }

package/templates/cursor/aaac/complexity.yaml

@@ -0,0 +1,98 @@
+# Complexity governance — SSOT for create / update / fix (code-changing verbs)
+# Policy: .cursor/policies/minimal-complexity.md
+# Scored in plan; validated at validate gate; enforced at fitness_functions gate.
+
+version: 1
+
+mutating_verbs: [create, update, fix]
+
+optimization:
+  target: "maximum outcome / minimum structure"
+  default_verb_when_ambiguous: update
+
+strategy_priority:
+  - reuse_existing
+  - extend_existing
+  - modify_existing
+  - create_new
+
+scoring:
+  description: Sum weights for every net-new artifact in the plan (not edits to existing files).
+  weights:
+    new_file: 1
+    new_component: 1
+    new_function: 1
+    new_hook: 1
+    new_module: 3
+    new_service: 5
+    new_api_endpoint: 2
+    new_table: 3
+    new_migration: 2
+    new_state_machine: 4
+    new_queue_or_bus: 5
+    new_abstraction_layer: 4
+    new_orchestrator: 4
+    new_skill: 2
+    new_dependency: 2
+
+thresholds:
+  fix: 5
+  update: 8
+  create: 12
+
+yagni:
+  rule: Future requirements do not exist unless the user stated them.
+  reject_without_user_evidence:
+    - maybe later
+    - might need
+    - future-proof
+    - future proof
+    - scalability
+    - extensibility
+    - plugin system
+    - event bus
+    - generic framework
+    - abstraction layer
+    - for flexibility
+    - potential use case
+
+plan_artifact:
+  path: Run.artifacts.plan
+  required_for_verbs: [create, update, fix]
+  required_fields:
+    requirement_map:
+      description: Each stated requirement mapped to satisfying artifacts
+      item_shape:
+        requirement: string
+        satisfies_with: list
+    complexity_score: number
+    complexity_breakdown: object
+    reuse:
+      description: Existing artifacts to reuse or extend (preferred)
+      type: list
+    modify:
+      description: Existing artifacts to change in place
+      type: list
+    create:
+      description: Net-new artifacts — each must cite requirement_map entry
+      item_shape:
+        artifact: string
+        kind: string
+        requirement_ref: string
+        why_not_reuse: string
+    rejected_alternatives:
+      description: Higher-complexity options considered and rejected
+      type: list
+
+gate_rules:
+  validate:
+    fail_when:
+      - missing required plan fields for mutating verb
+      - create entry without requirement_ref or why_not_reuse
+      - yagni phrase in plan without user intent evidence
+  fitness_functions:
+    function: minimal_complexity
+    fail_when:
+      - complexity_score above threshold for verb
+      - speculative create not justified
+    blocking: true

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

@@ -1,12 +1,13 @@
 name: fix-bug
-purpose: Repair broken behavior in a domain
+purpose: Repair broken behavior in a domain (alias of fix-module workflow)
 inputs:
   domain:
     required: false
+    enum: [cms, ui, database, aaac]
   intent:
     required: true
 outputs:
-  findings:
+  investigation:
     type: markdown
     required: true
   root_cause:
@@ -24,9 +25,15 @@ outputs:
     type: markdown
     required: true
 lifecycle_verb: fix
+workflow: fix-bug
 success_criteria:
-  - deep investigation and root_cause before plan
+  - discovery swarm completed (4-6 agents)
+  - fix investigation swarm completed (7 parallel agents)
+  - root_cause confidence at least 0.7
+  - repro_status fixed after execute
   - impact_analysis proceed yes or rollback defined
 failure_conditions:
+  - skip discovery or investigate_swarm phase
   - root_cause confidence below 0.7
   - symptom patch without root cause frame
+  - repro_status not_fixed while claiming success

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

@@ -0,0 +1,41 @@
+name: fix-module
+purpose: Repair broken behavior in a bounded domain module
+inputs:
+  domain:
+    required: true
+    enum: [cms, ui, database, aaac]
+  intent:
+    required: true
+outputs:
+  investigation:
+    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
+workflow: fix-module
+success_criteria:
+  - discovery swarm completed (4-6 agents)
+  - fix investigation swarm completed (7 parallel agents)
+  - root_cause confidence at least 0.7
+  - repro_status fixed after execute
+  - domain inventory Section 3 synced after execute
+  - complexity_score at most 5
+failure_conditions:
+  - skip discovery or investigate_swarm phase
+  - plan or execute before root_cause artifact
+  - symptom patch without root cause frame
+  - repro_status not_fixed while claiming success
+  - domain slug missing for resolver commands

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

@@ -1,9 +1,22 @@
 name: investigation
-purpose: Deep investigation for fix paths and incidents
+purpose: Deep investigation swarm for fix paths and incidents
 outputs:
+  investigation_frame:
+    type: object
+    required: true
   findings:
     type: list
     required: true
+  repro_steps:
+    type: list
+    required: true
+  repro_confirmed:
+    type: string
+    required: true
+    enum: [yes, partial, no]
+  suspect_files:
+    type: list
+    required: true
   risks:
     type: list
     required: true
@@ -14,4 +27,12 @@ outputs:
     type: object
     required: true
     fields: [architecture, requirements, scope]
+swarm:
+  fix_path:
+    prerequisite: discovery
+    agents: 7
+    parallel: mandatory
+  incident_path:
+    agents: 4
+    parallel: mandatory
 readonly: true

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

@@ -0,0 +1,17 @@
+name: planning
+purpose: Plan mutating changes with complexity score and requirement map before execute
+applies_to_verbs: [create, update, fix]
+outputs:
+  plan:
+    type: object
+    required_for_verbs: [create, update, fix]
+    required_fields:
+      - requirement_map
+      - complexity_score
+      - complexity_breakdown
+      - reuse
+      - modify
+      - create
+      - rejected_alternatives
+    store_at: Run.artifacts.plan
+readonly: true

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

@@ -1,5 +1,6 @@
 name: validation
-purpose: Confidence gates before execute
+purpose: Confidence and complexity gates before execute (mutating verbs)
+applies_to_verbs: [create, update, fix]
 outputs:
   validation:
     type: enum
@@ -8,6 +9,13 @@ outputs:
   scores:
     type: object
     required: true
+  complexity:
+    type: object
+    required_for_verbs: [create, update, fix]
+    fields:
+      score: number
+      threshold: number
+      pass: boolean
   clarification_questions:
     type: list
     required_when: validation fail

package/templates/cursor/aaac/dispatch.md

@@ -2,10 +2,22 @@
 
 Agents running any AAAC command **must** follow this sequence.
 
+**Enforcement (runtime):** Cursor hooks in [.cursor/hooks.json](../hooks.json) create Runs and **block code edits** until the `execute` phase. See [.cursor/rules/aaac-enforcement.mdc](../rules/aaac-enforcement.mdc). Applies to **all** AAAC slash commands.
+
 **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).
 
+## 0. Hook-initiated Run (automatic)
+
+On submit, hooks call [scripts/run-engine/init-run.mjs](../scripts/run-engine/init-run.mjs). Follow `run.json` phases. `preToolUse` denies Write/StrReplace/Delete outside allowed phases.
+
+Advance after swarm + artifacts:
+
+```bash
+node .cursor/aaac/scripts/run-engine/advance-phase.mjs <run_id> <completed_phase>
+```
+
 ## 1. Parse input
 
 From `$ARGUMENTS` and the user message:
@@ -21,6 +33,8 @@ If intent contains `Sync inventory only` (case-insensitive), orchestrator runs *
 
 **Resume:** If user references `run_{id}`, load `state/runs/{run_id}/run.json` and continue from `phase`.
 
+**Workflow exceptions:** Commands like `write-article` use `command_workflows.<command>` in graph (not `verb_runtime`). `fix-module` and `fix-bug` also have explicit workflows matching the fix verb runtime. No governance gate stack unless orchestrator specifies one.
+
 **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).
@@ -37,9 +51,10 @@ Read [graph.yaml](graph.yaml) and [ontology.json](ontology.json).
 - **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
+- **Capabilities:** resolve `object_capabilities.<object>` via [capabilities/registry.json](capabilities/registry.json) — `init-run.mjs` records providers on `Run.capabilities_resolved`; on completion `capability-evidence.mjs` aggregates evidence into [state/capability-stats.json](state/capability-stats.json) and evaluates [capabilities/promotion-rules.json](capabilities/promotion-rules.json)
 - **Dependencies:** [dependencies.yaml](dependencies.yaml)
-- **Fitness:** [fitness-functions.yaml](fitness-functions.yaml)
+- **Fitness:** [fitness-functions.yaml](fitness-functions.yaml) — includes `minimal_complexity` for create/update/fix
+- **Complexity:** [complexity.yaml](complexity.yaml) + [minimal-complexity.md](../policies/minimal-complexity.md) for create/update/fix
 - **Contracts:** validate against [contracts/commands/](contracts/commands/) and [contracts/skills/](contracts/skills/)
 
 ## 2.5 Create or resume Run
@@ -47,7 +62,7 @@ Read [graph.yaml](graph.yaml) and [ontology.json](ontology.json).
 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)
+2. Set `pending` from `command_workflows.<command>` when present, else `verb_runtime.<verb>`
 3. Set `status: running`, first `phase`, `phase_kind: work`
 4. Record resolved orchestrator, object, domain, intent on Run
 
@@ -63,6 +78,7 @@ All state and observability live on the Run — **no** standalone execution-stat
   - [master-rules.md](../policies/master-rules.md)
   - [implementation.md](../policies/implementation.md)
   - [mcp-and-deploy.md](../policies/mcp-and-deploy.md)
+  - [minimal-complexity.md](../policies/minimal-complexity.md) — **create / update / fix only**
 - 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
 
@@ -89,10 +105,10 @@ Gates run after `plan`, before `execute` (or before `report` when verb has no ex
 
 | Gate | Skill |
 |------|-------|
-| **validate** | [validation/SKILL.md](../skills/shared/validation/SKILL.md) |
+| **validate** | [validation/SKILL.md](../skills/shared/validation/SKILL.md) — confidence + **complexity plan** |
 | **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) |
+| **fitness_functions** | [fitness-functions/SKILL.md](../skills/shared/fitness-functions/SKILL.md) — **`minimal_complexity` blocks on fail** |
 | **rollback** | [rollback/SKILL.md](../skills/shared/rollback/SKILL.md) when maturity or blast radius requires |
 
 ### Human approval at gate boundaries
@@ -121,7 +137,16 @@ Do **not** proceed until user approves in chat. On approval: log decision, set `
 |------|----------------|
 | 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) |
+| fix | [investigation](../skills/shared/investigation/SKILL.md) Mode A (7-agent swarm) → [root-cause](../skills/shared/root-cause/SKILL.md) |
+
+### Fix swarm (mandatory on fix verb / fix_mode)
+
+1. **discover** — 4–6 parallel Task agents per [discovery/SKILL.md](../skills/shared/discovery/SKILL.md)
+2. **investigate_swarm** — 7 parallel Task agents per investigation Mode A — **one message**
+3. **root_cause** — artifact required; confidence ≥ 0.7 before plan
+4. **verify** — fix verify swarm (3 parallel) per [testing/SKILL.md](../skills/shared/testing/SKILL.md); **website build gate** (`verify-website-build.mjs`) must pass for create/update/fix; fail if `repro_status: not_fixed`
+
+Skipping swarms because the issue "looks simple" is a **contract violation** for `fix-module` / `fix-bug` / `fix_mode`.
 
 ## 5. Report
 

package/templates/cursor/aaac/enforcement.json

@@ -0,0 +1,25 @@
+{
+  "version": 2,
+  "description": "AAAC runtime enforcement — SSOT for hooks and run engine",
+  "edit_phases": ["execute", "sync_inventory", "persist", "write"],
+  "artifact_write_phases": ["plan", "report", "verify"],
+  "verify_verbs": ["create", "update", "fix"],
+  "swarm_min_agents": {
+    "discover": 4,
+    "investigate_swarm": 7,
+    "research_swarm": 6,
+    "verify_fix": 3
+  },
+  "phase_artifacts": {
+    "investigate_swarm": ["artifacts/investigation.md"],
+    "root_cause": ["artifacts/root_cause.yaml"],
+    "plan": ["artifacts/plan.yaml"],
+    "verify": ["artifacts/verify.yaml"],
+    "report": ["artifacts/report.md"]
+  },
+  "allowed_path_prefixes": {
+    "run_artifacts": [".cursor/aaac/state/runs/", "aaac/state/runs/"],
+    "write_article": [".cursor/write-article-runs/"]
+  },
+  "fix_commands": ["fix-module", "fix-bug", "module-fix", "bug-fix"]
+}

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

@@ -28,6 +28,14 @@ functions:
     skill: architecture
     applies_to: [module, component, feature, app]
 
+  minimal_complexity:
+    description: Reuse-first plan, complexity score within verb threshold, YAGNI — no speculative architecture
+    policy: minimal-complexity
+    config: aaac/complexity.yaml
+    applies_to: [function, component, module, schema, model, migration, feature, workflow, integration, app, domain, architecture]
+    applies_to_verbs: [create, update, fix]
+    blocking: true
+
 scoring:
   pass: meets criteria
   warning: minor gap — document in report, may proceed if user intent clear

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

@@ -24,10 +24,14 @@
     "human_approval": {
       "trigger_when": [
         "confidence below threshold",
-        "fitness fail on security or layer_boundaries",
+        "fitness fail on security or layer_boundaries or minimal_complexity",
+        "complexity score above verb threshold",
+        "plan missing requirement_map or unjustified create",
         "impact proceed false",
         "rollback unverified",
-        "user intent contains requires approval"
+        "user intent contains requires approval",
+        "capability runtime require_approval",
+        "capability state deprecated"
       ],
       "run_fields": {
         "status": "blocked",