@ludecker/aaac 1.0.0 → 1.1.1

package/templates/cursor/agents/fix-code-path.md

@@ -0,0 +1,27 @@
+# Agent: fix-code-path
+
+**Readonly.** Do not edit files.
+
+## Role
+
+Trace execution from symptom to the code that produces the behavior.
+
+## Inputs (from parent)
+
+- Intent and repro steps from `fix-repro` when available
+- Domain inventory file map
+
+## Procedure
+
+1. Start at user-visible surface (route, component, action, migration, API)
+2. Follow imports and call chain until data source or side effect
+3. Identify **suspect files** (max 10) with `path:line` anchors
+4. Note **branch points** (conditionals, env, auth, cache, ISR)
+5. Flag **layer violations** (Supabase in page, UI fetching, duplicate SSOT)
+
+## Return
+
+- Execution trace (ordered bullets)
+- Suspect files with evidence
+- Layer or boundary issues if any
+- Confidence: high | medium | low

package/templates/cursor/agents/fix-hypothesis-validate.md

@@ -0,0 +1,26 @@
+# Agent: fix-hypothesis-validate
+
+**Readonly.** Do not edit files.
+
+## Role
+
+Challenge the proposed root cause before planning — second opinion when confidence is borderline.
+
+## Inputs
+
+- Merged investigation + draft root_cause hypothesis
+- Evidence from fix-code-path and fix-recent-changes
+
+## Procedure
+
+1. State alternative hypotheses (max 3)
+2. For each: evidence for / against
+3. Recommend **proceed** | **investigate_more** with specific next checks
+4. Score root_cause confidence 0.0–1.0
+
+## Return
+
+- Alternative hypotheses ranked
+- Recommended action: proceed | investigate_more
+- root_cause_confidence: 0.0–1.0
+- Missing evidence (if investigate_more)

package/templates/cursor/agents/fix-inventory-confirm.md

@@ -0,0 +1,22 @@
+# Agent: fix-inventory-confirm
+
+**Readonly.** Do not edit files.
+
+## Role
+
+Validate domain inventory against actual repo layout for the fix scope.
+
+## Procedure
+
+1. Read `domains/<slug>/update/inventory/SKILL.md` when domain is known
+2. Confirm file map entries exist; flag stale or missing paths
+3. Restate **in scope** and **out of scope** for this fix
+4. List inventory **Section 2 constraints** that apply to the symptom
+
+## Return
+
+- Inventory freshness: current | stale | missing
+- Confirmed scope boundaries
+- Applicable constraints (bullets)
+- Recommended domain slug if ambiguous
+- Confidence: high | medium | low

package/templates/cursor/agents/fix-recent-changes.md

@@ -0,0 +1,22 @@
+# Agent: fix-recent-changes
+
+**Readonly.** Do not edit files.
+
+## Role
+
+Find recent changes that could have introduced the defect.
+
+## Procedure
+
+1. `git log --oneline -20` on suspect paths from inventory or code-path agent
+2. `git blame` on lines flagged by code-path agent when available
+3. Correlate with deploy dates, migration timestamps, or PR themes if mentioned in intent
+4. List **candidate commits** (hash + one-line summary + files touched)
+5. Rank **likelihood**: high | medium | low per candidate
+
+## Return
+
+- Candidate commits with likelihood
+- Files changed in window that match symptom scope
+- Regression hypothesis (one paragraph max)
+- Confidence: high | medium | low

package/templates/cursor/agents/fix-regression-scope.md

@@ -0,0 +1,27 @@
+# Agent: fix-regression-scope
+
+**Readonly.** Do not edit files.
+
+## Role
+
+Estimate blast radius and related features that could break from a fix.
+
+## Inputs
+
+- Domain inventory constraints and `depends_on` from `aaac/dependencies.yaml`
+- Suspect files from code-path agent
+
+## Procedure
+
+1. List **direct dependents** (imports, routes, types, RLS policies)
+2. Cross-reference [dependency-analysis.md](./dependency-analysis.md) patterns
+3. Tag risks: auth, migrations, ISR/revalidation, public API, design tokens
+4. Set **blast_radius**: low | medium | high
+
+## Return
+
+- Affected domains and surfaces
+- Risk tags
+- blast_radius
+- Features to spot-check after fix
+- Confidence: high | medium | low

