@ludecker/aaac 1.0.0

package/templates/cursor/aaac/ontology.md

@@ -0,0 +1,90 @@
+# AAAC ontology (first principles)
+
+SSOT: [ontology.json](ontology.json). Regenerate graph and commands:
+
+```bash
+node .cursor/aaac/generate-graph.mjs
+node .cursor/aaac/generate-commands.mjs
+```
+
+## Hierarchy (how developers already think)
+
+```text
+function → component → module → feature → domain → system
+```
+
+Four layers in the graph:
+
+| Layer | Objects | Examples |
+|-------|---------|----------|
+| **code** | function, component, module | `/fix-function`, `/review-component`, `/update-module` |
+| **data** | schema, model, migration | `/update-schema`, `/create-migration` |
+| **product** | feature, workflow, integration | `/create-feature`, `/check-workflow` |
+| **system** | app, domain, architecture | `/release-app`, `/update-domain`, `/review-architecture` |
+
+## Verbs (unchanged)
+
+create · update · fix · review · check · test · release · remove
+
+## Ludecker domains
+
+| Slug | Bounded context |
+|------|-----------------|
+| `cms` | `apps/website` — public site + CMS admin |
+| `ui` | `packages/ui` — design system |
+| `database` | `supabase/migrations` — schema, RLS, type mirrors |
+
+## Granular aliases
+
+Finer nouns (api, endpoint, hook, spec, skill, graph, …) map to a canonical command — see `command_aliases` in [ontology.json](ontology.json). Examples:
+
+| You type | Resolves to |
+|----------|-------------|
+| `/update-api` | `update-integration` |
+| `/fix-hook` | `fix-function` |
+| `/update-doc` | `update-architecture` |
+| `/update-design` | `update-component` (cms/ui resolver) |
+| `/check-inventory` | `check-module` |
+| `/create-skill` | `create-module` |
+| `/ship-ludecker` | `release-app` |
+
+## Exceptions
+
+| Command | Note |
+|---------|------|
+| `fix-bug` | Defect repair; domain resolver (`cms`, `ui`, `database`); unknown slug → `verb-fix` |
+| `review-incident` | Production/deploy incident (`swarm-check` alias) |
+| `test-function` | Journey verification (dedicated orchestrator) |
+| `release-app` | Full platform ship (`ship-ludecker` alias) |
+| `write-article` | Content research swarm → CMS persist |
+
+## Invalid `release-*`
+
+Use `release-app`, `release-feature`, or `release-integration` — not `release-function`, `release-module`, `release-schema`, etc. (see `invalid_pairs` in graph).
+
+## Verb lifecycle and gates
+
+**Work:** [lifecycle/lifecycle.json](lifecycle/lifecycle.json) → graph `verb_work_phases`  
+**Gates:** [governance/gates.json](governance/gates.json) → graph `governance_gate_stacks`  
+**Runtime (composed):** graph `verb_runtime` on Run at dispatch  
+**Run:** [run/schema.json](run/schema.json) — primary execution object  
+
+Phase → skill: [lifecycle/phases.json](lifecycle/phases.json)
+
+## Object capabilities
+
+Ontology declares `object_capabilities` per object. Graph resolves to provider skills via [capabilities/registry.json](capabilities/registry.json). Generated `object_skills` in graph.yaml is derived — do not edit by hand.
+
+Example: `component` → `[component-model, layer-boundaries, ui-design]` → `[component, architecture, ludecker-design-system]`
+
+## Domain argument
+
+- **Required:** `update-module`, `update-domain`, …
+- **Optional:** `*-function`, `review-incident`, `write-article`
+
+## Manual commands (not in graph)
+
+| Command | Purpose |
+|---------|---------|
+| `/launch-ludecker` | Local dev: kill stale processes, clean `.next`, start `pnpm dev` |
+| `/kill-ludecker` | Kill local dev port listeners |

package/templates/cursor/aaac/project.config.json

@@ -0,0 +1,3 @@
+{
+  "manual_commands": []
+}

package/templates/cursor/aaac/run/RUN.md

