@ludecker/aaac 1.0.0 → 1.1.1

package/templates/cursor/skills/shared/verbs/create/orchestrator/SKILL.md

@@ -23,8 +23,8 @@ Lifecycle: graph `verb_runtime.create` (work + gates on Run)
 2. **load_inventory** — when `domains/<slug>/update/inventory/SKILL.md` exists
 3. **discover** — [discovery](../../discovery/SKILL.md) readonly
 4. **investigate_lite** — [investigation-lite](../../investigation-lite/SKILL.md)
-5. **plan** — [planning](../../planning/SKILL.md)
-6. **validate** — [validation](../../validation/SKILL.md) — confidence gates
+5. **plan** — [planning](../../planning/SKILL.md) — **requirement_map + complexity_score** on Run
+6. **validate** — [validation](../../validation/SKILL.md) — confidence + complexity gates
 7. **impact_analysis** — [impact-analysis](../../impact-analysis/SKILL.md)
 8. **dependency_graph** — [dependency-graph](../../dependency-graph/SKILL.md)
 9. **fitness_functions** — [fitness-functions](../../fitness-functions/SKILL.md)

package/templates/cursor/skills/shared/verbs/fix/orchestrator/SKILL.md

@@ -1,33 +1,43 @@
 ---
 name: verb-fix-orchestrator
-description: Orchestrates fix-* except fix-bug resolver paths. Internal only.
+description: Orchestrates fix-* resolver fallbacks and generic fix-{object} commands. Internal only.
 disable-model-invocation: true
 ---
 
 # fix-* orchestrator
 
-**Object** from graph. `fix-bug` uses domain resolver (see [dispatch.md](../../../aaac/dispatch.md) for fallback).
+**Object** from graph or resolver `default_object`. Domain resolver paths (`fix-module`, `fix-bug`, …) prefer `*-fix-bug` orchestrators — see [dispatch.md](../../../aaac/dispatch.md).
 
 Read [_dispatch-utils.md](../_dispatch-utils.md) and [_lifecycle.md](../_lifecycle.md) first.
 
-Lifecycle: graph `verb_runtime.fix` (work + gates on Run)
+Contract: [contract.yaml](./contract.yaml)  
+Command contracts: [fix-module.yaml](../../../aaac/contracts/commands/fix-module.yaml), [fix-bug.yaml](../../../aaac/contracts/commands/fix-bug.yaml)
+
+Lifecycle: graph `verb_runtime.fix` or `command_workflows.fix-module` on Run
 
 ## Phases (deterministic — do not skip)
 
-1. **policies**
-2. **load_inventory** — when domain inventory exists
-3. **discover** — [discovery](../../discovery/SKILL.md) readonly
-4. **investigate** — [investigation](../../investigation/SKILL.md) deep
-5. **root_cause** — [root-cause](../../root-cause/SKILL.md)
-6. **plan** — [planning](../../planning/SKILL.md)
+1. **policies** — all four including [minimal-complexity.md](../../../policies/minimal-complexity.md)
+2. **load_inventory** — when `domains/<slug>/update/inventory/SKILL.md` exists
+3. **discover** — [discovery](../../discovery/SKILL.md) — **4–6 parallel** agents, one message
+4. **investigate_swarm** — [investigation](../../investigation/SKILL.md) Mode A — **7 parallel** agents, one message
+5. **root_cause** — [root-cause](../../root-cause/SKILL.md) — optional [fix-hypothesis-validate](../../../agents/fix-hypothesis-validate.md)
+6. **plan** — [planning](../../planning/SKILL.md) — minimal diff; `complexity_score` max **5**
 7. **validate** — [validation](../../validation/SKILL.md)
 8. **impact_analysis** — [impact-analysis](../../impact-analysis/SKILL.md)
 9. **dependency_graph** — [dependency-graph](../../dependency-graph/SKILL.md)
 10. **fitness_functions** — [fitness-functions](../../fitness-functions/SKILL.md)
 11. **rollback** — [rollback](../../rollback/SKILL.md) when maturity protected/critical or blast_radius ≥ medium
 12. **execute** — [execution](../../execution/SKILL.md)