package/templates/cursor/agents/fix-repro-verify.md

@@ -0,0 +1,21 @@
+# Agent: fix-repro-verify
+
+**Readonly** for investigation; may run dev server or tests to verify fix.
+
+## Role
+
+After execute, confirm the original repro steps now pass and no obvious regression.
+
+## Procedure
+
+1. Re-run repro steps from Run artifact `investigation.repro_steps`
+2. Run targeted tests from `fix-test-failures` recommendations
+3. Spot-check 2–3 items from `fix-regression-scope` when blast_radius ≥ medium
+4. Record **repro_status**: fixed | partial | not_fixed
+
+## Return
+
+- repro_status
+- Steps executed and outcomes
+- Regressions observed (if any)
+- Confidence: high | medium | low

package/templates/cursor/agents/fix-repro.md

@@ -0,0 +1,29 @@
+# Agent: fix-repro
+
+**Readonly.** Do not edit files.
+
+## Role
+
+Confirm the reported symptom and produce deterministic reproduction steps.
+
+## Inputs (from parent)
+
+- Intent (symptom + expected behavior)
+- Domain slug and inventory path when available
+- Route, URL, error message, or CLI output if provided
+
+## Procedure
+
+1. Restate **Issue**, **Symptoms**, **Expected** in one line each
+2. Find the smallest path to reproduce (route, component, query, migration, CLI command)
+3. List **repro steps** numbered (max 8 steps)
+4. Note **environment** (local dev, production, browser, auth state)
+5. Mark **repro_confirmed**: yes | partial | no — with evidence
+
+## Return
+
+- Findings (bullets, product language in summary)
+- Evidence (`path:line`, log snippet, test name — no secrets)
+- Gaps (what could not be reproduced)
+- `repro_confirmed`: yes | partial | no
+- Confidence: high | medium | low

package/templates/cursor/agents/fix-runtime-evidence.md

@@ -0,0 +1,22 @@
+# Agent: fix-runtime-evidence
+
+**Readonly.** Do not edit files.
+
+## Role
+
+Gather runtime evidence — logs, CI, MCP, browser errors — for the symptom.
+
+## Procedure
+
+1. If intent mentions CI or deploy → use `ci-investigator` subagent pattern or read recent workflow logs
+2. If database/RLS → Supabase MCP `get_logs`, `get_advisors` (project `anseivwusnyiwopihnqu`)
+3. If Render deploy → check deployment status via Render MCP when available
+4. If error message pasted → search codebase for matching string
+5. Never log secrets or tokens
+
+## Return
+
+- Runtime signals (errors, status codes, advisor findings)
+- Evidence sources (CI run, log type, MCP tool)
+- Whether symptom is **production-only** or **local-only**
+- Confidence: high | medium | low

package/templates/cursor/agents/fix-test-failures.md

@@ -0,0 +1,23 @@
+# Agent: fix-test-failures
+
+**Readonly.** Do not edit files unless running tests is required — prefer read-only test discovery.
+
+## Role
+
+Find existing tests, failures, and coverage gaps related to the symptom.
+
+## Procedure
+
+1. Search domain inventory for test paths and vitest config
+2. Run targeted tests only when necessary (`pnpm test` scoped to relevant package)
+3. List **failing tests** with assertion message and file
+4. List **missing coverage** — behavior with no test near suspect code
+5. Propose **minimal test** that would catch regression (describe only — do not implement)
+
+## Return
+
+- Existing tests covering symptom area
+- Failures (name, file, message)
+- Coverage gaps
+- Suggested regression test (one sentence)
+- Confidence: high | medium | low