@@ -0,0 +1,72 @@
+# Run — primary execution object
+
+**Every AAAC command executes within a Run.** There is no standalone lifecycle execution or standalone logging.
+
+Schema: [schema.json](schema.json)
+
+## Create Run (dispatch step 2.5 — after graph resolve, before orchestrator)
+
+1. Generate `run_id`: `run_{YYYYMMDD}_{short-slug}` or resume existing if user says `resume run_…`
+2. Compose runtime phases from [lifecycle/lifecycle.json](../lifecycle/lifecycle.json) + [governance/gates.json](../governance/gates.json):
+   - `pending` = work phases through `plan` + gate stack + work phases from `execute`
+3. Write manifest: `state/runs/{run_id}/run.json`
+4. Set `status: running`, `phase: first pending item`, `phase_kind: work`
+
+## Update Run (after every phase)
+
+1. Append to `log[]`
+2. Move phase from `pending` to `completed`
+3. Write checkpoint: `state/runs/{run_id}/checkpoints/{phase}.json`
+4. Store artifacts under `state/runs/{run_id}/artifacts/` — reference paths in `artifacts{}`
+5. Append routing/capability choices to `decisions[]`
+6. Persist `run.json`
+
+## Gate stack execution
+
+After `plan` completes:
+
+1. Set `phase_kind: gate`, `gates.stack` from lifecycle
+2. Run each gate in [governance/gates.json](../governance/gates.json) order
+3. On fail → `status: blocked`, `awaiting_approval: true`, `blocked_reason`, **STOP**
+4. On pass → record in `gates.results`, continue to `execute`
+
+## Human approval
+
+When `awaiting_approval: true`:
+
+```text
+STOP — awaiting approval
+Reason: {blocked_reason}
+Run: {run_id}
+```
+
+User approves → log decision, set `status: running`, `awaiting_approval: false`, retry or continue.
+
+## Observability
+
+All observability lives on the Run:
+
+| Field | Purpose |
+|-------|---------|
+| `decisions[]` | Why route/capability/gate |
+| `log[]` | Phase and skill events |
+| `checkpoints[]` | Resume points |
+
+**No** append to standalone `decision-log.md` or `execution-log.md`.
+
+## Capability resolution (record on Run)
+
+When resolving `object_capabilities` → providers:
+
+```yaml
+capabilities_resolved:
+  layer-boundaries:
+    providers: [architecture]
+    source: object module
+```
+
+MCP providers (type `mcp`) are recorded in decisions but do not map to graph skill keys.
+
+## Report
+
+Final phase writes `artifacts.report` and sets `status: completed`.

package/templates/cursor/aaac/run/schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "aaac run — primary execution object",
+  "version": 1,
+  "description": "Every command executes within a Run. No standalone execution or logging.",
+  "run": {
+    "run_id": "run_{timestamp}_{slug}",
+    "command": "string",
+    "verb": "string",
+    "object": "string | null",
+    "domain": "string | null",
+    "intent": "string",
+    "orchestrator": "string",
+    "status": "pending | running | blocked | completed | failed",
+    "phase": "string | null",
+    "phase_kind": "work | gate | null",
+    "awaiting_approval": false,
+    "blocked_reason": "string | null",
+    "completed": [],
+    "pending": [],
+    "decisions": [],
+    "artifacts": {},
+    "checkpoints": [],
+    "log": [],
+    "capabilities_resolved": {},
+    "confidence": {
+      "architecture": null,
+      "requirements": null,
+      "scope": null
+    },
+    "gates": {
+      "stack": "string | null",
+      "results": {}
+    },
+    "created_at": "iso8601",
+    "updated_at": "iso8601"
+  },
+  "storage": {
+    "root": "aaac/state/runs/{run_id}/",
+    "manifest": "run.json",
+    "artifacts_dir": "artifacts/",
+    "checkpoints_dir": "checkpoints/"
+  },
+  "decision_entry": {
+    "at": "iso8601",
+    "phase": "string",
+    "decision": "string",
+    "reason": "string",
+    "evidence": "string"
+  },
+  "log_entry": {
+    "at": "iso8601",
+    "phase": "string",
+    "phase_kind": "work | gate",
+    "skill": "string | null",
+    "event": "phase_start | phase_complete | gate_pass | gate_fail | blocked | resumed",
+    "detail": "string"
+  },
+  "checkpoint_entry": {
+    "phase": "string",
+    "at": "iso8601",
+    "artifact_refs": [],
+    "outputs_summary": "string"
+  },
+  "artifact_keys": [
+    "plan",
+    "investigation",
+    "root_cause",
+    "impact",
+    "dependency_graph",
+    "fitness",
+    "rollback",
+    "report"
+  ],
+  "resume": {
+    "read_manifest": "state/runs/{run_id}/run.json",
+    "continue_from": "phase field when status running or blocked with user approval"
+  },
+  "human_approval": {
+    "when_blocked": "Set awaiting_approval true; do not execute until user approves in chat",
+    "on_approve": "status running; retry failed gate or continue pending",
+    "record_decision": "User approved gate {phase}: {reason}"
+  }
+}

package/templates/cursor/aaac/state/checkpoints/README.md

@@ -0,0 +1,20 @@
+# Run checkpoints — per Run, per phase
+
+Checkpoints live under each Run:
+
+```text
+state/runs/{run_id}/
+  run.json
+  checkpoints/{phase}.json
+  artifacts/
+```
+
+Gitignored except this README. Enables resume after gate block or crash.
+
+Each checkpoint records:
+- run_id, command, phase, timestamp
+- outputs required by contracts/skills for that phase
+- confidence, gate results when applicable
+- next pending phase
+
+Do not commit active runs to git.

