@ludecker/aaac 1.0.0

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

@@ -0,0 +1,302 @@
+---
+name: refactor
+description: Analyze code for SOLID violations, code smells, and master-rules compliance; suggest targeted, low-risk refactorings. Use when the user asks to refactor, review architecture, reduce complexity, extract modules, or runs /refactor on a file, directory, or module.
+argument-hint: "<file_or_module> [--focus srp|ocp|lsp|isp|dip] [--threshold low|medium|high]"
+effort: medium
+disable-model-invocation: true
+---
+
+# SOLID Refactoring Assistant
+
+Analyze code for SOLID violations and suggest targeted improvements.
+
+**Mandatory:** Read [docs/master_rules.md](../../docs/master_rules.md) (especially §19 Module Size Budgets) before analysis. Master rules are non-negotiable — if a SOLID suggestion conflicts with them, the master rules win.
+
+## Purpose
+
+Identify refactoring opportunities based on:
+- SOLID principle violations
+- Code smells and anti-patterns
+- Complexity metrics
+- Duplication detection
+- Master rules compliance (SSOT, layer separation, no inline components/styles, explicit state machines, validation at boundaries)
+
+## Parse Arguments
+
+From `$ARGUMENTS` (or the user's message), resolve:
+
+| Input | Scope |
+|-------|-------|
+| Single file path | Deep file analysis |
+| Directory path | Cross-file pattern detection |
+| `--focus=<principle>` | Filter findings to one SOLID letter |
+| `--threshold=high` | Only report high-impact issues (large files, mixed layers, critical smells) |
+
+Default target: path the user named, or the file/module under discussion.
+
+## Instructions
+
+### Step 1: Scope Analysis
+
+Determine the refactoring scope from user input:
+- Single file: Deep analysis
+- Directory: Pattern detection across files
+- Function/class: Focused extraction suggestions
+
+```bash
+TARGET="${1:-.}"
+if [ -f "$TARGET" ]; then
+  wc -l "$TARGET"
+  echo "Single file analysis"
+elif [ -d "$TARGET" ]; then
+  find "$TARGET" -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" \) | wc -l
+  echo "Directory analysis"
+fi
+```
+
+Also read the target with codebase tools (Grep, Read) — do not rely on shell alone.
+
+### Step 2: SOLID Violations Detection
+
+#### S - Single Responsibility
+
+Look for:
+- Files over budget (see Master Rules §19: routes 200, components 250, lib 300, openrouter 350)
+- Functions over 80 lines (or nested callbacks over 40)
+- Classes with > 10 methods
+- Mixed concerns (data + UI + business logic)
+
+**Master rules overlay:**
+- UI doing fetch, business logic, or state orchestration (Rule 2)
+- Domain logic in components or route handlers
+- Duplicated state (local + store, multiple stores) (Rule 1)
+- Side effects during render (Rules 8, 14)
+- Files that violate "one truth" by mirroring server data
+
+```bash
+find "$TARGET" -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" \) -exec wc -l {} + 2>/dev/null | sort -rn | head -10
+```
+
+#### O - Open/Closed Principle
+
+Look for:
+- Switch/case statements on types
+- Repeated if/else type checking
+- Direct modifications vs extensions
+
+**Master rules overlay:**
+- Feature behavior extended by editing core modules instead of adding strategy/handler modules (Rule 3)
+- Hardcoded branching that should live in schemas or configuration (Rule 4)
+
+#### L - Liskov Substitution
+
+Look for:
+- Overridden methods that throw "not implemented"
+- Type checks before method calls
+- Empty method overrides
+
+#### I - Interface Segregation
+
+Look for:
+- Large interfaces (> 10 methods)
+- Classes implementing unused interface methods
+- Fat service classes
+
+**Master rules overlay:**
+- Props/interfaces forcing consumers to depend on unused fields
+- "God" context or store slices consumed wholesale
+
+#### D - Dependency Inversion
+
+Look for:
+- Direct instantiation of dependencies (`new Service()`)
+- Hardcoded class references
+- Missing dependency injection
+
+**Master rules overlay:**
+- Infrastructure (API, DB) imported directly into UI
+- Utilities with hidden side effects (Rule 14)
+- Missing validation at boundaries — trust of raw input/API data (Rule 13)
+
+### Step 3: Master Rules Smell Pass
+
+After SOLID, scan for these project-specific violations:
+
+| Rule | Smell | Where to look |
+|------|-------|---------------|
+| 1 SSOT | Duplicated constants, mirrored state | `src/app/store/`, component local state |
+| 2 Layers | Business logic in `src/app/components/` | Components with fetch, transforms, rules |
+| 4 No hardcoding | Magic strings/numbers/IDs | Inline literals, layout numbers |
+| 5–6 UI | Inline `style={}`, nested component defs | `src/app/components/` |
+| 8 Flow | Circular imports, UI-triggered indirect mutations | Import graph, event handlers |
+| 9 State machines | Ad-hoc boolean flags for complex flows | `useState` clusters, string unions without machine |
+| 10 Async | Non-cancellable effects, overlapping requests | `useEffect`, route handlers |
+| 13 Boundaries | Missing Zod/schema parse on API I/O | `server/routes/`, `src/app/api.ts` |
+| 16 Errors | Swallowed errors, silent fallbacks | empty `catch`, `?.` chains without logging |
+| 19 Logging | Bare `console.log`, missing structured logs | `server/`, async paths |
+| 20 Testing | Changed behavior without tests | Colocated `*.test.ts` |
+
+Map each finding to the rule number in output.
+
+### Step 4: Code Smells
+
+Use Grep/Read (preferred) or:
+
+```bash
+# Long parameter lists (5+ comma-separated params — heuristic)
+rg -n "function [^(]+\([^)]*,[^)]*,[^)]*,[^)]*," "$TARGET" 2>/dev/null | head -10
+
+# Deep nesting (8+ spaces / 2+ tab levels — heuristic)
+rg -n "^\s{16,}\S" "$TARGET" 2>/dev/null | head -10
+```
+
+Also check:
+- Duplicate logic blocks (similar functions, copy-pasted handlers)
+- Long methods and deep nesting
+- Magic numbers/strings (Rule 4)
+- Missing early returns
+
+For duplication at repo scale, optionally suggest running the `fallow` skill if the user wants static analysis.
+
+### Step 5: Complexity Assessment
+
+For each issue found, assess:
+- **Impact**: How much code is affected?
+- **Risk**: What could break?
+- **Effort**: Lines to change, tests needed?
+- **Master rule**: Which rule(s) does fixing this satisfy?
+
+Prioritize: clarity and predictability over clever abstractions (Rule 22).
+
+## Output Format
+
+Use this template exactly:
+
+---
+
+### 🔧 Refactoring Analysis
+
+**Target**: [file/directory]
+**Lines Analyzed**: [count]
+**Focus**: [all | srp | ocp | lsp | isp | dip]
+**Threshold**: [low | medium | high]
+
+### 📊 SOLID Scorecard
+
+| Principle | Status | Issues Found |
+|-----------|--------|--------------|
+| Single Responsibility | 🟡/🟢/🔴 | [summary] |
+| Open/Closed | 🟡/🟢/🔴 | [summary] |
+| Liskov Substitution | 🟡/🟢/🔴 | [summary] |
+| Interface Segregation | 🟡/🟢/🔴 | [summary] |
+| Dependency Inversion | 🟡/🟢/🔴 | [summary] |
+
+### 📐 Master Rules Scorecard
+
+| Area | Status | Top violations |
+|------|--------|----------------|
+| SSOT & layers | 🟡/🟢/🔴 | [e.g. UI fetching in component] |
+| UI discipline | 🟡/🟢/🔴 | [e.g. inline components] |
+| 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] |
+
+### 🎯 Priority Refactorings
+
+#### 1. [Highest Impact] - [Short title]
+
+**Violation**: [SOLID principle + Rule #]
+**Current**: [what the code does today, with path:line]
+**Suggested**:
+```
+[Before structure]
+    ↓ [Extract | Move | Replace pattern]
+[After structure]
+```
+**Risk**: [Low | Medium | High] — [why]
+**Tests Needed**: [what to add/update]
+
+#### 2. [Second Priority] - [Short title]
+
+**Location**: `path/file.ts:line`
+**Current**:
+```typescript
+// minimal illustrative snippet
+```
+**Suggested**: [concrete pattern — strategy, extract module, move to domain, etc.]
+**Risk**: [Low | Medium | High]
+
+(Include 3–5 items max unless `--threshold=low`.)
+
+### 📝 Code Smells
+
+| Smell | Location | Rule/SOLID | Severity |
+|-------|----------|------------|----------|
+| Long Method | `api.ts:calculateTotal` (120 lines) | SRP | 🟠 High |
+| Duplicate Code | `utils/*.ts` | SSOT (Rule 1) | 🟡 Medium |
+| Deep Nesting | `parser.ts:parse` | — | 🟡 Medium |
+
+### 🚀 Quick Wins (Low Risk, High Value)
+
+1. [Concrete, scoped action]
+2. [Concrete, scoped action]
+3. [Concrete, scoped action]
+
+### ⚠️ Technical Debt Notes
+
+- [Items to defer — document why per Rule 21 if suggesting exceptions]
+
+---
+
+## Refactoring Safety Checklist
+
+Before applying suggestions:
+
+- [ ] Tests exist for affected code (Rule 20)
+- [ ] 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)
+
+## Applying Refactorings
+
+When the user asks to implement (not just analyze):
+
+1. Read surrounding code; match existing conventions
+2. Preserve layer boundaries: UI → state → domain → infrastructure
+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)
+
+## Usage
+
+**Analyze specific file:**
+```
+/refactor src/services/user.ts
+```
+
+**Analyze directory:**
+```
+/refactor src/api/
+```
+
+**Focus on specific principle:**
+```
+/refactor --focus=srp src/services/
+```
+
+**With complexity threshold:**
+```
+/refactor --threshold=high
+```
+
+## References
+
+- [docs/master_rules.md](../../docs/master_rules.md) — project non-negotiables
+- Martin Fowler's Refactoring Catalog
+- Clean Code by Robert C. Martin
+- SOLID principles by Robert C. Martin

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