package/templates/cursor/agents/playwright-check-run.md

@@ -0,0 +1,44 @@
+# Agent: playwright-check-run
+
+## Role
+
+Run AAAC verb contract Playwright checks and optional public-site smoke during verify.
+
+## When
+
+**Verify phase** for commands whose verb is `create`, `update`, or `fix` (including aliases such as `fix-module`, `create-component`, `update-module`).
+
+**Report phase** for commands whose verb is `check` (including `check-module`, `check-component`, …) — readonly; contract checks only.
+
+Contract checks always run. Browser smoke runs only when `PLAYWRIGHT_BASE_URL` is set.
+
+## Commands
+
+From repo root:
+
+```bash
+pnpm --filter @ludecker/aaac test:e2e
+```
+
+Optional website smoke (dev server or deployed URL):
+
+```bash
+PLAYWRIGHT_BASE_URL=http://localhost:3000 pnpm --filter @ludecker/aaac test:e2e
+```
+
+Interactive debugging:
+
+```bash
+pnpm --filter @ludecker/aaac test:e2e:ui
+```
+
+## What passes
+
+- `runtime-registry.json` command entries match `graph.yaml` `verb_runtime` for the command verb
+- Fix verb includes `investigate_swarm` and `root_cause` before `plan`
+- Check verb has no `execute` or `plan` — pending matches `verb_runtime.check`
+- Skipped browser tests when `PLAYWRIGHT_BASE_URL` is unset (CI default)
+
+## Return
+
+Exit code, failing spec file names, contract mismatch details (command vs `verb_runtime`), browser smoke failures with route and status.

package/templates/cursor/hooks/aaac-before-submit.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+exec node .cursor/aaac/scripts/run-engine/init-run.mjs

package/templates/cursor/hooks/aaac-pre-tool.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# AAAC: block code edits until execute phase. failClosed in hooks.json.
+set -euo pipefail
+exec node .cursor/aaac/scripts/run-engine/gate-write.mjs

package/templates/cursor/hooks/aaac-stop.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+exec node .cursor/aaac/scripts/run-engine/stop-check.mjs

package/templates/cursor/hooks/aaac-subagent-start.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+exec node .cursor/aaac/scripts/run-engine/record-task.mjs

package/templates/cursor/hooks.json

@@ -0,0 +1,30 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeSubmitPrompt": [
+      {
+        "command": ".cursor/hooks/aaac-before-submit.sh",
+        "matcher": "UserPromptSubmit"
+      }
+    ],
+    "preToolUse": [
+      {
+        "command": ".cursor/hooks/aaac-pre-tool.sh",
+        "matcher": "Write|StrReplace|Delete|EditNotebook|ApplyPatch",
+        "failClosed": true
+      }
+    ],
+    "subagentStart": [
+      {
+        "command": ".cursor/hooks/aaac-subagent-start.sh",
+        "failClosed": false
+      }
+    ],
+    "stop": [
+      {
+        "command": ".cursor/hooks/aaac-stop.sh",
+        "loop_limit": 5
+      }
+    ]
+  }
+}

package/templates/cursor/policies/minimal-complexity.md

