@ludecker/aaac 1.1.0 → 1.1.2

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,71 +23,87 @@ 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 (optional until you add domains) | `payments` |
+| Intent | Goal in plain language | `"Add idempotency key to webhook handler"` |
+
+### Command matrix (ships with every install)
 
-### Commands (AAAC v1)
+AAAC generates ~130 commands from **8 verbs × 12 objects**:
+
+| 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 |
 | `update-doc` | Update architecture documentation (no code) |
-| `create-feature` | Add a new capability |
-| `fix-bug` | Fix broken behavior |
 | `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) |
-
-Verb×object matrix commands (`create-component`, `check-schema`, …) route through shared verb orchestrators. See [`.cursor/aaac/ontology.md`](../.cursor/aaac/ontology.md).
+| `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 |
+
+### Fresh install — what works day one
+
+- Verb×object commands and shared pipeline (discover → plan → execute → verify → report)
+- Cursor hook enforcement and Run lifecycle
+- Generic capability registry (shared skills only)
+- **No** project domains, **no** hardcoded app build gate (`verify.enabled: false` in `project.config.json`)
+
+### After you customize (any stack)
+
+1. Write `docs/master_rules.md` and `docs/architecture.md`
+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 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"
-/release-app production "Ship with typecheck"
+/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"
 ```
 
 ### What you should not need to know
 
 skill, agent, subagent, tool, workflow, graph, orchestrator — infrastructure only.
 
----
-
-## 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:
+### Reference implementation
 
-```bash
-npx @ludecker/aaac@latest generate
-# or
-pnpm dlx @ludecker/aaac@latest generate
-```
+[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.
 
-### 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)
+## Part 2 — Appendix (maintainers)
 
 ### 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 +113,122 @@ 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/
 ```
 
-**SSOT:** [`.cursor/aaac/graph.yaml`](../.cursor/aaac/graph.yaml)
+| 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 (you add these) |
+| 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
 
-**Dispatch:** [`.cursor/aaac/dispatch.md`](../.cursor/aaac/dispatch.md)
+```text
+Intent → Command → Execution Graph → Result
+```
+
+**Execution graph** = orchestrator + skills + agents + tools + rules + documentation.
+
+**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)
 
 ### Directory layout
 
 ```text
 .cursor/
   commands/          # thin routers (public)
-  aaac/              # ontology, graph, generators config
+  aaac/
+    graph.project.yaml # your overlay (resolvers, orchestrators)
+    graph.yaml         # generated wiring
   domains/<slug>/update/
-    orchestrator/
-    inventory/
-  skills/shared/     # pipeline + verb orchestrators
+    orchestrator/    # what happens
+    inventory/       # what exists
+  skills/shared/     # framework pipeline
+  skills/<project>/  # your object-capability skills (optional)
   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
+```
+
+### 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 |
+|--|--------------|-----------|
+| Question | What should happen? | What exists? |
+| Updates when | Workflow changes | After every code-changing `update-module` |
+
+### Execution determinism (create / update / fix)
+
+**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))
+
+### 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)
 ```
 
+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)
+
+### Adding a product domain
+
+1. Add `domains/<slug>/update/` (inventory + orchestrator)
+2. Add resolver entries to `graph.project.yaml` — **no new command shape**
+3. Regenerate: `npx @ludecker/aaac@latest generate`
+
+See [module-authoring/SKILL.md](../.cursor/skills/shared/module-authoring/SKILL.md).
+
 ### Release swarm (`release-app`)
 
-Wave 1: `release-git` (blocking). Configure deploy agents in `graph.project.yaml` for your host.
+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
+npx @ludecker/aaac@latest generate
+```
 
-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)