-13. **verify** — [testing](../../testing/SKILL.md) + [verification](../../verification/SKILL.md)
-14. **sync_inventory**
+13. **verify** — [testing](../../testing/SKILL.md) fix verify swarm + [verification](../../verification/SKILL.md)
+14. **sync_inventory** — when domain inventory exists
 15. **report** — [reporting](../../reporting/SKILL.md)
 
+## Swarm anti-patterns (hard fail)
+
+- Skipping discovery or investigate_swarm because the issue "looks simple"
+- Sequential Task launches when parallel is required
+- Execute before `root_cause_confidence` ≥ 0.7
+- Claim success when `repro_status: not_fixed`
+
 Gate failure → **STOP, REQUEST CLARIFICATION**

package/templates/cursor/skills/shared/verbs/fix/orchestrator/contract.yaml

@@ -6,28 +6,42 @@ inputs:
   intent:
     required: true
 outputs:
+  investigation:
+    type: markdown
+    required: true
+  root_cause:
+    type: markdown
+    required: true
   code_changes:
     type: boolean
   inventory_synced:
     type: boolean
+  repro_status:
+    type: string
+    required: true
+    enum: [fixed, partial, not_fixed]
   report:
     type: markdown
 success_criteria:
   - All policies loaded before execute
-  - investigation completed before planning
+  - discovery swarm completed (4-6 parallel agents)
+  - investigate_swarm completed (7 parallel fix agents)
+  - root_cause_confidence at least 0.7 before plan
   - domain inventory loaded when domains/<slug>/update/inventory exists
   - object skills from graph object_skills / object_skill_verbs loaded
   - governance/implementation followed for all edits
+  - repro_status fixed or partial with documented follow-up
   - fallow check_changed clean on touched files
   - user intent satisfied per verification
 failure_conditions:
   - execute without approved plan
-  - skip investigation phase
+  - skip discover or investigate_swarm phase
   - skip governance/implementation on code changes
   - skip domain inventory when slug resolves to inventory file
+  - repro_status not_fixed while claiming success
 dependencies:
-  skills: [investigation, discovery, planning, execution, testing, verification, reporting]
-  policies: [master-rules, implementation, mcp-and-deploy]
+  skills: [discovery, investigation, root-cause, planning, execution, testing, verification, reporting]
+  policies: [master-rules, implementation, mcp-and-deploy, minimal-complexity]
   docs:
     - docs/master_rules.md
     - docs/architecture.md
@@ -35,4 +49,5 @@ dependencies:
 verification:
   - sync_inventory
   - run_tests
+  - fix_repro_verify_swarm
   - fallow_check_changed

package/templates/cursor/skills/shared/verbs/update/orchestrator/SKILL.md

@@ -18,8 +18,8 @@ Lifecycle: graph `verb_runtime.update` (work + gates on Run)
 2. **load_inventory** — when domain inventory exists
 3. **discover** — [discovery](../../discovery/SKILL.md)
 4. **investigate_lite** — [investigation-lite](../../investigation-lite/SKILL.md) — **mandatory** (what exists, depends on, constraints)
-5. **plan** — [planning](../../planning/SKILL.md)
-6. **validate** — [validation](../../validation/SKILL.md)
+5. **plan** — [planning](../../planning/SKILL.md) — **requirement_map + complexity_score** (max 8)
+6. **validate** — [validation](../../validation/SKILL.md) — confidence + complexity gates
 7. **impact_analysis** — [impact-analysis](../../impact-analysis/SKILL.md)
 8. **dependency_graph** — [dependency-graph](../../dependency-graph/SKILL.md)
 9. **fitness_functions** — [fitness-functions](../../fitness-functions/SKILL.md)

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

@@ -14,6 +14,9 @@ After `testing`. Before `report`.
 
 ## Checks
 
+- **Website build gate** (create / update / fix): `artifacts/verify.yaml` from [verify-website-build.mjs](../../../aaac/scripts/run-engine/verify-website-build.mjs) — static assets in `index.html` must exist; `pnpm --filter @ludecker/website build` must pass
+- **Playwright verb checks** (create / update / fix): launch [playwright-check-run](../../../agents/playwright-check-run.md) — `pnpm --filter @ludecker/aaac test:e2e` must pass; set `PLAYWRIGHT_BASE_URL` for public-route smoke
+- Run artifact `artifacts.testing.repro_status` is **fixed** or **partial** with documented follow-up (fix paths)
 - Orchestrator `contract.yaml` `success_criteria`
 - Graph `object_skills` / `object_skill_verbs` skills were loaded for command object + verb
 - User instruction satisfied (spot-check 2–3 behaviors in code or tests)