@@ -0,0 +1,101 @@
+# Policy: Minimal complexity
+
+**SSOT:** [.cursor/aaac/complexity.yaml](../aaac/complexity.yaml)
+
+**Applies to:** `create`, `update`, `fix` commands (and domain orchestrators in those modes).
+
+**Loaded with:** master-rules, implementation, mcp-and-deploy — before plan phase on mutating verbs.
+
+## Optimization target
+
+```text
+User request
+  → Simplest solution that satisfies all stated requirements
+  → NOT the most elegant or future-proof architecture
+```
+
+Optimize **capability / complexity**, not capability alone.
+
+## Strategy priority (mandatory)
+
+Before proposing new artifacts, search and document in the plan:
+
+```text
+1. Reuse existing function / component / module
+2. Extend existing (minimal additive change)
+3. Modify existing in place
+4. Create new — only when 1–3 cannot satisfy a stated requirement
+```
+
+**Default verb bias:** prefer `update` over `create` when intent is ambiguous.
+
+## YAGNI
+
+Future requirements **do not exist** unless the user explicitly stated them.
+
+Reject plan items justified only by:
+
+- maybe later / might need
+- future-proofing / scalability / extensibility
+- generic framework / plugin system / event bus “for flexibility”
+
+If the user did state a future requirement, cite their exact words in `requirement_map`.
+
+## Complexity score
+
+Sum weights from [complexity.yaml](../aaac/complexity.yaml) for each **net-new** artifact in the plan.
+
+| Verb | Max score (block above) |
+|------|-------------------------|
+| fix | 5 |
+| update | 8 |
+| create | 12 |
+
+Lower score wins when comparing alternatives. Document rejected higher-score options in `rejected_alternatives`.
+
+## Plan artifact (required)
+
+Before `validate` gate on create/update/fix, write to Run `artifacts.plan`:
+
+```yaml
+requirement_map:
+  - requirement: "User can export CSV"
+    satisfies_with: ["ExportButton", "GET /api/export"]
+complexity_score: 2
+complexity_breakdown:
+  new_component: 0
+  new_api_endpoint: 1
+  modify: 1
+reuse:
+  - "ExportButton pattern from packages/ui"
+modify:
+  - "apps/website/app/api/export/route.ts (extend existing export handler)"
+create:
+  - artifact: "GET /api/export/csv"
+    kind: new_api_endpoint
+    requirement_ref: "User can export CSV"
+    why_not_reuse: "No existing CSV export route"
+rejected_alternatives:
+  - option: "Event bus + background queue + retry framework"
+    complexity_score: 14
+    rejected_because: "No requirement for async or retries"
+```
+
+## Gate enforcement
+
+| Gate | Check |
+|------|-------|
+| **validate** | Plan fields present; no unjustified create; YAGNI |
+| **fitness_functions** | `minimal_complexity` pass; score ≤ threshold |
+
+On fail → Run `blocked`, `awaiting_approval: true` — same as other gates.
+
+## Fix verb
+
+Fix plans must be **minimal correct change** — smallest diff that resolves root cause. Prefer modify over create. Score threshold is strictest (5).
+
+## Pruning mindset
+
+On create/update, ask: **what existing code can this replace or extend?**
+
+Deletion and simplification are in scope for `update`/`fix` when they reduce complexity without breaking requirements.

package/templates/cursor/rules/aaac-enforcement.mdc

@@ -0,0 +1,42 @@
+---
+description: AAAC pipeline enforcement — hooks block edits until Run reaches execute phase. Applies to ALL slash commands.
+alwaysApply: true
+---
+
+# AAAC enforcement (mandatory)
+
+**Runtime SSOT:** [.cursor/hooks.json](../hooks.json), [.cursor/aaac/enforcement.json](../aaac/enforcement.json)
+
+Every AAAC slash command (`/fix-module`, `/update-module`, `/write-article`, …) **must** execute inside a **Run**. This is not optional.
+
+## Prerequisites
+
+1. **Cursor Hooks enabled** — Settings → Hooks; restart Cursor after `.cursor/hooks.json` changes
+2. **Registry current** — `node .cursor/aaac/generate-graph.mjs`
+
+## Hook behavior (automatic)
+
+| Hook | Effect |
+|------|--------|
+| `beforeSubmitPrompt` | Detects `/command` → creates Run scoped to **`conversation_id`** (this chat only) |
+| `preToolUse` | **Denies** Write/StrReplace/Delete for **this chat only** until execute phase |
+| `subagentStart` | Counts Task launches for swarm phase validation |
+| `stop` | Follow-up if Run not `completed` |
+
+## Agent obligations
+
+1. **First action** after AAAC command: confirm Run exists for **this chat** (`.cursor/aaac/state/active-runs/{conversation_id}.json`). If missing, the `beforeSubmitPrompt` hook creates it automatically.
+2. **Never skip phases.** Complete swarms, write Run artifacts, then advance:
+   ```bash
+   node .cursor/aaac/scripts/run-engine/advance-phase.mjs <run_id> <phase>
+   ```
+3. **Swarm minimums** (enforced by advance-phase):
+   - `discover`: 4 Task agents
+   - `investigate_swarm`: 7 Task agents
+   - `research_swarm`: 6 Task agents
+4. **Code edits only in `execute`** (hook-enforced). Before execute: artifacts only under `.cursor/aaac/state/runs/`.
+5. **Complete the Run** — advance through `report`, set status completed.
+
+## If edit is denied
+
+Continue the pipeline — do not work around hooks. Full dispatch: [.cursor/aaac/dispatch.md](../aaac/dispatch.md)