package/templates/cursor/agents/boundary-review.md

@@ -0,0 +1,11 @@
+# Agent: boundary-review
+
+**Readonly.**
+
+## Role
+
+Layer violations, fetch in UI, business logic in routes, cross-module coupling.
+
+## Return
+
+Findings, Evidence, Severity (critical | suggestion), Confidence.

package/templates/cursor/agents/check-capability-trace.md

@@ -0,0 +1,18 @@
+# Agent: check-capability-trace
+
+**Readonly.** Do not edit files.
+
+## Role
+
+Answer whether the codebase supports the asked capability and how it is implemented.
+
+Trace: entry points (UI, API, MCP, CLI) → handlers → domain logic → persistence/external calls.
+
+## Return
+
+- **Can do:** yes | no | partial (with conditions)
+- **How:** numbered flow in product language
+- Findings (bullets)
+- Evidence (`path:line` for each claim)
+- Gaps (unverified assumptions, missing tests, dead paths)
+- Confidence: high | medium | low

package/templates/cursor/agents/dependency-analysis.md

@@ -0,0 +1,11 @@
+# Agent: dependency-analysis
+
+**Readonly.**
+
+## Role
+
+Import direction, circular deps, god files, duplicate logic.
+
+## Return
+
+Findings, Evidence, Gaps, Confidence.

package/templates/cursor/agents/discovery-boundaries.md

@@ -0,0 +1,11 @@
+# Agent: discovery-boundaries
+
+**Readonly.**
+
+## Role
+
+What is in scope vs out of scope for this domain? Handoffs to adjacent modules?
+
+## Return
+
+Findings, Evidence, Gaps, Confidence.

package/templates/cursor/agents/discovery-inventory.md

@@ -0,0 +1,14 @@
+# Agent: discovery-inventory
+
+**Readonly.** Do not edit files.
+
+## Role
+
+Find all files, routes, tests, and migrations belonging to the target domain.
+
+## Return
+
+- Findings (bullets, product language in summary)
+- Evidence (`path:line` for verification)
+- Gaps (what could not be confirmed)
+- Confidence: high | medium | low

package/templates/cursor/agents/discovery-ssot.md

@@ -0,0 +1,11 @@
+# Agent: discovery-ssot
+
+**Readonly.**
+
+## Role
+
+Who owns state? Named state machines vs hooks? Duplicate SSOT risks?
+
+## Return
+
+Findings, Evidence, Gaps, Confidence.

package/templates/cursor/agents/fallow-check-changed.md

@@ -0,0 +1,9 @@
+# Agent: fallow-check-changed
+
+## Role
+
+Run Fallow MCP `check_changed` on touched files. Report new budget or boundary violations.
+
+## Return
+
+Verdict, file scores, required extractions before merge.

package/templates/cursor/agents/impact-analysis.md

@@ -0,0 +1,22 @@
+# Agent: impact-analysis
+
+**Readonly.** Do not edit files.
+
+## Role
+
+Given an approved plan, list affected domains/systems and risk categories.
+
+## Inputs
+
+- Plan summary (files, routes, migrations)
+- [dependencies.yaml](../aaac/dependencies.yaml)
+- Domain inventory constraints
+
+## Return
+
+```yaml
+affected: [cms, ui, database, integration, ...]
+risk: [migrations, breaking_contracts, auth, deployment]
+blast_radius: low | medium | high
+evidence: path:line bullets
+```

package/templates/cursor/agents/plan-layer-map.md

@@ -0,0 +1,11 @@
+# Agent: plan-layer-map
+
+**Readonly** until parent approves plan.
+
+## Role
+
+Map user intent to layers (UI, store, domain, server, shared schemas). Flag files ≥80% size budget.
+
+## Return
+
+Proposed file list, layer per file, extraction needs, risks.

package/templates/cursor/agents/plan-state-machines.md

@@ -0,0 +1,11 @@
+# Agent: plan-state-machines
+
+**Readonly.**
+
+## Role
+
+Does this change need explicit state machine transitions? Name states/events if yes.
+
+## Return
+
+Machine proposal or "local UI only", anti-patterns to avoid (race guards, useEffect orchestration).

package/templates/cursor/agents/release-git.md