package/templates/docs/agentic_architecture.md

@@ -6,8 +6,6 @@
 
 You express intent; the architecture determines execution.
 
-Installed by [{{PROJECT_NAME}}](https://ludecker.com) — generic AAAC kernel for Cursor.
-
 ---
 
 ## Part 1 — For everyone
@@ -25,36 +23,71 @@ Ask: *What do I want?* Then type:
 | Part | Meaning | Example |
 |------|---------|---------|
 | Command | Kind of work | `update-module` |
-| Domain | Which bounded context | `api` |
-| Intent | Goal in plain language | `"Add pagination to list endpoint"` |
+| Domain | Which area | `cms` |
+| Intent | Goal in plain language | `"Add featured hero toggle to home page"` |
+
+### Ludecker domains
+
+| Slug | Scope |
+|------|-------|
+| `cms` | `apps/website` — public site, CMS admin, content queries |
+| `ui` | `packages/ui` — design system, tokens, components |
+| `database` | `supabase/migrations` — schema, RLS, type mirrors |
+| `aaac` | `packages/aaac` — `@ludecker/aaac` npm package, CLI, templates, generators |
 
-### Commands (AAAC v1)
+### Commands (Ludecker v1)
 
 | Command | When to use |
 |---------|-------------|
-| `update-module` | Change an existing bounded module |
+| `update-module` | Change an existing bounded module (`cms`, `ui`, `database`, `aaac`) |
 | `update-doc` | Update architecture documentation (no code) |
-| `create-feature` | Add a new capability |
-| `fix-bug` | Fix broken behavior |
+| `update-design` | UI / design-system changes (`cms` or `ui`) |
+| `create-feature` | Add a new capability in a domain |
+| `fix-module` | Fix broken module — **requires domain**; full fix swarm |
+| `fix-bug` | Same pipeline as `fix-module`; domain optional (`module-fix`, `bug-fix` aliases) |
 | `review-module` | Quality/architecture review (no code) |
 | `review-incident` | Investigate deploy or production issue |
 | `test-module` | Test and verify a module |
 | `test-function` | Test a user journey |
-| `release-app` | Phased release (git → deploy) |
+| `release-app` | Phased release swarm (git → Render) |
+| `publish-aaac` | Bump, smoke-test, and publish `@ludecker/aaac` to npm |
+| `write-article` | Research swarm → CMS article persist |
 
-Verb×object matrix commands (`create-component`, `check-schema`, …) route through shared verb orchestrators. See [`.cursor/aaac/ontology.md`](../.cursor/aaac/ontology.md).
+### Manual commands (local dev)
+
+| Command | When to use |
+|---------|-------------|
+| `launch-ludecker` | Clean local dev server start |
+| `kill-ludecker` | Kill stale local port listeners |
 
 ### Examples
 
 ```text
-/update-module api "Add rate limiting middleware"
-/fix-bug "Checkout fails on empty cart"
-/update-doc architecture "Document domain boundaries"
-/review-module api "Check layer boundaries and size budgets"
-/test-function "Sign-up to welcome email journey"
+/update-module cms "Improve docs shell navigation"
+/update-module ui "Add dark mode token for muted text"
+/update-module aaac "Add --version flag to CLI"
+/fix-bug cms "CMS publish does not revalidate home page"
+/fix-bug aaac "init fails when target dir already exists"
+/test-module aaac "Run init smoke and aaac:generate diff check"
+/publish-aaac "Ship 1.0.1 with template sync"
+/update-doc architecture "Document AAAC agent topology"
+/review-module cms "Check size budgets and layer boundaries"
+/test-module cms "Run full module verification"
 /release-app production "Ship with typecheck"
+/write-article guide, How to use Commands in Cursor
+/launch-ludecker
 ```
 
+### Deprecated (still work one release)
+
+| Old | New |
+|-----|-----|
+| `/ship-ludecker` | `/release-app` |
+| `/module-update` | `/update-module` |
+| `/architecture` | `/update-doc` |
+| `/swarm-check` | `/review-incident` or `/fix-bug` |
+| `/refactor` | `/review-module` |
+
 ### What you should not need to know
 
 skill, agent, subagent, tool, workflow, graph, orchestrator — infrastructure only.
@@ -63,33 +96,9 @@ skill, agent, subagent, tool, workflow, graph, orchestrator — infrastructure o
 
 ## Part 2 — Appendix (maintainers)
 
-### Install and regenerate
-
-```bash
-npx @ludecker/aaac@latest init
-# or
-pnpm dlx @ludecker/aaac@latest init
-```
-
-After changing ontology or project wiring:
-
-```bash
-npx @ludecker/aaac@latest generate
-# or
-pnpm dlx @ludecker/aaac@latest generate
-```
-
-### Adding a product domain
-
-1. Create `.cursor/domains/<slug>/update/orchestrator/` (SKILL.md + contract.yaml)
-2. Create `.cursor/domains/<slug>/update/inventory/` (file map + constraints)
-3. Add resolver entries to `.cursor/aaac/graph.project.yaml`
-4. Add `command_overrides` to `.cursor/aaac/ontology.json` if slug-based routing is needed
-5. Regenerate graph and commands (see above)
-
 ### Responsibility layers
 
-Full map: [`.cursor/aaac/layers.md`](../.cursor/aaac/layers.md)
+AAAC is organized by **responsibility**, not file type. Full map: [`.cursor/aaac/layers.md`](../.cursor/aaac/layers.md)
 
 ```text
 User Layer          → Commands
@@ -99,33 +108,207 @@ Governance Layer    → gate stacks (gates.json), policies, fitness
 Run Layer           → Run manifest (state + observability)
 Execution Layer     → Orchestrators, pipeline skills, capabilities, agents
 Contracts Layer     → command + skill contracts
-Knowledge Layer     → {{DOCS_ROOT}}/
+Knowledge Layer     → docs/
+```
+
+| Component | Responsibility |
+|-----------|----------------|
+| Commands | User-facing API |
+| Ontology | Vocabulary and classification |
+| Dispatch | Command resolution, Run creation |
+| Graph | Execution routing |
+| Lifecycle | **Work** phase configuration |
+| Gate stacks | **Approval** checkpoints |
+| Run | Primary execution object; decisions, log, checkpoints |
+| Domain orchestrators | Domain coordination |
+| Shared pipeline skills | Phase execution |
+| Capability registry | object → capability → provider |
+| Object skills | Skill-type providers |
+| Agent specs | Agent behavior |
+| Policies | Mandatory governance |
+| Dependencies | Impact analysis |
+| Fitness functions | Architecture validation |
+| Contracts | Input/output invariants |
+| Documentation | System knowledge |
+
+### Execution graph
+
+```text
+Intent → Command → Execution Graph → Result
 ```
 
+**Execution graph** = orchestrator + skills + agents + tools + rules + documentation.
+
 **SSOT:** [`.cursor/aaac/graph.yaml`](../.cursor/aaac/graph.yaml)
 
-**Dispatch:** [`.cursor/aaac/dispatch.md`](../.cursor/aaac/dispatch.md)
+**Dispatch procedure:** [`.cursor/aaac/dispatch.md`](../.cursor/aaac/dispatch.md)
 
 ### Directory layout
 
 ```text
 .cursor/
   commands/          # thin routers (public)
-  aaac/              # ontology, graph, generators config
+  aaac/graph.yaml    # wiring (private OS)
   domains/<slug>/update/
-    orchestrator/
-    inventory/
-  skills/shared/     # pipeline + verb orchestrators
+    orchestrator/    # what happens
+    inventory/       # what exists
+  skills/shared/     # framework (discovery, planning, execution, …)
+  skills/ludecker/   # project-specific object skills
+  skills/write-article/  # content swarm
   agents/            # subagent prompt specs
-  policies/          # inherited governance
-{{DOCS_ROOT}}/
-  agentic_architecture.md
-  master_rules.md    # your project rules (create if missing)
-  architecture.md    # your system map (create if missing)
+  policies/          # rules all skills inherit
+```
+
+### Orchestrator vs inventory
+
+| | Orchestrator | Inventory |
+|--|--------------|-----------|
+| Question | What should happen? | What exists? |
+| Updates when | Workflow changes | After every code-changing `update-module` |
+
+Inventory documents constraints and file maps. **Dependency reasoning** uses [`.cursor/aaac/dependencies.yaml`](../.cursor/aaac/dependencies.yaml) via the `dependency_graph` phase — not inventory alone.
+
+### Execution determinism (create / update / fix)
+
+Commands define *what* to load; **work lifecycle** defines phases of work; **gate stacks** define approval checkpoints; the **Run** holds state and observability.
+
+**Mature stack (composed on Run):**
+
+```text
+Policies → Ontology → Graph → Create Run
+→ Work: Discovery → Investigation → Planning
+→ Gates: Validation → Impact → Deps → Fitness → Rollback
+→ Work: Execute → Verify → Report
+```
+
+**Work lifecycles** (SSOT: [`.cursor/aaac/lifecycle/lifecycle.json`](../.cursor/aaac/lifecycle/lifecycle.json)):
+
+| Verb | Work | Gate stack |
+|------|------|------------|
+| create | discover → investigate_lite → plan → execute → verify → report | pre_execute |
+| update | same | pre_execute |
+| fix | discover → investigate_swarm → root_cause → plan → execute → verify → report | pre_execute |
+| release | execute → verify → report | release |
+
+**Gate stacks** (SSOT: [`.cursor/aaac/governance/gates.json`](../.cursor/aaac/governance/gates.json)) — approval, not work.
+
+Composed runtime in graph `verb_runtime`. Human approval at gate boundaries: Run `status: blocked`, `awaiting_approval: true`.
+
+**Confidence gates** — before execute, if any score is below threshold → `STOP, REQUEST CLARIFICATION`:
+
+| Dimension | Minimum |
+|-----------|---------|
+| architecture | 0.9 |
+| requirements | 0.8 |
+| scope | 0.8 |
+
+**Object maturity** — harder objects require more phases:
+
+| Level | Objects (examples) | Extra requirements |
+|-------|-------------------|-------------------|
+| protected | schema, migration, architecture | impact + deps + rollback |
+| critical | module, integration, app | impact + deps |
+| stable | feature, workflow | impact on fix |
+| evolving | component, function | lifecycle only |
+
+**Fitness functions** — [`.cursor/aaac/fitness-functions.yaml`](../.cursor/aaac/fitness-functions.yaml): api_first, design_system, accessibility, security, layer_boundaries, performance. Scored `pass` / `warning` / `fail` before execute.
+
+Lifecycle reference: [`.cursor/skills/shared/verbs/_lifecycle.md`](../.cursor/skills/shared/verbs/_lifecycle.md)
+
+### Fix swarm (`/fix-module`, `/fix-bug`, `fix_mode`)
+
+Same rigor as `write-article` research — parallel Task subagents, one message per wave.
+
+| Phase | Agent specs | Count |
+|-------|-------------|-------|
+| discover | discovery-inventory, discovery-boundaries, discovery-ssot | 4–6 |
+| investigate_swarm | fix-repro, fix-code-path, fix-recent-changes, fix-test-failures, fix-regression-scope, fix-runtime-evidence, fix-inventory-confirm | **7** |
+| root_cause | parent + optional fix-hypothesis-validate | 0–1 |
+| verify (fix) | fix-repro-verify, unit-test-run, fallow-check-changed | **3** |
+
+Skills: [investigation/SKILL.md](../.cursor/skills/shared/investigation/SKILL.md), [testing/SKILL.md](../.cursor/skills/shared/testing/SKILL.md).  
+Contracts: [fix-module.yaml](../.cursor/aaac/contracts/commands/fix-module.yaml), [fix-bug.yaml](../.cursor/aaac/contracts/commands/fix-bug.yaml).
+
+Resolver: `fix-domain-by-slug` (`fix-module`) and `fix-bug-by-slug` → `cms-fix-bug` | `ui-fix-bug` | `database-fix-bug` | `aaac-fix-bug`.
+
+### Capability registry
+
+Objects declare capabilities in ontology; providers resolve from [`.cursor/aaac/capabilities/registry.json`](../.cursor/aaac/capabilities/registry.json):
+
+```text
+object → capability → provider (skill | mcp | expert)
 ```
 
+Graph `object_skills` includes skill-type providers only. MCP providers (e.g. `supabase-mcp` on `database-design`) are recorded on the Run.
+
+**Capability lifecycle (evidence-driven):** State belongs to the **capability**, not the provider. After each completed Run, `capability-evidence.mjs` aggregates per-run evidence into [`.cursor/aaac/state/capability-stats.json`](../.cursor/aaac/state/capability-stats.json) and evaluates deterministic promotion using [`.cursor/aaac/capabilities/promotion-rules.json`](../.cursor/aaac/capabilities/promotion-rules.json):
+
+```text
+experimental → validated → trusted → canonical → deprecated
+```
+
+Promotion uses accumulated metrics: `invocations`, `success_rate`, `rollback_rate`, `gate_failure_rate`, `avg_fitness`. `canonical` requires `manual_approval` (human override on the capability entry). Providers contribute evidence; governance changes state.
+
+### Run (primary execution object)
+
+**SSOT:** [`.cursor/aaac/run/schema.json`](../.cursor/aaac/run/schema.json), [`.cursor/aaac/run/RUN.md`](../.cursor/aaac/run/RUN.md)
+
+Every command executes within a Run at `state/runs/{run_id}/run.json`:
+
+| Field | Purpose |
+|-------|---------|
+| `phase`, `pending`, `completed` | Where we are |
+| `decisions[]` | Why routes and gates |
+| `log[]` | Phase events |
+| `checkpoints[]` | Resume points |
+| `artifacts{}` | Plan, impact, report, … |
+| `awaiting_approval` | Human gate approval |
+
+Observability: [`.cursor/aaac/observability/telemetry.yaml`](../.cursor/aaac/observability/telemetry.yaml) — all telemetry on Run, no standalone logs.
+
+### Contracts
+
+Command contracts: [`.cursor/aaac/contracts/commands/`](../.cursor/aaac/contracts/commands/). Skill contracts: [`.cursor/aaac/contracts/skills/`](../.cursor/aaac/contracts/skills/). Schema: [`.cursor/aaac/contract-schema.md`](../.cursor/aaac/contract-schema.md)
+
+### Implementation governance
+
+Not a slash command. Loaded by `shared/execution` on code changes:
+
+[`.cursor/skills/shared/governance/implementation/SKILL.md`](../.cursor/skills/shared/governance/implementation/SKILL.md)
+
+### Adding a product domain
+
+1. Add `domains/<slug>/update/` (inventory + orchestrator)
+2. Add slug to `graph.yaml` resolvers — **no new command shape**
+3. Regenerate: `node .cursor/aaac/generate-graph.mjs && node .cursor/aaac/generate-commands.mjs`
+
+### Contracts
+
+Plugins may include `contract.yaml` beside `SKILL.md`. Central contracts: [`.cursor/aaac/contracts/`](../.cursor/aaac/contracts/). Schema: [`.cursor/aaac/contract-schema.md`](../.cursor/aaac/contract-schema.md)
+
 ### Release swarm (`release-app`)
 
-Wave 1: `release-git` (blocking). Configure deploy agents in `graph.project.yaml` for your host.
+Expert subagents run in **waves**, not one monolithic agent:
+
+| Wave | Agents | Notes |
+|------|--------|-------|
+| 0 | Preflight typecheck (optional) | From intent, e.g. "with tests" |
+| 1 | `release-git` | **Blocking** — must return `commit_sha` before wave 2 |
+| 2 | `release-render` | Poll `ludecker-website` until `live`; smoke-check `/` |
+
+Wiring: `graph.yaml` agents `release-*`. Orchestrator: [platform-release/orchestrator](../.cursor/skills/shared/platform-release/orchestrator/SKILL.md). DAG: [platform-release/SKILL.md](../.cursor/skills/shared/platform-release/SKILL.md).
+
+### Regenerating commands
+
+```bash
+pnpm aaac:generate
+```
+
+Or:
+
+```bash
+node .cursor/aaac/generate-graph.mjs
+node .cursor/aaac/generate-commands.mjs
+```
 
-Orchestrator: [`.cursor/skills/shared/platform-release/orchestrator`](../.cursor/skills/shared/platform-release/orchestrator/SKILL.md)
+Ontology reference: [`.cursor/aaac/ontology.md`](../.cursor/aaac/ontology.md)