@@ -0,0 +1,47 @@
+---
+name: shared-check
+description: >-
+  Fast readonly validate/inspect — can X do Y, how does it work. All check-* commands.
+  Not user-facing.
+disable-model-invocation: true
+---
+
+# Shared capability check
+
+## When
+
+Orchestrator phase `check_swarm`. **Readonly** — no file edits.
+
+Lighter than [discovery](../discovery/SKILL.md) (no full 4–6 agent sweep) and narrower than [architecture](../architecture/SKILL.md) (no SOLID/size review).
+
+## Frame
+
+```
+Question:   can it do X? / how does Y work?
+Scope:      domain slug, path hint, or symbols from intent
+Success:    yes | no | partial + conditions
+```
+
+## Swarm (mandatory)
+
+Launch **3** parallel `Task` subagents (`explore`, `readonly: true`) in **one message**:
+
+| Agent spec | Angle |
+|------------|-------|
+| [discovery-inventory.md](../../../agents/discovery-inventory.md) | Relevant files, routes, tests |
+| [discovery-ssot.md](../../../agents/discovery-ssot.md) | State and data ownership |
+| [check-capability-trace.md](../../../agents/check-capability-trace.md) | Entry → logic → persistence trace |
+
+Optional **4th** agent (second wave, only if intent names external system): `discovery-boundaries.md` for integration edges.
+
+## Merge
+
+Parent synthesizes one brief:
+
+1. **Answer** — yes / no / partial (one sentence)
+2. **How it works** — 3–7 steps, layman first
+3. **Evidence** — `path:line` list
+4. **Gaps** — what was not confirmed
+5. **Confidence** — high | medium | low
+
+Spot-check every `path:line` claim before reporting.

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

