@ludecker/aaac 1.1.2 → 1.1.4

package/README.md

@@ -24,14 +24,16 @@ npx @ludecker/aaac@latest init --yes --dir /path/to/your/repo
 
 ## What you get
 
-- `.cursor/hooks.json` — runtime enforcement (enable in Cursor Settings → Hooks)
+Works **out of the box** after `init` — open in Cursor and run commands. No post-install setup.
+
+- `.cursor/hooks.json` — Run lifecycle and edit enforcement (installed with the project)
 - `.cursor/aaac/` — ontology, graph, lifecycle, run model, enforcement
 - `.cursor/skills/shared/` — full pipeline (discovery → execute → verify → report)
 - `.cursor/agents/` — 13 generic subagent specs
 - `.cursor/commands/` — ~130 generated slash commands
-- `docs/agentic_architecture.md` — user + maintainer guide
+- `docs/` — ready-to-use `master_rules.md`, `ui_design.md`, `project_context.md`, `architecture.md`, and `agentic_architecture.md`
 
-Add project-specific **domains** under `.cursor/domains/<slug>/` (see maintainer appendix).
+Optional later: add **domains** under `.cursor/domains/<slug>/` (see maintainer appendix in `agentic_architecture.md`).
 
 ## Regenerate
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ludecker/aaac",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Agentic Architecture as Code (AAAC) — installable Cursor agent framework",
   "type": "module",
   "license": "MIT",

package/src/cli.mjs

@@ -86,20 +86,21 @@ async function cmdInit(args) {
   });
 
   console.log(`
-AAAC installed.
+Agentic OS is ready.
 
   .cursor/     → ${cursorDest}
   docs/        → ${docsDest}
 
-Next steps:
-  1. Enable Cursor Hooks (Settings → Hooks) and restart Cursor
-  2. Open the project in Cursor
-  3. Create ${options.docsRoot}/master_rules.md and ${options.docsRoot}/architecture.md if missing
-  4. Try /review-architecture or /check-architecture
-  5. Read ${options.docsRoot}/agentic_architecture.md — Part 2 for adding domains
+Open this project in Cursor and use any command, for example:
 
-Regenerate after ontology changes:
-  pnpm dlx @ludecker/aaac@latest generate
+  /create-module api "Add health check endpoint"
+  /fix-module auth "Session expires too soon"
+  /review-architecture system "Check structure"
+
+No setup required after install. Rules and architecture docs are already in place.
+To go deeper later, read ${options.docsRoot}/agentic_architecture.md (Part 2 — optional).
+
+Regenerate commands after ontology edits:
   npx @ludecker/aaac@latest generate
 `);
 }

package/templates/cursor/aaac/graph.project.yaml

@@ -189,5 +189,7 @@ agents:
 
 policies:
   - policies/master-rules.md
+  - policies/project-context.md
+  - policies/ui-design.md
   - policies/implementation.md
   - policies/mcp-and-deploy.md

package/templates/cursor/aaac/scripts/run-engine/verify-website-build.mjs

