@ludecker/aaac 1.1.1 → 1.1.3

package/templates/docs/agentic_architecture.md

@@ -23,75 +23,85 @@ Ask: *What do I want?* Then type:
 | Part | Meaning | Example |
 |------|---------|---------|
 | Command | Kind of work | `update-module` |
-| Domain | Which area | `cms` |
-| Intent | Goal in plain language | `"Add featured hero toggle to home page"` |
+| Domain | Which area (optional until you add domains) | `payments` |
+| Intent | Goal in plain language | `"Add idempotency key to webhook handler"` |
 
-### Ludecker domains
+### Command matrix (ships with every install)
 
-| 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 |
+AAAC generates ~130 commands from **8 verbs × 12 objects**:
 
-### Commands (Ludecker v1)
+| Verb | Meaning | Example |
+|------|---------|---------|
+| `create` | Add something new | `/create-module api "Add rate limiter"` |
+| `update` | Change existing | `/update-component ui "Extract Button variants"` |
+| `fix` | Repair broken behavior | `/fix-module auth "Session expires on refresh"` |
+| `review` | Readonly quality check | `/review-architecture system "Check layer boundaries"` |
+| `check` | Readonly capability trace | `/check-module api "Can we add OAuth?"` |
+| `test` | Run verification | `/test-module api "Contract tests for webhooks"` |
+| `release` | Ship to production | `/release-app production "Ship v2.1.0"` |
+| `remove` | Delete safely | `/remove-module legacy "Drop v1 export path"` |
+
+**Exception commands** (dedicated orchestrators):
 
 | Command | When to use |
 |---------|-------------|
-| `update-module` | Change an existing bounded module (`cms`, `ui`, `database`, `aaac`) |
 | `update-doc` | Update architecture documentation (no code) |
-| `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 swarm (git → Render) |
-| `publish-aaac` | Bump, smoke-test, and publish `@ludecker/aaac` to npm |
-| `write-article` | Research swarm → CMS article persist |
-
-### Manual commands (local dev)
-
-| Command | When to use |
-|---------|-------------|
-| `launch-ludecker` | Clean local dev server start |
-| `kill-ludecker` | Kill stale local port listeners |
+| `review-incident` | Investigate production or deploy issue |
+| `test-function` | Test a user journey end-to-end |
+| `release-app` | Phased release swarm (git → deploy) |
+| `fix-module` / `fix-bug` | Full fix swarm — domain optional until you add resolvers |
+
+### Out of the box — no setup after install
+
+Install copies everything you need. Open the project in Cursor and run commands.
+
+- ~130 slash commands and the full shared pipeline (discover → plan → execute → verify → report)
+- Generic `master_rules.md` and `architecture.md` in your docs folder — **already filled in**, not empty stubs
+- Hook scripts and Run lifecycle under `.cursor/`
+- Generic capability registry (shared skills only)
+- **No** project domains required; **no** app build gate until you opt in (`verify.enabled: false` in `project.config.json`)
+
+You do **not** need to enable hooks manually, write rules, add domains, or configure a stack before your first command.
+
+### Optional — when you want more (any stack)
+
+1. Replace or extend `docs/master_rules.md` and `docs/architecture.md` with team-specific detail
+2. Add `domains/<slug>/update/` (orchestrator + inventory) — see Part 2
+3. Extend `graph.project.yaml` with resolvers and project skills
+4. Enable verify in `project.config.json` when you have a web app to gate:
+
+```json
+{
+  "verify": {
+    "enabled": true,
+    "app_root": "apps/web",
+    "index_html": "apps/web/index.html",
+    "build": { "command": "pnpm", "args": ["--filter", "web", "build"] }
+  }
+}
+```
 
-### Examples
+### Examples (generic)
 
 ```text
