@ludecker/aaac 1.1.0 → 1.1.1

package/templates/cursor/skills/shared/platform-release/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: shared-platform-release
 description: >-
-  Phased release swarm coordination for release-app. Wave 1 git (blocking),
-  Wave 2 Render deploy. Internal only.
+  Phased release for release-app: mandatory preflight, git, optional conditional
+  package publish, Render poll, verify, report.
 disable-model-invocation: true
 ---
 
@@ -11,36 +11,39 @@ disable-model-invocation: true
 ## Swarm DAG
 
 ```text
-Preflight (optional tests)
+Wave 0: pnpm typecheck (mandatory)
   ↓
 Wave 1: release-git  ← BLOCKING
   ↓
-Wave 2: release-render
+Wave 1.5: conditional package publish ← OPTIONAL (project overlay; blocking when triggered)
   ↓
-Parent: verification + reporting
+Wave 2: release-render ← BLOCKING (poll until live or fail)
+  ↓
+Wave 3: verification + reporting
 ```
 
-## Wave 1 — launch one agent
+## Wave 0 — preflight
 
+```bash
+pnpm typecheck
 ```
-Task (shell or generalPurpose): release-git
-Read: agents/release-git.md, ship-procedure.md
-Return: commit_sha, commit_message_*
-On failure: abort pipeline
-```
 
-## Wave 2 — Render deploy
+Always. Optional extra tests when intent requests them.
+
+## Wave 1 — git
+
+Execute [agents/release-git.md](../../../agents/release-git.md) or spawn shell subagent.
+
+## Wave 1.5 — conditional publish (project overlay)
 
-Only after Wave 1 `status: success`. Pass `commit_sha` and messages.
+When the project ships an npm package with the app (e.g. `@ludecker/aaac`), the project overlay supplies a conditional publish agent and detection scripts. Skip when no changes detected.
 
-| Agent spec | Tool |
-|------------|------|
-| [release-render.md](../../../agents/release-render.md) | generalPurpose or render-assistant MCP |
+## Wave 2 — Render (mandatory)
 
-## Preflight
+Execute [agents/release-render.md](../../../agents/release-render.md).
 
-If intent contains "test" / "with tests": run `pnpm typecheck` before Wave 1.
+**Never** end ship without polled deploy status.
 
 ## Reference
 
-Full step detail: [ship-procedure.md](ship-procedure.md)
+Full steps: [ship-procedure.md](ship-procedure.md)

package/templates/cursor/skills/shared/platform-release/orchestrator/contract.yaml

@@ -1,5 +1,5 @@
 name: release-app-orchestrator
-purpose: Ship to main with phased expert subagents (git, then parallel integrations)
+purpose: Ship to main with preflight, git push, optional conditional package publish, mandatory Render deploy poll, smoke check, report
 inputs:
   domain:
     required: false
@@ -9,21 +9,41 @@ inputs:
 outputs:
   commit_sha:
     type: string
+  package_publish_skipped:
+    type: boolean
+  package_version:
+    type: string
+  package_tag:
+    type: string
+  package_publish_status:
+    type: string
   deploy_status:
     type: string
+  deploy_id:
+    type: string
+  smoke_http_code:
+    type: number
   report:
     type: markdown
 success_criteria:
-  - git push to main succeeded
-  - render deploy reached live or build failure reported with logs
-  - posthog and linear agents run after git (parallel wave)
+  - pnpm typecheck passed
+  - git push to main succeeded (or HEAD already on remote)
+  - when package changes detected, ship checks passed and version published
+  - render deploy reached live for commit_sha
+  - smoke check returned 200
 failure_conditions:
+  - typecheck failed
   - git push failed
-  - wave 2 started before commit_sha known
+  - wave 1.5 or 2 started before commit_sha known
+  - package ship checks failed when triggered
+  - package publish monitor timeout when triggered
+  - render build_failed or poll timeout
+  - smoke check not 200
 dependencies:
   skills: [platform-release, testing, verification, reporting]
   policies: [master-rules, mcp-and-deploy]
 verification:
+  - typecheck_passed
   - git_pushed
-  - render_polled
-  - agent_wave_order_respected
+  - render_polled_until_live
+  - smoke_200

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

@@ -18,6 +18,11 @@ Phase `verify` (and `test_only` orchestrators). On **fix** paths, run fix verify
 2. Invoke [unit-test-run.md](../../../agents/unit-test-run.md) pattern for targeted vitest
 3. Fallow MCP → `check_changed` on touched files when configured
 4. `ReadLints` on edited paths
+5. **Website build gate (mandatory on create / update / fix):** before advancing `verify`, run:
+   ```bash
+   node .cursor/aaac/scripts/run-engine/verify-website-build.mjs --run-id <run_id>
+   ```
+   This checks `index.html` static asset paths resolve under `apps/website/public/` (or project root for Vite dev) and runs `pnpm --filter @ludecker/website build`. `advance-phase.mjs verify` **blocks** until this passes and writes `artifacts/verify.yaml`.
 
 ## Fix verify swarm (mandatory on fix verb / fix_mode)
 

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

@@ -14,6 +14,7 @@ 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`

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)