@@ -0,0 +1,24 @@
+---
+name: shared-component
+description: >-
+  UI components, views, pages, forms, hooks-as-UI. Object component (code layer).
+  Not user-facing.
+disable-model-invocation: true
+---
+
+# Shared component
+
+## Scope
+
+- `src/app/components/`, routes-as-views, layout composition
+- Props-driven components; token/class styling only (no inline styles)
+- One component per file; no inline component definitions
+
+## Execution focus
+
+- Reuse design system primitives; match existing patterns
+- Accessibility and test ids for interactive flows
+
+## Review focus
+
+- Re-render boundaries, prop drilling, separation from state layer

package/templates/cursor/skills/shared/dependency-graph/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: shared-dependency-graph
+description: >-
+  Resolve dependency graph before execute using dependencies.yaml and inventory.
+  Not user-facing.
+disable-model-invocation: true
+---
+
+# Dependency graph validation
+
+**When:** Verb lifecycle phase `dependency_graph` — before execute.
+
+## SSOT
+
+[dependencies.yaml](../../../aaac/dependencies.yaml) — domain and object edges.
+
+## Procedure
+
+1. Resolve target domain slug (if present) → `domains.<slug>.depends_on`
+2. Resolve command object → `objects.<object>.<domain>` or `objects.<object>.default`
+3. Merge with domain inventory Section 3 file map
+4. Spawn readonly [dependency-analysis.md](../../../agents/dependency-analysis.md) to confirm no hidden imports/coupling
+
+## Output
+
+```yaml
+target: cms | ui | database | ...
+depends_on: [resolved list]
+depended_by: [consumers that may break]
+graph_valid: true | false
+violations: [layer boundary or circular deps — empty if valid]
+```
+
+If `graph_valid: false` → **STOP** — fix plan or request clarification.
+
+## Note
+
+Inventory documents what exists; this phase **reasons** over edges. Both are required.

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