-/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
+/create-module billing "Add invoice PDF export"
+/update-component ui "Tokenize spacing scale"
+/fix-module api "Webhook signature validation fails on chunked bodies"
+/review-module billing "Check SSOT for tax rates"
+/test-function checkout "Guest can complete purchase"
+/release-app staging "Deploy with migration"
+/update-doc architecture "Document event bus boundaries"
 ```
 
-### 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.
 
+### Reference implementation
+
+[Lüdecker](https://ludecker.com) dogfoods AAAC with `cms`, `ui`, `database`, and `aaac` domains. That overlay lives in the Lüdecker repo — not in the generic npm template.
+
 ---
 
 ## Part 2 — Appendix (maintainers)
@@ -120,7 +130,7 @@ Knowledge Layer     → docs/
 | Lifecycle | **Work** phase configuration |
 | Gate stacks | **Approval** checkpoints |
 | Run | Primary execution object; decisions, log, checkpoints |
-| Domain orchestrators | Domain coordination |
+| Domain orchestrators | Domain coordination (you add these) |
 | Shared pipeline skills | Phase execution |
 | Capability registry | object → capability → provider |
 | Object skills | Skill-type providers |
@@ -139,7 +149,7 @@ Intent → Command → Execution Graph → Result
 
 **Execution graph** = orchestrator + skills + agents + tools + rules + documentation.
 
-**SSOT:** [`.cursor/aaac/graph.yaml`](../.cursor/aaac/graph.yaml)
+**SSOT:** [`.cursor/aaac/graph.yaml`](../.cursor/aaac/graph.yaml) (generated — edit `graph.project.yaml` instead)
 
 **Dispatch procedure:** [`.cursor/aaac/dispatch.md`](../.cursor/aaac/dispatch.md)
 
@@ -148,17 +158,32 @@ Intent → Command → Execution Graph → Result
 ```text
 .cursor/
   commands/          # thin routers (public)
-  aaac/graph.yaml    # wiring (private OS)
+  aaac/
+    graph.project.yaml # your overlay (resolvers, orchestrators)
+    graph.yaml         # generated wiring
   domains/<slug>/update/
     orchestrator/    # what happens
     inventory/       # what exists
-  skills/shared/     # framework (discovery, planning, execution, …)
-  skills/ludecker/   # project-specific object skills
-  skills/write-article/  # content swarm
+  skills/shared/     # framework pipeline
+  skills/<project>/  # your object-capability skills (optional)
   agents/            # subagent prompt specs
   policies/          # rules all skills inherit
 ```
 
+### Generic kernel vs project overlay
+
+| Layer | Location | Owner |
+|-------|----------|-------|
+| Generic kernel | `@ludecker/aaac` npm templates | Package maintainers |
+| Project overlay | `.cursor/aaac/graph.project.yaml`, `ontology.json`, `project.config.json` | Your repo |
+| Domains | `.cursor/domains/<slug>/` | Your repo |
+
+Regenerate after ontology or overlay edits:
+
+```bash
+npx @ludecker/aaac@latest generate
+```
+
 ### Orchestrator vs inventory
 
 | | Orchestrator | Inventory |
@@ -166,21 +191,8 @@ Intent → Command → Execution Graph → Result
 | 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 |
@@ -190,125 +202,38 @@ Policies → Ontology → Graph → Create Run
 | 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`.
+**Gate stacks** (SSOT: [`.cursor/aaac/governance/gates.json`](../.cursor/aaac/governance/gates.json))
 
 ### 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)
+object → capability → provider (skill | mcp)
 ```
 
-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.
+Replace generic shared-skill providers with project skills as you mature.
 
 ### 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
+2. Add resolver entries to `graph.project.yaml` — **no new command shape**
+3. Regenerate: `npx @ludecker/aaac@latest generate`
 
-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)
+See [module-authoring/SKILL.md](../.cursor/skills/shared/module-authoring/SKILL.md).
 
 ### Release swarm (`release-app`)
 
-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).
+Wave 1: `release-git` (blocking). Add deploy agents in your overlay (e.g. `release-render`, `release-k8s`) — generic template ships git only.
 
 ### Regenerating commands
 
 ```bash