@@ -0,0 +1,36 @@
+# Agent: release-git
+
+**Wave 1 — blocking.** Parent must not start Wave 2 until this agent returns success.
+
+## Role
+
+Commit and push all pending work to `main` for the Lüdecker monorepo.
+
+## Inputs (from orchestrator)
+
+- User intent (optional): e.g. "with tests" handled by preflight, not this agent
+- `domain`: `production` (default)
+- Flags from user message: `--no-commit`, `--message "…"`, `--dry-run`
+
+## Procedure
+
+Follow [ship-procedure.md § Git](../skills/shared/platform-release/ship-procedure.md).
+
+**Repo check:** `git rev-parse --show-toplevel` must be the ludecker monorepo.
+
+## Return
+
+```yaml
+status: success | failed
+commit_sha: string
+commit_message_first_line: string
+commit_message_body: string
+evidence: git log -1 output
+```
+
+## Rules
+
+- Never force-push `main`
+- Never skip hooks unless user explicitly requested
+- Never stage `.env*` or service role keys
+- On failure: stop pipeline; do not start Render agent

package/templates/cursor/agents/system-decomposition.md

@@ -0,0 +1,11 @@
+# Agent: system-decomposition
+
+**Readonly.**
+
+## Role
+
+Can responsibilities split into smaller modules? Size budget hotspots?
+
+## Return
+
+Findings, Evidence, recommended extractions, Confidence.

package/templates/cursor/agents/unit-test-run.md

@@ -0,0 +1,19 @@
+# Agent: unit-test-run
+
+## Role
+
+Run targeted tests for paths from domain inventory. Report pass/fail with test names.
+
+## Lüdecker defaults
+
+From repo root:
+
+```bash
+pnpm typecheck
+```
+
+If domain inventory lists vitest/jest targets, run those instead.
+
+## Return
+
+Command run, exit code, failing test summary, suggested fix area (path only).

package/templates/cursor/policies/implementation.md

@@ -0,0 +1,8 @@
+# Policy: Implementation governance
+
+**Sources:**
+
+- [{{DOCS_ROOT}}/architecture.md](../../{{DOCS_ROOT}}/architecture.md)
+- [.cursor/skills/shared/governance/implementation/SKILL.md](../skills/shared/governance/implementation/SKILL.md)
+
+Loaded on every mutating command. Architecture boundaries and SSOT rules apply before execute.

package/templates/cursor/policies/master-rules.md

@@ -0,0 +1,7 @@
+# Policy: Master rules
+
+**Source of truth:** [{{DOCS_ROOT}}/master_rules.md](../../{{DOCS_ROOT}}/master_rules.md)
+
+All AAAC orchestrators, skills, and agents **must** comply. Domain skills cannot weaken these rules.
+
+When `governance/implementation` or `execution` runs, master rules override convenience.

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

@@ -0,0 +1,26 @@
+---
+name: shared-api
+description: >-
+  HTTP routes, BFF handlers, request/response contracts. Used by verb orchestrators
+  when object is api. Not user-facing.
+disable-model-invocation: true
+---
+
+# Shared API layer
+
+## Scope
+
+- `server/routes/`, route handlers, middleware
+- Request validation (Zod/schemas at boundaries)
+- Auth and project scoping on endpoints
+- OpenAPI or shared route constants if present
+
+## Execution focus
+
+- One route family per change; no cross-cutting drive-by edits
+- Validate at boundary; errors explicit and actionable
+- CORS and origins per deploy policy
+
+## Discovery / check angles
+
+Map: method + path → handler → service → DB/external.

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

@@ -0,0 +1,25 @@
+---
+name: shared-architecture-review
+description: >-
+  SOLID, boundaries, decomposition review. Used by review-module. Readonly.
+  Not user-facing.
+disable-model-invocation: true
+---
+
+# Shared architecture review
+
+## When
+
+`review-module` orchestrator. **Readonly** unless user also invoked a code command.
+
+## Swarm
+
+Parallel readonly agents per [boundary-review.md](../../../agents/boundary-review.md), [dependency-analysis.md](../../../agents/dependency-analysis.md), [system-decomposition.md](../../../agents/system-decomposition.md).
+
+## Depth
+
+For file-level SOLID/size detail, also read [refactor-analysis.md](refactor-analysis.md) for target path.
+
+## Output
+
+Prioritized findings: critical vs suggestion. No drive-by refactors unless user invoked `update-module` separately.

package/templates/cursor/skills/shared/architecture/orchestrator/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: review-module-orchestrator
+description: Orchestrates review-module — architecture and quality analysis. Internal only.
+disable-model-invocation: true
+---
+
+# review-module orchestrator
+
+## Parse
+
+- **Domain:** slug or path hint
+- **Intent:** quoted analysis goal
+
+## Phases
+
+1. Load domain inventory if slug maps in graph
+2. [discovery](../discovery/SKILL.md) — readonly, focused scope
+3. [architecture review](../SKILL.md)
+4. [reporting](../reporting/SKILL.md)
+
+No code changes in this command alone.