@@ -0,0 +1,29 @@
+---
+name: shared-discovery
+description: >-
+  Readonly discovery swarm for AAAC orchestrators. Spawns parallel subagents
+  per .cursor/agents/discovery-*.md. Use only via graph — not user-facing.
+disable-model-invocation: true
+---
+
+# Shared discovery
+
+## When
+
+Orchestrator phase `discovery_swarm`. **Readonly** — no file edits.
+
+## Swarm (mandatory)
+
+Launch **4–6** parallel `Task` subagents (`explore`, `readonly: true`) in **one message**:
+
+| Agent spec | Angle |
+|------------|-------|
+| [discovery-inventory.md](../../../agents/discovery-inventory.md) | Files, routes, tests |
+| [discovery-boundaries.md](../../../agents/discovery-boundaries.md) | In/out of scope |
+| [discovery-ssot.md](../../../agents/discovery-ssot.md) | State ownership |
+
+Add domain-specific angles from inventory skill. Max **8** agents total; second wave ≤2 for critical gaps.
+
+## Output
+
+Merged brief for `planning`: findings, evidence, gaps, confidence. Parent spot-checks `path:line` claims.

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

@@ -0,0 +1,21 @@
+---
+name: shared-documentation
+description: >-
+  Plain-language architecture docs to docs/. Readonly investigation until write.
+  Used by update-doc orchestrator. Not user-facing.
+disable-model-invocation: true
+---
+
+# Shared documentation
+
+## Spec
+
+Follow [write-arch-doc.md](write-arch-doc.md) exactly.
+
+## Swarm
+
+Use [discovery](../discovery/SKILL.md) with product-language angles (purpose, lifecycle, flow, boundaries). **Readonly** until writing `docs/architecture_<slug>.md`.
+
+## Output
+
+`docs/architecture_<slug>.md` — no code changes unless user also invoked a code command.