-pnpm aaac:generate
-```
-
-Or:
-
-```bash
-node .cursor/aaac/generate-graph.mjs
-node .cursor/aaac/generate-commands.mjs
+npx @ludecker/aaac@latest generate
 ```
 
 Ontology reference: [`.cursor/aaac/ontology.md`](../.cursor/aaac/ontology.md)

package/templates/docs/architecture.md

@@ -1,5 +1,47 @@
 # Architecture
 
-Describe your system map: layers, modules, data flow, and deployment.
+This describes how your repo works with Agentic OS. It ships ready to use — edit only when you want project-specific detail.
 
-AAAC policies reference this file. Replace this stub with your project architecture.
+## Your project + Agentic OS
+
+```text
+your-repo/
+  (your app code — any stack)
+  .cursor/          ← Agentic OS (commands, skills, agents, runs)
+  docs/             ← rules and architecture (this folder)
+```
+
+Agentic OS does not replace your app. It sits beside your code and gives Cursor a structured way to create, update, fix, review, test, and release work.
+
+## How you work
+
+You type a **command** and a short **intent**. The system runs a pipeline (discover → plan → execute → verify → report) and keeps agents on track.
+
+```text
+/create-module billing "Add invoice export"
+/fix-module api "Webhook fails on retries"
+/review-architecture system "Check layer boundaries"
+```
+
+You do not need to learn skills, agents, or orchestrators — those are internal.
+
+## Layers (generic)
+
+| Layer | Does | Does not |
+|-------|------|----------|
+| UI | Render, user interaction | Business rules, direct database access |
+| Domain | Rules, validation, invariants | UI markup, framework-specific rendering |
+| Infrastructure | APIs, persistence, adapters | Business decisions |
+
+## What ships on install
+
+- ~130 slash commands (create, update, fix, review, check, test, release, remove × modules, APIs, UI, etc.)
+- Shared pipeline skills and subagent specs
+- Run lifecycle and hook scripts under `.cursor/`
+- Generic rules in this folder (ready without edits)
+
+## Optional later
+
+Add domains under `.cursor/domains/<name>/` when you want deeper knowledge of a bounded area (payments, auth, CMS, etc.). Extend `.cursor/aaac/graph.project.yaml` to route commands to those domains. Enable build verification in `.cursor/aaac/project.config.json` when you have a web app to gate before release.
+
+None of that is required to start.

package/templates/docs/master_rules.md

@@ -1,5 +1,29 @@
 # Master rules
 
-Define your project’s non-negotiable architecture and implementation rules here.
+These rules apply to every code change in this project. Agentic OS loads them automatically — you do not need to configure anything after install.
 
-AAAC orchestrators load this file via `.cursor/policies/master-rules.md`. Replace this stub with your team’s rules.
+## Core principles
+
+1. **One source of truth** — Each fact lives in one place. Do not duplicate constants, config, or state.
+2. **Clear layers** — UI renders and handles interaction. Domain logic holds business rules. Infrastructure talks to databases and APIs. Do not mix these roles in one file.
+3. **Predictable flow** — Data moves in one direction: input → logic → output. No hidden side effects.
+4. **Explicit errors** — Log and surface failures. Do not fail silently.
+5. **Clarity over cleverness** — Prefer readable code over shortcuts.
+
+## Implementation
+
+- Pull values from config, env, or constants — not unexplained literals in components.
+- Use shared styles or design tokens — not inline styles in UI code.
+- One named component per file.
+- Async work should be cancellable where possible and logged at boundaries.
+- Add or update tests when behavior changes.
+
+## Modules
+
+- Keep files focused: one job per module.
+- Reuse and extend existing code before adding parallel implementations.
+- Name things for intent, not implementation detail.
+
+## Optional later
+
+When your project grows, you can replace or extend this file with team-specific rules. Until then, these defaults are enough.