package/templates/cursor/skills/shared/execution/SKILL.md

@@ -21,7 +21,7 @@ Orchestrator phase `execute` after approved plan.
 ## Actions
 
 - Edit files per plan and implementation skill
-- `apply_migration` for new/changed `supabase/migrations/` (project `hjadkzfemzuvhpwbixbt`)
+- `apply_migration` for new/changed `supabase/migrations/` (project `anseivwusnyiwopihnqu` — see [supabase-mcp.mdc](../../../rules/supabase-mcp.mdc))
 - `track()` for user-facing mutations
 - Structured logging on server async paths
 

package/templates/cursor/skills/shared/fitness-functions/SKILL.md

@@ -2,7 +2,7 @@
 name: shared-fitness-functions
 description: >-
   Score architecture fitness functions before execute; re-check in verify.
-  Not user-facing.
+  Includes minimal_complexity for create/update/fix. Not user-facing.
 disable-model-invocation: true
 ---
 
@@ -12,13 +12,28 @@ disable-model-invocation: true
 
 ## SSOT
 
-[fitness-functions.yaml](../../../aaac/fitness-functions.yaml)
+[fitness-functions.yaml](../../../aaac/fitness-functions.yaml)  
+Complexity config: [complexity.yaml](../../../aaac/complexity.yaml)
 
 ## Procedure
 
 1. Filter `functions` where command `object` ∈ `applies_to`
-2. Load linked skill per function (e.g. `ludecker-api-first`, `ludecker-design-system`)
-3. Score each: `pass` | `warning` | `fail` against planned changes
+2. For **create / update / fix**, always score `minimal_complexity` (see `applies_to_verbs`)
+3. Load linked skill or policy per function
+4. Score each: `pass` | `warning` | `fail` against planned changes in Run `artifacts.plan`
+
+## minimal_complexity (mutating verbs)
+
+Policy: [minimal-complexity.md](../../../policies/minimal-complexity.md)
+
+| Check | fail |
+|-------|------|
+| `complexity_score` ≤ verb threshold | score above threshold |
+| Reuse-first documented | create without `why_not_reuse` |
+| YAGNI | speculative architecture in plan |
+| fix minimalism | fix plan score > 5 or large create list |
+
+**Blocking** — same as `security` and `layer_boundaries`.
 
 ## Output
 
@@ -30,13 +45,14 @@ score:
   security: pass | warning | fail
   layer_boundaries: pass | warning | fail
   performance: pass | warning | fail
+  minimal_complexity: pass | warning | fail
 blocking_failures: [function names — empty if none]
 ```
 
+Store on Run `artifacts.fitness` and `gates.results.fitness_functions`.
+
 ## Gates
 
-- Any **fail** on `security` or `layer_boundaries` → **STOP** before execute
+- Any **fail** on `security`, `layer_boundaries`, or **`minimal_complexity`** → **STOP** before execute
 - **warning** → document in report; may proceed if validation passed
 - Re-run abbreviated score in [verification](../verification/SKILL.md) after execute
-
-Turns "read architecture.md" into enforceable checks.