package/templates/cursor/skills/shared/documentation/orchestrator/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: update-doc-orchestrator
+description: >-
+  Orchestrates update-doc: plain-language module architecture docs. Internal only.
+disable-model-invocation: true
+---
+
+# update-doc orchestrator
+
+## Parse
+
+- **Domain:** slug or product name → `docs/architecture_<slug>.md`
+- **Intent:** quoted string in `$ARGUMENTS`
+
+## Phases
+
+1. Frame module brief (product name, scope, unknowns)
+2. [discovery](../SKILL.md) swarm — readonly
+3. [documentation](../SKILL.md) — write/replace doc per write-arch-doc.md
+4. [reporting](../reporting/SKILL.md)
+
+**Hard rule:** No application code changes.
+
+## contract.yaml
+
+See [contract.yaml](contract.yaml).

package/templates/cursor/skills/shared/documentation/orchestrator/contract.yaml

@@ -0,0 +1,20 @@
+name: update-doc-orchestrator
+purpose: Write or refresh plain-language architecture doc for a product module
+inputs:
+  domain:
+    required: true
+  intent:
+    required: true
+outputs:
+  report:
+    type: markdown
+success_criteria:
+  - docs/architecture_<slug>.md follows write-arch-doc.md
+  - investigation was readonly until write
+failure_conditions:
+  - ambiguous module name without user clarification
+dependencies:
+  skills: [discovery, documentation, reporting]
+  policies: [master-rules]
+verification:
+  - doc_structure_check

package/templates/cursor/skills/shared/documentation/write-arch-doc.md

