@ludecker/aaac 1.1.3 → 1.1.5

package/README.md

@@ -31,7 +31,7 @@ Works **out of the box** after `init` — open in Cursor and run commands. No po
 - `.cursor/skills/shared/` — full pipeline (discovery → execute → verify → report)
 - `.cursor/agents/` — 13 generic subagent specs
 - `.cursor/commands/` — ~130 generated slash commands
-- `docs/` — ready-to-use `master_rules.md`, `architecture.md`, and `agentic_architecture.md`
+- `docs/` — ready-to-use `master_rules.md`, `ui_design.md`, `project_context.md`, `architecture.md`, and `agentic_architecture.md`
 
 Optional later: add **domains** under `.cursor/domains/<slug>/` (see maintainer appendix in `agentic_architecture.md`).
 

package/package.json

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

package/src/run-engine/advance-phase.mjs

@@ -16,6 +16,7 @@ import {
   phaseKind,
   isEditPhase,
   isGatePhase,
+  resolveSwarmMinimum,
   writeJson,
   saveActiveRun,
 } from "./lib.mjs";
@@ -55,11 +56,7 @@ if (manifest.phase !== completedPhase) {
   process.exit(1);
 }
 
-const minAgents =
-  completedPhase === "verify" &&
-  (enforcement.fix_commands?.includes(manifest.command) || manifest.verb === "fix")
-    ? enforcement.swarm_min_agents?.verify_fix
-    : enforcement.swarm_min_agents?.[completedPhase];
+const minAgents = resolveSwarmMinimum(completedPhase, manifest, enforcement);
 const launches = manifest.swarm?.task_launches_this_phase ?? 0;
 if (minAgents && launches < minAgents && !force) {
   recordLog(manifest, {

package/src/run-engine/debug-run.mjs

@@ -31,6 +31,12 @@ if (summary.blocked_reason) console.log(`Blocked: ${summary.blocked_reason}`);
 console.log(`Completed: ${summary.completed.join(" → ") || "(none)"}`);
 console.log(`Pending: ${summary.pending.join(" → ") || "(none)"}`);
 console.log(`Swarm: phase=${summary.swarm.phase} count=${summary.swarm.task_launches_this_phase}`);
+if (summary.swarm.agents?.length) {
+  console.log(`Agents: ${summary.swarm.agents.length} recorded this phase`);
+  for (const a of summary.swarm.agents.slice(-5)) {
+    console.log(`  #${a.index} ${a.subagent_type ?? "?"} ${a.description ?? ""} @ ${a.at}`);
+  }
+}
 console.log(`Log: ${summary.log_count} entries  Decisions: ${summary.decisions_count}`);
 console.log("--- last 10 log entries ---");
 for (const e of summary.last_log_entries) {

package/src/run-engine/lib.mjs

@@ -136,6 +136,23 @@ export function phaseKind(phase, registry) {
   return isGatePhase(phase, registry) ? "gate" : "work";
 }
 
+/** Swarm minimum for completed phase — check verb uses check_swarm on discover. */
+export function resolveSwarmMinimum(completedPhase, manifest, enforcement) {
+  if (
+    completedPhase === "verify" &&
+    (enforcement.fix_commands?.includes(manifest.command) || manifest.verb === "fix")
+  ) {
+    return enforcement.swarm_min_agents?.verify_fix;
+  }
+  if (completedPhase === "discover" && manifest.verb === "check") {
+    return (
+      enforcement.swarm_min_agents?.check_swarm ??
+      enforcement.swarm_min_agents?.discover
+    );
+  }
+  return enforcement.swarm_min_agents?.[completedPhase];
+}
+
 export function promptFromHook(hook) {
   return hook?.prompt ?? hook?.text ?? hook?.content ?? "";
 }

package/src/run-engine/log.mjs

@@ -334,7 +334,7 @@ export function debugRunSummary(manifest) {
     awaiting_approval: manifest.awaiting_approval,
     completed: manifest.completed ?? [],
     pending: manifest.pending ?? [],
-    swarm: { phase: swarmPhase, task_launches_this_phase: swarmCount },
+    swarm: { phase: swarmPhase, task_launches_this_phase: swarmCount, agents: manifest.swarm?.agents ?? [] },
     edit_allowed: manifest.enforcement?.edit_allowed ?? false,
     last_log_entries: log.slice(-10),
     decisions_count: (manifest.decisions ?? []).length,

package/src/run-engine/record-task.mjs

@@ -44,19 +44,40 @@ process.stdin.on("end", () => {
   if (manifest.conversation_id && manifest.conversation_id !== conversationId) allow();
 
   manifest.swarm = manifest.swarm ?? {};
-  manifest.swarm.task_launches_this_phase = (manifest.swarm.task_launches_this_phase ?? 0) + 1;
+  const launchIndex = (manifest.swarm.task_launches_this_phase ?? 0) + 1;
+  manifest.swarm.task_launches_this_phase = launchIndex;
   manifest.swarm.phase = manifest.phase;
-  manifest.updated_at = isoNow();
+
+  const agentEntry = {
+    at: isoNow(),
+    index: launchIndex,
+    phase: manifest.phase,
+    subagent_type: hook.subagent_type ?? hook.subagentType ?? null,
+    description: hook.description ?? hook.subagent_description ?? null,
+    model: hook.model ?? null,
+    readonly: hook.readonly ?? null,
+  };
+  manifest.swarm.agents = manifest.swarm.agents ?? [];
+  manifest.swarm.agents.push(agentEntry);
+
+  const telemetryDetail = JSON.stringify({
+    count: launchIndex,
+    subagent_type: agentEntry.subagent_type,
+    index: launchIndex,
+  });
 
   recordLog(manifest, {
     event: "agent_spawned",
     phase: manifest.phase,
     phase_kind: manifest.phase_kind,
-    detail: `count=${manifest.swarm.task_launches_this_phase}`,
+    detail: telemetryDetail,
     level: "debug",
   });
 
   writeJson(path.join(runDir(active.run_id), "run.json"), manifest);
-  saveActiveRun(conversationId, { ...active, task_launches_this_phase: manifest.swarm.task_launches_this_phase });
+  saveActiveRun(conversationId, {
+    ...active,
+    task_launches_this_phase: manifest.swarm.task_launches_this_phase,
+  });
   allow();
 });

package/templates/cursor/aaac/enforcement.json

@@ -6,6 +6,7 @@
   "verify_verbs": ["create", "update", "fix"],
   "swarm_min_agents": {
     "discover": 4,
+    "check_swarm": 3,
     "investigate_swarm": 7,
     "research_swarm": 6,
     "verify_fix": 3
@@ -14,6 +15,11 @@
     "investigate_swarm": ["artifacts/investigation.md"],
     "root_cause": ["artifacts/root_cause.yaml"],
     "plan": ["artifacts/plan.yaml"],
+    "validate": ["artifacts/validate.yaml"],
+    "impact_analysis": ["artifacts/impact.yaml"],
+    "dependency_graph": ["artifacts/dependency_graph.yaml"],
+    "fitness_functions": ["artifacts/fitness.yaml"],
+    "rollback": ["artifacts/rollback.yaml"],
     "verify": ["artifacts/verify.yaml"],
     "report": ["artifacts/report.md"]
   },

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/run/schema.json

@@ -35,6 +35,11 @@
       "stack": "string | null",
       "results": {}
     },
+    "swarm": {
+      "task_launches_this_phase": 0,
+      "phase": "string | null",
+      "agents": []
+    },
     "created_at": "iso8601",
     "updated_at": "iso8601"
   },

package/templates/cursor/aaac/scripts/run-engine/advance-phase.mjs

@@ -16,6 +16,7 @@ import {
   phaseKind,
   isEditPhase,
   isGatePhase,
+  resolveSwarmMinimum,
   writeJson,
   saveActiveRun,
 } from "./lib.mjs";
@@ -55,11 +56,7 @@ if (manifest.phase !== completedPhase) {
   process.exit(1);
 }
 
-const minAgents =
-  completedPhase === "verify" &&
-  (enforcement.fix_commands?.includes(manifest.command) || manifest.verb === "fix")
-    ? enforcement.swarm_min_agents?.verify_fix
-    : enforcement.swarm_min_agents?.[completedPhase];
+const minAgents = resolveSwarmMinimum(completedPhase, manifest, enforcement);
 const launches = manifest.swarm?.task_launches_this_phase ?? 0;
 if (minAgents && launches < minAgents && !force) {
   recordLog(manifest, {

package/templates/cursor/aaac/scripts/run-engine/debug-run.mjs

@@ -31,6 +31,12 @@ if (summary.blocked_reason) console.log(`Blocked: ${summary.blocked_reason}`);
 console.log(`Completed: ${summary.completed.join(" → ") || "(none)"}`);
 console.log(`Pending: ${summary.pending.join(" → ") || "(none)"}`);
 console.log(`Swarm: phase=${summary.swarm.phase} count=${summary.swarm.task_launches_this_phase}`);
+if (summary.swarm.agents?.length) {
+  console.log(`Agents: ${summary.swarm.agents.length} recorded this phase`);
+  for (const a of summary.swarm.agents.slice(-5)) {
+    console.log(`  #${a.index} ${a.subagent_type ?? "?"} ${a.description ?? ""} @ ${a.at}`);
+  }
+}
 console.log(`Log: ${summary.log_count} entries  Decisions: ${summary.decisions_count}`);
 console.log("--- last 10 log entries ---");
 for (const e of summary.last_log_entries) {

package/templates/cursor/aaac/scripts/run-engine/lib.mjs

@@ -136,6 +136,23 @@ export function phaseKind(phase, registry) {
   return isGatePhase(phase, registry) ? "gate" : "work";
 }
 
+/** Swarm minimum for completed phase — check verb uses check_swarm on discover. */
+export function resolveSwarmMinimum(completedPhase, manifest, enforcement) {
+  if (
+    completedPhase === "verify" &&
+    (enforcement.fix_commands?.includes(manifest.command) || manifest.verb === "fix")
+  ) {
+    return enforcement.swarm_min_agents?.verify_fix;
+  }
+  if (completedPhase === "discover" && manifest.verb === "check") {
+    return (
+      enforcement.swarm_min_agents?.check_swarm ??
+      enforcement.swarm_min_agents?.discover
+    );
+  }
+  return enforcement.swarm_min_agents?.[completedPhase];
+}
+
 export function promptFromHook(hook) {
   return hook?.prompt ?? hook?.text ?? hook?.content ?? "";
 }

package/templates/cursor/aaac/scripts/run-engine/log.mjs

@@ -334,7 +334,7 @@ export function debugRunSummary(manifest) {
     awaiting_approval: manifest.awaiting_approval,
     completed: manifest.completed ?? [],
     pending: manifest.pending ?? [],
-    swarm: { phase: swarmPhase, task_launches_this_phase: swarmCount },
+    swarm: { phase: swarmPhase, task_launches_this_phase: swarmCount, agents: manifest.swarm?.agents ?? [] },
     edit_allowed: manifest.enforcement?.edit_allowed ?? false,
     last_log_entries: log.slice(-10),
     decisions_count: (manifest.decisions ?? []).length,

package/templates/cursor/aaac/scripts/run-engine/record-task.mjs

@@ -44,19 +44,40 @@ process.stdin.on("end", () => {
   if (manifest.conversation_id && manifest.conversation_id !== conversationId) allow();
 
   manifest.swarm = manifest.swarm ?? {};
-  manifest.swarm.task_launches_this_phase = (manifest.swarm.task_launches_this_phase ?? 0) + 1;
+  const launchIndex = (manifest.swarm.task_launches_this_phase ?? 0) + 1;
+  manifest.swarm.task_launches_this_phase = launchIndex;
   manifest.swarm.phase = manifest.phase;
-  manifest.updated_at = isoNow();
+
+  const agentEntry = {
+    at: isoNow(),
+    index: launchIndex,
+    phase: manifest.phase,
+    subagent_type: hook.subagent_type ?? hook.subagentType ?? null,
+    description: hook.description ?? hook.subagent_description ?? null,
+    model: hook.model ?? null,
+    readonly: hook.readonly ?? null,
+  };
+  manifest.swarm.agents = manifest.swarm.agents ?? [];
+  manifest.swarm.agents.push(agentEntry);
+
+  const telemetryDetail = JSON.stringify({
+    count: launchIndex,
+    subagent_type: agentEntry.subagent_type,
+    index: launchIndex,
+  });
 
   recordLog(manifest, {
     event: "agent_spawned",
     phase: manifest.phase,
     phase_kind: manifest.phase_kind,
-    detail: `count=${manifest.swarm.task_launches_this_phase}`,
+    detail: telemetryDetail,
     level: "debug",
   });
 
   writeJson(path.join(runDir(active.run_id), "run.json"), manifest);
-  saveActiveRun(conversationId, { ...active, task_launches_this_phase: manifest.swarm.task_launches_this_phase });
+  saveActiveRun(conversationId, {
+    ...active,
+    task_launches_this_phase: manifest.swarm.task_launches_this_phase,
+  });
   allow();
 });

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. **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`
+1. **Cursor Hooks enabled** — Settings → Hooks; restart Cursor after `.cursor/hooks.json` changes
+2. **Registry current** — `node .cursor/aaac/generate-graph.mjs`
 
 ## Hook behavior (automatic)
 
@@ -31,11 +31,16 @@ Every AAAC slash command (`/fix-module`, `/update-module`, `/write-article`, …
    node .cursor/aaac/scripts/run-engine/advance-phase.mjs <run_id> <phase>
    ```
 3. **Swarm minimums** (enforced by advance-phase):
-   - `discover`: 4 Task agents
+   - `discover`: 4 Task agents (check verbs: `check_swarm` 3)
    - `investigate_swarm`: 7 Task agents
    - `research_swarm`: 6 Task agents
-4. **Code edits only in `execute`** (hook-enforced). Before execute: artifacts only under `.cursor/aaac/state/runs/`.
-5. **Complete the Run** — advance through `report`, set status completed.
+4. **Verify gate (create / update / fix):** before advancing past `verify`, run:
+   ```bash
+   node .cursor/aaac/scripts/run-engine/verify-website-build.mjs --run-id <run_id>
+   ```
+   `advance-phase.mjs verify` runs this automatically and blocks on missing static assets or failed `vite build` (catches favicon/path regressions).
+5. **Code edits only in `execute`** (hook-enforced). Before execute: artifacts only under `.cursor/aaac/state/runs/`.
+6. **Complete the Run** — advance through `report`, set status completed.
 
 ## If edit is denied
 

package/templates/cursor/skills/shared/_task-prompt-policy.md

@@ -0,0 +1,18 @@
+# Task prompt policy excerpt (mandatory)
+
+Append this block to **every** Task sub-agent prompt the orchestrator sends.
+
+## Policies (mandatory)
+
+- **Readonly** unless the agent spec explicitly allows test runs or shell commands.
+- **Evidence:** every claim needs `path:line` citations the parent can spot-check.
+- **SSOT:** do not invent constants, routes, or file paths — read the repo.
+- **Prime directive** (master rules): clarity beats cleverness; predictability beats shortcuts; one truth beats convenience.
+- **Layer boundaries:** `packages/ui` must not import `apps/website`; `packages/types` and `packages/utils` stay runtime-free.
+- **Errors:** never silent — state gaps explicitly in the return block.
+
+Full policy chain: [.cursor/policies/master-rules.md](../../policies/master-rules.md) → [docs/master_rules.md](../../../docs/master_rules.md)
+
+## Return shape
+
+Follow the agent spec (`Findings`, `Evidence`, `Gaps`, `Confidence`). Do not edit files unless the spec allows it.

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/check/SKILL.md

@@ -34,6 +34,10 @@ Launch **3** parallel `Task` subagents (`explore`, `readonly: true`) in **one me
 
 Optional **4th** agent (second wave, only if intent names external system): `discovery-boundaries.md` for integration edges.
 
+## Task prompt (mandatory)
+
+Every Task prompt **must** include the policy excerpt from [_task-prompt-policy.md](../_task-prompt-policy.md) plus: question, scope, agent spec path, and inventory path when available.
+
 ## Merge
 
 Parent synthesizes one brief:

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

@@ -24,6 +24,10 @@ Launch **4–6** parallel `Task` subagents (`explore`, `readonly: true`) in **on
 
 Add domain-specific angles from inventory skill. Max **8** agents total; second wave ≤2 for critical gaps.
 
+## Task prompt (mandatory)
+
+Every Task prompt **must** include the policy excerpt from [_task-prompt-policy.md](../_task-prompt-policy.md) plus: intent, domain, inventory constraints, and the linked agent spec path.
+
 ## Output
 
 Merged brief for `planning`: findings, evidence, gaps, confidence. Parent spot-checks `path:line` claims.

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,7 +44,7 @@ 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)
@@ -50,4 +53,4 @@ Direction: **Input → State → Logic → Output**. No circular imports across
 
 ## Project overlay (optional)
 
-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`.
+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/investigation/SKILL.md

@@ -53,7 +53,7 @@ Launch **7 parallel** `Task` subagents in **one message**. `readonly: true` unle
 | 6 | [fix-runtime-evidence.md](../../../agents/fix-runtime-evidence.md) | `generalPurpose` | CI/logs/MCP evidence |
 | 7 | [fix-inventory-confirm.md](../../../agents/fix-inventory-confirm.md) | `explore` | Inventory scope + constraints |
 
-**Parent prompt must include:** intent, domain, inventory path, discovery brief summary, frame fields.
+**Parent prompt must include:** intent, domain, inventory path, discovery brief summary, frame fields, and the policy excerpt from [_task-prompt-policy.md](../_task-prompt-policy.md).
 
 **Anti-patterns (hard fail):**
 

package/templates/cursor/skills/shared/investigation-lite/SKILL.md

@@ -36,3 +36,5 @@ Pass output to [validation](../validation/SKILL.md). If any confidence below thr
 ## Agents
 
 Reuse readonly specs: [discovery-inventory.md](../../../agents/discovery-inventory.md), [discovery-ssot.md](../../../agents/discovery-ssot.md), [dependency-analysis.md](../../../agents/dependency-analysis.md) — 2–3 parallel max for lite path.
+
+Every Task prompt **must** include the policy excerpt from [_task-prompt-policy.md](../_task-prompt-policy.md).

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