@ludecker/aaac 1.1.2 → 1.1.3

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`, `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.3",
   "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/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/governance/implementation/SKILL.md

@@ -48,6 +48,6 @@ Direction: **Input → State → Logic → Output**. No circular imports across
 
 ---
 
-## 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. When you outgrow defaults, extend those docs or add a `skills/<project>/implementation/` skill and wire it in `graph.project.yaml`.

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` 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. 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:

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.