@@ -0,0 +1,168 @@
+# Write Architecture Doc (Plain Language)
+
+**Audience:** Anyone who uses or cares about the product — not developers. Product owners, designers, support, new team members, stakeholders.
+
+**Goal:** After reading, the reader can explain *what this part of the platform does*, *why it exists*, and *how it behaves in everyday use* — without reading code.
+
+**Mandatory:** Every architecture doc produced by `/architecture` MUST follow this guide exactly.
+
+---
+
+## Output Location & Naming
+
+| Rule | Value |
+|------|-------|
+| Folder | `docs/` at repo root |
+| Pattern | `docs/architecture_<slug>.md` |
+| Slug | Lowercase, underscores, derived from module name (e.g. `Question Suggestion Engine` → `architecture_question_suggestion_engine.md`) |
+| Format | Plain Markdown (`.md`), not MDX |
+| Update | If the file exists, rewrite it with current facts — do not create duplicates |
+
+---
+
+## Required Document Structure
+
+Use this template. **Do not skip sections.** **Do not add developer sections** (no file paths, no API tables, no code snippets except Mermaid).
+
+```markdown
+# [Human-Friendly Module Name]
+
+> One sentence: what this is and the main benefit it gives users.
+
+## Introduction
+
+[2–4 short paragraphs. Plain language only.
+
+- What problem does this solve?
+- Who interacts with it (directly or indirectly)?
+- Why does the platform need it?
+- What would be missing if it did not exist?]
+
+## At a Glance
+
+| | |
+|---|---|
+| **Purpose** | … |
+| **When it runs** | … |
+| **Who notices it** | … |
+| **What it produces** | … |
+
+## How the Pieces Fit Together
+
+[Mermaid diagram — see rules below]
+
+## How It Works
+
+[Numbered steps, 5–10 max. Each step = one clear action or decision in plain language.
+
+Example tone: "When you open a requirement, the system checks whether more questions would help clarify it."
+
+NOT: "The RequirementFocusMachine dispatches REQUEST_SUGGESTION."]
+
+1. …
+2. …
+3. …
+
+## Key Ideas
+
+[3–6 bullets. Define terms the reader might hear in conversation — in everyday words.
+
+Format: **Term** — plain definition]
+
+## Common Situations
+
+[3–5 short scenarios: "When X happens, Y occurs."
+
+Helps the reader predict behavior. Include at least one "nothing happens" or "it waits" case if applicable.]
+
+## Connected Parts
+
+[Bullet list of other platform areas this module talks to or depends on — use product names, not code module names.
+
+Example: "Requirements — needs a requirement to exist before suggesting questions"]
+
+## Limits & Boundaries
+
+[What this part does **not** do. Prevents wrong assumptions. 3–5 bullets.]
+```
+
+---
+
+## Mermaid Diagram Rules
+
+**Purpose:** Show flow and relationships so a non-technical reader can follow the story visually.
+
+| Rule | Detail |
+|------|--------|
+| Type | Prefer `flowchart TD` or `flowchart LR` |
+| Labels | User/product language only — "User opens requirement", "AI suggests questions", "Questions appear in list" |
+| Nodes | 4–10 nodes; merge tiny steps rather than exploding detail |
+| Forbidden in labels | File names, function names, HTTP verbs, database terms, acronyms without gloss |
+| Direction | `TD` for timelines; `LR` for left-to-right pipelines |
+| Styling | No custom colors or classes unless essential for clarity |
+
+**Good example:**
+
+```mermaid
+flowchart TD
+  A[User focuses on a requirement] --> B{Need more clarity?}
+  B -->|Yes| C[AI reads requirement context]
+  C --> D[Draft questions generated]
+  D --> E[New questions appear for review]
+  B -->|No| F[Nothing suggested]
+```
+
+**Bad example:** nodes like `POST /suggest/:id` or `requirementFocusMachine.ts`.
+
+Place the diagram under `## How the Pieces Fit Together` with a one-sentence caption above it explaining what the reader is looking at.
+
+---
+
+## Plain Language Rules
+
+1. **Short sentences** — average 15 words; one idea per sentence
+2. **Active voice** — "The system suggests questions" not "Questions are suggested by the system"
+3. **No jargon** — if a technical word is unavoidable, define it immediately in parentheses
+4. **No code** — no `backticked` identifiers, paths, env vars, or stack names in body text
+5. **Concrete over abstract** — describe what the user sees and what changes
+6. **Honest uncertainty** — use "usually", "may", "in most cases" when behavior varies
+7. **Second person sparingly** — "you" is fine for user-facing flows; "the team" for internal behavior
+
+### Banned → Preferred
+
+| Avoid | Use instead |
+|-------|-------------|
+| dispatch, invoke, persist | send, run, save |
+| state machine, slice, hook | workflow, memory, automatic handler |
+| endpoint, payload | request, information sent |
+| dedupe, hydrate | remove duplicates, load |
+| frontend / backend | app / server (only if needed) |
+
+---
+
+## Accuracy Rules
+
+- Every claim must come from swarm investigation evidence — **never invent behavior**
+- If the swarm could not verify something, omit it or say "Behavior may vary depending on setup"
+- Prefer describing **observable outcomes** over internal mechanism guesses
+- When two agents disagree, the doc writer must verify in code before stating either version
+
+---
+
+## Quality Checklist (before saving)
+
+- [ ] A non-developer can read the Introduction alone and understand the purpose
+- [ ] Mermaid diagram uses zero code terms in node labels
+- [ ] No file paths, class names, or API routes in the document body
+- [ ] "How It Works" steps match actual product behavior verified by the swarm
+- [ ] "Limits & Boundaries" clarifies what this module does not do
+- [ ] Filename matches `docs/architecture_<slug>.md`
+- [ ] Document is self-contained — reader does not need `docs/architecture.md` first
+
+---
+
+## Reference Example (tone only — do not copy content)
+
+**Introduction opening:** "The Question Suggestion Engine helps teams fill gaps in a requirement by proposing questions they might not have thought to ask. When someone is working on a requirement, the platform can automatically offer new questions based on what is already written and answered."
+
+**Step example:** "4. If the suggested question is not already on the list, it appears alongside existing questions so the user can accept, edit, or ignore it."