@@ -25,7 +25,7 @@ function loadVerifyConfig() {
   if (!verify.enabled) {
     return { enabled: false };
   }
-  const appRootRel = verify.app_root ?? "apps/website";
+  const appRootRel = verify.app_root ?? "apps/web";
   const indexRel =
     verify.index_html ?? path.join(appRootRel, "index.html").replace(/\\/g, "/");
   const appRoot = path.join(PROJECT_ROOT, appRootRel);

package/templates/cursor/agents/fix-runtime-evidence.md

@@ -9,7 +9,7 @@ Gather runtime evidence — logs, CI, MCP, browser errors — for the symptom.
 ## Procedure
 
 1. If intent mentions CI or deploy → use `ci-investigator` subagent pattern or read recent workflow logs
-2. If database/RLS → Supabase MCP `get_logs`, `get_advisors` (project `anseivwusnyiwopihnqu`)
+2. If database/RLS → use configured database MCP `get_logs`, `get_advisors` (see [mcp-and-deploy.md](../../policies/mcp-and-deploy.md))
 3. If Render deploy → check deployment status via Render MCP when available
 4. If error message pasted → search codebase for matching string
 5. Never log secrets or tokens

package/templates/cursor/policies/implementation.md

@@ -2,6 +2,9 @@
 
 **Sources:**
 
+- [{{DOCS_ROOT}}/master_rules.md](../../{{DOCS_ROOT}}/master_rules.md)
+- [{{DOCS_ROOT}}/ui_design.md](../../{{DOCS_ROOT}}/ui_design.md)
+- [{{DOCS_ROOT}}/project_context.md](../../{{DOCS_ROOT}}/project_context.md)
 - [{{DOCS_ROOT}}/architecture.md](../../{{DOCS_ROOT}}/architecture.md)
 - [.cursor/skills/shared/governance/implementation/SKILL.md](../skills/shared/governance/implementation/SKILL.md)
 

package/templates/cursor/policies/mcp-and-deploy.md

@@ -0,0 +1,14 @@
+# Policy: MCP and deploy
+
+Optional project overlay. Add rule files under `.cursor/rules/` when you use MCP servers or a deploy platform.
+
+| Concern | Where to configure |
+|---------|-------------------|
+| Database MCP | `.cursor/rules/<provider>-mcp.mdc` — migrations, project ref, RLS |
+| Deploy / hosting | `.cursor/rules/deploy.mdc` — service name, blueprint, smoke URL |
+
+**Migrations:** When you add SQL under your migrations folder, apply via your configured database MCP immediately after the change.
+
+**Deploy checks:** Use the MCP server your team configures in Cursor settings. Put vendor project IDs and service names in `docs/project_context.md` or `.cursor/rules/` — not in shared generic skills.
+
+Generic installs ship without provider-specific rule files. Add them when you connect Supabase, Render, or another provider.

package/templates/cursor/policies/minimal-complexity.md

@@ -67,9 +67,9 @@ complexity_breakdown:
   new_api_endpoint: 1
   modify: 1
 reuse:
-  - "ExportButton pattern from packages/ui"
+  - "ExportButton pattern from <design-system-package>"
 modify:
-  - "apps/website/app/api/export/route.ts (extend existing export handler)"
+  - "<app>/api/export/route.ts (extend existing export handler)"
 create:
   - artifact: "GET /api/export/csv"
     kind: new_api_endpoint

package/templates/cursor/policies/project-context.md

@@ -0,0 +1,5 @@
+# Policy: Project context
+
+**Source of truth:** [{{DOCS_ROOT}}/project_context.md](../../{{DOCS_ROOT}}/project_context.md)
+
+Project-specific paths, SSOT anchors, and tooling. Master rules stay stack-agnostic. Domain skills cannot override master rules.

package/templates/cursor/policies/ui-design.md

@@ -0,0 +1,5 @@
+# Policy: UI design and CSS
+
+**Source of truth:** [{{DOCS_ROOT}}/ui_design.md](../../{{DOCS_ROOT}}/ui_design.md)
+
+Loaded for UI, component, and styling work. Agents must read before writing CSS or presentational markup. Master Rules §5 and §41 apply.

package/templates/cursor/rules/aaac-enforcement.mdc

@@ -11,8 +11,8 @@ Every AAAC slash command (`/fix-module`, `/update-module`, `/write-article`, …
 
 ## Prerequisites
 
-1. **Cursor Hooks enabled** — Settings → Hooks; restart Cursor after `.cursor/hooks.json` changes
-2. **Registry current** — `node .cursor/aaac/generate-graph.mjs`
+1. **Project opened in Cursor** — `.cursor/hooks.json` is installed by `init`; hooks run when the project is open
+2. **Registry current** — after ontology edits: `npx @ludecker/aaac@latest generate`
 
 ## Hook behavior (automatic)
 

package/templates/cursor/skills/shared/architecture/refactor-analysis.md

@@ -61,7 +61,7 @@ Also read the target with codebase tools (Grep, Read) — do not rely on shell a
 #### S - Single Responsibility
 
 Look for:
-- Files over budget (see Master Rules §19: routes 200, components 250, lib 300, openrouter 350)
+- Files over budget (see Master Rules §19: routes 200, components 250, lib 300)
 - Functions over 80 lines (or nested callbacks over 40)
 - Classes with > 10 methods
 - Mixed concerns (data + UI + business logic)
@@ -166,7 +166,7 @@ For each issue found, assess:
 - **Effort**: Lines to change, tests needed?
 - **Master rule**: Which rule(s) does fixing this satisfy?
 
-Prioritize: clarity and predictability over clever abstractions (Rule 22).
+Prioritize: clarity and predictability over clever abstractions (Rule 42).
 
 ## Output Format
 
@@ -196,7 +196,7 @@ Use this template exactly:
 | Area | Status | Top violations |
 |------|--------|----------------|
 | SSOT & layers | 🟡/🟢/🔴 | [e.g. UI fetching in component] |
-| UI discipline | 🟡/🟢/🔴 | [e.g. inline components] |
+| UI discipline | 🟡/🟢/🔴 | [e.g. inline components, deep CSS selectors — see ui_design.md] |
 | Boundaries & errors | 🟡/🟢/🔴 | [e.g. unvalidated API body] |
 | Async & state | 🟡/🟢/🔴 | [e.g. ad-hoc flags vs state machine] |
 | Testing & logging | 🟡/🟢/🔴 | [e.g. no tests for changed module] |
@@ -244,7 +244,7 @@ Use this template exactly:
 
 ### ⚠️ Technical Debt Notes
 
-- [Items to defer — document why per Rule 21 if suggesting exceptions]
+- [Items to defer — document why per Rule 34 if suggesting exceptions]
 
 ---
 
@@ -252,14 +252,14 @@ Use this template exactly:
 
 Before applying suggestions:
 
-- [ ] Tests exist for affected code (Rule 20)
+- [ ] Tests exist for affected code (Rule 21)
 - [ ] Create feature branch
 - [ ] Commit current state (only when user asks)
 - [ ] Apply **one** refactoring at a time
 - [ ] Run tests after each change
 - [ ] Review diff before committing
 - [ ] No scope creep — minimal diff (user preference)
-- [ ] Document any intentional rule exception (Rule 21)
+- [ ] Document any intentional rule exception (Rule 34)
 
 ## Applying Refactorings
 
@@ -270,7 +270,7 @@ When the user asks to implement (not just analyze):
 3. Centralize schemas and validation at boundaries
 4. Extract to new files (no inline components)
 5. Add/update behavioral tests, not implementation-detail tests
-6. Use structured logging on new async paths (Rule 19)
+6. Use structured logging on new async paths (Rule 20)
 
 ## Usage
 

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

@@ -15,14 +15,13 @@ Orchestrator phase `execute` after approved plan.
 ## Mandatory
 
 1. Read [governance/implementation/SKILL.md](../governance/implementation/SKILL.md)
-2. Read domain [inventory](../../../domains/) constraints
+2. Read domain inventory when present (`domains/<slug>/update/inventory/`)
 3. Read [policies/](../../../policies/)
 
 ## Actions
 
 - Edit files per plan and implementation skill
-- `apply_migration` for new/changed `supabase/migrations/` (project `anseivwusnyiwopihnqu` — see [supabase-mcp.mdc](../../../rules/supabase-mcp.mdc))
-- `track()` for user-facing mutations
+- Apply database migrations via configured MCP when your project uses one (see [mcp-and-deploy.md](../../../policies/mcp-and-deploy.md) and `{{DOCS_ROOT}}/project_context.md`)
 - Structured logging on server async paths
 
 ## Must not

package/templates/cursor/skills/shared/governance/implementation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: implementation
-description: Enforces project master rules and architecture when implementing code. Read {{DOCS_ROOT}}/master_rules.md and {{DOCS_ROOT}}/architecture.md before any code change.
+description: Enforces project master rules and architecture when implementing code. Read {{DOCS_ROOT}}/master_rules.md, {{DOCS_ROOT}}/ui_design.md (UI/CSS), {{DOCS_ROOT}}/project_context.md, and {{DOCS_ROOT}}/architecture.md before any code change.
 ---
 
 # Implementation
@@ -10,6 +10,8 @@ All code changes must comply with your project docs. **If implementation conflic
 | Document | Path | Governs |
 |----------|------|---------|
 | Master Rules | [{{DOCS_ROOT}}/master_rules.md](../../../../{{DOCS_ROOT}}/master_rules.md) | Architecture, layers, SSOT, testing |
+| UI Design | [{{DOCS_ROOT}}/ui_design.md](../../../../{{DOCS_ROOT}}/ui_design.md) | CSS discipline, selectors, layout, a11y |
+| Project Context | [{{DOCS_ROOT}}/project_context.md](../../../../{{DOCS_ROOT}}/project_context.md) | Repo paths, SSOT anchors, tooling |
 | Architecture | [{{DOCS_ROOT}}/architecture.md](../../../../{{DOCS_ROOT}}/architecture.md) | System shape, modules, data flow, deploy |
 
 Read the relevant sections **before** implementing. Add project-specific object skills under `.cursor/skills/<project>/` and wire them in `capabilities/registry.json` when you outgrow the generic defaults.
@@ -20,8 +22,9 @@ Read the relevant sections **before** implementing. Add project-specific object
 
 1. **Identify the layer** you are touching (UI, state, domain, infrastructure).
 2. **Read** the matching section in master rules and architecture docs.
-3. **Check reuse** — extend existing modules before adding new ones.
-4. **Respect boundaries** — UI renders only; domain owns rules; infrastructure persists.
+3. **UI/CSS work:** read [ui_design.md](../../../../{{DOCS_ROOT}}/ui_design.md) — shallow CSS, no premature token architecture (Rules §5, §41).
+4. **Check reuse** — extend existing modules before adding new ones.
+5. **Respect boundaries** — UI renders only; domain owns rules; infrastructure persists.
 
 ---
 
@@ -41,13 +44,13 @@ Direction: **Input → State → Logic → Output**. No circular imports across
 ## Checklist (execute phase)
 
 - [ ] Values from config/constants — no unexplained literals
-- [ ] Token/class-based CSS — no inline styles in UI components
+- [ ] Class-based CSS per ui_design.md — no inline styles; shallow selectors
 - [ ] One component per file; named exports
 - [ ] Async ops: cancellable, logged at boundaries
 - [ ] Tests appropriate to the change (unit for domain, integration for boundaries)
 
 ---
 
-## Project overlay
+## Project overlay (optional)
 
-After `npx @ludecker/aaac init`, replace this generic skill with project-specific rules, or add a `skills/<project>/implementation/` skill and point `execution` depends in `graph.project.yaml`.
+Generic rules ship in `{{DOCS_ROOT}}/master_rules.md` and work without edits. Put repo-specific paths and SSOT anchors in `{{DOCS_ROOT}}/project_context.md`. When you outgrow defaults, extend those docs or add a `skills/<project>/implementation/` skill and wire it in `graph.project.yaml`.

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

@@ -9,8 +9,8 @@ disable-model-invocation: true
 
 ## Scope
 
-- `apps/website/app/api/`, Supabase MCP, Render deploy policies
-- Project rules: [deploy.mdc](../../../../rules/deploy.mdc), [supabase-mcp.mdc](../../../../rules/supabase-mcp.mdc)
+- Your app's API routes, webhooks, and OAuth adapters
+- Optional: [mcp-and-deploy.md](../../../policies/mcp-and-deploy.md) and `.cursor/rules/` when MCP or deploy is configured
 
 ## Execution focus
 

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

@@ -17,7 +17,7 @@ Wave 1: release-git  ← BLOCKING
   ↓
 Wave 1.5: conditional package publish ← OPTIONAL (project overlay; blocking when triggered)
   ↓
-Wave 2: release-render ← BLOCKING (poll until live or fail)
+Wave 2: deploy agent ← OPTIONAL (project overlay; poll until live or fail)
   ↓
 Wave 3: verification + reporting
 ```
@@ -36,13 +36,11 @@ Execute [agents/release-git.md](../../../agents/release-git.md) or spawn shell s
 
 ## Wave 1.5 — conditional publish (project overlay)
 
-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.
+When the project ships an npm package with the app, the project overlay supplies a conditional publish agent and detection scripts. Skip when no changes detected.
 
-## Wave 2 — Render (mandatory)
+## Wave 2 — Deploy (optional)
 
-Execute [agents/release-render.md](../../../agents/release-render.md).
-
-**Never** end ship without polled deploy status.
+When configured, run the project overlay deploy agent. **Never** end ship without polled deploy status when deploy is enabled.
 
 ## Reference
 

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

@@ -18,7 +18,7 @@ disable-model-invocation: true
 1. [../SKILL.md](../SKILL.md) — swarm DAG
 2. [ship-procedure.md](../ship-procedure.md) — step reference
 3. [graph.yaml](../../../../aaac/graph.yaml) — `release-app`
-4. [ludecker-infrastructure](../../../ludecker/infrastructure/SKILL.md)
+4. Project overlay infrastructure skill when present (`skills/<project>/infrastructure/`)
 
 ## Phases
 
@@ -32,11 +32,11 @@ Spawn subagent per [agents/release-git.md](../../../../agents/release-git.md).
 
 **Do not** start Wave 2 until `commit_sha` is returned.
 
-### 2. Wave 2 — Render
+### 2. Wave 2 — Deploy (optional)
 
-Spawn [release-render](../../../../agents/release-render.md) with `commit_sha`, `commit_message_first_line`, `commit_message_body`.
+When project overlay supplies a deploy agent, spawn it with `commit_sha`, `commit_message_first_line`, `commit_message_body`. Skip when not configured.
 
-If Render `build_failed`, overall status is failed.
+If deploy `build_failed`, overall status is failed.
 
 ### 3. Verify + report
 

package/templates/cursor/skills/shared/platform-release/ship-procedure.md

@@ -1,31 +1,30 @@
 # Release ship procedure (reference)
 
-Canonical steps migrated from legacy `/ship-ludecker`. Subagents in `agents/release-*.md` own each slice.
+Generic git-first release. Deploy steps are **optional** — enable via project overlay (`docs/project_context.md`, `.cursor/rules/deploy.mdc`). Subagents in `agents/release-*.md` own each slice.
 
 ## Git (Wave 1 — blocking)
 
-1. Confirm repo: `signalbynoise/ludecker` (or local ludecker monorepo)
+1. Confirm repo root (`git rev-parse --show-toplevel`)
 2. `git status` + `git diff` + `git diff --staged` + `git log -5 --oneline`
-3. Never stage `.env`, `.env.local`, credentials, or API keys
+3. Never stage `.env`, credentials, or API keys
 4. Draft 1–2 sentence commit message from diff and user intent
 5. `git add` intentional paths → `git commit` (HEREDOC message)
-6. Ensure on `main`: `git checkout main` if needed; `git pull --rebase origin main`
-7. `git push origin main` — on reject, rebase once more; never force-push main
+6. Ensure on default branch: checkout if needed; `git pull --rebase origin <branch>`
+7. `git push origin <branch>` — on reject, rebase once more; never force-push protected branches
 8. Output: `commit_sha`, `commit_message_first_line`, `commit_message_body`
 
-**Rules:** No force-push main. On pre-commit hook failure: fix and new commit — never amend unless user asked.
+**Rules:** No force-push to protected branches. On pre-commit hook failure: fix and new commit — never amend unless user asked.
 
-## Render (Wave 2 — after push)
+## Deploy (Wave 2 — optional, project overlay)
 
-MCP: `user-render` only (not `plugin-render-render`).
+Skip when no deploy agent or `project.config.json` deploy section is configured.
 
-**Service SSOT:** `ludecker-website` (see `render.yaml`, `docs/deployment.md`).
-
-1. `list_services` — find `name === "ludecker-website"`, note `id`
-2. After push: `list_deploys` (`limit: 5`) — match deploy `commit.id` to `commit_sha`
-3. Poll up to **15 minutes**, every **30s**, until `status === "live"` or terminal failure
-4. Smoke check: `curl -fsS -o /dev/null -w "%{http_code}" https://ludecker-website.onrender.com/` — expect **200**
+1. Read service name and smoke URL from `docs/project_context.md` or `.cursor/rules/deploy.mdc`
+2. Use your team's configured deploy MCP (see [mcp-and-deploy.md](../../../policies/mcp-and-deploy.md))
+3. After push: list deploys — match `commit.id` to `commit_sha`
+4. Poll until `live` or terminal failure
+5. Smoke check production URL — expect success status
 
 ## Preflight (optional, Wave 0)
 
-If intent includes "with tests": run `pnpm typecheck` from repo root before git work.
+If intent includes "with tests": run project typecheck/test command from repo root before git work.

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

@@ -14,7 +14,7 @@ disable-model-invocation: true
 
 ## Execution focus
 
-- New migration file per change; apply via Supabase MCP (`hjadkzfemzuvhpwbixbt`)
+- New migration file per change; apply via configured database MCP (see [mcp-and-deploy.md](../../../policies/mcp-and-deploy.md))
 - Backward-compatible defaults; document breaking changes in report
 - RLS and security advisors after apply
 

package/templates/cursor/skills/shared/verbs/_dispatch-utils.md

@@ -16,9 +16,11 @@ Orchestrators execute phases from the Run `pending` queue. Do not skip gates unl
 Read before any phase:
 
 1. [.cursor/policies/master-rules.md](../../../policies/master-rules.md)
-2. [.cursor/policies/implementation.md](../../../policies/implementation.md)
-3. [.cursor/policies/mcp-and-deploy.md](../../../policies/mcp-and-deploy.md)
-4. [.cursor/policies/minimal-complexity.md](../../../policies/minimal-complexity.md) — **required for create / update / fix**
+2. [.cursor/policies/project-context.md](../../../policies/project-context.md)
+3. [.cursor/policies/ui-design.md](../../../policies/ui-design.md)
+4. [.cursor/policies/implementation.md](../../../policies/implementation.md)
+5. [.cursor/policies/mcp-and-deploy.md](../../../policies/mcp-and-deploy.md)
+6. [.cursor/policies/minimal-complexity.md](../../../policies/minimal-complexity.md) — **required for create / update / fix**
 
 ## Minimal complexity (create / update / fix)
 

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

@@ -17,7 +17,7 @@ Read [_dispatch-utils.md](../_dispatch-utils.md) first.
 3. **load_inventory** — when domain slug maps to inventory
 4. **object_skills** — from graph `object_skills.<object>`
 5. [check](../../check/SKILL.md) — swarm per check skill
-6. **contract_checks** — run project test commands from domain inventory when present; for `@ludecker/aaac` package maintenance use `pnpm --filter @ludecker/aaac test` and `test:e2e`
+6. **contract_checks** — run test commands from domain inventory or `project.config.json` when present
 7. [reporting](../../reporting/SKILL.md) — **Answer** (yes/no/partial) then **How**
 
 No code changes. For test runs use `test-*`; for fixes use `fix-*`.

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

@@ -23,9 +23,11 @@ failure_conditions:
   - skip domain inventory when slug resolves to inventory file
 dependencies:
   skills: [discovery, planning, execution, testing, verification, reporting]
-  policies: [master-rules, implementation, mcp-and-deploy]
+  policies: [master-rules, project-context, ui-design, implementation, mcp-and-deploy]
   docs:
     - docs/master_rules.md
+    - docs/ui_design.md
+    - docs/project_context.md
     - docs/architecture.md
     - docs/design_system.md
 verification:

package/templates/docs/agentic_architecture.md

@@ -52,16 +52,21 @@ AAAC generates ~130 commands from **8 verbs × 12 objects**:
 | `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
+### Out of the box — no setup after install
 
-- Verb×object commands and shared pipeline (discover → plan → execute → verify → report)
-- Cursor hook enforcement and Run lifecycle
+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`, `ui_design.md`, `project_context.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, **no** hardcoded app build gate (`verify.enabled: false` in `project.config.json`)
+- **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.
 
-### After you customize (any stack)
+### Optional — when you want more (any stack)
 
-1. Write `docs/master_rules.md` and `docs/architecture.md`
+1. Fill in `docs/project_context.md` with your repo layout and SSOT anchors; extend `docs/master_rules.md` and `docs/architecture.md` when needed
 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:

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.