Update decomposition skill documentation and templates; remove obsolete feature specification and initial structure templates. Enhance task decomposition descriptions and adjust directory paths for project documentation.

.cursor/skills/autopilot/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: autopilot
+description: |
+  Auto-chaining orchestrator that drives the full BUILD-SHIP workflow from problem gathering through deployment.
+  Detects current project state from _docs/ folder, resumes from where it left off, and flows through
+  problem → research → plan → decompose → implement → deploy without manual skill invocation.
+  Maximizes work per conversation by auto-transitioning between skills.
+  Trigger phrases:
+  - "autopilot", "auto", "start", "continue"
+  - "what's next", "where am I", "project status"
+category: meta
+tags: [orchestrator, workflow, auto-chain, state-machine, meta-skill]
+disable-model-invocation: true
+---
+
+# Autopilot Orchestrator
+
+Auto-chaining execution engine that drives the full BUILD → SHIP workflow. Detects project state from `_docs/`, resumes from where work stopped, and flows through skills automatically. The user invokes `/autopilot` once — the engine handles sequencing, transitions, and re-entry.
+
+## File Index
+
+| File | Purpose |
+|------|---------|
+| `flows/greenfield.md` | Detection rules, step table, and auto-chain rules for new projects |
+| `flows/existing-code.md` | Detection rules, step table, and auto-chain rules for existing codebases |
+| `state.md` | State file format, rules, re-entry protocol, session boundaries |
+| `protocols.md` | User interaction, Jira MCP auth, choice format, error handling, status summary |
+
+**On every invocation**: read all four files above before executing any logic.
+
+## Core Principles
+
+- **Auto-chain**: when a skill completes, immediately start the next one — no pause between skills
+- **Only pause at decision points**: BLOCKING gates inside sub-skills are the natural pause points; do not add artificial stops between steps
+- **State from disk**: all progress is persisted to `_docs/_autopilot_state.md` and cross-checked against `_docs/` folder structure
+- **Rich re-entry**: on every invocation, read the state file for full context before continuing
+- **Delegate, don't duplicate**: read and execute each sub-skill's SKILL.md; never inline their logic here
+- **Sound on pause**: follow `.cursor/rules/human-attention-sound.mdc` — play a notification sound before every pause that requires human input
+- **Minimize interruptions**: only ask the user when the decision genuinely cannot be resolved automatically
+- **Single project per workspace**: all `_docs/` paths are relative to workspace root; for monorepos, each service needs its own Cursor workspace
+
+## Flow Resolution
+
+Determine which flow to use:
+
+1. If workspace has source code files **and** `_docs/` does not exist → **existing-code flow** (Pre-Step detection)
+2. If `_docs/_autopilot_state.md` exists and records Document in `Completed Steps` → **existing-code flow**
+3. If `_docs/_autopilot_state.md` exists and `step: done` AND workspace contains source code → **existing-code flow** (completed project re-entry — loops to New Task)
+4. Otherwise → **greenfield flow**
+
+After selecting the flow, apply its detection rules (first match wins) to determine the current step.
+
+## Execution Loop
+
+Every invocation follows this sequence:
+
+```
+1. Read _docs/_autopilot_state.md (if exists)
+2. Read all File Index files above
+3. Cross-check state file against _docs/ folder structure (rules in state.md)
+4. Resolve flow (see Flow Resolution above)
+5. Resolve current step (detection rules from the active flow file)
+6. Present Status Summary (template in active flow file)
+7. Execute:
+   a. Delegate to current skill (see Skill Delegation below)
+   b. If skill returns FAILED → apply Skill Failure Retry Protocol (see protocols.md):
+      - Auto-retry the same skill (failure may be caused by missing user input or environment issue)
+      - If 3 consecutive auto-retries fail → record in state file Blockers, warn user, stop auto-retry
+   c. When skill completes successfully → reset retry counter, update state file (rules in state.md)
+   d. Re-detect next step from the active flow's detection rules
+   e. If next skill is ready → auto-chain (go to 7a with next skill)
+   f. If session boundary reached → update state, suggest new conversation (rules in state.md)
+   g. If all steps done → update state → report completion
+```
+
+## Skill Delegation
+
+For each step, the delegation pattern is:
+
+1. Update state file: set `step` to the autopilot step number, status to `in_progress`, set `sub_step` to the sub-skill's current internal step/phase, reset `retry_count: 0`
+2. Announce: "Starting [Skill Name]..."
+3. Read the skill file: `.cursor/skills/[name]/SKILL.md`
+4. Execute the skill's workflow exactly as written, including all BLOCKING gates, self-verification checklists, save actions, and escalation rules. Update `sub_step` in state each time the sub-skill advances.
+5. If the skill **fails**: follow the Skill Failure Retry Protocol in `protocols.md` — increment `retry_count`, auto-retry up to 3 times, then escalate.
+6. When complete (success): reset `retry_count: 0`, mark step `completed`, record date + key outcome, add key decisions to state file, return to auto-chain rules (from active flow file)
+
+Do NOT modify, skip, or abbreviate any part of the sub-skill's workflow. The autopilot is a sequencer, not an optimizer.
+
+## Trigger Conditions
+
+This skill activates when the user wants to:
+- Start a new project from scratch
+- Continue an in-progress project
+- Check project status
+- Let the AI guide them through the full workflow
+
+**Keywords**: "autopilot", "auto", "start", "continue", "what's next", "where am I", "project status"
+
+**Differentiation**:
+- User wants only research → use `/research` directly
+- User wants only planning → use `/plan` directly
+- User wants to document an existing codebase → use `/document` directly
+- User wants the full guided workflow → use `/autopilot`
+
+## Flow Reference
+
+See `flows/greenfield.md` and `flows/existing-code.md` for step tables, detection rules, auto-chain rules, and status summary templates.

.cursor/skills/autopilot/flows/existing-code.md

@@ -0,0 +1,234 @@
+# Existing Code Workflow
+
+Workflow for projects with an existing codebase. Starts with documentation, produces test specs, decomposes and implements tests, verifies them, refactors with that safety net, then adds new functionality and deploys.
+
+## Step Reference Table
+
+| Step | Name | Sub-Skill | Internal SubSteps |
+|------|------|-----------|-------------------|
+| 1 | Document | document/SKILL.md | Steps 1–8 |
+| 2 | Test Spec | test-spec/SKILL.md | Phase 1a–1b |
+| 3 | Decompose Tests | decompose/SKILL.md (tests-only) | Step 1t + Step 3 + Step 4 |
+| 4 | Implement Tests | implement/SKILL.md | (batch-driven, no fixed sub-steps) |
+| 5 | Run Tests | test-run/SKILL.md | Steps 1–4 |
+| 6 | Refactor | refactor/SKILL.md | Phases 0–5 (6-phase method) |
+| 7 | New Task | new-task/SKILL.md | Steps 1–8 (loop) |
+| 8 | Implement | implement/SKILL.md | (batch-driven, no fixed sub-steps) |
+| 9 | Run Tests | test-run/SKILL.md | Steps 1–4 |
+| 10 | Security Audit | security/SKILL.md | Phase 1–5 (optional) |
+| 11 | Performance Test | (autopilot-managed) | Load/stress tests (optional) |
+| 12 | Deploy | deploy/SKILL.md | Step 1–7 |
+
+After Step 12, the existing-code workflow is complete.
+
+## Detection Rules
+
+Check rules in order — first match wins.
+
+---
+
+**Step 1 — Document**
+Condition: `_docs/` does not exist AND the workspace contains source code files (e.g., `*.py`, `*.cs`, `*.rs`, `*.ts`, `src/`, `Cargo.toml`, `*.csproj`, `package.json`)
+
+Action: An existing codebase without documentation was detected. Read and execute `.cursor/skills/document/SKILL.md`. After the document skill completes, re-detect state (the produced `_docs/` artifacts will place the project at Step 2 or later).
+
+---
+
+**Step 2 — Test Spec**
+Condition: `_docs/02_document/FINAL_report.md` exists AND workspace contains source code files (e.g., `*.py`, `*.cs`, `*.rs`, `*.ts`) AND `_docs/02_document/tests/traceability-matrix.md` does not exist AND the autopilot state shows Document was run (check `Completed Steps` for "Document" entry)
+
+Action: Read and execute `.cursor/skills/test-spec/SKILL.md`
+
+This step applies when the codebase was documented via the `/document` skill. Test specifications must be produced before refactoring or further development.
+
+---
+
+**Step 3 — Decompose Tests**
+Condition: `_docs/02_document/tests/traceability-matrix.md` exists AND workspace contains source code files AND the autopilot state shows Document was run AND (`_docs/02_tasks/` does not exist or has no task files)
+
+Action: Read and execute `.cursor/skills/decompose/SKILL.md` in **tests-only mode** (pass `_docs/02_document/tests/` as input). The decompose skill will:
+1. Run Step 1t (test infrastructure bootstrap)
+2. Run Step 3 (blackbox test task decomposition)
+3. Run Step 4 (cross-verification against test coverage)
+
+If `_docs/02_tasks/` has some task files already, the decompose skill's resumability handles it.
+
+---
+
+**Step 4 — Implement Tests**
+Condition: `_docs/02_tasks/` contains task files AND `_dependencies_table.md` exists AND the autopilot state shows Step 3 (Decompose Tests) is completed AND `_docs/03_implementation/FINAL_implementation_report.md` does not exist
+
+Action: Read and execute `.cursor/skills/implement/SKILL.md`
+
+The implement skill reads test tasks from `_docs/02_tasks/` and implements them.
+
+If `_docs/03_implementation/` has batch reports, the implement skill detects completed tasks and continues.
+
+---
+
+**Step 5 — Run Tests**
+Condition: `_docs/03_implementation/FINAL_implementation_report.md` exists AND the autopilot state shows Step 4 (Implement Tests) is completed AND the autopilot state does NOT show Step 5 (Run Tests) as completed
+
+Action: Read and execute `.cursor/skills/test-run/SKILL.md`
+
+Verifies the implemented test suite passes before proceeding to refactoring. The tests form the safety net for all subsequent code changes.
+
+---
+
+**Step 6 — Refactor**
+Condition: the autopilot state shows Step 5 (Run Tests) is completed AND `_docs/04_refactoring/FINAL_report.md` does not exist
+
+Action: Read and execute `.cursor/skills/refactor/SKILL.md`
+
+The refactor skill runs the full 6-phase method using the implemented tests as a safety net.
+
+If `_docs/04_refactoring/` has phase reports, the refactor skill detects completed phases and continues.
+
+---
+
+**Step 7 — New Task**
+Condition: the autopilot state shows Step 6 (Refactor) is completed AND the autopilot state does NOT show Step 7 (New Task) as completed
+
+Action: Read and execute `.cursor/skills/new-task/SKILL.md`
+
+The new-task skill interactively guides the user through defining new functionality. It loops until the user is done adding tasks. New task files are written to `_docs/02_tasks/`.
+
+---
+
+**Step 8 — Implement**
+Condition: the autopilot state shows Step 7 (New Task) is completed AND `_docs/03_implementation/` does not contain a FINAL report covering the new tasks (check state for distinction between test implementation and feature implementation)
+
+Action: Read and execute `.cursor/skills/implement/SKILL.md`
+
+The implement skill reads the new tasks from `_docs/02_tasks/` and implements them. Tasks already implemented in Step 4 are skipped (the implement skill tracks completed tasks in batch reports).
+
+If `_docs/03_implementation/` has batch reports from this phase, the implement skill detects completed tasks and continues.
+
+---
+
+**Step 9 — Run Tests**
+Condition: the autopilot state shows Step 8 (Implement) is completed AND the autopilot state does NOT show Step 9 (Run Tests) as completed
+
+Action: Read and execute `.cursor/skills/test-run/SKILL.md`
+
+---
+
+**Step 10 — Security Audit (optional)**
+Condition: the autopilot state shows Step 9 (Run Tests) is completed AND the autopilot state does NOT show Step 10 (Security Audit) as completed or skipped AND (`_docs/04_deploy/` does not exist or is incomplete)
+
+Action: Present using Choose format:
+
+```
+══════════════════════════════════════
+ DECISION REQUIRED: Run security audit before deploy?
+══════════════════════════════════════
+ A) Run security audit (recommended for production deployments)
+ B) Skip — proceed directly to deploy
+══════════════════════════════════════
+ Recommendation: A — catches vulnerabilities before production
+══════════════════════════════════════
+```
+
+- If user picks A → Read and execute `.cursor/skills/security/SKILL.md`. After completion, auto-chain to Step 11 (Performance Test).
+- If user picks B → Mark Step 10 as `skipped` in the state file, auto-chain to Step 11 (Performance Test).
+
+---
+
+**Step 11 — Performance Test (optional)**
+Condition: the autopilot state shows Step 10 (Security Audit) is completed or skipped AND the autopilot state does NOT show Step 11 (Performance Test) as completed or skipped AND (`_docs/04_deploy/` does not exist or is incomplete)
+
+Action: Present using Choose format:
+
+```
+══════════════════════════════════════
+ DECISION REQUIRED: Run performance/load tests before deploy?
+══════════════════════════════════════
+ A) Run performance tests (recommended for latency-sensitive or high-load systems)
+ B) Skip — proceed directly to deploy
+══════════════════════════════════════
+ Recommendation: [A or B — base on whether acceptance criteria
+ include latency, throughput, or load requirements]
+══════════════════════════════════════
+```
+
+- If user picks A → Run performance tests:
+  1. If `scripts/run-performance-tests.sh` exists (generated by the test-spec skill Phase 4), execute it
+  2. Otherwise, check if `_docs/02_document/tests/performance-tests.md` exists for test scenarios, detect appropriate load testing tool (k6, locust, artillery, wrk, or built-in benchmarks), and execute performance test scenarios against the running system
+  3. Present results vs acceptance criteria thresholds
+  4. If thresholds fail → present Choose format: A) Fix and re-run, B) Proceed anyway, C) Abort
+  5. After completion, auto-chain to Step 12 (Deploy)
+- If user picks B → Mark Step 11 as `skipped` in the state file, auto-chain to Step 12 (Deploy).
+
+---
+
+**Step 12 — Deploy**
+Condition: the autopilot state shows Step 9 (Run Tests) is completed AND (Step 10 is completed or skipped) AND (Step 11 is completed or skipped) AND (`_docs/04_deploy/` does not exist or is incomplete)
+
+Action: Read and execute `.cursor/skills/deploy/SKILL.md`
+
+After deployment completes, the existing-code workflow is done.
+
+---
+
+**Re-Entry After Completion**
+Condition: the autopilot state shows `step: done` OR all steps through 12 (Deploy) are completed
+
+Action: The project completed a full cycle. Present status and loop back to New Task:
+
+```
+══════════════════════════════════════
+ PROJECT CYCLE COMPLETE
+══════════════════════════════════════
+ The previous cycle finished successfully.
+ You can now add new functionality.
+══════════════════════════════════════
+ A) Add new features (start New Task)
+ B) Done — no more changes needed
+══════════════════════════════════════
+```
+
+- If user picks A → set `step: 7`, `status: not_started` in the state file, then auto-chain to Step 7 (New Task). Previous cycle history stays in Completed Steps.
+- If user picks B → report final project status and exit.
+
+## Auto-Chain Rules
+
+| Completed Step | Next Action |
+|---------------|-------------|
+| Document (1) | Auto-chain → Test Spec (2) |
+| Test Spec (2) | Auto-chain → Decompose Tests (3) |
+| Decompose Tests (3) | **Session boundary** — suggest new conversation before Implement Tests |
+| Implement Tests (4) | Auto-chain → Run Tests (5) |
+| Run Tests (5, all pass) | Auto-chain → Refactor (6) |
+| Refactor (6) | Auto-chain → New Task (7) |
+| New Task (7) | **Session boundary** — suggest new conversation before Implement |
+| Implement (8) | Auto-chain → Run Tests (9) |
+| Run Tests (9, all pass) | Auto-chain → Security Audit choice (10) |
+| Security Audit (10, done or skipped) | Auto-chain → Performance Test choice (11) |
+| Performance Test (11, done or skipped) | Auto-chain → Deploy (12) |
+| Deploy (12) | **Workflow complete** — existing-code flow done |
+
+## Status Summary Template
+
+```
+═══════════════════════════════════════════════════
+ AUTOPILOT STATUS (existing-code)
+═══════════════════════════════════════════════════
+ Step 1   Document            [DONE / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 2   Test Spec           [DONE / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 3   Decompose Tests     [DONE (N tasks) / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 4   Implement Tests     [DONE / IN PROGRESS (batch M) / NOT STARTED / FAILED (retry N/3)]
+ Step 5   Run Tests           [DONE (N passed, M failed) / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 6   Refactor            [DONE / IN PROGRESS (phase N) / NOT STARTED / FAILED (retry N/3)]
+ Step 7   New Task            [DONE (N tasks) / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 8   Implement           [DONE / IN PROGRESS (batch M of ~N) / NOT STARTED / FAILED (retry N/3)]
+ Step 9   Run Tests           [DONE (N passed, M failed) / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 10  Security Audit      [DONE / SKIPPED / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 11  Performance Test    [DONE / SKIPPED / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 12  Deploy              [DONE / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+═══════════════════════════════════════════════════
+ Current: Step N — Name
+ SubStep: M — [sub-skill internal step name]
+ Retry:   [N/3 if retrying, omit if 0]
+ Action:  [what will happen next]
+═══════════════════════════════════════════════════
+```

.cursor/skills/autopilot/flows/greenfield.md

@@ -0,0 +1,235 @@
+# Greenfield Workflow
+
+Workflow for new projects built from scratch. Flows linearly: Problem → Research → Plan → UI Design (if applicable) → Decompose → Implement → Run Tests → Security Audit (optional) → Performance Test (optional) → Deploy.
+
+## Step Reference Table
+
+| Step | Name | Sub-Skill | Internal SubSteps |
+|------|------|-----------|-------------------|
+| 1 | Problem | problem/SKILL.md | Phase 1–4 |
+| 2 | Research | research/SKILL.md | Mode A: Phase 1–4 · Mode B: Step 0–8 |
+| 3 | Plan | plan/SKILL.md | Step 1–6 + Final |
+| 4 | UI Design | ui-design/SKILL.md | Phase 0–8 (conditional — UI projects only) |
+| 5 | Decompose | decompose/SKILL.md | Step 1–4 |
+| 6 | Implement | implement/SKILL.md | (batch-driven, no fixed sub-steps) |
+| 7 | Run Tests | test-run/SKILL.md | Steps 1–4 |
+| 8 | Security Audit | security/SKILL.md | Phase 1–5 (optional) |
+| 9 | Performance Test | (autopilot-managed) | Load/stress tests (optional) |
+| 10 | Deploy | deploy/SKILL.md | Step 1–7 |
+
+## Detection Rules
+
+Check rules in order — first match wins.
+
+---
+
+**Step 1 — Problem Gathering**
+Condition: `_docs/00_problem/` does not exist, OR any of these are missing/empty:
+- `problem.md`
+- `restrictions.md`
+- `acceptance_criteria.md`
+- `input_data/` (must contain at least one file)
+
+Action: Read and execute `.cursor/skills/problem/SKILL.md`
+
+---
+
+**Step 2 — Research (Initial)**
+Condition: `_docs/00_problem/` is complete AND `_docs/01_solution/` has no `solution_draft*.md` files
+
+Action: Read and execute `.cursor/skills/research/SKILL.md` (will auto-detect Mode A)
+
+---
+
+**Research Decision** (inline gate between Step 2 and Step 3)
+Condition: `_docs/01_solution/` contains `solution_draft*.md` files AND `_docs/01_solution/solution.md` does not exist AND `_docs/02_document/architecture.md` does not exist
+
+Action: Present the current research state to the user:
+- How many solution drafts exist
+- Whether tech_stack.md and security_analysis.md exist
+- One-line summary from the latest draft
+
+Then present using the **Choose format**:
+
+```
+══════════════════════════════════════
+ DECISION REQUIRED: Research complete — next action?
+══════════════════════════════════════
+ A) Run another research round (Mode B assessment)
+ B) Proceed to planning with current draft
+══════════════════════════════════════
+ Recommendation: [A or B] — [reason based on draft quality]
+══════════════════════════════════════
+```
+
+- If user picks A → Read and execute `.cursor/skills/research/SKILL.md` (will auto-detect Mode B)
+- If user picks B → auto-chain to Step 3 (Plan)
+
+---
+
+**Step 3 — Plan**
+Condition: `_docs/01_solution/` has `solution_draft*.md` files AND `_docs/02_document/architecture.md` does not exist
+
+Action:
+1. The plan skill's Prereq 2 will rename the latest draft to `solution.md` — this is handled by the plan skill itself
+2. Read and execute `.cursor/skills/plan/SKILL.md`
+
+If `_docs/02_document/` exists but is incomplete (has some artifacts but no `FINAL_report.md`), the plan skill's built-in resumability handles it.
+
+---
+
+**Step 4 — UI Design (conditional)**
+Condition: `_docs/02_document/architecture.md` exists AND the autopilot state does NOT show Step 4 (UI Design) as completed or skipped AND the project is a UI project
+
+**UI Project Detection** — the project is a UI project if ANY of the following are true:
+- `package.json` exists in the workspace root or any subdirectory
+- `*.html`, `*.jsx`, `*.tsx` files exist in the workspace
+- `_docs/02_document/components/` contains a component whose `description.md` mentions UI, frontend, page, screen, dashboard, form, or view
+- `_docs/02_document/architecture.md` mentions frontend, UI layer, SPA, or client-side rendering
+- `_docs/01_solution/solution.md` mentions frontend, web interface, or user-facing UI
+
+If the project is NOT a UI project → mark Step 4 as `skipped` in the state file and auto-chain to Step 5.
+
+If the project IS a UI project → present using Choose format:
+
+```
+══════════════════════════════════════
+ DECISION REQUIRED: UI project detected — generate mockups?
+══════════════════════════════════════
+ A) Generate UI mockups before decomposition (recommended)
+ B) Skip — proceed directly to decompose
+══════════════════════════════════════
+ Recommendation: A — mockups before decomposition
+ produce better task specs for frontend components
+══════════════════════════════════════
+```
+
+- If user picks A → Read and execute `.cursor/skills/ui-design/SKILL.md`. After completion, auto-chain to Step 5 (Decompose).
+- If user picks B → Mark Step 4 as `skipped` in the state file, auto-chain to Step 5 (Decompose).
+
+---
+
+**Step 5 — Decompose**
+Condition: `_docs/02_document/` contains `architecture.md` AND `_docs/02_document/components/` has at least one component AND `_docs/02_tasks/` does not exist or has no task files (excluding `_dependencies_table.md`)
+
+Action: Read and execute `.cursor/skills/decompose/SKILL.md`
+
+If `_docs/02_tasks/` has some task files already, the decompose skill's resumability handles it.
+
+---
+
+**Step 6 — Implement**
+Condition: `_docs/02_tasks/` contains task files AND `_dependencies_table.md` exists AND `_docs/03_implementation/FINAL_implementation_report.md` does not exist
+
+Action: Read and execute `.cursor/skills/implement/SKILL.md`
+
+If `_docs/03_implementation/` has batch reports, the implement skill detects completed tasks and continues.
+
+---
+
+**Step 7 — Run Tests**
+Condition: `_docs/03_implementation/FINAL_implementation_report.md` exists AND the autopilot state does NOT show Step 7 (Run Tests) as completed AND (`_docs/04_deploy/` does not exist or is incomplete)
+
+Action: Read and execute `.cursor/skills/test-run/SKILL.md`
+
+---
+
+**Step 8 — Security Audit (optional)**
+Condition: the autopilot state shows Step 7 (Run Tests) is completed AND the autopilot state does NOT show Step 8 (Security Audit) as completed or skipped AND (`_docs/04_deploy/` does not exist or is incomplete)
+
+Action: Present using Choose format:
+
+```
+══════════════════════════════════════
+ DECISION REQUIRED: Run security audit before deploy?
+══════════════════════════════════════
+ A) Run security audit (recommended for production deployments)
+ B) Skip — proceed directly to deploy
+══════════════════════════════════════
+ Recommendation: A — catches vulnerabilities before production
+══════════════════════════════════════
+```
+
+- If user picks A → Read and execute `.cursor/skills/security/SKILL.md`. After completion, auto-chain to Step 9 (Performance Test).
+- If user picks B → Mark Step 8 as `skipped` in the state file, auto-chain to Step 9 (Performance Test).
+
+---
+
+**Step 9 — Performance Test (optional)**
+Condition: the autopilot state shows Step 8 (Security Audit) is completed or skipped AND the autopilot state does NOT show Step 9 (Performance Test) as completed or skipped AND (`_docs/04_deploy/` does not exist or is incomplete)
+
+Action: Present using Choose format:
+
+```
+══════════════════════════════════════
+ DECISION REQUIRED: Run performance/load tests before deploy?
+══════════════════════════════════════
+ A) Run performance tests (recommended for latency-sensitive or high-load systems)
+ B) Skip — proceed directly to deploy
+══════════════════════════════════════
+ Recommendation: [A or B — base on whether acceptance criteria
+ include latency, throughput, or load requirements]
+══════════════════════════════════════
+```
+
+- If user picks A → Run performance tests:
+  1. If `scripts/run-performance-tests.sh` exists (generated by the test-spec skill Phase 4), execute it
+  2. Otherwise, check if `_docs/02_document/tests/performance-tests.md` exists for test scenarios, detect appropriate load testing tool (k6, locust, artillery, wrk, or built-in benchmarks), and execute performance test scenarios against the running system
+  3. Present results vs acceptance criteria thresholds
+  4. If thresholds fail → present Choose format: A) Fix and re-run, B) Proceed anyway, C) Abort
+  5. After completion, auto-chain to Step 10 (Deploy)
+- If user picks B → Mark Step 9 as `skipped` in the state file, auto-chain to Step 10 (Deploy).
+
+---
+
+**Step 10 — Deploy**
+Condition: the autopilot state shows Step 7 (Run Tests) is completed AND (Step 8 is completed or skipped) AND (Step 9 is completed or skipped) AND (`_docs/04_deploy/` does not exist or is incomplete)
+
+Action: Read and execute `.cursor/skills/deploy/SKILL.md`
+
+---
+
+**Done**
+Condition: `_docs/04_deploy/` contains all expected artifacts (containerization.md, ci_cd_pipeline.md, environment_strategy.md, observability.md, deployment_procedures.md)
+
+Action: Report project completion with summary. If the user runs autopilot again after greenfield completion, Flow Resolution rule 3 routes to the existing-code flow (re-entry after completion) so they can add new features.
+
+## Auto-Chain Rules
+
+| Completed Step | Next Action |
+|---------------|-------------|
+| Problem (1) | Auto-chain → Research (2) |
+| Research (2) | Auto-chain → Research Decision (ask user: another round or proceed?) |
+| Research Decision → proceed | Auto-chain → Plan (3) |
+| Plan (3) | Auto-chain → UI Design detection (4) |
+| UI Design (4, done or skipped) | Auto-chain → Decompose (5) |
+| Decompose (5) | **Session boundary** — suggest new conversation before Implement |
+| Implement (6) | Auto-chain → Run Tests (7) |
+| Run Tests (7, all pass) | Auto-chain → Security Audit choice (8) |
+| Security Audit (8, done or skipped) | Auto-chain → Performance Test choice (9) |
+| Performance Test (9, done or skipped) | Auto-chain → Deploy (10) |
+| Deploy (10) | Report completion |
+
+## Status Summary Template
+
+```
+═══════════════════════════════════════════════════
+ AUTOPILOT STATUS (greenfield)
+═══════════════════════════════════════════════════
+ Step 1   Problem             [DONE / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 2   Research            [DONE (N drafts) / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 3   Plan                [DONE / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 4   UI Design           [DONE / SKIPPED / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 5   Decompose           [DONE (N tasks) / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 6   Implement           [DONE / IN PROGRESS (batch M of ~N) / NOT STARTED / FAILED (retry N/3)]
+ Step 7   Run Tests           [DONE (N passed, M failed) / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 8   Security Audit      [DONE / SKIPPED / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 9   Performance Test    [DONE / SKIPPED / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+ Step 10  Deploy              [DONE / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
+═══════════════════════════════════════════════════
+ Current: Step N — Name
+ SubStep: M — [sub-skill internal step name]
+ Retry:   [N/3 if retrying, omit if 0]
+ Action:  [what will happen next]
+═══════════════════════════════════════════════════
+```

.cursor/skills/autopilot/protocols.md

@@ -0,0 +1,314 @@
+# Autopilot Protocols
+
+## User Interaction Protocol
+
+Every time the autopilot or a sub-skill needs a user decision, use the **Choose A / B / C / D** format. This applies to:
+
+- State transitions where multiple valid next actions exist
+- Sub-skill BLOCKING gates that require user judgment
+- Any fork where the autopilot cannot confidently pick the right path
+- Trade-off decisions (tech choices, scope, risk acceptance)
+
+### When to Ask (MUST ask)
+
+- The next action is ambiguous (e.g., "another research round or proceed?")
+- The decision has irreversible consequences (e.g., architecture choices, skipping a step)
+- The user's intent or preference cannot be inferred from existing artifacts
+- A sub-skill's BLOCKING gate explicitly requires user confirmation
+- Multiple valid approaches exist with meaningfully different trade-offs
+
+### When NOT to Ask (auto-transition)
+
+- Only one logical next step exists (e.g., Problem complete → Research is the only option)
+- The transition is deterministic from the state (e.g., Plan complete → Decompose)
+- The decision is low-risk and reversible
+- Existing artifacts or prior decisions already imply the answer
+
+### Choice Format
+
+Always present decisions in this format:
+
+```
+══════════════════════════════════════
+ DECISION REQUIRED: [brief context]
+══════════════════════════════════════
+ A) [Option A — short description]
+ B) [Option B — short description]
+ C) [Option C — short description, if applicable]
+ D) [Option D — short description, if applicable]
+══════════════════════════════════════
+ Recommendation: [A/B/C/D] — [one-line reason]
+══════════════════════════════════════
+```
+
+Rules:
+1. Always provide 2–4 concrete options (never open-ended questions)
+2. Always include a recommendation with a brief justification
+3. Keep option descriptions to one line each
+4. If only 2 options make sense, use A/B only — do not pad with filler options
+5. Play the notification sound (per `human-attention-sound.mdc`) before presenting the choice
+6. Record every user decision in the state file's `Key Decisions` section
+7. After the user picks, proceed immediately — no follow-up confirmation unless the choice was destructive
+
+## Work Item Tracker Authentication
+
+Several workflow steps create work items (epics, tasks, links). The system supports **Jira MCP** and **Azure DevOps MCP** as interchangeable backends. Detect which is configured by listing available MCP servers.
+
+### Tracker Detection
+
+1. Check for available MCP servers: Jira MCP (`user-Jira-MCP-Server`) or Azure DevOps MCP (`user-AzureDevops`)
+2. If both are available, ask the user which to use (Choose format)
+3. Record the choice in the state file: `tracker: jira` or `tracker: ado`
+4. If neither is available, set `tracker: local` and proceed without external tracking
+
+### Steps That Require Work Item Tracker
+
+| Flow | Step | Sub-Step | Tracker Action |
+|------|------|----------|----------------|
+| greenfield | 3 (Plan) | Step 6 — Epics | Create epics for each component |
+| greenfield | 5 (Decompose) | Step 1–3 — All tasks | Create ticket per task, link to epic |
+| existing-code | 3 (Decompose Tests) | Step 1t + Step 3 — All test tasks | Create ticket per task, link to epic |
+| existing-code | 7 (New Task) | Step 7 — Ticket | Create ticket per task, link to epic |
+
+### Authentication Gate
+
+Before entering a step that requires work item tracking (see table above) for the first time, the autopilot must:
+
+1. Call `mcp_auth` on the detected tracker's MCP server
+2. If authentication succeeds → proceed normally
+3. If the user **skips** or authentication fails → present using Choose format:
+
+```
+══════════════════════════════════════
+ Tracker authentication failed
+══════════════════════════════════════
+ A) Retry authentication (retry mcp_auth)
+ B) Continue without tracker (tasks saved locally only)
+══════════════════════════════════════
+ Recommendation: A — Tracker IDs drive task referencing,
+ dependency tracking, and implementation batching.
+ Without tracker, task files use numeric prefixes instead.
+══════════════════════════════════════
+```
+
+If user picks **B** (continue without tracker):
+- Set a flag in the state file: `tracker: local`
+- All skills that would create tickets instead save metadata locally in the task/epic files with `Tracker: pending` status
+- Task files keep numeric prefixes (e.g., `01_initial_structure.md`) instead of tracker ID prefixes
+- The workflow proceeds normally in all other respects
+
+### Re-Authentication
+
+If the tracker MCP was already authenticated in a previous invocation (verify by listing available tools beyond `mcp_auth`), skip the auth gate.
+
+## Error Handling
+
+All error situations that require user input MUST use the **Choose A / B / C / D** format.
+
+| Situation | Action |
+|-----------|--------|
+| State detection is ambiguous (artifacts suggest two different steps) | Present findings and use Choose format with the candidate steps as options |
+| Sub-skill fails or hits an unrecoverable blocker | Use Choose format: A) retry, B) skip with warning, C) abort and fix manually |
+| User wants to skip a step | Use Choose format: A) skip (with dependency warning), B) execute the step |
+| User wants to go back to a previous step | Use Choose format: A) re-run (with overwrite warning), B) stay on current step |
+| User asks "where am I?" without wanting to continue | Show Status Summary only, do not start execution |
+
+## Skill Failure Retry Protocol
+
+Sub-skills can return a **failed** result. Failures are often caused by missing user input, environment issues, or transient errors that resolve on retry. The autopilot auto-retries before escalating.
+
+### Retry Flow
+
+```
+Skill execution → FAILED
+  │
+  ├─ retry_count < 3 ?
+  │    YES → increment retry_count in state file
+  │         → log failure reason in state file (Retry Log section)
+  │         → re-read the sub-skill's SKILL.md
+  │         → re-execute from the current sub_step
+  │         → (loop back to check result)
+  │
+  │    NO (retry_count = 3) →
+  │         → set status: failed in Current Step
+  │         → add entry to Blockers section:
+  │             "[Skill Name] failed 3 consecutive times at sub_step [M].
+  │              Last failure: [reason]. Auto-retry exhausted."
+  │         → present warning to user (see Escalation below)
+  │         → do NOT auto-retry again until user intervenes
+```
+
+### Retry Rules
+
+1. **Auto-retry immediately**: when a skill fails, retry it without asking the user — the failure is often transient (missing user confirmation in a prior step, docker not running, file lock, etc.)
+2. **Preserve sub_step**: retry from the last recorded `sub_step`, not from the beginning of the skill — unless the failure indicates corruption, in which case restart from sub_step 1
+3. **Increment `retry_count`**: update `retry_count` in the state file's `Current Step` section on each retry attempt
+4. **Log each failure**: append the failure reason and timestamp to the state file's `Retry Log` section
+5. **Reset on success**: when the skill eventually succeeds, reset `retry_count: 0` and clear the `Retry Log` for that step
+
+### Escalation (after 3 consecutive failures)
+
+After 3 failed auto-retries of the same skill, the failure is likely not user-related. Stop retrying and escalate:
+
+1. Update the state file:
+   - Set `status: failed` in `Current Step`
+   - Set `retry_count: 3`
+   - Add a blocker entry describing the repeated failure
+2. Play notification sound (per `human-attention-sound.mdc`)
+3. Present using Choose format:
+
+```
+══════════════════════════════════════
+ SKILL FAILED: [Skill Name] — 3 consecutive failures
+══════════════════════════════════════
+ Step: [N] — [Name]
+ SubStep: [M] — [sub-step name]
+ Last failure reason: [reason]
+══════════════════════════════════════
+ A) Retry with fresh context (new conversation)
+ B) Skip this step with warning
+ C) Abort — investigate and fix manually
+══════════════════════════════════════
+ Recommendation: A — fresh context often resolves
+ persistent failures
+══════════════════════════════════════
+```
+
+### Re-Entry After Failure
+
+On the next autopilot invocation (new conversation), if the state file shows `status: failed` and `retry_count: 3`:
+
+- Present the blocker to the user before attempting execution
+- If the user chooses to retry → reset `retry_count: 0`, set `status: in_progress`, and re-execute
+- If the user chooses to skip → mark step as `skipped`, proceed to next step
+- Do NOT silently auto-retry — the user must acknowledge the persistent failure first
+
+## Error Recovery Protocol
+
+### Stuck Detection
+
+When executing a sub-skill, monitor for these signals:
+
+- Same artifact overwritten 3+ times without meaningful change
+- Sub-skill repeatedly asks the same question after receiving an answer
+- No new artifacts saved for an extended period despite active execution
+
+### Recovery Actions (ordered)
+
+1. **Re-read state**: read `_docs/_autopilot_state.md` and cross-check against `_docs/` folders
+2. **Retry current sub-step**: re-read the sub-skill's SKILL.md and restart from the current sub-step
+3. **Escalate**: after 2 failed retries, present diagnostic summary to user using Choose format:
+
+```
+══════════════════════════════════════
+ RECOVERY: [skill name] stuck at [sub-step]
+══════════════════════════════════════
+ A) Retry with fresh context (new conversation)
+ B) Skip this sub-step with warning
+ C) Abort and fix manually
+══════════════════════════════════════
+ Recommendation: A — fresh context often resolves stuck loops
+══════════════════════════════════════
+```
+
+### Circuit Breaker
+
+If the same autopilot step fails 3 consecutive times across conversations:
+
+- Record the failure pattern in the state file's `Blockers` section
+- Do NOT auto-retry on next invocation
+- Present the blocker and ask user for guidance before attempting again
+
+## Context Management Protocol
+
+### Principle
+
+Disk is memory. Never rely on in-context accumulation — read from `_docs/` artifacts, not from conversation history.
+
+### Minimal Re-Read Set Per Skill
+
+When re-entering a skill (new conversation or context refresh):
+
+- Always read: `_docs/_autopilot_state.md`
+- Always read: the active skill's `SKILL.md`
+- Conditionally read: only the `_docs/` artifacts the current sub-step requires (listed in each skill's Context Resolution section)
+- Never bulk-read: do not load all `_docs/` files at once
+
+### Mid-Skill Interruption
+
+If context is filling up during a long skill (e.g., document, implement):
+
+1. Save current sub-step progress to the skill's artifact directory
+2. Update `_docs/_autopilot_state.md` with exact sub-step position
+3. Suggest a new conversation: "Context is getting long — recommend continuing in a fresh conversation for better results"
+4. On re-entry, the skill's resumability protocol picks up from the saved sub-step
+
+### Large Artifact Handling
+
+When a skill needs to read large files (e.g., full solution.md, architecture.md):
+
+- Read only the sections relevant to the current sub-step
+- Use search tools (Grep, SemanticSearch) to find specific sections rather than reading entire files
+- Summarize key decisions from prior steps in the state file so they don't need to be re-read
+
+### Context Budget Heuristic
+
+Agents cannot programmatically query context window usage. Use these heuristics to avoid degradation:
+
+| Zone | Indicators | Action |
+|------|-----------|--------|
+| **Safe** | State file + SKILL.md + 2–3 focused artifacts loaded | Continue normally |
+| **Caution** | 5+ artifacts loaded, or 3+ large files (architecture, solution, discovery), or conversation has 20+ tool calls | Complete current sub-step, then suggest session break |
+| **Danger** | Repeated truncation in tool output, tool calls failing unexpectedly, responses becoming shallow or repetitive | Save immediately, update state file, force session boundary |
+
+**Skill-specific guidelines**:
+
+| Skill | Recommended session breaks |
+|-------|---------------------------|
+| **document** | After every ~5 modules in Step 1; between Step 4 (Verification) and Step 5 (Solution Extraction) |
+| **implement** | Each batch is a natural checkpoint; if more than 2 batches completed in one session, suggest break |
+| **plan** | Between Step 5 (Test Specifications) and Step 6 (Epics) for projects with many components |
+| **research** | Between Mode A rounds; between Mode A and Mode B |
+
+**How to detect caution/danger zone without API**:
+
+1. Count tool calls made so far — if approaching 20+, context is likely filling up
+2. If reading a file returns truncated content, context is under pressure
+3. If the agent starts producing shorter or less detailed responses than earlier in the conversation, context quality is degrading
+4. When in doubt, save and suggest a new conversation — re-entry is cheap thanks to the state file
+
+## Rollback Protocol
+
+### Implementation Steps (git-based)
+
+Handled by `/implement` skill — each batch commit is a rollback checkpoint via `git revert`.
+
+### Planning/Documentation Steps (artifact-based)
+
+For steps that produce `_docs/` artifacts (problem, research, plan, decompose, document):
+
+1. **Before overwriting**: if re-running a step that already has artifacts, the sub-skill's prerequisite check asks the user (resume/overwrite/skip)
+2. **Rollback to previous step**: use Choose format:
+
+```
+══════════════════════════════════════
+ ROLLBACK: Re-run [step name]?
+══════════════════════════════════════
+ A) Re-run the step (overwrites current artifacts)
+ B) Stay on current step
+══════════════════════════════════════
+ Warning: This will overwrite files in _docs/[folder]/
+══════════════════════════════════════
+```
+
+3. **Git safety net**: artifacts are committed with each autopilot step completion. To roll back: `git log --oneline _docs/` to find the commit, then `git checkout <commit> -- _docs/<folder>/`
+4. **State file rollback**: when rolling back artifacts, also update `_docs/_autopilot_state.md` to reflect the rolled-back step (set it to `in_progress`, clear completed date)
+
+## Status Summary
+
+On every invocation, before executing any skill, present a status summary built from the state file (with folder scan fallback). Use the Status Summary Template from the active flow file (`flows/greenfield.md` or `flows/existing-code.md`).
+
+For re-entry (state file exists), also include:
+- Key decisions from the state file's `Key Decisions` section
+- Last session context from the `Last Session` section
+- Any blockers from the `Blockers` section

.cursor/skills/autopilot/state.md

@@ -0,0 +1,122 @@
+# Autopilot State Management
+
+## State File: `_docs/_autopilot_state.md`
+
+The autopilot persists its state to `_docs/_autopilot_state.md`. This file is the primary source of truth for re-entry. Folder scanning is the fallback when the state file doesn't exist.
+
+### Format
+
+```markdown
+# Autopilot State
+
+## Current Step
+flow: [greenfield | existing-code]
+step: [1-10 for greenfield, 1-12 for existing-code, or "done"]
+name: [step name from the active flow's Step Reference Table]
+status: [not_started / in_progress / completed / skipped / failed]
+sub_step: [optional — sub-skill internal step number + name if interrupted mid-step]
+retry_count: [0-3 — number of consecutive auto-retry attempts for current step, reset to 0 on success]
+
+When updating `Current Step`, always write it as:
+  flow: existing-code   ← active flow
+  step: N               ← autopilot step (sequential integer)
+  sub_step: M           ← sub-skill's own internal step/phase number + name
+  retry_count: 0        ← reset on new step or success; increment on each failed retry
+Example:
+  flow: greenfield
+  step: 3
+  name: Plan
+  status: in_progress
+  sub_step: 4 — Architecture Review & Risk Assessment
+  retry_count: 0
+Example (failed after 3 retries):
+  flow: existing-code
+  step: 2
+  name: Test Spec
+  status: failed
+  sub_step: 1b — Test Case Generation
+  retry_count: 3
+
+## Completed Steps
+
+| Step | Name | Completed | Key Outcome |
+|------|------|-----------|-------------|
+| 1 | [name] | [date] | [one-line summary] |
+| 2 | [name] | [date] | [one-line summary] |
+| ... | ... | ... | ... |
+
+## Key Decisions
+- [decision 1: e.g. "Tech stack: Python + Rust for perf-critical, Postgres DB"]
+- [decision N]
+
+## Last Session
+date: [date]
+ended_at: Step [N] [Name] — SubStep [M] [sub-step name]
+reason: [completed step / session boundary / user paused / context limit]
+notes: [any context for next session]
+
+## Retry Log
+| Attempt | Step | Name | SubStep | Failure Reason | Timestamp |
+|---------|------|------|---------|----------------|-----------|
+| 1 | [step] | [name] | [sub_step] | [reason] | [date-time] |
+| ... | ... | ... | ... | ... | ... |
+
+(Clear this table when the step succeeds or user resets. Append a row on each failed auto-retry.)
+
+## Blockers
+- [blocker 1, if any]
+- [none]
+```
+
+### State File Rules
+
+1. **Create** the state file on the very first autopilot invocation (after state detection determines Step 1)
+2. **Update** the state file after every step completion, every session boundary, every BLOCKING gate confirmation, and every failed retry attempt
+3. **Read** the state file as the first action on every invocation — before folder scanning
+4. **Cross-check**: after reading the state file, verify against actual `_docs/` folder contents. If they disagree (e.g., state file says Step 3 but `_docs/02_document/architecture.md` already exists), trust the folder structure and update the state file to match
+5. **Never delete** the state file. It accumulates history across the entire project lifecycle
+6. **Retry tracking**: increment `retry_count` on each failed auto-retry; reset to `0` when the step succeeds or the user manually resets. If `retry_count` reaches 3, set `status: failed` and add an entry to `Blockers`
+7. **Failed state on re-entry**: if the state file shows `status: failed` with `retry_count: 3`, do NOT auto-retry — present the blocker to the user and wait for their decision before proceeding
+
+## State Detection
+
+Read `_docs/_autopilot_state.md` first. If it exists and is consistent with the folder structure, use the `Current Step` from the state file. If the state file doesn't exist or is inconsistent, fall back to folder scanning.
+
+### Folder Scan Rules (fallback)
+
+Scan `_docs/` to determine the current workflow position. The detection rules are defined in each flow file (`flows/greenfield.md` and `flows/existing-code.md`). Check the existing-code flow first (Step 1 detection), then greenfield flow rules. First match wins.
+
+## Re-Entry Protocol
+
+When the user invokes `/autopilot` and work already exists:
+
+1. Read `_docs/_autopilot_state.md`
+2. Cross-check against `_docs/` folder structure
+3. Present Status Summary with context from state file (key decisions, last session, blockers)
+4. If the detected step has a sub-skill with built-in resumability (plan, decompose, implement, deploy all do), the sub-skill handles mid-step recovery
+5. Continue execution from detected state
+
+## Session Boundaries
+
+After any decompose/planning step completes, **do not auto-chain to implement**. Instead:
+
+1. Update state file: mark the step as completed, set current step to the next implement step with status `not_started`
+   - Existing-code flow: After Step 3 (Decompose Tests) → set current step to 4 (Implement Tests)
+   - Existing-code flow: After Step 7 (New Task) → set current step to 8 (Implement)
+   - Greenfield flow: After Step 5 (Decompose) → set current step to 6 (Implement)
+2. Write `Last Session` section: `reason: session boundary`, `notes: Decompose complete, implementation ready`
+3. Present a summary: number of tasks, estimated batches, total complexity points
+4. Use Choose format:
+
+```
+══════════════════════════════════════
+ DECISION REQUIRED: Decompose complete — start implementation?
+══════════════════════════════════════
+ A) Start a new conversation for implementation (recommended for context freshness)
+ B) Continue implementation in this conversation
+══════════════════════════════════════
+ Recommendation: A — implementation is the longest phase, fresh context helps
+══════════════════════════════════════
+```
+
+These are the only hard session boundaries. All other transitions auto-chain.

.cursor/skills/code-review/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: code-review
+description: |
+  Multi-phase code review against task specs with structured findings output.
+  6-phase workflow: context loading, spec compliance, code quality, security quick-scan, performance scan, cross-task consistency.
+  Produces a structured report with severity-ranked findings and a PASS/FAIL/PASS_WITH_WARNINGS verdict.
+  Invoked by /implement skill after each batch, or manually.
+  Trigger phrases:
+  - "code review", "review code", "review implementation"
+  - "check code quality", "review against specs"
+category: review
+tags: [code-review, quality, security-scan, performance, SOLID]
+disable-model-invocation: true
+---
+
+# Code Review
+
+Multi-phase code review that verifies implementation against task specs, checks code quality, and produces structured findings.
+
+## Core Principles
+
+- **Understand intent first**: read the task specs before reviewing code — know what it should do before judging how
+- **Structured output**: every finding has severity, category, location, description, and suggestion
+- **Deduplicate**: same issue at the same location is reported once using `{file}:{line}:{title}` as key
+- **Severity-ranked**: findings sorted Critical > High > Medium > Low
+- **Verdict-driven**: clear PASS/FAIL/PASS_WITH_WARNINGS drives automation decisions
+
+## Input
+
+- List of task spec files that were just implemented (paths to `[JIRA-ID]_[short_name].md`)
+- Changed files (detected via `git diff` or provided by the `/implement` skill)
+- Project context: `_docs/00_problem/restrictions.md`, `_docs/01_solution/solution.md`
+
+## Phase 1: Context Loading
+
+Before reviewing code, build understanding of intent:
+
+1. Read each task spec — acceptance criteria, scope, constraints, dependencies
+2. Read project restrictions and solution overview
+3. Map which changed files correspond to which task specs
+4. Understand what the code is supposed to do before judging how it does it
+
+## Phase 2: Spec Compliance Review
+
+For each task, verify implementation satisfies every acceptance criterion:
+
+- Walk through each AC (Given/When/Then) and trace it in the code
+- Check that unit tests cover each AC
+- Check that blackbox tests exist where specified in the task spec
+- Flag any AC that is not demonstrably satisfied as a **Spec-Gap** finding (severity: High)
+- Flag any scope creep (implementation beyond what the spec asked for) as a **Scope** finding (severity: Low)
+
+## Phase 3: Code Quality Review
+
+Check implemented code against quality standards:
+
+- **SOLID principles** — single responsibility, open/closed, Liskov, interface segregation, dependency inversion
+- **Error handling** — consistent strategy, no bare catch/except, meaningful error messages
+- **Naming** — clear intent, follows project conventions
+- **Complexity** — functions longer than 50 lines or cyclomatic complexity > 10
+- **DRY** — duplicated logic across files
+- **Test quality** — tests assert meaningful behavior, not just "no error thrown"
+- **Dead code** — unused imports, unreachable branches
+
+## Phase 4: Security Quick-Scan
+
+Lightweight security checks (defer deep analysis to the `/security` skill):
+
+- SQL injection via string interpolation
+- Command injection (subprocess with shell=True, exec, eval)
+- Hardcoded secrets, API keys, passwords
+- Missing input validation on external inputs
+- Sensitive data in logs or error messages
+- Insecure deserialization
+
+## Phase 5: Performance Scan
+
+Check for common performance anti-patterns:
+
+- O(n^2) or worse algorithms where O(n) is possible
+- N+1 query patterns
+- Unbounded data fetching (missing pagination/limits)
+- Blocking I/O in async contexts
+- Unnecessary memory copies or allocations in hot paths
+
+## Phase 6: Cross-Task Consistency
+
+When multiple tasks were implemented in the same batch:
+
+- Interfaces between tasks are compatible (method signatures, DTOs match)
+- No conflicting patterns (e.g., one task uses repository pattern, another does raw SQL)
+- Shared code is not duplicated across task implementations
+- Dependencies declared in task specs are properly wired
+
+## Output Format
+
+Produce a structured report with findings deduplicated and sorted by severity:
+
+```markdown
+# Code Review Report
+
+**Batch**: [task list]
+**Date**: [YYYY-MM-DD]
+**Verdict**: PASS | PASS_WITH_WARNINGS | FAIL
+
+## Findings
+
+| # | Severity | Category | File:Line | Title |
+|---|----------|----------|-----------|-------|
+| 1 | Critical | Security | src/api/auth.py:42 | SQL injection via f-string |
+| 2 | High | Spec-Gap | src/service/orders.py | AC-3 not satisfied |
+
+### Finding Details
+
+**F1: SQL injection via f-string** (Critical / Security)
+- Location: `src/api/auth.py:42`
+- Description: User input interpolated directly into SQL query
+- Suggestion: Use parameterized query via bind parameters
+- Task: 04_auth_service
+
+**F2: AC-3 not satisfied** (High / Spec-Gap)
+- Location: `src/service/orders.py`
+- Description: AC-3 requires order total recalculation on item removal, but no such logic exists
+- Suggestion: Add recalculation in remove_item() method
+- Task: 07_order_processing
+```
+
+## Severity Definitions
+
+| Severity | Meaning | Blocks? |
+|----------|---------|---------|
+| Critical | Security vulnerability, data loss, crash | Yes — verdict FAIL |
+| High | Spec gap, logic bug, broken test | Yes — verdict FAIL |
+| Medium | Performance issue, maintainability concern, missing validation | No — verdict PASS_WITH_WARNINGS |
+| Low | Style, minor improvement, scope creep | No — verdict PASS_WITH_WARNINGS |
+
+## Category Values
+
+Bug, Spec-Gap, Security, Performance, Maintainability, Style, Scope
+
+## Verdict Logic
+
+- **FAIL**: any Critical or High finding exists
+- **PASS_WITH_WARNINGS**: only Medium or Low findings
+- **PASS**: no findings
+
+## Integration with /implement
+
+The `/implement` skill invokes this skill after each batch completes:
+
+1. Collects changed files from all implementer agents in the batch
+2. Passes task spec paths + changed files to this skill
+3. If verdict is FAIL — presents findings to user (BLOCKING), user fixes or confirms
+4. If verdict is PASS or PASS_WITH_WARNINGS — proceeds automatically (findings shown as info)
+
+## Integration Contract
+
+### Inputs (provided by the implement skill)
+
+| Input | Type | Source | Required |
+|-------|------|--------|----------|
+| `task_specs` | list of file paths | Task `.md` files from `_docs/02_tasks/` for the current batch | Yes |
+| `changed_files` | list of file paths | Files modified by implementer agents (from `git diff` or agent reports) | Yes |
+| `batch_number` | integer | Current batch number (for report naming) | Yes |
+| `project_restrictions` | file path | `_docs/00_problem/restrictions.md` | If exists |
+| `solution_overview` | file path | `_docs/01_solution/solution.md` | If exists |
+
+### Invocation Pattern
+
+The implement skill invokes code-review by:
+
+1. Reading `.cursor/skills/code-review/SKILL.md`
+2. Providing the inputs above as context (read the files, pass content to the review phases)
+3. Executing all 6 phases sequentially
+4. Consuming the verdict from the output
+
+### Outputs (returned to the implement skill)
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `verdict` | `PASS` / `PASS_WITH_WARNINGS` / `FAIL` | Drives the implement skill's auto-fix gate |
+| `findings` | structured list | Each finding has: severity, category, file:line, title, description, suggestion, task reference |
+| `critical_count` | integer | Number of Critical findings |
+| `high_count` | integer | Number of High findings |
+| `report_path` | file path | `_docs/03_implementation/reviews/batch_[NN]_review.md` |
+
+### Report Persistence
+
+Save the review report to `_docs/03_implementation/reviews/batch_[NN]_review.md` (create the `reviews/` directory if it does not exist). The report uses the Output Format defined above.
+
+The implement skill uses `verdict` to decide:
+- `PASS` / `PASS_WITH_WARNINGS` → proceed to commit
+- `FAIL` → enter auto-fix loop (up to 2 attempts), then escalate to user

.cursor/skills/decompose/SKILL.md

@@ -1,25 +1,30 @@
 ---
 name: decompose
 description: |
-  Decompose planned components into atomic implementable features with bootstrap structure plan.
+  Decompose planned components into atomic implementable tasks with bootstrap structure plan.
-  4-step workflow: bootstrap structure plan, feature decomposition, cross-component verification, and Jira task creation.
+  4-step workflow: bootstrap structure plan, component task decomposition, blackbox test task decomposition, and cross-task verification.
-  Supports project mode (_docs/ structure), single component mode, and standalone mode (@file.md).
+  Supports full decomposition (_docs/ structure), single component mode, and tests-only mode.
   Trigger phrases:
   - "decompose", "decompose features", "feature decomposition"
   - "task decomposition", "break down components"
   - "prepare for implementation"
+  - "decompose tests", "test decomposition"
+category: build
+tags: [decomposition, tasks, dependencies, jira, implementation-prep]
 disable-model-invocation: true
 ---
 
-# Feature Decomposition
+# Task Decomposition
 
-Decompose planned components into atomic, implementable feature specs with a bootstrap structure plan through a systematic workflow.
+Decompose planned components into atomic, implementable task specs with a bootstrap structure plan through a systematic workflow. All tasks are named with their Jira ticket ID prefix in a flat directory.
 
 ## Core Principles
 
-- **Atomic features**: each feature does one thing; if it exceeds 5 complexity points, split it
+- **Atomic tasks**: each task does one thing; if it exceeds 5 complexity points, split it
 - **Behavioral specs, not implementation plans**: describe what the system should do, not how to build it
-- **Save immediately**: write artifacts to disk after each component; never accumulate unsaved work
+- **Flat structure**: all tasks are Jira-ID-prefixed files in TASKS_DIR — no component subdirectories
+- **Save immediately**: write artifacts to disk after each task; never accumulate unsaved work
+- **Jira inline**: create Jira ticket immediately after writing each task file
 - **Ask, don't assume**: when requirements are ambiguous, ask the user before proceeding
 - **Plan, don't code**: this workflow produces documents and Jira tasks, never implementation code
 
@@ -27,27 +32,26 @@ Decompose planned components into atomic, implementable feature specs with a boo
 
 Determine the operating mode based on invocation before any other logic runs.
 
-**Full project mode** (no explicit input file provided):
+**Default** (no explicit input file provided):
-- PLANS_DIR: `_docs/02_plans/`
+- DOCUMENT_DIR: `_docs/02_document/`
 - TASKS_DIR: `_docs/02_tasks/`
-- Reads from: `_docs/00_problem/`, `_docs/01_solution/`, PLANS_DIR
+- Reads from: `_docs/00_problem/`, `_docs/01_solution/`, DOCUMENT_DIR
-- Runs Step 1 (bootstrap) + Step 2 (all components) + Step 3 (cross-verification) + Step 4 (Jira)
+- Runs Step 1 (bootstrap) + Step 2 (all components) + Step 3 (blackbox tests) + Step 4 (cross-verification)
 
-**Single component mode** (provided file is within `_docs/02_plans/` and inside a `components/` subdirectory):
+**Single component mode** (provided file is within `_docs/02_document/` and inside a `components/` subdirectory):
-- PLANS_DIR: `_docs/02_plans/`
+- DOCUMENT_DIR: `_docs/02_document/`
 - TASKS_DIR: `_docs/02_tasks/`
-- Derive `<topic>`, component number, and component name from the file path
+- Derive component number and component name from the file path
 - Ask user for the parent Epic ID
-- Runs Step 2 (that component only) + Step 4 (Jira)
+- Runs Step 2 (that component only, appending to existing task numbering)
-- Overwrites existing feature files in that component's TASKS_DIR subdirectory
 
-**Standalone mode** (explicit input file provided, not within `_docs/02_plans/`):
+**Tests-only mode** (provided file/directory is within `tests/`, or `DOCUMENT_DIR/tests/` exists and input explicitly requests test decomposition):
-- INPUT_FILE: the provided file (treated as a component spec)
+- DOCUMENT_DIR: `_docs/02_document/`
-- Derive `<topic>` from the input filename (without extension)
+- TASKS_DIR: `_docs/02_tasks/`
-- TASKS_DIR: `_standalone/<topic>/tasks/`
+- TESTS_DIR: `DOCUMENT_DIR/tests/`
-- Guardrails relaxed: only INPUT_FILE must exist and be non-empty
+- Reads from: `_docs/00_problem/`, `_docs/01_solution/`, TESTS_DIR
-- Ask user for the parent Epic ID
+- Runs Step 1t (test infrastructure bootstrap) + Step 3 (blackbox test decomposition) + Step 4 (cross-verification against test coverage)
-- Runs Step 2 (that component only) + Step 4 (Jira)
+- Skips Step 1 (project bootstrap) and Step 2 (component decomposition) — the codebase already exists
 
 Announce the detected mode and resolved paths to the user before proceeding.
 
@@ -55,17 +59,18 @@ Announce the detected mode and resolved paths to the user before proceeding.
 
 ### Required Files
 
-**Full project mode:**
+**Default:**
 
 | File | Purpose |
 |------|---------|
 | `_docs/00_problem/problem.md` | Problem description and context |
-| `_docs/00_problem/restrictions.md` | Constraints and limitations (if available) |
+| `_docs/00_problem/restrictions.md` | Constraints and limitations |
-| `_docs/00_problem/acceptance_criteria.md` | Measurable acceptance criteria (if available) |
+| `_docs/00_problem/acceptance_criteria.md` | Measurable acceptance criteria |
 | `_docs/01_solution/solution.md` | Finalized solution |
-| `PLANS_DIR/<topic>/architecture.md` | Architecture from plan skill |
+| `DOCUMENT_DIR/architecture.md` | Architecture from plan skill |
-| `PLANS_DIR/<topic>/system-flows.md` | System flows from plan skill |
+| `DOCUMENT_DIR/system-flows.md` | System flows from plan skill |
-| `PLANS_DIR/<topic>/components/[##]_[name]/description.md` | Component specs from plan skill |
+| `DOCUMENT_DIR/components/[##]_[name]/description.md` | Component specs from plan skill |
+| `DOCUMENT_DIR/tests/` | Blackbox test specs from plan skill |
 
 **Single component mode:**
 
@@ -74,64 +79,70 @@ Announce the detected mode and resolved paths to the user before proceeding.
 | The provided component `description.md` | Component spec to decompose |
 | Corresponding `tests.md` in the same directory (if available) | Test specs for context |
 
-**Standalone mode:**
+**Tests-only mode:**
 
 | File | Purpose |
 |------|---------|
-| INPUT_FILE (the provided file) | Component spec to decompose |
+| `TESTS_DIR/environment.md` | Test environment specification (Docker services, networks, volumes) |
+| `TESTS_DIR/test-data.md` | Test data management (seed data, mocks, isolation) |
+| `TESTS_DIR/blackbox-tests.md` | Blackbox functional scenarios (positive + negative) |
+| `TESTS_DIR/performance-tests.md` | Performance test scenarios |
+| `TESTS_DIR/resilience-tests.md` | Resilience test scenarios |
+| `TESTS_DIR/security-tests.md` | Security test scenarios |
+| `TESTS_DIR/resource-limit-tests.md` | Resource limit test scenarios |
+| `TESTS_DIR/traceability-matrix.md` | AC/restriction coverage mapping |
+| `_docs/00_problem/problem.md` | Problem context |
+| `_docs/00_problem/restrictions.md` | Constraints for test design |
+| `_docs/00_problem/acceptance_criteria.md` | Acceptance criteria being verified |
 
 ### Prerequisite Checks (BLOCKING)
 
-**Full project mode:**
+**Default:**
-1. At least one `<topic>/` directory exists under PLANS_DIR with `architecture.md` and `components/` — **STOP if missing**
+1. DOCUMENT_DIR contains `architecture.md` and `components/` — **STOP if missing**
-2. If multiple topics exist, ask user which one to decompose
+2. Create TASKS_DIR if it does not exist
-3. Create TASKS_DIR if it does not exist
+3. If TASKS_DIR already contains task files, ask user: **resume from last checkpoint or start fresh?**
-4. If `TASKS_DIR/<topic>/` already exists, ask user: **resume from last checkpoint or start fresh?**
 
 **Single component mode:**
 1. The provided component file exists and is non-empty — **STOP if missing**
-2. Create the component's subdirectory under TASKS_DIR if it does not exist
 
-**Standalone mode:**
+**Tests-only mode:**
-1. INPUT_FILE exists and is non-empty — **STOP if missing**
+1. `TESTS_DIR/blackbox-tests.md` exists and is non-empty — **STOP if missing**
-2. Create TASKS_DIR if it does not exist
+2. `TESTS_DIR/environment.md` exists — **STOP if missing**
+3. Create TASKS_DIR if it does not exist
+4. If TASKS_DIR already contains task files, ask user: **resume from last checkpoint or start fresh?**
 
 ## Artifact Management
 
 ### Directory Structure
 
 ```
-TASKS_DIR/<topic>/
+TASKS_DIR/
-├── initial_structure.md                        (Step 1, full mode only)
+├── [JIRA-ID]_initial_structure.md
-├── cross_dependencies.md                       (Step 3, full mode only)
+├── [JIRA-ID]_[short_name].md
-├── SUMMARY.md                                  (final)
+├── [JIRA-ID]_[short_name].md
-├── [##]_[component_name]/
+├── ...
-│   ├── [##].[##]_feature_[feature_name].md
+└── _dependencies_table.md
-│   ├── [##].[##]_feature_[feature_name].md
-│   └── ...
-├── [##]_[component_name]/
-│   └── ...
-└── ...
 ```
 
+**Naming convention**: Each task file is initially saved with a temporary numeric prefix (`[##]_[short_name].md`). After creating the Jira ticket, rename the file to use the Jira ticket ID as prefix (`[JIRA-ID]_[short_name].md`). For example: `01_initial_structure.md` → `AZ-42_initial_structure.md`.
+
 ### Save Timing
 
 | Step | Save immediately after | Filename |
 |------|------------------------|----------|
-| Step 1 | Bootstrap structure plan complete | `initial_structure.md` |
+| Step 1 | Bootstrap structure plan complete + Jira ticket created + file renamed | `[JIRA-ID]_initial_structure.md` |
-| Step 2 | Each component decomposed | `[##]_[name]/[##].[##]_feature_[feature_name].md` |
+| Step 1t | Test infrastructure bootstrap complete + Jira ticket created + file renamed | `[JIRA-ID]_test_infrastructure.md` |
-| Step 3 | Cross-component verification complete | `cross_dependencies.md` |
+| Step 2 | Each component task decomposed + Jira ticket created + file renamed | `[JIRA-ID]_[short_name].md` |
-| Step 4 | Jira tasks created | Jira via MCP |
+| Step 3 | Each blackbox test task decomposed + Jira ticket created + file renamed | `[JIRA-ID]_[short_name].md` |
-| Final | All steps complete | `SUMMARY.md` |
+| Step 4 | Cross-task verification complete | `_dependencies_table.md` |
 
 ### Resumability
 
-If `TASKS_DIR/<topic>/` already contains artifacts:
+If TASKS_DIR already contains task files:
 
-1. List existing files and match them to the save timing table
+1. List existing `*_*.md` files (excluding `_dependencies_table.md`) and count them
-2. Identify the last completed component based on which feature files exist
+2. Resume numbering from the next number (for temporary numeric prefix before Jira rename)
-3. Resume from the next incomplete component
+3. Inform the user which tasks already exist and are being skipped
-4. Inform the user which components are being skipped
 
 ## Progress Tracking
 
@@ -139,143 +150,240 @@ At the start of execution, create a TodoWrite with all applicable steps. Update
 
 ## Workflow
 
-### Step 1: Bootstrap Structure Plan (full project mode only)
+### Step 1t: Test Infrastructure Bootstrap (tests-only mode only)
+
+**Role**: Professional Quality Assurance Engineer
+**Goal**: Produce `01_test_infrastructure.md` — the first task describing the test project scaffold
+**Constraints**: This is a plan document, not code. The `/implement` skill executes it.
+
+1. Read `TESTS_DIR/environment.md` and `TESTS_DIR/test-data.md`
+2. Read problem.md, restrictions.md, acceptance_criteria.md for domain context
+3. Document the test infrastructure plan using `templates/test-infrastructure-task.md`
+
+The test infrastructure bootstrap must include:
+- Test project folder layout (`e2e/` directory structure)
+- Mock/stub service definitions for each external dependency
+- `docker-compose.test.yml` structure from environment.md
+- Test runner configuration (framework, plugins, fixtures)
+- Test data fixture setup from test-data.md seed data sets
+- Test reporting configuration (format, output path)
+- Data isolation strategy
+
+**Self-verification**:
+- [ ] Every external dependency from environment.md has a mock service defined
+- [ ] Docker Compose structure covers all services from environment.md
+- [ ] Test data fixtures cover all seed data sets from test-data.md
+- [ ] Test runner configuration matches the consumer app tech stack from environment.md
+- [ ] Data isolation strategy is defined
+
+**Save action**: Write `01_test_infrastructure.md` (temporary numeric name)
+
+**Jira action**: Create a Jira ticket for this task under the "Blackbox Tests" epic. Write the Jira ticket ID and Epic ID back into the task header.
+
+**Rename action**: Rename the file from `01_test_infrastructure.md` to `[JIRA-ID]_test_infrastructure.md`. Update the **Task** field inside the file to match the new filename.
+
+**BLOCKING**: Present test infrastructure plan summary to user. Do NOT proceed until user confirms.
+
+---
+
+### Step 1: Bootstrap Structure Plan (default mode only)
 
 **Role**: Professional software architect
-**Goal**: Produce `initial_structure.md` describing the project skeleton for implementation
+**Goal**: Produce `01_initial_structure.md` — the first task describing the project skeleton
-**Constraints**: This is a plan document, not code. The `implement-initial` command executes it.
+**Constraints**: This is a plan document, not code. The `/implement` skill executes it.
 
-1. Read architecture.md, all component specs, and system-flows.md from PLANS_DIR
+1. Read architecture.md, all component specs, system-flows.md, data_model.md, and `deployment/` from DOCUMENT_DIR
 2. Read problem, solution, and restrictions from `_docs/00_problem/` and `_docs/01_solution/`
 3. Research best implementation patterns for the identified tech stack
-4. Document the structure plan using `templates/initial-structure.md`
+4. Document the structure plan using `templates/initial-structure-task.md`
+
+The bootstrap structure plan must include:
+- Project folder layout with all component directories
+- Shared models, interfaces, and DTOs
+- Dockerfile per component (multi-stage, non-root, health checks, pinned base images)
+- `docker-compose.yml` for local development (all components + database + dependencies)
+- `docker-compose.test.yml` for blackbox test environment (blackbox test runner)
+- `.dockerignore`
+- CI/CD pipeline file (`.github/workflows/ci.yml` or `azure-pipelines.yml`) with stages from `deployment/ci_cd_pipeline.md`
+- Database migration setup and initial seed data scripts
+- Observability configuration: structured logging setup, health check endpoints (`/health/live`, `/health/ready`), metrics endpoint (`/metrics`)
+- Environment variable documentation (`.env.example`)
+- Test structure with unit and blackbox test locations
 
 **Self-verification**:
 - [ ] All components have corresponding folders in the layout
 - [ ] All inter-component interfaces have DTOs defined
-- [ ] CI/CD stages cover build, lint, test, security, deploy
+- [ ] Dockerfile defined for each component
+- [ ] `docker-compose.yml` covers all components and dependencies
+- [ ] `docker-compose.test.yml` enables blackbox testing
+- [ ] CI/CD pipeline file defined with lint, test, security, build, deploy stages
+- [ ] Database migration setup included
+- [ ] Health check endpoints specified for each service
+- [ ] Structured logging configuration included
+- [ ] `.env.example` with all required environment variables
 - [ ] Environment strategy covers dev, staging, production
-- [ ] Test structure includes unit and integration test locations
+- [ ] Test structure includes unit and blackbox test locations
 
-**Save action**: Write `initial_structure.md`
+**Save action**: Write `01_initial_structure.md` (temporary numeric name)
+
+**Jira action**: Create a Jira ticket for this task under the "Bootstrap & Initial Structure" epic. Write the Jira ticket ID and Epic ID back into the task header.
+
+**Rename action**: Rename the file from `01_initial_structure.md` to `[JIRA-ID]_initial_structure.md` (e.g., `AZ-42_initial_structure.md`). Update the **Task** field inside the file to match the new filename.
 
 **BLOCKING**: Present structure plan summary to user. Do NOT proceed until user confirms.
 
 ---
 
-### Step 2: Feature Decomposition (all modes)
+### Step 2: Task Decomposition (default and single component modes)
 
 **Role**: Professional software architect
-**Goal**: Decompose each component into atomic, implementable feature specs
+**Goal**: Decompose each component into atomic, implementable task specs — numbered sequentially starting from 02
 **Constraints**: Behavioral specs only — describe what, not how. No implementation code.
 
+**Numbering**: Tasks are numbered sequentially across all components in dependency order. Start from 02 (01 is initial_structure). In single component mode, start from the next available number in TASKS_DIR.
+
+**Component ordering**: Process components in dependency order — foundational components first (shared models, database), then components that depend on them.
+
 For each component (or the single provided component):
 
 1. Read the component's `description.md` and `tests.md` (if available)
-2. Decompose into atomic features; create only 1 feature if the component is simple or atomic
+2. Decompose into atomic tasks; create only 1 task if the component is simple or atomic
-3. Split into multiple features only when it is necessary and would be easier to implement
+3. Split into multiple tasks only when it is necessary and would be easier to implement
-4. Do not create features of other components — only features of the current component
+4. Do not create tasks for other components — only tasks for the current component
-5. Each feature should be atomic, containing 0 APIs or a list of semantically connected APIs
+5. Each task should be atomic, containing 0 APIs or a list of semantically connected APIs
-6. Write each feature spec using `templates/feature-spec.md`
+6. Write each task spec using `templates/task.md`
-7. Estimate complexity per feature (1, 2, 3, 5 points); no feature should exceed 5 points — split if it does
+7. Estimate complexity per task (1, 2, 3, 5 points); no task should exceed 5 points — split if it does
-8. Note feature dependencies (within component and cross-component)
+8. Note task dependencies (referencing Jira IDs of already-created dependency tasks, e.g., `AZ-42_initial_structure`)
+9. **Immediately after writing each task file**: create a Jira ticket, link it to the component's epic, write the Jira ticket ID and Epic ID back into the task header, then rename the file from `[##]_[short_name].md` to `[JIRA-ID]_[short_name].md`.
 
 **Self-verification** (per component):
-- [ ] Every feature is atomic (single concern)
+- [ ] Every task is atomic (single concern)
-- [ ] No feature exceeds 5 complexity points
+- [ ] No task exceeds 5 complexity points
-- [ ] Feature dependencies are noted
+- [ ] Task dependencies reference correct Jira IDs
-- [ ] Features cover all interfaces defined in the component spec
+- [ ] Tasks cover all interfaces defined in the component spec
-- [ ] No features duplicate work from other components
+- [ ] No tasks duplicate work from other components
+- [ ] Every task has a Jira ticket linked to the correct epic
 
-**Save action**: Write each `[##]_[name]/[##].[##]_feature_[feature_name].md`
+**Save action**: Write each `[##]_[short_name].md` (temporary numeric name), create Jira ticket inline, then rename the file to `[JIRA-ID]_[short_name].md`. Update the **Task** field inside the file to match the new filename. Update **Dependencies** references in the file to use Jira IDs of the dependency tasks.
 
 ---
 
-### Step 3: Cross-Component Verification (full project mode only)
+### Step 3: Blackbox Test Task Decomposition (default and tests-only modes)
+
+**Role**: Professional Quality Assurance Engineer
+**Goal**: Decompose blackbox test specs into atomic, implementable task specs
+**Constraints**: Behavioral specs only — describe what, not how. No test code.
+
+**Numbering**:
+- In default mode: continue sequential numbering from where Step 2 left off.
+- In tests-only mode: start from 02 (01 is the test infrastructure bootstrap from Step 1t).
+
+1. Read all test specs from `DOCUMENT_DIR/tests/` (`blackbox-tests.md`, `performance-tests.md`, `resilience-tests.md`, `security-tests.md`, `resource-limit-tests.md`)
+2. Group related test scenarios into atomic tasks (e.g., one task per test category or per component under test)
+3. Each task should reference the specific test scenarios it implements and the environment/test-data specs
+4. Dependencies:
+   - In default mode: blackbox test tasks depend on the component implementation tasks they exercise
+   - In tests-only mode: blackbox test tasks depend on the test infrastructure bootstrap task (Step 1t)
+5. Write each task spec using `templates/task.md`
+6. Estimate complexity per task (1, 2, 3, 5 points); no task should exceed 5 points — split if it does
+7. Note task dependencies (referencing Jira IDs of already-created dependency tasks)
+8. **Immediately after writing each task file**: create a Jira ticket under the "Blackbox Tests" epic, write the Jira ticket ID and Epic ID back into the task header, then rename the file from `[##]_[short_name].md` to `[JIRA-ID]_[short_name].md`.
+
+**Self-verification**:
+- [ ] Every scenario from `tests/blackbox-tests.md` is covered by a task
+- [ ] Every scenario from `tests/performance-tests.md`, `tests/resilience-tests.md`, `tests/security-tests.md`, and `tests/resource-limit-tests.md` is covered by a task
+- [ ] No task exceeds 5 complexity points
+- [ ] Dependencies correctly reference the dependency tasks (component tasks in default mode, test infrastructure in tests-only mode)
+- [ ] Every task has a Jira ticket linked to the "Blackbox Tests" epic
+
+**Save action**: Write each `[##]_[short_name].md` (temporary numeric name), create Jira ticket inline, then rename to `[JIRA-ID]_[short_name].md`.
+
+---
+
+### Step 4: Cross-Task Verification (default and tests-only modes)
 
 **Role**: Professional software architect and analyst
-**Goal**: Verify feature consistency across all components
+**Goal**: Verify task consistency and produce `_dependencies_table.md`
-**Constraints**: Review step — fix gaps found, do not add new features
+**Constraints**: Review step — fix gaps found, do not add new tasks
 
-1. Verify feature dependencies across all components are consistent
+1. Verify task dependencies across all tasks are consistent
-2. Check no gaps: every interface in architecture.md has features covering it
+2. Check no gaps:
-3. Check no overlaps: features don't duplicate work across components
+   - In default mode: every interface in architecture.md has tasks covering it
-4. Produce dependency matrix showing cross-component feature dependencies
+   - In tests-only mode: every test scenario in `traceability-matrix.md` is covered by a task
-5. Determine recommended implementation order based on dependencies
+3. Check no overlaps: tasks don't duplicate work
+4. Check no circular dependencies in the task graph
+5. Produce `_dependencies_table.md` using `templates/dependencies-table.md`
 
 **Self-verification**:
-- [ ] Every architecture interface is covered by at least one feature
-- [ ] No circular feature dependencies across components
-- [ ] Cross-component dependencies are explicitly noted in affected feature specs
 
-**Save action**: Write `cross_dependencies.md`
+Default mode:
+- [ ] Every architecture interface is covered by at least one task
+- [ ] No circular dependencies in the task graph
+- [ ] Cross-component dependencies are explicitly noted in affected task specs
+- [ ] `_dependencies_table.md` contains every task with correct dependencies
 
-**BLOCKING**: Present cross-component summary to user. Do NOT proceed until user confirms.
+Tests-only mode:
+- [ ] Every test scenario from traceability-matrix.md "Covered" entries has a corresponding task
+- [ ] No circular dependencies in the task graph
+- [ ] Test task dependencies reference the test infrastructure bootstrap
+- [ ] `_dependencies_table.md` contains every task with correct dependencies
+
+**Save action**: Write `_dependencies_table.md`
+
+**BLOCKING**: Present dependency summary to user. Do NOT proceed until user confirms.
 
 ---
 
-### Step 4: Jira Tasks (all modes)
-
-**Role**: Professional product manager
-**Goal**: Create Jira tasks from feature specs under the appropriate parent epics
-**Constraints**: Be concise — fewer words with the same meaning is better
-
-1. For each feature spec, create a Jira task following the parsing rules and field mapping from `gen_jira_task_and_branch.md` (skip branch creation and file renaming — those happen during implementation)
-2. In full mode: search Jira for epics matching component names/labels to find parent epic IDs
-3. In single component mode: use the Epic ID obtained during context resolution
-4. In standalone mode: use the Epic ID obtained during context resolution
-5. Do NOT create git branches or rename files — that happens during implementation
-
-**Self-verification**:
-- [ ] Every feature has a corresponding Jira task
-- [ ] Every task is linked to the correct parent epic
-- [ ] Task descriptions match feature spec content
-
-**Save action**: Jira tasks created via MCP
-
----
-
-## Summary Report
-
-After all steps complete, write `SUMMARY.md` using `templates/summary.md` as structure.
-
 ## Common Mistakes
 
 - **Coding during decomposition**: this workflow produces specs, never code
-- **Over-splitting**: don't create many features if the component is simple — 1 feature is fine
+- **Over-splitting**: don't create many tasks if the component is simple — 1 task is fine
-- **Features exceeding 5 points**: split them; no feature should be too complex for a single task
+- **Tasks exceeding 5 points**: split them; no task should be too complex for a single implementer
-- **Cross-component features**: each feature belongs to exactly one component
+- **Cross-component tasks**: each task belongs to exactly one component
 - **Skipping BLOCKING gates**: never proceed past a BLOCKING marker without user confirmation
 - **Creating git branches**: branch creation is an implementation concern, not a decomposition one
+- **Creating component subdirectories**: all tasks go flat in TASKS_DIR
+- **Forgetting Jira**: every task must have a Jira ticket created inline — do not defer to a separate step
+- **Forgetting to rename**: after Jira ticket creation, always rename the file from numeric prefix to Jira ID prefix
 
 ## Escalation Rules
 
 | Situation | Action |
 |-----------|--------|
 | Ambiguous component boundaries | ASK user |
-| Feature complexity exceeds 5 points after splitting | ASK user |
+| Task complexity exceeds 5 points after splitting | ASK user |
-| Missing component specs in PLANS_DIR | ASK user |
+| Missing component specs in DOCUMENT_DIR | ASK user |
 | Cross-component dependency conflict | ASK user |
 | Jira epic not found for a component | ASK user for Epic ID |
-| Component naming | PROCEED, confirm at next BLOCKING gate |
+| Task naming | PROCEED, confirm at next BLOCKING gate |
 
 ## Methodology Quick Reference
 
 ```
 ┌────────────────────────────────────────────────────────────────┐
-│            Feature Decomposition (4-Step Method)               │
+│          Task Decomposition (Multi-Mode)                        │
 ├────────────────────────────────────────────────────────────────┤
-│ CONTEXT: Resolve mode (full / single component / standalone)   │
+│ CONTEXT: Resolve mode (default / single component / tests-only)│
-│ 1. Bootstrap Structure  → initial_structure.md (full only)     │
+│                                                                │
+│ DEFAULT MODE:                                                   │
+│  1.  Bootstrap Structure  → [JIRA-ID]_initial_structure.md     │
 │      [BLOCKING: user confirms structure]                       │
-│ 2. Feature Decompose    → [##]_[name]/[##].[##]_feature_*     │
+│  2.  Component Tasks      → [JIRA-ID]_[short_name].md each    │
-│ 3. Cross-Verification   → cross_dependencies.md (full only)   │
+│  3.  Blackbox Tests       → [JIRA-ID]_[short_name].md each    │
+│  4.  Cross-Verification   → _dependencies_table.md            │
 │      [BLOCKING: user confirms dependencies]                    │
-│ 4. Jira Tasks           → Jira via MCP                        │
+│                                                                │
-│    ─────────────────────────────────────────────────           │
+│ TESTS-ONLY MODE:                                                │
-│    Summary → SUMMARY.md                                        │
+│  1t. Test Infrastructure  → [JIRA-ID]_test_infrastructure.md   │
+│      [BLOCKING: user confirms test scaffold]                   │
+│  3.  Blackbox Tests       → [JIRA-ID]_[short_name].md each    │
+│  4.  Cross-Verification   → _dependencies_table.md            │
+│      [BLOCKING: user confirms dependencies]                    │
+│                                                                │
+│ SINGLE COMPONENT MODE:                                          │
+│  2.  Component Tasks      → [JIRA-ID]_[short_name].md each    │
 ├────────────────────────────────────────────────────────────────┤
-│ Principles: Atomic features · Behavioral specs · Save now      │
+│ Principles: Atomic tasks · Behavioral specs · Flat structure   │
-│             Ask don't assume · Plan don't code                 │
+│   Jira inline · Rename to Jira ID · Save now · Ask don't assume│
 └────────────────────────────────────────────────────────────────┘
 ```

.cursor/skills/decompose/templates/dependencies-table.md

@@ -0,0 +1,31 @@
+# Dependencies Table Template
+
+Use this template after cross-task verification. Save as `TASKS_DIR/_dependencies_table.md`.
+
+---
+
+```markdown
+# Dependencies Table
+
+**Date**: [YYYY-MM-DD]
+**Total Tasks**: [N]
+**Total Complexity Points**: [N]
+
+| Task | Name | Complexity | Dependencies | Epic |
+|------|------|-----------|-------------|------|
+| [JIRA-ID] | initial_structure | [points] | None | [EPIC-ID] |
+| [JIRA-ID] | [short_name] | [points] | [JIRA-ID] | [EPIC-ID] |
+| [JIRA-ID] | [short_name] | [points] | [JIRA-ID] | [EPIC-ID] |
+| [JIRA-ID] | [short_name] | [points] | [JIRA-ID], [JIRA-ID] | [EPIC-ID] |
+| ... | ... | ... | ... | ... |
+```
+
+---
+
+## Guidelines
+
+- Every task from TASKS_DIR must appear in this table
+- Dependencies column lists Jira IDs (e.g., "AZ-43, AZ-44") or "None"
+- No circular dependencies allowed
+- Tasks should be listed in recommended execution order
+- The `/implement` skill reads this table to compute parallel batches

.cursor/skills/decompose/templates/initial-structure-task.md

@@ -1,15 +1,20 @@
-# Initial Structure Plan Template
+# Initial Structure Task Template
 
-Use this template for the bootstrap structure plan. Save as `TASKS_DIR/<topic>/initial_structure.md`.
+Use this template for the bootstrap structure plan. Save as `TASKS_DIR/01_initial_structure.md` initially, then rename to `TASKS_DIR/[JIRA-ID]_initial_structure.md` after Jira ticket creation.
 
 ---
 
 ```markdown
-# Initial Project Structure Plan
+# Initial Project Structure
 
-**Date**: [YYYY-MM-DD]
+**Task**: [JIRA-ID]_initial_structure
-**Tech Stack**: [language, framework, database, etc.]
+**Name**: Initial Structure
-**Source**: architecture.md, component specs from _docs/02_plans/<topic>/
+**Description**: Scaffold the project skeleton — folders, shared models, interfaces, stubs, CI/CD, DB migrations, test structure
+**Complexity**: [3|5] points
+**Dependencies**: None
+**Component**: Bootstrap
+**Jira**: [TASK-ID]
+**Epic**: [EPIC-ID]
 
 ## Project Folder Layout
 
@@ -35,7 +40,7 @@ project-root/
 
 | Component | Interface | Methods | Exposed To |
 |-----------|-----------|---------|-----------|
-| [##]_[name] | [InterfaceName] | [method list] | [consumers] |
+| [name] | [InterfaceName] | [method list] | [consumers] |
 
 ## CI/CD Pipeline
 
@@ -44,7 +49,7 @@ project-root/
 | Build | Compile/bundle the application | Every push |
 | Lint / Static Analysis | Code quality and style checks | Every push |
 | Unit Tests | Run unit test suite | Every push |
-| Integration Tests | Run integration test suite | Every push |
+| Blackbox Tests | Run blackbox test suite | Every push |
 | Security Scan | SAST / dependency check | Every push |
 | Deploy to Staging | Deploy to staging environment | Merge to staging branch |
 
@@ -97,16 +102,33 @@ tests/
 
 | Order | Component | Reason |
 |-------|-----------|--------|
-| 1 | [##]_[name] | [why first — foundational, no dependencies] |
+| 1 | [name] | [why first — foundational, no dependencies] |
-| 2 | [##]_[name] | [depends on #1] |
+| 2 | [name] | [depends on #1] |
 | ... | ... | ... |
+
+## Acceptance Criteria
+
+**AC-1: Project scaffolded**
+Given the structure plan above
+When the implementer executes this task
+Then all folders, stubs, and configuration files exist
+
+**AC-2: Tests runnable**
+Given the scaffolded project
+When the test suite is executed
+Then all stub tests pass (even if they only assert true)
+
+**AC-3: CI/CD configured**
+Given the scaffolded project
+When CI pipeline runs
+Then build, lint, and test stages complete successfully
 ```
 
 ---
 
 ## Guidance Notes
 
-- This is a PLAN document, not code. The `3.05_implement_initial_structure` command executes it.
+- This is a PLAN document, not code. The `/implement` skill executes it.
 - Focus on structure and organization decisions, not implementation details.
 - Reference component specs for interface and DTO details — don't repeat everything.
 - The folder layout should follow conventions of the identified tech stack.

.cursor/skills/decompose/templates/summary.md

@@ -1,59 +0,0 @@
-# Decomposition Summary Template
-
-Use this template after all steps complete. Save as `TASKS_DIR/<topic>/SUMMARY.md`.
-
----
-
-```markdown
-# Decomposition Summary
-
-**Date**: [YYYY-MM-DD]
-**Topic**: [topic name]
-**Total Components**: [N]
-**Total Features**: [N]
-**Total Complexity Points**: [N]
-
-## Component Breakdown
-
-| # | Component | Features | Total Points | Jira Epic |
-|---|-----------|----------|-------------|-----------|
-| 01 | [name] | [count] | [sum] | [EPIC-ID] |
-| 02 | [name] | [count] | [sum] | [EPIC-ID] |
-| ... | ... | ... | ... | ... |
-
-## Feature List
-
-| Component | Feature | Complexity | Jira Task | Dependencies |
-|-----------|---------|-----------|-----------|-------------|
-| [##]_[name] | [##].[##]_feature_[name] | [points] | [TASK-ID] | [deps or "None"] |
-| ... | ... | ... | ... | ... |
-
-## Implementation Order
-
-Recommended sequence based on dependency analysis:
-
-| Phase | Components / Features | Rationale |
-|-------|----------------------|-----------|
-| 1 | [list] | [foundational, no dependencies] |
-| 2 | [list] | [depends on phase 1] |
-| 3 | [list] | [depends on phase 1-2] |
-| ... | ... | ... |
-
-### Parallelization Opportunities
-
-[Features/components that can be implemented concurrently within each phase]
-
-## Cross-Component Dependencies
-
-| From (Feature) | To (Feature) | Dependency Type |
-|----------------|-------------|-----------------|
-| [comp.feature] | [comp.feature] | [data / API / event] |
-| ... | ... | ... |
-
-## Artifacts Produced
-
-- `initial_structure.md` — project skeleton plan
-- `cross_dependencies.md` — dependency matrix
-- `[##]_[name]/[##].[##]_feature_*.md` — feature specs per component
-- Jira tasks created under respective epics
-```

.cursor/skills/decompose/templates/task.md

@@ -1,17 +1,21 @@
-# Feature Specification Template
+# Task Specification Template
 
 Create a focused behavioral specification that describes **what** the system should do, not **how** it should be built.
-Save as `TASKS_DIR/<topic>/[##]_[component_name]/[##].[##]_feature_[feature_name].md`.
+Save as `TASKS_DIR/[##]_[short_name].md` initially, then rename to `TASKS_DIR/[JIRA-ID]_[short_name].md` after Jira ticket creation.
 
 ---
 
 ```markdown
 # [Feature Name]
 
-**Status**: Draft | **Date**: [YYYY-MM-DD] | **Feature**: [Brief Feature Description]
+**Task**: [JIRA-ID]_[short_name]
+**Name**: [short human name]
+**Description**: [one-line description of what this task delivers]
 **Complexity**: [1|2|3|5] points
-**Dependencies**: [List dependent features or "None"]
+**Dependencies**: [AZ-43_shared_models, AZ-44_db_migrations] or "None"
-**Component**: [##]_[component_name]
+**Component**: [component name for context]
+**Jira**: [TASK-ID]
+**Epic**: [EPIC-ID]
 
 ## Problem
 
@@ -21,11 +25,12 @@ Clear, concise statement of the problem users are facing.
 
 - Measurable or observable goal 1
 - Measurable or observable goal 2
+- ...
 
 ## Scope
 
 ### Included
-- What's in scope for this feature
+- What's in scope for this task
 
 ### Excluded
 - Explicitly what's NOT in scope
@@ -59,7 +64,7 @@ Then [expected result]
 |--------|-------------|-----------------|
 | AC-1 | [test subject] | [expected result] |
 
-## Integration Tests
+## Blackbox Tests
 
 | AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
 |--------|------------------------|-------------|-------------------|----------------|
@@ -86,7 +91,7 @@ Then [expected result]
 - 2 points: Non-trivial, low complexity, minimal coordination
 - 3 points: Multi-step, moderate complexity, potential alignment needed
 - 5 points: Difficult, interconnected logic, medium-high risk
-- 8 points: Too complex — split into smaller features
+- 8 points: Too complex — split into smaller tasks
 
 ## Output Guidelines
 
@@ -97,7 +102,7 @@ Then [expected result]
 - Include realistic scope boundaries
 - Write from the user's perspective
 - Include complexity estimation
-- Note dependencies on other features
+- Reference dependencies by Jira ID (e.g., AZ-43_shared_models)
 
 **DON'T:**
 - Include implementation details (file paths, classes, methods)

.cursor/skills/decompose/templates/test-infrastructure-task.md

@@ -0,0 +1,129 @@
+# Test Infrastructure Task Template
+
+Use this template for the test infrastructure bootstrap (Step 1t in tests-only mode). Save as `TASKS_DIR/01_test_infrastructure.md` initially, then rename to `TASKS_DIR/[JIRA-ID]_test_infrastructure.md` after Jira ticket creation.
+
+---
+
+```markdown
+# Test Infrastructure
+
+**Task**: [JIRA-ID]_test_infrastructure
+**Name**: Test Infrastructure
+**Description**: Scaffold the Blackbox test project — test runner, mock services, Docker test environment, test data fixtures, reporting
+**Complexity**: [3|5] points
+**Dependencies**: None
+**Component**: Blackbox Tests
+**Jira**: [TASK-ID]
+**Epic**: [EPIC-ID]
+
+## Test Project Folder Layout
+
+```
+e2e/
+├── conftest.py
+├── requirements.txt
+├── Dockerfile
+├── mocks/
+│   ├── [mock_service_1]/
+│   │   ├── Dockerfile
+│   │   └── [entrypoint file]
+│   └── [mock_service_2]/
+│       ├── Dockerfile
+│       └── [entrypoint file]
+├── fixtures/
+│   └── [test data files]
+├── tests/
+│   ├── test_[category_1].py
+│   ├── test_[category_2].py
+│   └── ...
+└── docker-compose.test.yml
+```
+
+### Layout Rationale
+
+[Brief explanation of directory structure choices — framework conventions, separation of mocks from tests, fixture management]
+
+## Mock Services
+
+| Mock Service | Replaces | Endpoints | Behavior |
+|-------------|----------|-----------|----------|
+| [name] | [external service] | [endpoints it serves] | [response behavior, configurable via control API] |
+
+### Mock Control API
+
+Each mock service exposes a `POST /mock/config` endpoint for test-time behavior control (e.g., simulate downtime, inject errors). A `GET /mock/[resource]` endpoint returns recorded interactions for assertion.
+
+## Docker Test Environment
+
+### docker-compose.test.yml Structure
+
+| Service | Image / Build | Purpose | Depends On |
+|---------|--------------|---------|------------|
+| [system-under-test] | [build context] | Main system being tested | [mock services] |
+| [mock-1] | [build context] | Mock for [external service] | — |
+| [e2e-consumer] | [build from e2e/] | Test runner | [system-under-test] |
+
+### Networks and Volumes
+
+[Isolated test network, volume mounts for test data, model files, results output]
+
+## Test Runner Configuration
+
+**Framework**: [e.g., pytest]
+**Plugins**: [e.g., pytest-csv, sseclient-py, requests]
+**Entry point**: [e.g., pytest --csv=/results/report.csv]
+
+### Fixture Strategy
+
+| Fixture | Scope | Purpose |
+|---------|-------|---------|
+| [name] | [session/module/function] | [what it provides] |
+
+## Test Data Fixtures
+
+| Data Set | Source | Format | Used By |
+|----------|--------|--------|---------|
+| [name] | [volume mount / generated / API seed] | [format] | [test categories] |
+
+### Data Isolation
+
+[Strategy: fresh containers per run, volume cleanup, mock state reset]
+
+## Test Reporting
+
+**Format**: [e.g., CSV]
+**Columns**: [e.g., Test ID, Test Name, Execution Time (ms), Result, Error Message]
+**Output path**: [e.g., /results/report.csv → mounted to host]
+
+## Acceptance Criteria
+
+**AC-1: Test environment starts**
+Given the docker-compose.test.yml
+When `docker compose -f docker-compose.test.yml up` is executed
+Then all services start and the system-under-test is reachable
+
+**AC-2: Mock services respond**
+Given the test environment is running
+When the e2e-consumer sends requests to mock services
+Then mock services respond with configured behavior
+
+**AC-3: Test runner executes**
+Given the test environment is running
+When the e2e-consumer starts
+Then the test runner discovers and executes test files
+
+**AC-4: Test report generated**
+Given tests have been executed
+When the test run completes
+Then a report file exists at the configured output path with correct columns
+```
+
+---
+
+## Guidance Notes
+
+- This is a PLAN document, not code. The `/implement` skill executes it.
+- Focus on test infrastructure decisions, not individual test implementations.
+- Reference environment.md and test-data.md from the test specs — don't repeat everything.
+- Mock services must be deterministic: same input always produces same output.
+- The Docker environment must be self-contained: `docker compose up` sufficient.

.cursor/skills/deploy/SKILL.md

@@ -0,0 +1,491 @@
+---
+name: deploy
+description: |
+  Comprehensive deployment skill covering status check, env setup, containerization, CI/CD pipeline, environment strategy, observability, deployment procedures, and deployment scripts.
+  7-step workflow: Status & env check, Docker containerization, CI/CD pipeline definition, environment strategy, observability planning, deployment procedures, deployment scripts.
+  Uses _docs/04_deploy/ structure.
+  Trigger phrases:
+  - "deploy", "deployment", "deployment strategy"
+  - "CI/CD", "pipeline", "containerize"
+  - "observability", "monitoring", "logging"
+  - "dockerize", "docker compose"
+category: ship
+tags: [deployment, docker, ci-cd, observability, monitoring, containerization, scripts]
+disable-model-invocation: true
+---
+
+# Deployment Planning
+
+Plan and document the full deployment lifecycle: check deployment status and environment requirements, containerize the application, define CI/CD pipelines, configure environments, set up observability, document deployment procedures, and generate deployment scripts.
+
+## Core Principles
+
+- **Docker-first**: every component runs in a container; local dev, blackbox tests, and production all use Docker
+- **Infrastructure as code**: all deployment configuration is version-controlled
+- **Observability built-in**: logging, metrics, and tracing are part of the deployment plan, not afterthoughts
+- **Environment parity**: dev, staging, and production environments mirror each other as closely as possible
+- **Save immediately**: write artifacts to disk after each step; never accumulate unsaved work
+- **Ask, don't assume**: when infrastructure constraints or preferences are unclear, ask the user
+- **Plan, don't code**: this workflow produces deployment documents and specifications, not implementation code (except deployment scripts in Step 7)
+
+## Context Resolution
+
+Fixed paths:
+
+- DOCUMENT_DIR: `_docs/02_document/`
+- DEPLOY_DIR: `_docs/04_deploy/`
+- REPORTS_DIR: `_docs/04_deploy/reports/`
+- SCRIPTS_DIR: `scripts/`
+- ARCHITECTURE: `_docs/02_document/architecture.md`
+- COMPONENTS_DIR: `_docs/02_document/components/`
+
+Announce the resolved paths to the user before proceeding.
+
+## Input Specification
+
+### Required Files
+
+| File | Purpose | Required |
+|------|---------|----------|
+| `_docs/00_problem/problem.md` | Problem description and context | Greenfield only |
+| `_docs/00_problem/restrictions.md` | Constraints and limitations | Greenfield only |
+| `_docs/01_solution/solution.md` | Finalized solution | Greenfield only |
+| `DOCUMENT_DIR/architecture.md` | Architecture (from plan or document skill) | Always |
+| `DOCUMENT_DIR/components/` | Component specs | Always |
+
+### Prerequisite Checks (BLOCKING)
+
+1. `architecture.md` exists — **STOP if missing**, run `/plan` first
+2. At least one component spec exists in `DOCUMENT_DIR/components/` — **STOP if missing**
+3. Create DEPLOY_DIR, REPORTS_DIR, and SCRIPTS_DIR if they do not exist
+4. If DEPLOY_DIR already contains artifacts, ask user: **resume from last checkpoint or start fresh?**
+
+## Artifact Management
+
+### Directory Structure
+
+```
+DEPLOY_DIR/
+├── containerization.md
+├── ci_cd_pipeline.md
+├── environment_strategy.md
+├── observability.md
+├── deployment_procedures.md
+├── deploy_scripts.md
+└── reports/
+    └── deploy_status_report.md
+
+SCRIPTS_DIR/           (project root)
+├── deploy.sh
+├── pull-images.sh
+├── start-services.sh
+├── stop-services.sh
+└── health-check.sh
+
+.env                   (project root, git-ignored)
+.env.example           (project root, committed)
+```
+
+### Save Timing
+
+| Step | Save immediately after | Filename |
+|------|------------------------|----------|
+| Step 1 | Status check & env setup complete | `reports/deploy_status_report.md` + `.env` + `.env.example` |
+| Step 2 | Containerization plan complete | `containerization.md` |
+| Step 3 | CI/CD pipeline defined | `ci_cd_pipeline.md` |
+| Step 4 | Environment strategy documented | `environment_strategy.md` |
+| Step 5 | Observability plan complete | `observability.md` |
+| Step 6 | Deployment procedures documented | `deployment_procedures.md` |
+| Step 7 | Deployment scripts created | `deploy_scripts.md` + scripts in `SCRIPTS_DIR/` |
+
+### Resumability
+
+If DEPLOY_DIR already contains artifacts:
+
+1. List existing files and match to the save timing table
+2. Identify the last completed step
+3. Resume from the next incomplete step
+4. Inform the user which steps are being skipped
+
+## Progress Tracking
+
+At the start of execution, create a TodoWrite with all steps (1 through 7). Update status as each step completes.
+
+## Workflow
+
+### Step 1: Deployment Status & Environment Setup
+
+**Role**: DevOps / Platform engineer
+**Goal**: Assess current deployment readiness, identify all required environment variables, and create `.env` files
+**Constraints**: Must complete before any other step
+
+1. Read architecture.md, all component specs, and restrictions.md
+2. Assess deployment readiness:
+   - List all components and their current state (planned / implemented / tested)
+   - Identify external dependencies (databases, APIs, message queues, cloud services)
+   - Identify infrastructure prerequisites (container registry, cloud accounts, DNS, SSL certificates)
+   - Check if any deployment blockers exist
+3. Identify all required environment variables by scanning:
+   - Component specs for configuration needs
+   - Database connection requirements
+   - External API endpoints and credentials
+   - Feature flags and runtime configuration
+   - Container registry credentials
+   - Cloud provider credentials
+   - Monitoring/logging service endpoints
+4. Generate `.env.example` in project root with all variables and placeholder values (committed to VCS)
+5. Generate `.env` in project root with development defaults filled in where safe (git-ignored)
+6. Ensure `.gitignore` includes `.env` (but NOT `.env.example`)
+7. Produce a deployment status report summarizing readiness, blockers, and required setup
+
+**Self-verification**:
+- [ ] All components assessed for deployment readiness
+- [ ] External dependencies catalogued
+- [ ] Infrastructure prerequisites identified
+- [ ] All required environment variables discovered
+- [ ] `.env.example` created with placeholder values
+- [ ] `.env` created with safe development defaults
+- [ ] `.gitignore` updated to exclude `.env`
+- [ ] Status report written to `reports/deploy_status_report.md`
+
+**Save action**: Write `reports/deploy_status_report.md` using `templates/deploy_status_report.md`, create `.env` and `.env.example` in project root
+
+**BLOCKING**: Present status report and environment variables to user. Do NOT proceed until confirmed.
+
+---
+
+### Step 2: Containerization
+
+**Role**: DevOps / Platform engineer
+**Goal**: Define Docker configuration for every component, local development, and blackbox test environments
+**Constraints**: Plan only — no Dockerfile creation. Describe what each Dockerfile should contain.
+
+1. Read architecture.md and all component specs
+2. Read restrictions.md for infrastructure constraints
+3. Research best Docker practices for the project's tech stack (multi-stage builds, base image selection, layer optimization)
+4. For each component, define:
+   - Base image (pinned version, prefer alpine/distroless for production)
+   - Build stages (dependency install, build, production)
+   - Non-root user configuration
+   - Health check endpoint and command
+   - Exposed ports
+   - `.dockerignore` contents
+5. Define `docker-compose.yml` for local development:
+   - All application components
+   - Database (Postgres) with named volume
+   - Any message queues, caches, or external service mocks
+   - Shared network
+   - Environment variable files (`.env`)
+6. Define `docker-compose.test.yml` for blackbox tests:
+   - Application components under test
+   - Test runner container (black-box, no internal imports)
+   - Isolated database with seed data
+   - All tests runnable via `docker compose -f docker-compose.test.yml up --abort-on-container-exit`
+7. Define image tagging strategy: `<registry>/<project>/<component>:<git-sha>` for CI, `latest` for local dev only
+
+**Self-verification**:
+- [ ] Every component has a Dockerfile specification
+- [ ] Multi-stage builds specified for all production images
+- [ ] Non-root user for all containers
+- [ ] Health checks defined for every service
+- [ ] docker-compose.yml covers all components + dependencies
+- [ ] docker-compose.test.yml enables black-box testing
+- [ ] `.dockerignore` defined
+
+**Save action**: Write `containerization.md` using `templates/containerization.md`
+
+**BLOCKING**: Present containerization plan to user. Do NOT proceed until confirmed.
+
+---
+
+### Step 3: CI/CD Pipeline
+
+**Role**: DevOps engineer
+**Goal**: Define the CI/CD pipeline with quality gates, security scanning, and multi-environment deployment
+**Constraints**: Pipeline definition only — produce YAML specification, not implementation
+
+1. Read architecture.md for tech stack and deployment targets
+2. Read restrictions.md for CI/CD constraints (cloud provider, registry, etc.)
+3. Research CI/CD best practices for the project's platform (GitHub Actions / Azure Pipelines)
+4. Define pipeline stages:
+
+| Stage | Trigger | Steps | Quality Gate |
+|-------|---------|-------|-------------|
+| **Lint** | Every push | Run linters per language (black, rustfmt, prettier, dotnet format) | Zero errors |
+| **Test** | Every push | Unit tests, blackbox tests, coverage report | 75%+ coverage (see `.cursor/rules/cursor-meta.mdc` Quality Thresholds) |
+| **Security** | Every push | Dependency audit, SAST scan (Semgrep/SonarQube), image scan (Trivy) | Zero critical/high CVEs |
+| **Build** | PR merge to dev | Build Docker images, tag with git SHA | Build succeeds |
+| **Push** | After build | Push to container registry | Push succeeds |
+| **Deploy Staging** | After push | Deploy to staging environment | Health checks pass |
+| **Smoke Tests** | After staging deploy | Run critical path tests against staging | All pass |
+| **Deploy Production** | Manual approval | Deploy to production | Health checks pass |
+
+5. Define caching strategy: dependency caches, Docker layer caches, build artifact caches
+6. Define parallelization: which stages can run concurrently
+7. Define notifications: build failures, deployment status, security alerts
+
+**Self-verification**:
+- [ ] All pipeline stages defined with triggers and gates
+- [ ] Coverage threshold enforced (75%+)
+- [ ] Security scanning included (dependencies + images + SAST)
+- [ ] Caching configured for dependencies and Docker layers
+- [ ] Multi-environment deployment (staging → production)
+- [ ] Rollback procedure referenced
+- [ ] Notifications configured
+
+**Save action**: Write `ci_cd_pipeline.md` using `templates/ci_cd_pipeline.md`
+
+---
+
+### Step 4: Environment Strategy
+
+**Role**: Platform engineer
+**Goal**: Define environment configuration, secrets management, and environment parity
+**Constraints**: Strategy document — no secrets or credentials in output
+
+1. Define environments:
+
+| Environment | Purpose | Infrastructure | Data |
+|-------------|---------|---------------|------|
+| **Development** | Local developer workflow | docker-compose, local volumes | Seed data, mocks for external APIs |
+| **Staging** | Pre-production validation | Mirrors production topology | Anonymized production-like data |
+| **Production** | Live system | Full infrastructure | Real data |
+
+2. Define environment variable management:
+   - Reference `.env.example` created in Step 1
+   - Per-environment variable sources (`.env` for dev, secret manager for staging/prod)
+   - Validation: fail fast on missing required variables at startup
+3. Define secrets management:
+   - Never commit secrets to version control
+   - Development: `.env` files (git-ignored)
+   - Staging/Production: secret manager (AWS Secrets Manager / Azure Key Vault / Vault)
+   - Rotation policy
+4. Define database management per environment:
+   - Development: Docker Postgres with named volume, seed data
+   - Staging: managed Postgres, migrations applied via CI/CD
+   - Production: managed Postgres, migrations require approval
+
+**Self-verification**:
+- [ ] All three environments defined with clear purpose
+- [ ] Environment variable documentation complete (references `.env.example` from Step 1)
+- [ ] No secrets in any output document
+- [ ] Secret manager specified for staging/production
+- [ ] Database strategy per environment
+
+**Save action**: Write `environment_strategy.md` using `templates/environment_strategy.md`
+
+---
+
+### Step 5: Observability
+
+**Role**: Site Reliability Engineer (SRE)
+**Goal**: Define logging, metrics, tracing, and alerting strategy
+**Constraints**: Strategy document — describe what to implement, not how to wire it
+
+1. Read architecture.md and component specs for service boundaries
+2. Research observability best practices for the tech stack
+
+**Logging**:
+- Structured JSON to stdout/stderr (no file logging in containers)
+- Fields: `timestamp` (ISO 8601), `level`, `service`, `correlation_id`, `message`, `context`
+- Levels: ERROR (exceptions), WARN (degraded), INFO (business events), DEBUG (diagnostics, dev only)
+- No PII in logs
+- Retention: dev = console, staging = 7 days, production = 30 days
+
+**Metrics**:
+- Expose Prometheus-compatible `/metrics` endpoint per service
+- System metrics: CPU, memory, disk, network
+- Application metrics: `request_count`, `request_duration` (histogram), `error_count`, `active_connections`
+- Business metrics: derived from acceptance criteria
+- Collection interval: 15s
+
+**Distributed Tracing**:
+- OpenTelemetry SDK integration
+- Trace context propagation via HTTP headers and message queue metadata
+- Span naming: `<service>.<operation>`
+- Sampling: 100% in dev/staging, 10% in production (adjust based on volume)
+
+**Alerting**:
+
+| Severity | Response Time | Condition Examples |
+|----------|---------------|-------------------|
+| Critical | 5 min | Service down, data loss, health check failed |
+| High | 30 min | Error rate > 5%, P95 latency > 2x baseline |
+| Medium | 4 hours | Disk > 80%, elevated latency |
+| Low | Next business day | Non-critical warnings |
+
+**Dashboards**:
+- Operations: service health, request rate, error rate, response time percentiles, resource utilization
+- Business: key business metrics from acceptance criteria
+
+**Self-verification**:
+- [ ] Structured logging format defined with required fields
+- [ ] Metrics endpoint specified per service
+- [ ] OpenTelemetry tracing configured
+- [ ] Alert severities with response times defined
+- [ ] Dashboards cover operations and business metrics
+- [ ] PII exclusion from logs addressed
+
+**Save action**: Write `observability.md` using `templates/observability.md`
+
+---
+
+### Step 6: Deployment Procedures
+
+**Role**: DevOps / Platform engineer
+**Goal**: Define deployment strategy, rollback procedures, health checks, and deployment checklist
+**Constraints**: Procedures document — no implementation
+
+1. Define deployment strategy:
+   - Preferred pattern: blue-green / rolling / canary (choose based on architecture)
+   - Zero-downtime requirement for production
+   - Graceful shutdown: 30-second grace period for in-flight requests
+   - Database migration ordering: migrate before deploy, backward-compatible only
+
+2. Define health checks:
+
+| Check | Type | Endpoint | Interval | Threshold |
+|-------|------|----------|----------|-----------|
+| Liveness | HTTP GET | `/health/live` | 10s | 3 failures → restart |
+| Readiness | HTTP GET | `/health/ready` | 5s | 3 failures → remove from LB |
+| Startup | HTTP GET | `/health/ready` | 5s | 30 attempts max |
+
+3. Define rollback procedures:
+   - Trigger criteria: health check failures, error rate spike, critical alert
+   - Rollback steps: redeploy previous image tag, verify health, rollback database if needed
+   - Communication: notify stakeholders during rollback
+   - Post-mortem: required after every production rollback
+
+4. Define deployment checklist:
+   - [ ] All tests pass in CI
+   - [ ] Security scan clean (zero critical/high CVEs)
+   - [ ] Database migrations reviewed and tested
+   - [ ] Environment variables configured
+   - [ ] Health check endpoints responding
+   - [ ] Monitoring alerts configured
+   - [ ] Rollback plan documented and tested
+   - [ ] Stakeholders notified
+
+**Self-verification**:
+- [ ] Deployment strategy chosen and justified
+- [ ] Zero-downtime approach specified
+- [ ] Health checks defined (liveness, readiness, startup)
+- [ ] Rollback trigger criteria and steps documented
+- [ ] Deployment checklist complete
+
+**Save action**: Write `deployment_procedures.md` using `templates/deployment_procedures.md`
+
+**BLOCKING**: Present deployment procedures to user. Do NOT proceed until confirmed.
+
+---
+
+### Step 7: Deployment Scripts
+
+**Role**: DevOps / Platform engineer
+**Goal**: Create executable deployment scripts for pulling Docker images and running services on the remote target machine
+**Constraints**: Produce real, executable shell scripts. This is the ONLY step that creates implementation artifacts.
+
+1. Read containerization.md and deployment_procedures.md from previous steps
+2. Read `.env.example` for required variables
+3. Create the following scripts in `SCRIPTS_DIR/`:
+
+**`deploy.sh`** — Main deployment orchestrator:
+   - Validates that required environment variables are set (sources `.env` if present)
+   - Calls `pull-images.sh`, then `stop-services.sh`, then `start-services.sh`, then `health-check.sh`
+   - Exits with non-zero code on any failure
+   - Supports `--rollback` flag to redeploy previous image tags
+
+**`pull-images.sh`** — Pull Docker images to target machine:
+   - Reads image list and tags from environment or config
+   - Authenticates with container registry
+   - Pulls all required images
+   - Verifies image integrity (digest check)
+
+**`start-services.sh`** — Start services on target machine:
+   - Runs `docker compose up -d` or individual `docker run` commands
+   - Applies environment variables from `.env`
+   - Configures networks and volumes
+   - Waits for containers to reach healthy state
+
+**`stop-services.sh`** — Graceful shutdown:
+   - Stops services with graceful shutdown period
+   - Saves current image tags for rollback reference
+   - Cleans up orphaned containers/networks
+
+**`health-check.sh`** — Verify deployment health:
+   - Checks all health endpoints
+   - Reports status per service
+   - Returns non-zero if any service is unhealthy
+
+4. All scripts must:
+   - Be POSIX-compatible (#!/bin/bash with set -euo pipefail)
+   - Source `.env` from project root or accept env vars from the environment
+   - Include usage/help output (`--help` flag)
+   - Be idempotent where possible
+   - Handle SSH connection to remote target (configurable via `DEPLOY_HOST` env var)
+
+5. Document all scripts in `deploy_scripts.md`
+
+**Self-verification**:
+- [ ] All five scripts created and executable
+- [ ] Scripts source environment variables correctly
+- [ ] `deploy.sh` orchestrates the full flow
+- [ ] `pull-images.sh` handles registry auth and image pull
+- [ ] `start-services.sh` starts containers with correct config
+- [ ] `stop-services.sh` handles graceful shutdown
+- [ ] `health-check.sh` validates all endpoints
+- [ ] Rollback supported via `deploy.sh --rollback`
+- [ ] Scripts work for remote deployment via SSH (DEPLOY_HOST)
+- [ ] `deploy_scripts.md` documents all scripts
+
+**Save action**: Write scripts to `SCRIPTS_DIR/`, write `deploy_scripts.md` using `templates/deploy_scripts.md`
+
+---
+
+## Escalation Rules
+
+| Situation | Action |
+|-----------|--------|
+| Unknown cloud provider or hosting | **ASK user** |
+| Container registry not specified | **ASK user** |
+| CI/CD platform preference unclear | **ASK user** — default to GitHub Actions |
+| Secret manager not chosen | **ASK user** |
+| Deployment pattern trade-offs | **ASK user** with recommendation |
+| Missing architecture.md | **STOP** — run `/plan` first |
+| Remote target machine details unknown | **ASK user** for SSH access, OS, and specs |
+
+## Common Mistakes
+
+- **Implementing during planning**: Steps 1–6 produce documents, not code (Step 7 is the exception — it creates scripts)
+- **Hardcoding secrets**: never include real credentials in deployment documents or scripts
+- **Ignoring blackbox test containerization**: the test environment must be containerized alongside the app
+- **Skipping BLOCKING gates**: never proceed past a BLOCKING marker without user confirmation
+- **Using `:latest` tags**: always pin base image versions
+- **Forgetting observability**: logging, metrics, and tracing are deployment concerns, not post-deployment additions
+- **Committing `.env`**: only `.env.example` goes to version control; `.env` must be in `.gitignore`
+- **Non-portable scripts**: deployment scripts must work across environments; avoid hardcoded paths
+
+## Methodology Quick Reference
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│            Deployment Planning (7-Step Method)                  │
+├────────────────────────────────────────────────────────────────┤
+│ PREREQ: architecture.md + component specs exist                │
+│                                                                │
+│ 1. Status & Env     → reports/deploy_status_report.md          │
+│                       + .env + .env.example                    │
+│    [BLOCKING: user confirms status & env vars]                 │
+│ 2. Containerization  → containerization.md                     │
+│    [BLOCKING: user confirms Docker plan]                       │
+│ 3. CI/CD Pipeline    → ci_cd_pipeline.md                       │
+│ 4. Environment       → environment_strategy.md                 │
+│ 5. Observability     → observability.md                        │
+│ 6. Procedures        → deployment_procedures.md                │
+│    [BLOCKING: user confirms deployment plan]                   │
+│ 7. Scripts           → deploy_scripts.md + scripts/            │
+├────────────────────────────────────────────────────────────────┤
+│ Principles: Docker-first · IaC · Observability built-in        │
+│             Environment parity · Save immediately              │
+└────────────────────────────────────────────────────────────────┘
+```

.cursor/skills/deploy/templates/ci_cd_pipeline.md

@@ -0,0 +1,87 @@
+# CI/CD Pipeline Template
+
+Save as `_docs/04_deploy/ci_cd_pipeline.md`.
+
+---
+
+```markdown
+# [System Name] — CI/CD Pipeline
+
+## Pipeline Overview
+
+| Stage | Trigger | Quality Gate |
+|-------|---------|-------------|
+| Lint | Every push | Zero lint errors |
+| Test | Every push | 75%+ coverage, all tests pass |
+| Security | Every push | Zero critical/high CVEs |
+| Build | PR merge to dev | Docker build succeeds |
+| Push | After build | Images pushed to registry |
+| Deploy Staging | After push | Health checks pass |
+| Smoke Tests | After staging deploy | Critical paths pass |
+| Deploy Production | Manual approval | Health checks pass |
+
+## Stage Details
+
+### Lint
+- [Language-specific linters and formatters]
+- Runs in parallel per language
+
+### Test
+- Unit tests: [framework and command]
+- Blackbox tests: [framework and command, uses docker-compose.test.yml]
+- Coverage threshold: 75% overall, 90% critical paths
+- Coverage report published as pipeline artifact
+
+### Security
+- Dependency audit: [tool, e.g., npm audit / pip-audit / dotnet list package --vulnerable]
+- SAST scan: [tool, e.g., Semgrep / SonarQube]
+- Image scan: Trivy on built Docker images
+- Block on: critical or high severity findings
+
+### Build
+- Docker images built using multi-stage Dockerfiles
+- Tagged with git SHA: `<registry>/<component>:<sha>`
+- Build cache: Docker layer cache via CI cache action
+
+### Push
+- Registry: [container registry URL]
+- Authentication: [method]
+
+### Deploy Staging
+- Deployment method: [docker compose / Kubernetes / cloud service]
+- Pre-deploy: run database migrations
+- Post-deploy: verify health check endpoints
+- Automated rollback on health check failure
+
+### Smoke Tests
+- Subset of blackbox tests targeting staging environment
+- Validates critical user flows
+- Timeout: [maximum duration]
+
+### Deploy Production
+- Requires manual approval via [mechanism]
+- Deployment strategy: [blue-green / rolling / canary]
+- Pre-deploy: database migration review
+- Post-deploy: health checks + monitoring for 15 min
+
+## Caching Strategy
+
+| Cache | Key | Restore Keys |
+|-------|-----|-------------|
+| Dependencies | [lockfile hash] | [partial match] |
+| Docker layers | [Dockerfile hash] | [partial match] |
+| Build artifacts | [source hash] | [partial match] |
+
+## Parallelization
+
+[Diagram or description of which stages run concurrently]
+
+## Notifications
+
+| Event | Channel | Recipients |
+|-------|---------|-----------|
+| Build failure | [Slack/email] | [team] |
+| Security alert | [Slack/email] | [team + security] |
+| Deploy success | [Slack] | [team] |
+| Deploy failure | [Slack/email + PagerDuty] | [on-call] |
+```

.cursor/skills/deploy/templates/containerization.md

@@ -0,0 +1,94 @@
+# Containerization Plan Template
+
+Save as `_docs/04_deploy/containerization.md`.
+
+---
+
+```markdown
+# [System Name] — Containerization
+
+## Component Dockerfiles
+
+### [Component Name]
+
+| Property | Value |
+|----------|-------|
+| Base image | [e.g., mcr.microsoft.com/dotnet/aspnet:8.0-alpine] |
+| Build image | [e.g., mcr.microsoft.com/dotnet/sdk:8.0-alpine] |
+| Stages | [dependency install → build → production] |
+| User | [non-root user name] |
+| Health check | [endpoint and command] |
+| Exposed ports | [port list] |
+| Key build args | [if any] |
+
+### [Repeat for each component]
+
+## Docker Compose — Local Development
+
+```yaml
+# docker-compose.yml structure
+services:
+  [component]:
+    build: ./[path]
+    ports: ["host:container"]
+    environment: [reference .env.dev]
+    depends_on: [dependencies with health condition]
+    healthcheck: [command, interval, timeout, retries]
+
+  db:
+    image: [postgres:version-alpine]
+    volumes: [named volume]
+    environment: [credentials from .env.dev]
+    healthcheck: [pg_isready]
+
+volumes:
+  [named volumes]
+
+networks:
+  [shared network]
+```
+
+## Docker Compose — Blackbox Tests
+
+```yaml
+# docker-compose.test.yml structure
+services:
+  [app components under test]
+
+  test-runner:
+    build: ./tests/integration
+    depends_on: [app components with health condition]
+    environment: [test configuration]
+    # Exit code determines test pass/fail
+
+  db:
+    image: [postgres:version-alpine]
+    volumes: [seed data mount]
+```
+
+Run: `docker compose -f docker-compose.test.yml up --abort-on-container-exit`
+
+## Image Tagging Strategy
+
+| Context | Tag Format | Example |
+|---------|-----------|---------|
+| CI build | `<registry>/<project>/<component>:<git-sha>` | `ghcr.io/org/api:a1b2c3d` |
+| Release | `<registry>/<project>/<component>:<semver>` | `ghcr.io/org/api:1.2.0` |
+| Local dev | `<component>:latest` | `api:latest` |
+
+## .dockerignore
+
+```
+.git
+.cursor
+_docs
+_standalone
+node_modules
+**/bin
+**/obj
+**/__pycache__
+*.md
+.env*
+docker-compose*.yml
+```
+```

.cursor/skills/deploy/templates/deploy_scripts.md

@@ -0,0 +1,114 @@
+# Deployment Scripts Documentation Template
+
+Save as `_docs/04_deploy/deploy_scripts.md`.
+
+---
+
+```markdown
+# [System Name] — Deployment Scripts
+
+## Overview
+
+| Script | Purpose | Location |
+|--------|---------|----------|
+| `deploy.sh` | Main deployment orchestrator | `scripts/deploy.sh` |
+| `pull-images.sh` | Pull Docker images from registry | `scripts/pull-images.sh` |
+| `start-services.sh` | Start all services | `scripts/start-services.sh` |
+| `stop-services.sh` | Graceful shutdown | `scripts/stop-services.sh` |
+| `health-check.sh` | Verify deployment health | `scripts/health-check.sh` |
+
+## Prerequisites
+
+- Docker and Docker Compose installed on target machine
+- SSH access to target machine (configured via `DEPLOY_HOST`)
+- Container registry credentials configured
+- `.env` file with required environment variables (see `.env.example`)
+
+## Environment Variables
+
+All scripts source `.env` from the project root or accept variables from the environment.
+
+| Variable | Required By | Purpose |
+|----------|------------|---------|
+| `DEPLOY_HOST` | All (remote mode) | SSH target for remote deployment |
+| `REGISTRY_URL` | `pull-images.sh` | Container registry URL |
+| `REGISTRY_USER` | `pull-images.sh` | Registry authentication |
+| `REGISTRY_PASS` | `pull-images.sh` | Registry authentication |
+| `IMAGE_TAG` | `pull-images.sh`, `start-services.sh` | Image version to deploy (default: latest git SHA) |
+| [add project-specific variables] | | |
+
+## Script Details
+
+### deploy.sh
+
+Main orchestrator that runs the full deployment flow.
+
+**Usage**:
+- `./scripts/deploy.sh` — Deploy latest version
+- `./scripts/deploy.sh --rollback` — Rollback to previous version
+- `./scripts/deploy.sh --help` — Show usage
+
+**Flow**:
+1. Validate required environment variables
+2. Call `pull-images.sh`
+3. Call `stop-services.sh`
+4. Call `start-services.sh`
+5. Call `health-check.sh`
+6. Report success or failure
+
+**Rollback**: When `--rollback` is passed, reads the previous image tags saved by `stop-services.sh` and redeploys those versions.
+
+### pull-images.sh
+
+**Usage**: `./scripts/pull-images.sh [--help]`
+
+**Steps**:
+1. Authenticate with container registry (`REGISTRY_URL`)
+2. Pull all required images with specified `IMAGE_TAG`
+3. Verify image integrity via digest check
+4. Report pull results per image
+
+### start-services.sh
+
+**Usage**: `./scripts/start-services.sh [--help]`
+
+**Steps**:
+1. Run `docker compose up -d` with the correct env file
+2. Configure networks and volumes
+3. Wait for all containers to report healthy state
+4. Report startup status per service
+
+### stop-services.sh
+
+**Usage**: `./scripts/stop-services.sh [--help]`
+
+**Steps**:
+1. Save current image tags to `previous_tags.env` (for rollback)
+2. Stop services with graceful shutdown period (30s)
+3. Clean up orphaned containers and networks
+
+### health-check.sh
+
+**Usage**: `./scripts/health-check.sh [--help]`
+
+**Checks**:
+
+| Service | Endpoint | Expected |
+|---------|----------|----------|
+| [Component 1] | `http://localhost:[port]/health/live` | HTTP 200 |
+| [Component 2] | `http://localhost:[port]/health/ready` | HTTP 200 |
+| [add all services] | | |
+
+**Exit codes**:
+- `0` — All services healthy
+- `1` — One or more services unhealthy
+
+## Common Script Properties
+
+All scripts:
+- Use `#!/bin/bash` with `set -euo pipefail`
+- Support `--help` flag for usage information
+- Source `.env` from project root if present
+- Are idempotent where possible
+- Support remote execution via SSH when `DEPLOY_HOST` is set
+```

.cursor/skills/deploy/templates/deploy_status_report.md

@@ -0,0 +1,73 @@
+# Deployment Status Report Template
+
+Save as `_docs/04_deploy/reports/deploy_status_report.md`.
+
+---
+
+```markdown
+# [System Name] — Deployment Status Report
+
+## Deployment Readiness Summary
+
+| Aspect | Status | Notes |
+|--------|--------|-------|
+| Architecture defined | ✅ / ❌ | |
+| Component specs complete | ✅ / ❌ | |
+| Infrastructure prerequisites met | ✅ / ❌ | |
+| External dependencies identified | ✅ / ❌ | |
+| Blockers | [count] | [summary] |
+
+## Component Status
+
+| Component | State | Docker-ready | Notes |
+|-----------|-------|-------------|-------|
+| [Component 1] | planned / implemented / tested | yes / no | |
+| [Component 2] | planned / implemented / tested | yes / no | |
+
+## External Dependencies
+
+| Dependency | Type | Required For | Status |
+|------------|------|-------------|--------|
+| [e.g., PostgreSQL] | Database | Data persistence | [available / needs setup] |
+| [e.g., Redis] | Cache | Session management | [available / needs setup] |
+| [e.g., External API] | API | [purpose] | [available / needs setup] |
+
+## Infrastructure Prerequisites
+
+| Prerequisite | Status | Action Needed |
+|-------------|--------|--------------|
+| Container registry | [ready / not set up] | [action] |
+| Cloud account | [ready / not set up] | [action] |
+| DNS configuration | [ready / not set up] | [action] |
+| SSL certificates | [ready / not set up] | [action] |
+| CI/CD platform | [ready / not set up] | [action] |
+| Secret manager | [ready / not set up] | [action] |
+
+## Deployment Blockers
+
+| Blocker | Severity | Resolution |
+|---------|----------|-----------|
+| [blocker description] | critical / high / medium | [resolution steps] |
+
+## Required Environment Variables
+
+| Variable | Purpose | Required In | Default (Dev) | Source (Staging/Prod) |
+|----------|---------|------------|---------------|----------------------|
+| `DATABASE_URL` | Postgres connection string | All components | `postgres://dev:dev@db:5432/app` | Secret manager |
+| `DEPLOY_HOST` | Remote target machine | Deployment scripts | `localhost` | Environment |
+| `REGISTRY_URL` | Container registry URL | CI/CD, deploy scripts | `localhost:5000` | Environment |
+| `REGISTRY_USER` | Registry username | CI/CD, deploy scripts | — | Secret manager |
+| `REGISTRY_PASS` | Registry password | CI/CD, deploy scripts | — | Secret manager |
+| [add all required variables] | | | | |
+
+## .env Files Created
+
+- `.env.example` — committed to VCS, contains all variable names with placeholder values
+- `.env` — git-ignored, contains development defaults
+
+## Next Steps
+
+1. [Resolve any blockers listed above]
+2. [Set up missing infrastructure prerequisites]
+3. [Proceed to containerization planning]
+```

.cursor/skills/deploy/templates/deployment_procedures.md

@@ -0,0 +1,103 @@
+# Deployment Procedures Template
+
+Save as `_docs/04_deploy/deployment_procedures.md`.
+
+---
+
+```markdown
+# [System Name] — Deployment Procedures
+
+## Deployment Strategy
+
+**Pattern**: [blue-green / rolling / canary]
+**Rationale**: [why this pattern fits the architecture]
+**Zero-downtime**: required for production deployments
+
+### Graceful Shutdown
+
+- Grace period: 30 seconds for in-flight requests
+- Sequence: stop accepting new requests → drain connections → shutdown
+- Container orchestrator: `terminationGracePeriodSeconds: 40`
+
+### Database Migration Ordering
+
+- Migrations run **before** new code deploys
+- All migrations must be backward-compatible (old code works with new schema)
+- Irreversible migrations require explicit approval
+
+## Health Checks
+
+| Check | Type | Endpoint | Interval | Failure Threshold | Action |
+|-------|------|----------|----------|-------------------|--------|
+| Liveness | HTTP GET | `/health/live` | 10s | 3 failures | Restart container |
+| Readiness | HTTP GET | `/health/ready` | 5s | 3 failures | Remove from load balancer |
+| Startup | HTTP GET | `/health/ready` | 5s | 30 attempts | Kill and recreate |
+
+### Health Check Responses
+
+- `/health/live`: returns 200 if process is running (no dependency checks)
+- `/health/ready`: returns 200 if all dependencies (DB, cache, queues) are reachable
+
+## Staging Deployment
+
+1. CI/CD builds and pushes Docker images tagged with git SHA
+2. Run database migrations against staging
+3. Deploy new images to staging environment
+4. Wait for health checks to pass (readiness probe)
+5. Run smoke tests against staging
+6. If smoke tests fail: automatic rollback to previous image
+
+## Production Deployment
+
+1. **Approval**: manual approval required via [mechanism]
+2. **Pre-deploy checks**:
+   - [ ] Staging smoke tests passed
+   - [ ] Security scan clean
+   - [ ] Database migration reviewed
+   - [ ] Monitoring alerts configured
+   - [ ] Rollback plan confirmed
+3. **Deploy**: apply deployment strategy (blue-green / rolling / canary)
+4. **Verify**: health checks pass, error rate stable, latency within baseline
+5. **Monitor**: observe dashboards for 15 minutes post-deploy
+6. **Finalize**: mark deployment as successful or trigger rollback
+
+## Rollback Procedures
+
+### Trigger Criteria
+
+- Health check failures persist after deploy
+- Error rate exceeds 5% for more than 5 minutes
+- Critical alert fires within 15 minutes of deploy
+- Manual decision by on-call engineer
+
+### Rollback Steps
+
+1. Redeploy previous Docker image tag (from CI/CD artifact)
+2. Verify health checks pass
+3. If database migration was applied:
+   - Run DOWN migration if reversible
+   - If irreversible: assess data impact, escalate if needed
+4. Notify stakeholders
+5. Schedule post-mortem within 24 hours
+
+### Post-Mortem
+
+Required after every production rollback:
+- Timeline of events
+- Root cause
+- What went wrong
+- Prevention measures
+
+## Deployment Checklist
+
+- [ ] All tests pass in CI
+- [ ] Security scan clean (zero critical/high CVEs)
+- [ ] Docker images built and pushed
+- [ ] Database migrations reviewed and tested
+- [ ] Environment variables configured for target environment
+- [ ] Health check endpoints verified
+- [ ] Monitoring alerts configured
+- [ ] Rollback plan documented and tested
+- [ ] Stakeholders notified of deployment window
+- [ ] On-call engineer available during deployment
+```

.cursor/skills/deploy/templates/environment_strategy.md

@@ -0,0 +1,61 @@
+# Environment Strategy Template
+
+Save as `_docs/04_deploy/environment_strategy.md`.
+
+---
+
+```markdown
+# [System Name] — Environment Strategy
+
+## Environments
+
+| Environment | Purpose | Infrastructure | Data Source |
+|-------------|---------|---------------|-------------|
+| Development | Local developer workflow | docker-compose | Seed data, mocked externals |
+| Staging | Pre-production validation | [mirrors production] | Anonymized production-like data |
+| Production | Live system | [full infrastructure] | Real data |
+
+## Environment Variables
+
+### Required Variables
+
+| Variable | Purpose | Dev Default | Staging/Prod Source |
+|----------|---------|-------------|-------------------|
+| `DATABASE_URL` | Postgres connection | `postgres://dev:dev@db:5432/app` | Secret manager |
+| [add all required variables] | | | |
+
+### `.env.example`
+
+```env
+# Copy to .env and fill in values
+DATABASE_URL=postgres://user:pass@host:5432/dbname
+# [all required variables with placeholder values]
+```
+
+### Variable Validation
+
+All services validate required environment variables at startup and fail fast with a clear error message if any are missing.
+
+## Secrets Management
+
+| Environment | Method | Tool |
+|-------------|--------|------|
+| Development | `.env` file (git-ignored) | dotenv |
+| Staging | Secret manager | [AWS Secrets Manager / Azure Key Vault / Vault] |
+| Production | Secret manager | [AWS Secrets Manager / Azure Key Vault / Vault] |
+
+Rotation policy: [frequency and procedure]
+
+## Database Management
+
+| Environment | Type | Migrations | Data |
+|-------------|------|-----------|------|
+| Development | Docker Postgres, named volume | Applied on container start | Seed data via init script |
+| Staging | Managed Postgres | Applied via CI/CD pipeline | Anonymized production snapshot |
+| Production | Managed Postgres | Applied via CI/CD with approval | Live data |
+
+Migration rules:
+- All migrations must be backward-compatible (support old and new code simultaneously)
+- Reversible migrations required (DOWN/rollback script)
+- Production migrations require review before apply
+```

.cursor/skills/deploy/templates/observability.md

@@ -0,0 +1,132 @@
+# Observability Template
+
+Save as `_docs/04_deploy/observability.md`.
+
+---
+
+```markdown
+# [System Name] — Observability
+
+## Logging
+
+### Format
+
+Structured JSON to stdout/stderr. No file-based logging in containers.
+
+```json
+{
+  "timestamp": "ISO8601",
+  "level": "INFO",
+  "service": "service-name",
+  "correlation_id": "uuid",
+  "message": "Event description",
+  "context": {}
+}
+```
+
+### Log Levels
+
+| Level | Usage | Example |
+|-------|-------|---------|
+| ERROR | Exceptions, failures requiring attention | Database connection failed |
+| WARN | Potential issues, degraded performance | Retry attempt 2/3 |
+| INFO | Significant business events | User registered, Order placed |
+| DEBUG | Detailed diagnostics (dev/staging only) | Request payload, Query params |
+
+### Retention
+
+| Environment | Destination | Retention |
+|-------------|-------------|-----------|
+| Development | Console | Session |
+| Staging | [log aggregator] | 7 days |
+| Production | [log aggregator] | 30 days |
+
+### PII Rules
+
+- Never log passwords, tokens, or session IDs
+- Mask email addresses and personal identifiers
+- Log user IDs (opaque) instead of usernames
+
+## Metrics
+
+### Endpoints
+
+Every service exposes Prometheus-compatible metrics at `/metrics`.
+
+### Application Metrics
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `request_count` | Counter | Total HTTP requests by method, path, status |
+| `request_duration_seconds` | Histogram | Response time by method, path |
+| `error_count` | Counter | Failed requests by type |
+| `active_connections` | Gauge | Current open connections |
+
+### System Metrics
+
+- CPU usage, Memory usage, Disk I/O, Network I/O
+
+### Business Metrics
+
+| Metric | Type | Description | Source |
+|--------|------|-------------|--------|
+| [from acceptance criteria] | | | |
+
+Collection interval: 15 seconds
+
+## Distributed Tracing
+
+### Configuration
+
+- SDK: OpenTelemetry
+- Propagation: W3C Trace Context via HTTP headers
+- Span naming: `<service>.<operation>`
+
+### Sampling
+
+| Environment | Rate | Rationale |
+|-------------|------|-----------|
+| Development | 100% | Full visibility |
+| Staging | 100% | Full visibility |
+| Production | 10% | Balance cost vs observability |
+
+### Integration Points
+
+- HTTP requests: automatic instrumentation
+- Database queries: automatic instrumentation
+- Message queues: manual span creation on publish/consume
+
+## Alerting
+
+| Severity | Response Time | Conditions |
+|----------|---------------|-----------|
+| Critical | 5 min | Service unreachable, health check failed for 1 min, data loss detected |
+| High | 30 min | Error rate > 5% for 5 min, P95 latency > 2x baseline for 10 min |
+| Medium | 4 hours | Disk usage > 80%, elevated latency, connection pool exhaustion |
+| Low | Next business day | Non-critical warnings, deprecated API usage |
+
+### Notification Channels
+
+| Severity | Channel |
+|----------|---------|
+| Critical | [PagerDuty / phone] |
+| High | [Slack + email] |
+| Medium | [Slack] |
+| Low | [Dashboard only] |
+
+## Dashboards
+
+### Operations Dashboard
+
+- Service health status (up/down per component)
+- Request rate and error rate
+- Response time percentiles (P50, P95, P99)
+- Resource utilization (CPU, memory per container)
+- Active alerts
+
+### Business Dashboard
+
+- [Key business metrics from acceptance criteria]
+- [User activity indicators]
+- [Transaction volumes]
+```

.cursor/skills/document/SKILL.md

@@ -0,0 +1,515 @@
+---
+name: document
+description: |
+  Bottom-up codebase documentation skill. Analyzes existing code from modules up through components
+  to architecture, then retrospectively derives problem/restrictions/acceptance criteria.
+  Produces the same _docs/ artifacts as the problem, research, and plan skills, but from code
+  analysis instead of user interview.
+  Trigger phrases:
+  - "document", "document codebase", "document this project"
+  - "documentation", "generate documentation", "create documentation"
+  - "reverse-engineer docs", "code to docs"
+  - "analyze and document"
+category: build
+tags: [documentation, code-analysis, reverse-engineering, architecture, bottom-up]
+disable-model-invocation: true
+---
+
+# Bottom-Up Codebase Documentation
+
+Analyze an existing codebase from the bottom up — individual modules first, then components, then system-level architecture — and produce the same `_docs/` artifacts that the `problem` and `plan` skills generate, without requiring user interview.
+
+## Core Principles
+
+- **Bottom-up always**: module docs -> component specs -> architecture/flows -> solution -> problem extraction. Every higher level is synthesized from the level below.
+- **Dependencies first**: process modules in topological order (leaves first). When documenting module X, all of X's dependencies already have docs.
+- **Incremental context**: each module's doc uses already-written dependency docs as context — no ever-growing chain.
+- **Verify against code**: cross-reference every entity in generated docs against actual codebase. Catch hallucinations.
+- **Save immediately**: write each artifact as soon as its step completes. Enable resume from any checkpoint.
+- **Ask, don't assume**: when code intent is ambiguous, ASK the user before proceeding.
+
+## Context Resolution
+
+Fixed paths:
+
+- DOCUMENT_DIR: `_docs/02_document/`
+- SOLUTION_DIR: `_docs/01_solution/`
+- PROBLEM_DIR: `_docs/00_problem/`
+
+Optional input:
+
+- FOCUS_DIR: a specific directory subtree provided by the user (e.g., `/document @src/api/`). When set, only this subtree and its transitive dependencies are analyzed.
+
+Announce resolved paths (and FOCUS_DIR if set) to user before proceeding.
+
+## Mode Detection
+
+Determine the execution mode before any other logic:
+
+| Mode | Trigger | Scope |
+|------|---------|-------|
+| **Full** | No input file, no existing state | Entire codebase |
+| **Focus Area** | User provides a directory path (e.g., `@src/api/`) | Only the specified subtree + transitive dependencies |
+| **Resume** | `state.json` exists in DOCUMENT_DIR | Continue from last checkpoint |
+
+Focus Area mode produces module + component docs for the targeted area only. It can be run repeatedly for different areas — each run appends to the existing module and component docs without overwriting other areas.
+
+## Prerequisite Checks
+
+1. If `_docs/` already exists and contains files AND mode is **Full**, ASK user: **overwrite, merge, or write to `_docs_generated/` instead?**
+2. Create DOCUMENT_DIR, SOLUTION_DIR, and PROBLEM_DIR if they don't exist
+3. If DOCUMENT_DIR contains a `state.json`, offer to **resume from last checkpoint or start fresh**
+4. If FOCUS_DIR is set, verify the directory exists and contains source files — **STOP if missing**
+
+## Progress Tracking
+
+Create a TodoWrite with all steps (0 through 7). Update status as each step completes.
+
+## Workflow
+
+### Step 0: Codebase Discovery
+
+**Role**: Code analyst
+**Goal**: Build a complete map of the codebase (or targeted subtree) before analyzing any code.
+
+**Focus Area scoping**: if FOCUS_DIR is set, limit the scan to that directory subtree. Still identify transitive dependencies outside FOCUS_DIR (modules that FOCUS_DIR imports) and include them in the processing order, but skip modules that are neither inside FOCUS_DIR nor dependencies of it.
+
+Scan and catalog:
+
+1. Directory tree (ignore `node_modules`, `.git`, `__pycache__`, `bin/`, `obj/`, build artifacts)
+2. Language detection from file extensions and config files
+3. Package manifests: `package.json`, `requirements.txt`, `pyproject.toml`, `*.csproj`, `Cargo.toml`, `go.mod`
+4. Config files: `Dockerfile`, `docker-compose.yml`, `.env.example`, CI/CD configs (`.github/workflows/`, `.gitlab-ci.yml`, `azure-pipelines.yml`)
+5. Entry points: `main.*`, `app.*`, `index.*`, `Program.*`, startup scripts
+6. Test structure: test directories, test frameworks, test runner configs
+7. Existing documentation: README, `docs/`, wiki references, inline doc coverage
+8. **Dependency graph**: build a module-level dependency graph by analyzing imports/references. Identify:
+   - Leaf modules (no internal dependencies)
+   - Entry points (no internal dependents)
+   - Cycles (mark for grouped analysis)
+   - Topological processing order
+   - If FOCUS_DIR: mark which modules are in-scope vs dependency-only
+
+**Save**: `DOCUMENT_DIR/00_discovery.md` containing:
+- Directory tree (concise, relevant directories only)
+- Tech stack summary table (language, framework, database, infra)
+- Dependency graph (textual list + Mermaid diagram)
+- Topological processing order
+- Entry points and leaf modules
+
+**Save**: `DOCUMENT_DIR/state.json` with initial state:
+```json
+{
+  "current_step": "module-analysis",
+  "completed_steps": ["discovery"],
+  "focus_dir": null,
+  "modules_total": 0,
+  "modules_documented": [],
+  "modules_remaining": [],
+  "module_batch": 0,
+  "components_written": [],
+  "last_updated": ""
+}
+```
+
+Set `focus_dir` to the FOCUS_DIR path if in Focus Area mode, or `null` for Full mode.
+
+---
+
+### Step 1: Module-Level Documentation
+
+**Role**: Code analyst
+**Goal**: Document every identified module individually, processing in topological order (leaves first).
+
+**Batched processing**: process modules in batches of ~5 (sorted by topological order). After each batch: save all module docs, update `state.json`, present a progress summary. Between batches, evaluate whether to suggest a session break.
+
+For each module in topological order:
+
+1. **Read**: read the module's source code. Assess complexity and what context is needed.
+2. **Gather context**: collect already-written docs of this module's dependencies (available because of bottom-up order). Note external library usage.
+3. **Write module doc** with these sections:
+   - **Purpose**: one-sentence responsibility
+   - **Public interface**: exported functions/classes/methods with signatures, input/output types
+   - **Internal logic**: key algorithms, patterns, non-obvious behavior
+   - **Dependencies**: what it imports internally and why
+   - **Consumers**: what uses this module (from the dependency graph)
+   - **Data models**: entities/types defined in this module
+   - **Configuration**: env vars, config keys consumed
+   - **External integrations**: HTTP calls, DB queries, queue operations, file I/O
+   - **Security**: auth checks, encryption, input validation, secrets access
+   - **Tests**: what tests exist for this module, what they cover
+4. **Verify**: cross-check that every entity referenced in the doc exists in the codebase. Flag uncertainties.
+
+**Cycle handling**: modules in a dependency cycle are analyzed together as a group, producing a single combined doc.
+
+**Large modules**: if a module exceeds comfortable analysis size, split into logical sub-sections and analyze each part, then combine.
+
+**Save**: `DOCUMENT_DIR/modules/[module_name].md` for each module.
+**State**: update `state.json` after each module completes (move from `modules_remaining` to `modules_documented`). Increment `module_batch` after each batch of ~5.
+
+**Session break heuristic**: after each batch, if more than 10 modules remain AND 2+ batches have already completed in this session, suggest a session break:
+
+```
+══════════════════════════════════════
+ SESSION BREAK SUGGESTED
+══════════════════════════════════════
+ Modules documented: [X] of [Y]
+ Batches completed this session: [N]
+══════════════════════════════════════
+ A) Continue in this conversation
+ B) Save and continue in a fresh conversation (recommended)
+══════════════════════════════════════
+ Recommendation: B — fresh context improves
+ analysis quality for remaining modules
+══════════════════════════════════════
+```
+
+Re-entry is seamless: `state.json` tracks exactly which modules are done.
+
+---
+
+### Step 2: Component Assembly
+
+**Role**: Software architect
+**Goal**: Group related modules into logical components and produce component specs.
+
+1. Analyze module docs from Step 1 to identify natural groupings:
+   - By directory structure (most common)
+   - By shared data models or common purpose
+   - By dependency clusters (tightly coupled modules)
+2. For each identified component, synthesize its module docs into a single component specification using `templates/component-spec.md` as structure:
+   - High-level overview: purpose, pattern, upstream/downstream
+   - Internal interfaces: method signatures, DTOs (from actual module code)
+   - External API specification (if the component exposes HTTP/gRPC endpoints)
+   - Data access patterns: queries, caching, storage estimates
+   - Implementation details: algorithmic complexity, state management, key libraries
+   - Extensions and helpers: shared utilities needed
+   - Caveats and edge cases: limitations, race conditions, bottlenecks
+   - Dependency graph: implementation order relative to other components
+   - Logging strategy
+3. Identify common helpers shared across multiple components -> document in `common-helpers/`
+4. Generate component relationship diagram (Mermaid)
+
+**Self-verification**:
+- [ ] Every module from Step 1 is covered by exactly one component
+- [ ] No component has overlapping responsibility with another
+- [ ] Inter-component interfaces are explicit (who calls whom, with what)
+- [ ] Component dependency graph has no circular dependencies
+
+**Save**:
+- `DOCUMENT_DIR/components/[##]_[name]/description.md` per component
+- `DOCUMENT_DIR/common-helpers/[##]_helper_[name].md` per shared helper
+- `DOCUMENT_DIR/diagrams/components.md` (Mermaid component diagram)
+
+**BLOCKING**: Present component list with one-line summaries to user. Do NOT proceed until user confirms the component breakdown is correct.
+
+---
+
+### Step 3: System-Level Synthesis
+
+**Role**: Software architect
+**Goal**: From component docs, synthesize system-level documents.
+
+All documents here are derived from component docs (Step 2) + module docs (Step 1). No new code reading should be needed. If it is, that indicates a gap in Steps 1-2 — go back and fill it.
+
+#### 3a. Architecture
+
+Using `templates/architecture.md` as structure:
+
+- System context and boundaries from entry points and external integrations
+- Tech stack table from discovery (Step 0) + component specs
+- Deployment model from Dockerfiles, CI configs, environment strategies
+- Data model overview from per-component data access sections
+- Integration points from inter-component interfaces
+- NFRs from test thresholds, config limits, health checks
+- Security architecture from per-module security observations
+- Key ADRs inferred from technology choices and patterns
+
+**Save**: `DOCUMENT_DIR/architecture.md`
+
+#### 3b. System Flows
+
+Using `templates/system-flows.md` as structure:
+
+- Trace main flows through the component interaction graph
+- Entry point -> component chain -> output for each major flow
+- Mermaid sequence diagrams and flowcharts
+- Error scenarios from exception handling patterns
+- Data flow tables per flow
+
+**Save**: `DOCUMENT_DIR/system-flows.md` and `DOCUMENT_DIR/diagrams/flows/flow_[name].md`
+
+#### 3c. Data Model
+
+- Consolidate all data models from module docs
+- Entity-relationship diagram (Mermaid ERD)
+- Migration strategy (if ORM/migration tooling detected)
+- Seed data observations
+- Backward compatibility approach (if versioning found)
+
+**Save**: `DOCUMENT_DIR/data_model.md`
+
+#### 3d. Deployment (if Dockerfile/CI configs exist)
+
+- Containerization summary
+- CI/CD pipeline structure
+- Environment strategy (dev, staging, production)
+- Observability (logging patterns, metrics, health checks found in code)
+
+**Save**: `DOCUMENT_DIR/deployment/` (containerization.md, ci_cd_pipeline.md, environment_strategy.md, observability.md — only files for which sufficient code evidence exists)
+
+---
+
+### Step 4: Verification Pass
+
+**Role**: Quality verifier
+**Goal**: Compare every generated document against actual code. Fix hallucinations, fill gaps, correct inaccuracies.
+
+For each document generated in Steps 1-3:
+
+1. **Entity verification**: extract all code entities (class names, function names, module names, endpoints) mentioned in the doc. Cross-reference each against the actual codebase. Flag any that don't exist.
+2. **Interface accuracy**: for every method signature, DTO, or API endpoint in component specs, verify it matches actual code.
+3. **Flow correctness**: for each system flow diagram, trace the actual code path and verify the sequence matches.
+4. **Completeness check**: are there modules or components discovered in Step 0 that aren't covered by any document? Flag gaps.
+5. **Consistency check**: do component docs agree with architecture doc? Do flow diagrams match component interfaces?
+
+Apply corrections inline to the documents that need them.
+
+**Save**: `DOCUMENT_DIR/04_verification_log.md` with:
+- Total entities verified vs flagged
+- Corrections applied (which document, what changed)
+- Remaining gaps or uncertainties
+- Completeness score (modules covered / total modules)
+
+**BLOCKING**: Present verification summary to user. Do NOT proceed until user confirms corrections are acceptable or requests additional fixes.
+
+**Session boundary**: After verification is confirmed, suggest a session break before proceeding to the synthesis steps (5–7). These steps produce different artifact types and benefit from fresh context:
+
+```
+══════════════════════════════════════
+ VERIFICATION COMPLETE — session break?
+══════════════════════════════════════
+ Steps 0–4 (analysis + verification) are done.
+ Steps 5–7 (solution + problem extraction + report)
+ can run in a fresh conversation.
+══════════════════════════════════════
+ A) Continue in this conversation
+ B) Save and continue in a new conversation (recommended)
+══════════════════════════════════════
+```
+
+If **Focus Area mode**: Steps 5–7 are skipped (they require full codebase coverage). Present a summary of modules and components documented for this area. The user can run `/document` again for another area, or run without FOCUS_DIR once all areas are covered to produce the full synthesis.
+
+---
+
+### Step 5: Solution Extraction (Retrospective)
+
+**Role**: Software architect
+**Goal**: From all verified technical documentation, retrospectively create `solution.md` — the same artifact the research skill produces. This makes downstream skills (`plan`, `deploy`, `decompose`) compatible with the documented codebase.
+
+Synthesize from architecture (Step 3) + component specs (Step 2) + system flows (Step 3) + verification findings (Step 4):
+
+1. **Product Solution Description**: what the system is, brief component interaction diagram (Mermaid)
+2. **Architecture**: the architecture that is implemented, with per-component solution tables:
+
+| Solution | Tools | Advantages | Limitations | Requirements | Security | Cost | Fit |
+|----------|-------|-----------|-------------|-------------|----------|------|-----|
+| [actual implementation] | [libs/platforms used] | [observed strengths] | [observed limitations] | [requirements met] | [security approach] | [cost indicators] | [fitness assessment] |
+
+3. **Testing Strategy**: summarize integration/functional tests and non-functional tests found in the codebase
+4. **References**: links to key config files, Dockerfiles, CI configs that evidence the solution choices
+
+**Save**: `SOLUTION_DIR/solution.md` (`_docs/01_solution/solution.md`)
+
+---
+
+### Step 6: Problem Extraction (Retrospective)
+
+**Role**: Business analyst
+**Goal**: From all verified technical docs, retrospectively derive the high-level problem definition — producing the same documents the `problem` skill creates through interview.
+
+This is the inverse of normal workflow: instead of problem -> solution -> code, we go code -> technical docs -> problem understanding.
+
+#### 6a. `problem.md`
+
+- Synthesize from architecture overview + component purposes + system flows
+- What is this system? What problem does it solve? Who are the users? How does it work at a high level?
+- Cross-reference with README if one exists
+- Free-form text, concise, readable by someone unfamiliar with the project
+
+#### 6b. `restrictions.md`
+
+- Extract from: tech stack choices, Dockerfile specs (OS, base images), CI configs (platform constraints), dependency versions, environment configs
+- Categorize with headers: Hardware, Software, Environment, Operational
+- Each restriction should be specific and testable
+
+#### 6c. `acceptance_criteria.md`
+
+- Derive from: test assertions (expected values, thresholds), performance configs (timeouts, rate limits, batch sizes), health check endpoints, validation rules in code
+- Categorize with headers by domain
+- Every criterion must have a measurable value — if only implied, note the source
+
+#### 6d. `input_data/`
+
+- Document data schemas found (DB schemas, API request/response types, config file formats)
+- Create `data_parameters.md` describing what data the system consumes, formats, volumes, update patterns
+
+#### 6e. `security_approach.md` (only if security code found)
+
+- Authentication mechanisms, authorization patterns, encryption, secrets handling, CORS, rate limiting, input sanitization — all from code observations
+- If no security-relevant code found, skip this file
+
+**Save**: all files to `PROBLEM_DIR/` (`_docs/00_problem/`)
+
+**BLOCKING**: Present all problem documents to user. These are the most abstracted and therefore most prone to interpretation error. Do NOT proceed until user confirms or requests corrections.
+
+---
+
+### Step 7: Final Report
+
+**Role**: Technical writer
+**Goal**: Produce `FINAL_report.md` integrating all generated documentation.
+
+Using `templates/final-report.md` as structure:
+
+- Executive summary from architecture + problem docs
+- Problem statement (transformed from problem.md, not copy-pasted)
+- Architecture overview with tech stack one-liner
+- Component summary table (number, name, purpose, dependencies)
+- System flows summary table
+- Risk observations from verification log (Step 4)
+- Open questions (uncertainties flagged during analysis)
+- Artifact index listing all generated documents with paths
+
+**Save**: `DOCUMENT_DIR/FINAL_report.md`
+
+**State**: update `state.json` with `current_step: "complete"`.
+
+---
+
+## Artifact Management
+
+### Directory Structure
+
+```
+_docs/
+├── 00_problem/                          # Step 6 (retrospective)
+│   ├── problem.md
+│   ├── restrictions.md
+│   ├── acceptance_criteria.md
+│   ├── input_data/
+│   │   └── data_parameters.md
+│   └── security_approach.md
+├── 01_solution/                         # Step 5 (retrospective)
+│   └── solution.md
+└── 02_document/                         # DOCUMENT_DIR
+    ├── 00_discovery.md                  # Step 0
+    ├── modules/                         # Step 1
+    │   ├── [module_name].md
+    │   └── ...
+    ├── components/                      # Step 2
+    │   ├── 01_[name]/description.md
+    │   ├── 02_[name]/description.md
+    │   └── ...
+    ├── common-helpers/                  # Step 2
+    ├── architecture.md                  # Step 3
+    ├── system-flows.md                  # Step 3
+    ├── data_model.md                    # Step 3
+    ├── deployment/                      # Step 3
+    ├── diagrams/                        # Steps 2-3
+    │   ├── components.md
+    │   └── flows/
+    ├── 04_verification_log.md           # Step 4
+    ├── FINAL_report.md                  # Step 7
+    └── state.json                       # Resumability
+```
+
+### Resumability
+
+Maintain `DOCUMENT_DIR/state.json`:
+
+```json
+{
+  "current_step": "module-analysis",
+  "completed_steps": ["discovery"],
+  "focus_dir": null,
+  "modules_total": 12,
+  "modules_documented": ["utils/helpers", "models/user"],
+  "modules_remaining": ["services/auth", "api/endpoints"],
+  "module_batch": 1,
+  "components_written": [],
+  "last_updated": "2026-03-21T14:00:00Z"
+}
+```
+
+Update after each module/component completes. If interrupted, resume from next undocumented module.
+
+When resuming:
+1. Read `state.json`
+2. Cross-check against actual files in DOCUMENT_DIR (trust files over state if they disagree)
+3. Continue from the next incomplete item
+4. Inform user which steps are being skipped
+
+### Save Principles
+
+1. **Save immediately**: write each module doc as soon as analysis completes
+2. **Incremental context**: each subsequent module uses already-written docs as context
+3. **Preserve intermediates**: keep all module docs even after synthesis into component docs
+4. **Enable recovery**: state file tracks exact progress for resume
+
+## Escalation Rules
+
+| Situation | Action |
+|-----------|--------|
+| Minified/obfuscated code detected | WARN user, skip module, note in verification log |
+| Module too large for context window | Split into sub-sections, analyze parts separately, combine |
+| Cycle in dependency graph | Group cycled modules, analyze together as one doc |
+| Generated code (protobuf, swagger-gen) | Note as generated, document the source spec instead |
+| No tests found in codebase | Note gap in acceptance_criteria.md, derive AC from validation rules and config limits only |
+| Contradictions between code and README | Flag in verification log, ASK user |
+| Binary files or non-code assets | Skip, note in discovery |
+| `_docs/` already exists | ASK user: overwrite, merge, or use `_docs_generated/` |
+| Code intent is ambiguous | ASK user, do not guess |
+
+## Common Mistakes
+
+- **Top-down guessing**: never infer architecture before documenting modules. Build up, don't assume down.
+- **Hallucinating entities**: always verify that referenced classes/functions/endpoints actually exist in code.
+- **Skipping modules**: every source module must appear in exactly one module doc and one component.
+- **Monolithic analysis**: don't try to analyze the entire codebase in one pass. Module by module, in order.
+- **Inventing restrictions**: only document constraints actually evidenced in code, configs, or Dockerfiles.
+- **Vague acceptance criteria**: "should be fast" is not a criterion. Extract actual numeric thresholds from code.
+- **Writing code**: this skill produces documents, never implementation code.
+
+## Methodology Quick Reference
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│          Bottom-Up Codebase Documentation (8-Step)               │
+├──────────────────────────────────────────────────────────────────┤
+│ MODE: Full / Focus Area (@dir) / Resume (state.json)             │
+│ PREREQ: Check _docs/ exists (overwrite/merge/new?)               │
+│ PREREQ: Check state.json for resume                              │
+│                                                                  │
+│ 0. Discovery          → dependency graph, tech stack, topo order │
+│    (Focus Area: scoped to FOCUS_DIR + transitive deps)           │
+│ 1. Module Docs        → per-module analysis (leaves first)       │
+│    (batched ~5 modules; session break between batches)           │
+│ 2. Component Assembly → group modules, write component specs     │
+│    [BLOCKING: user confirms components]                          │
+│ 3. System Synthesis   → architecture, flows, data model, deploy  │
+│ 4. Verification       → compare all docs vs code, fix errors     │
+│    [BLOCKING: user reviews corrections]                          │
+│    [SESSION BREAK suggested before Steps 5–7]                    │
+│    ── Focus Area mode stops here ──                              │
+│ 5. Solution Extraction → retrospective solution.md               │
+│ 6. Problem Extraction → retrospective problem, restrictions, AC  │
+│    [BLOCKING: user confirms problem docs]                        │
+│ 7. Final Report       → FINAL_report.md                          │
+├──────────────────────────────────────────────────────────────────┤
+│ Principles: Bottom-up always · Dependencies first                │
+│             Incremental context · Verify against code            │
+│             Save immediately · Resume from checkpoint            │
+│             Batch modules · Session breaks for large codebases   │
+└──────────────────────────────────────────────────────────────────┘
+```

.cursor/skills/implement/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: implement
+description: |
+  Orchestrate task implementation with dependency-aware batching, parallel subagents, and integrated code review.
+  Reads flat task files and _dependencies_table.md from TASKS_DIR, computes execution batches via topological sort,
+  launches up to 4 implementer subagents in parallel, runs code-review skill after each batch, and loops until done.
+  Use after /decompose has produced task files.
+  Trigger phrases:
+  - "implement", "start implementation", "implement tasks"
+  - "run implementers", "execute tasks"
+category: build
+tags: [implementation, orchestration, batching, parallel, code-review]
+disable-model-invocation: true
+---
+
+# Implementation Orchestrator
+
+Orchestrate the implementation of all tasks produced by the `/decompose` skill. This skill is a **pure orchestrator** — it does NOT write implementation code itself. It reads task specs, computes execution order, delegates to `implementer` subagents, validates results via the `/code-review` skill, and escalates issues.
+
+The `implementer` agent is the specialist that writes all the code — it receives a task spec, analyzes the codebase, implements the feature, writes tests, and verifies acceptance criteria.
+
+## Core Principles
+
+- **Orchestrate, don't implement**: this skill delegates all coding to `implementer` subagents
+- **Dependency-aware batching**: tasks run only when all their dependencies are satisfied
+- **Max 4 parallel agents**: never launch more than 4 implementer subagents simultaneously
+- **File isolation**: no two parallel agents may write to the same file
+- **Integrated review**: `/code-review` skill runs automatically after each batch
+- **Auto-start**: batches launch immediately — no user confirmation before a batch
+- **Gate on failure**: user confirmation is required only when code review returns FAIL
+- **Commit and push per batch**: after each batch is confirmed, commit and push to remote
+
+## Context Resolution
+
+- TASKS_DIR: `_docs/02_tasks/`
+- Task files: all `*.md` files in TASKS_DIR (excluding files starting with `_`)
+- Dependency table: `TASKS_DIR/_dependencies_table.md`
+
+## Prerequisite Checks (BLOCKING)
+
+1. TASKS_DIR exists and contains at least one task file — **STOP if missing**
+2. `_dependencies_table.md` exists — **STOP if missing**
+3. At least one task is not yet completed — **STOP if all done**
+
+## Algorithm
+
+### 1. Parse
+
+- Read all task `*.md` files from TASKS_DIR (excluding files starting with `_`)
+- Read `_dependencies_table.md` — parse into a dependency graph (DAG)
+- Validate: no circular dependencies, all referenced dependencies exist
+
+### 2. Detect Progress
+
+- Scan the codebase to determine which tasks are already completed
+- Match implemented code against task acceptance criteria
+- Mark completed tasks as done in the DAG
+- Report progress to user: "X of Y tasks completed"
+
+### 3. Compute Next Batch
+
+- Topological sort remaining tasks
+- Select tasks whose dependencies are ALL satisfied (completed)
+- If a ready task depends on any task currently being worked on in this batch, it must wait for the next batch
+- Cap the batch at 4 parallel agents
+- If the batch would exceed 20 total complexity points, suggest splitting and let the user decide
+
+### 4. Assign File Ownership
+
+For each task in the batch:
+- Parse the task spec's Component field and Scope section
+- Map the component to directories/files in the project
+- Determine: files OWNED (exclusive write), files READ-ONLY (shared interfaces, types), files FORBIDDEN (other agents' owned files)
+- If two tasks in the same batch would modify the same file, schedule them sequentially instead of in parallel
+
+### 5. Update Tracker Status → In Progress
+
+For each task in the batch, transition its ticket status to **In Progress** via the configured work item tracker (Jira MCP or Azure DevOps MCP — see `protocols.md` for detection) before launching the implementer. If `tracker: local`, skip this step.
+
+### 6. Launch Implementer Subagents
+
+For each task in the batch, launch an `implementer` subagent with:
+- Path to the task spec file
+- List of files OWNED (exclusive write access)
+- List of files READ-ONLY
+- List of files FORBIDDEN
+
+Launch all subagents immediately — no user confirmation.
+
+### 7. Monitor
+
+- Wait for all subagents to complete
+- Collect structured status reports from each implementer
+- If any implementer reports "Blocked", log the blocker and continue with others
+
+**Stuck detection** — while monitoring, watch for these signals per subagent:
+- Same file modified 3+ times without test pass rate improving → flag as stuck, stop the subagent, report as Blocked
+- Subagent has not produced new output for an extended period → flag as potentially hung
+- If a subagent is flagged as stuck, do NOT let it continue looping — stop it and record the blocker in the batch report
+
+### 8. Code Review
+
+- Run `/code-review` skill on the batch's changed files + corresponding task specs
+- The code-review skill produces a verdict: PASS, PASS_WITH_WARNINGS, or FAIL
+
+### 9. Auto-Fix Gate
+
+Auto-fix loop with bounded retries (max 2 attempts) before escalating to user:
+
+1. If verdict is **PASS** or **PASS_WITH_WARNINGS**: show findings as info, continue automatically to step 10
+2. If verdict is **FAIL** (attempt 1 or 2):
+   - Parse the code review findings (Critical and High severity items)
+   - For each finding, attempt an automated fix using the finding's location, description, and suggestion
+   - Re-run `/code-review` on the modified files
+   - If now PASS or PASS_WITH_WARNINGS → continue to step 10
+   - If still FAIL → increment retry counter, repeat from (2) up to max 2 attempts
+3. If still **FAIL** after 2 auto-fix attempts: present all findings to user (**BLOCKING**). User must confirm fixes or accept before proceeding.
+
+Track `auto_fix_attempts` count in the batch report for retrospective analysis.
+
+### 10. Test
+
+- Run the full test suite
+- If failures: report to user with details
+
+### 11. Commit and Push
+
+- After user confirms the batch (explicitly for FAIL, implicitly for PASS/PASS_WITH_WARNINGS):
+  - `git add` all changed files from the batch
+  - `git commit` with a message that includes ALL task IDs (Jira IDs, ADO IDs, or numeric prefixes) of tasks implemented in the batch, followed by a summary of what was implemented. Format: `[TASK-ID-1] [TASK-ID-2] ... Summary of changes`
+  - `git push` to the remote branch
+
+### 12. Update Tracker Status → In Testing
+
+After the batch is committed and pushed, transition the ticket status of each task in the batch to **In Testing** via the configured work item tracker. If `tracker: local`, skip this step.
+
+### 13. Loop
+
+- Go back to step 2 until all tasks are done
+- When all tasks are complete, report final summary
+
+## Batch Report Persistence
+
+After each batch completes, save the batch report to `_docs/03_implementation/batch_[NN]_report.md`. Create the directory if it doesn't exist. When all tasks are complete, produce `_docs/03_implementation/FINAL_implementation_report.md` with a summary of all batches.
+
+## Batch Report
+
+After each batch, produce a structured report:
+
+```markdown
+# Batch Report
+
+**Batch**: [N]
+**Tasks**: [list]
+**Date**: [YYYY-MM-DD]
+
+## Task Results
+
+| Task | Status | Files Modified | Tests | Issues |
+|------|--------|---------------|-------|--------|
+| [JIRA-ID]_[name] | Done | [count] files | [pass/fail] | [count or None] |
+
+## Code Review Verdict: [PASS/FAIL/PASS_WITH_WARNINGS]
+## Auto-Fix Attempts: [0/1/2]
+## Stuck Agents: [count or None]
+
+## Next Batch: [task list] or "All tasks complete"
+```
+
+## Stop Conditions and Escalation
+
+| Situation | Action |
+|-----------|--------|
+| Implementer fails same approach 3+ times | Stop it, escalate to user |
+| Task blocked on external dependency (not in task list) | Report and skip |
+| File ownership conflict unresolvable | ASK user |
+| Test failures exceed 50% of suite after a batch | Stop and escalate |
+| All tasks complete | Report final summary, suggest final commit |
+| `_dependencies_table.md` missing | STOP — run `/decompose` first |
+
+## Recovery
+
+Each batch commit serves as a rollback checkpoint. If recovery is needed:
+
+- **Tests fail after a batch commit**: `git revert <batch-commit-hash>` using the hash from the batch report in `_docs/03_implementation/`
+- **Resuming after interruption**: Read `_docs/03_implementation/batch_*_report.md` files to determine which batches completed, then continue from the next batch
+- **Multiple consecutive batches fail**: Stop and escalate to user with links to batch reports and commit hashes
+
+## Safety Rules
+
+- Never launch tasks whose dependencies are not yet completed
+- Never allow two parallel agents to write to the same file
+- If a subagent fails or is flagged as stuck, stop it and report — do not let it loop indefinitely
+- Always run tests after each batch completes

.cursor/skills/implement/references/batching-algorithm.md

@@ -0,0 +1,31 @@
+# Batching Algorithm Reference
+
+## Topological Sort with Batch Grouping
+
+The `/implement` skill uses a topological sort to determine execution order,
+then groups tasks into batches for parallel execution.
+
+## Algorithm
+
+1. Build adjacency list from `_dependencies_table.md`
+2. Compute in-degree for each task node
+3. Initialize batch 0 with all nodes that have in-degree 0
+4. For each batch:
+   a. Select up to 4 tasks from the ready set
+   b. Check file ownership — if two tasks would write the same file, defer one to the next batch
+   c. Launch selected tasks as parallel implementer subagents
+   d. When all complete, remove them from the graph and decrement in-degrees of dependents
+   e. Add newly zero-in-degree nodes to the next batch's ready set
+5. Repeat until the graph is empty
+
+## File Ownership Conflict Resolution
+
+When two tasks in the same batch map to overlapping files:
+- Prefer to run the lower-numbered task first (it's more foundational)
+- Defer the higher-numbered task to the next batch
+- If both have equal priority, ask the user
+
+## Complexity Budget
+
+Each batch should not exceed 20 total complexity points.
+If it does, split the batch and let the user choose which tasks to include.

.cursor/skills/implement/templates/batch-report.md

@@ -0,0 +1,36 @@
+# Batch Report Template
+
+Use this template after each implementation batch completes.
+
+---
+
+```markdown
+# Batch Report
+
+**Batch**: [N]
+**Tasks**: [list of task names]
+**Date**: [YYYY-MM-DD]
+
+## Task Results
+
+| Task | Status | Files Modified | Tests | Issues |
+|------|--------|---------------|-------|--------|
+| [JIRA-ID]_[name] | Done/Blocked/Partial | [count] files | [X/Y pass] | [count or None] |
+
+## Code Review Verdict: [PASS / FAIL / PASS_WITH_WARNINGS]
+
+[Link to code review report if FAIL or PASS_WITH_WARNINGS]
+
+## Test Suite
+
+- Total: [N] tests
+- Passed: [N]
+- Failed: [N]
+- Skipped: [N]
+
+## Commit
+
+[Suggested commit message]
+
+## Next Batch: [task list] or "All tasks complete"
+```

.cursor/skills/new-task/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: new-task
+description: |
+  Interactive skill for adding new functionality to an existing codebase.
+  Guides the user through describing the feature, assessing complexity,
+  optionally running research, analyzing the codebase for insertion points,
+  validating assumptions with the user, and producing a task spec with Jira ticket.
+  Supports a loop — the user can add multiple tasks in one session.
+  Trigger phrases:
+  - "new task", "add feature", "new functionality"
+  - "I want to add", "new component", "extend"
+category: build
+tags: [task, feature, interactive, planning, jira]
+disable-model-invocation: true
+---
+
+# New Task (Interactive Feature Planning)
+
+Guide the user through defining new functionality for an existing codebase. Produces one or more task specifications with Jira tickets, optionally running deep research for complex features.
+
+## Core Principles
+
+- **User-driven**: every task starts with the user's description; never invent requirements
+- **Right-size research**: only invoke the research skill when the change is big enough to warrant it
+- **Validate before committing**: surface all assumptions and uncertainties to the user before writing the task file
+- **Save immediately**: write task files to disk as soon as they are ready; never accumulate unsaved work
+- **Ask, don't assume**: when scope, insertion point, or approach is unclear, STOP and ask the user
+
+## Context Resolution
+
+Fixed paths:
+
+- TASKS_DIR: `_docs/02_tasks/`
+- PLANS_DIR: `_docs/02_task_plans/`
+- DOCUMENT_DIR: `_docs/02_document/`
+- DEPENDENCIES_TABLE: `_docs/02_tasks/_dependencies_table.md`
+
+Create TASKS_DIR and PLANS_DIR if they don't exist.
+
+If TASKS_DIR already contains task files, scan them to determine the next numeric prefix for temporary file naming.
+
+## Workflow
+
+The skill runs as a loop. Each iteration produces one task. After each task the user chooses to add another or finish.
+
+---
+
+### Step 1: Gather Feature Description
+
+**Role**: Product analyst
+**Goal**: Get a clear, detailed description of the new functionality from the user.
+
+Ask the user:
+
+```
+══════════════════════════════════════
+ NEW TASK: Describe the functionality
+══════════════════════════════════════
+ Please describe in detail the new functionality you want to add:
+ - What should it do?
+ - Who is it for?
+ - Any specific requirements or constraints?
+══════════════════════════════════════
+```
+
+**BLOCKING**: Do NOT proceed until the user provides a description.
+
+Record the description verbatim for use in subsequent steps.
+
+---
+
+### Step 2: Analyze Complexity
+
+**Role**: Technical analyst
+**Goal**: Determine whether deep research is needed.
+
+Read the user's description and the existing codebase documentation from DOCUMENT_DIR (architecture.md, components/, system-flows.md).
+
+Assess the change along these dimensions:
+- **Scope**: how many components/files are affected?
+- **Novelty**: does it involve libraries, protocols, or patterns not already in the codebase?
+- **Risk**: could it break existing functionality or require architectural changes?
+
+Classification:
+
+| Category | Criteria | Action |
+|----------|----------|--------|
+| **Needs research** | New libraries/frameworks, unfamiliar protocols, significant architectural change, multiple unknowns | Proceed to Step 3 (Research) |
+| **Skip research** | Extends existing functionality, uses patterns already in codebase, straightforward new component with known tech | Skip to Step 4 (Codebase Analysis) |
+
+Present the assessment to the user:
+
+```
+══════════════════════════════════════
+ COMPLEXITY ASSESSMENT
+══════════════════════════════════════
+ Scope:   [low / medium / high]
+ Novelty: [low / medium / high]
+ Risk:    [low / medium / high]
+══════════════════════════════════════
+ Recommendation: [Research needed / Skip research]
+ Reason: [one-line justification]
+══════════════════════════════════════
+```
+
+**BLOCKING**: Ask the user to confirm or override the recommendation before proceeding.
+
+---
+
+### Step 3: Research (conditional)
+
+**Role**: Researcher
+**Goal**: Investigate unknowns before task specification.
+
+This step only runs if Step 2 determined research is needed.
+
+1. Create a problem description file at `PLANS_DIR/<task_slug>/problem.md` summarizing the feature request and the specific unknowns to investigate
+2. Invoke `.cursor/skills/research/SKILL.md` in standalone mode:
+   - INPUT_FILE: `PLANS_DIR/<task_slug>/problem.md`
+   - BASE_DIR: `PLANS_DIR/<task_slug>/`
+3. After research completes, read the solution draft from `PLANS_DIR/<task_slug>/01_solution/solution_draft01.md`
+4. Extract the key findings relevant to the task specification
+
+The `<task_slug>` is a short kebab-case name derived from the feature description (e.g., `auth-provider-integration`, `real-time-notifications`).
+
+---
+
+### Step 4: Codebase Analysis
+
+**Role**: Software architect
+**Goal**: Determine where and how to insert the new functionality.
+
+1. Read the codebase documentation from DOCUMENT_DIR:
+   - `architecture.md` — overall structure
+   - `components/` — component specs
+   - `system-flows.md` — data flows (if exists)
+   - `data_model.md` — data model (if exists)
+2. If research was performed (Step 3), incorporate findings
+3. Analyze and determine:
+   - Which existing components are affected
+   - Where new code should be inserted (which layers, modules, files)
+   - What interfaces need to change
+   - What new interfaces or models are needed
+   - How data flows through the change
+4. If the change is complex enough, read the actual source files (not just docs) to verify insertion points
+
+Present the analysis:
+
+```
+══════════════════════════════════════
+ CODEBASE ANALYSIS
+══════════════════════════════════════
+ Affected components: [list]
+ Insertion points:    [list of modules/layers]
+ Interface changes:   [list or "None"]
+ New interfaces:      [list or "None"]
+ Data flow impact:    [summary]
+══════════════════════════════════════
+```
+
+---
+
+### Step 5: Validate Assumptions
+
+**Role**: Quality gate
+**Goal**: Surface every uncertainty and get user confirmation.
+
+Review all decisions and assumptions made in Steps 2–4. For each uncertainty:
+1. State the assumption clearly
+2. Propose a solution or approach
+3. List alternatives if they exist
+
+Present using the Choose format for each decision that has meaningful alternatives:
+
+```
+══════════════════════════════════════
+ ASSUMPTION VALIDATION
+══════════════════════════════════════
+ 1. [Assumption]: [proposed approach]
+    Alternative: [other option, if any]
+ 2. [Assumption]: [proposed approach]
+    Alternative: [other option, if any]
+ ...
+══════════════════════════════════════
+ Please confirm or correct these assumptions.
+══════════════════════════════════════
+```
+
+**BLOCKING**: Do NOT proceed until the user confirms or corrects all assumptions.
+
+---
+
+### Step 6: Create Task
+
+**Role**: Technical writer
+**Goal**: Produce the task specification file.
+
+1. Determine the next numeric prefix by scanning TASKS_DIR for existing files
+2. Write the task file using `.cursor/skills/decompose/templates/task.md`:
+   - Fill all fields from the gathered information
+   - Set **Complexity** based on the assessment from Step 2
+   - Set **Dependencies** by cross-referencing existing tasks in TASKS_DIR
+   - Set **Jira** and **Epic** to `pending` (filled in Step 7)
+3. Save as `TASKS_DIR/[##]_[short_name].md`
+
+**Self-verification**:
+- [ ] Problem section clearly describes the user need
+- [ ] Acceptance criteria are testable (Gherkin format)
+- [ ] Scope boundaries are explicit
+- [ ] Complexity points match the assessment
+- [ ] Dependencies reference existing task Jira IDs where applicable
+- [ ] No implementation details leaked into the spec
+
+---
+
+### Step 7: Work Item Ticket
+
+**Role**: Project coordinator
+**Goal**: Create a work item ticket and link it to the task file.
+
+1. Create a ticket via the configured work item tracker (Jira MCP or Azure DevOps MCP — see `autopilot/protocols.md` for detection):
+   - Summary: the task's **Name** field
+   - Description: the task's **Problem** and **Acceptance Criteria** sections
+   - Story points: the task's **Complexity** value
+   - Link to the appropriate epic (ask user if unclear which epic)
+2. Write the ticket ID and Epic ID back into the task file header:
+   - Update **Task** field: `[TICKET-ID]_[short_name]`
+   - Update **Jira** field: `[TICKET-ID]`
+   - Update **Epic** field: `[EPIC-ID]`
+3. Rename the file from `[##]_[short_name].md` to `[TICKET-ID]_[short_name].md`
+
+If the work item tracker is not authenticated or unavailable (`tracker: local`):
+- Keep the numeric prefix
+- Set **Jira** to `pending`
+- Set **Epic** to `pending`
+- The task is still valid and can be implemented; tracker sync happens later
+
+---
+
+### Step 8: Loop Gate
+
+Ask the user:
+
+```
+══════════════════════════════════════
+ Task created: [JIRA-ID or ##] — [task name]
+══════════════════════════════════════
+ A) Add another task
+ B) Done — finish and update dependencies
+══════════════════════════════════════
+```
+
+- If **A** → loop back to Step 1
+- If **B** → proceed to Finalize
+
+---
+
+### Finalize
+
+After the user chooses **Done**:
+
+1. Update (or create) `TASKS_DIR/_dependencies_table.md` — add all newly created tasks to the dependencies table
+2. Present a summary of all tasks created in this session:
+
+```
+══════════════════════════════════════
+ NEW TASK SUMMARY
+══════════════════════════════════════
+ Tasks created: N
+ Total complexity: M points
+ ─────────────────────────────────────
+ [JIRA-ID] [name] ([complexity] pts)
+ [JIRA-ID] [name] ([complexity] pts)
+ ...
+══════════════════════════════════════
+```
+
+## Escalation Rules
+
+| Situation | Action |
+|-----------|--------|
+| User description is vague or incomplete | **ASK** for more detail — do not guess |
+| Unclear which epic to link to | **ASK** user for the epic |
+| Research skill hits a blocker | Follow research skill's own escalation rules |
+| Codebase analysis reveals conflicting architectures | **ASK** user which pattern to follow |
+| Complexity exceeds 5 points | **WARN** user and suggest splitting into multiple tasks |
+| Jira MCP unavailable | **WARN**, continue with local-only task files |
+
+## Trigger Conditions
+
+When the user wants to:
+- Add new functionality to an existing codebase
+- Plan a new feature or component
+- Create task specifications for upcoming work
+
+**Keywords**: "new task", "add feature", "new functionality", "extend", "I want to add"
+
+**Differentiation**:
+- User wants to decompose an existing plan into tasks → use `/decompose`
+- User wants to research a topic without creating tasks → use `/research`
+- User wants to refactor existing code → use `/refactor`
+- User wants to define and plan a new feature → use this skill

.cursor/skills/new-task/templates/task.md

@@ -0,0 +1,2 @@
+<!-- This skill uses the shared task template at .cursor/skills/decompose/templates/task.md -->
+<!-- See that file for the full template structure. -->

.cursor/skills/plan/SKILL.md

@@ -1,19 +1,21 @@
 ---
 name: plan
 description: |
-  Decompose a solution into architecture, system flows, components, tests, and Jira epics.
+  Decompose a solution into architecture, data model, deployment plan, system flows, components, tests, and Jira epics.
-  Systematic 5-step planning workflow with BLOCKING gates, self-verification, and structured artifact management.
+  Systematic 6-step planning workflow with BLOCKING gates, self-verification, and structured artifact management.
-  Supports project mode (_docs/ + _docs/02_plans/ structure) and standalone mode (@file.md).
+  Uses _docs/ + _docs/02_document/ structure.
   Trigger phrases:
   - "plan", "decompose solution", "architecture planning"
   - "break down the solution", "create planning documents"
   - "component decomposition", "solution analysis"
+category: build
+tags: [planning, architecture, components, testing, jira, epics]
 disable-model-invocation: true
 ---
 
 # Solution Planning
 
-Decompose a problem and solution into architecture, system flows, components, tests, and Jira epics through a systematic 5-step workflow.
+Decompose a problem and solution into architecture, data model, deployment plan, system flows, components, tests, and Jira epics through a systematic 6-step workflow.
 
 ## Core Principles
 
@@ -25,329 +27,83 @@ Decompose a problem and solution into architecture, system flows, components, te
 
 ## Context Resolution
 
-Determine the operating mode based on invocation before any other logic runs.
+Fixed paths — no mode detection needed:
 
-**Project mode** (no explicit input file provided):
 - PROBLEM_FILE: `_docs/00_problem/problem.md`
 - SOLUTION_FILE: `_docs/01_solution/solution.md`
-- PLANS_DIR: `_docs/02_plans/`
+- DOCUMENT_DIR: `_docs/02_document/`
-- All existing guardrails apply as-is.
 
-**Standalone mode** (explicit input file provided, e.g. `/plan @some_doc.md`):
+Announce the resolved paths to the user before proceeding.
-- INPUT_FILE: the provided file (treated as combined problem + solution context)
-- Derive `<topic>` from the input filename (without extension)
-- PLANS_DIR: `_standalone/<topic>/plans/`
-- Guardrails relaxed: only INPUT_FILE must exist and be non-empty
-- `acceptance_criteria.md` and `restrictions.md` are optional — warn if absent
 
-Announce the detected mode and resolved paths to the user before proceeding.
+## Required Files
-
-## Input Specification
-
-### Required Files
-
-**Project mode:**
 
 | File | Purpose |
 |------|---------|
-| PROBLEM_FILE (`_docs/00_problem/problem.md`) | Problem description and context |
+| `_docs/00_problem/problem.md` | Problem description and context |
-| `_docs/00_problem/input_data/` | Reference data examples (if available) |
+| `_docs/00_problem/acceptance_criteria.md` | Measurable acceptance criteria |
-| `_docs/00_problem/restrictions.md` | Constraints and limitations (if available) |
+| `_docs/00_problem/restrictions.md` | Constraints and limitations |
-| `_docs/00_problem/acceptance_criteria.md` | Measurable acceptance criteria (if available) |
+| `_docs/00_problem/input_data/` | Reference data examples |
-| SOLUTION_FILE (`_docs/01_solution/solution.md`) | Solution draft to decompose |
+| `_docs/01_solution/solution.md` | Finalized solution to decompose |
 
-**Standalone mode:**
+## Prerequisites
 
-| File | Purpose |
+Read and follow `steps/00_prerequisites.md`. All three prerequisite checks are **BLOCKING** — do not start the workflow until they pass.
-|------|---------|
-| INPUT_FILE (the provided file) | Combined problem + solution context |
-
-### Prerequisite Checks (BLOCKING)
-
-**Project mode:**
-1. PROBLEM_FILE exists and is non-empty — **STOP if missing**
-2. SOLUTION_FILE exists and is non-empty — **STOP if missing**
-3. Create PLANS_DIR if it does not exist
-4. If `PLANS_DIR/<topic>/` already exists, ask user: **resume from last checkpoint or start fresh?**
-
-**Standalone mode:**
-1. INPUT_FILE exists and is non-empty — **STOP if missing**
-2. Warn if no `restrictions.md` or `acceptance_criteria.md` provided alongside INPUT_FILE
-3. Create PLANS_DIR if it does not exist
-4. If `PLANS_DIR/<topic>/` already exists, ask user: **resume from last checkpoint or start fresh?**
 
 ## Artifact Management
 
-### Directory Structure
+Read `steps/01_artifact-management.md` for directory structure, save timing, save principles, and resumability rules. Refer to it throughout the workflow.
-
-At the start of planning, create a topic-named working directory under PLANS_DIR:
-
-```
-PLANS_DIR/<topic>/
-├── architecture.md
-├── system-flows.md
-├── risk_mitigations.md
-├── risk_mitigations_02.md          (iterative, ## as sequence)
-├── components/
-│   ├── 01_[name]/
-│   │   ├── description.md
-│   │   └── tests.md
-│   ├── 02_[name]/
-│   │   ├── description.md
-│   │   └── tests.md
-│   └── ...
-├── common-helpers/
-│   ├── 01_helper_[name]/
-│   ├── 02_helper_[name]/
-│   └── ...
-├── e2e_test_infrastructure.md
-├── diagrams/
-│   ├── components.drawio
-│   └── flows/
-│       ├── flow_[name].md          (Mermaid)
-│       └── ...
-└── FINAL_report.md
-```
-
-### Save Timing
-
-| Step | Save immediately after | Filename |
-|------|------------------------|----------|
-| Step 1 | Architecture analysis complete | `architecture.md` |
-| Step 1 | System flows documented | `system-flows.md` |
-| Step 2 | Each component analyzed | `components/[##]_[name]/description.md` |
-| Step 2 | Common helpers generated | `common-helpers/[##]_helper_[name].md` |
-| Step 2 | Diagrams generated | `diagrams/` |
-| Step 3 | Risk assessment complete | `risk_mitigations.md` |
-| Step 4 | Tests written per component | `components/[##]_[name]/tests.md` |
-| Step 4b | E2E test infrastructure spec | `e2e_test_infrastructure.md` |
-| Step 5 | Epics created in Jira | Jira via MCP |
-| Final | All steps complete | `FINAL_report.md` |
-
-### Save Principles
-
-1. **Save immediately**: write to disk as soon as a step completes; do not wait until the end
-2. **Incremental updates**: same file can be updated multiple times; append or replace
-3. **Preserve process**: keep all intermediate files even after integration into final report
-4. **Enable recovery**: if interrupted, resume from the last saved artifact (see Resumability)
-
-### Resumability
-
-If `PLANS_DIR/<topic>/` already contains artifacts:
-
-1. List existing files and match them to the save timing table above
-2. Identify the last completed step based on which artifacts exist
-3. Resume from the next incomplete step
-4. Inform the user which steps are being skipped
 
 ## Progress Tracking
 
-At the start of execution, create a TodoWrite with all steps (1 through 5, including 4b). Update status as each step completes.
+At the start of execution, create a TodoWrite with all steps (1 through 6 plus Final). Update status as each step completes.
 
 ## Workflow
 
-### Step 1: Solution Analysis
+### Step 1: Blackbox Tests
 
-**Role**: Professional software architect
+Read and execute `.cursor/skills/test-spec/SKILL.md`.
-**Goal**: Produce `architecture.md` and `system-flows.md` from the solution draft
-**Constraints**: No code, no component-level detail yet; focus on system-level view
 
-1. Read all input files thoroughly
+Capture any new questions, findings, or insights that arise during test specification — these feed forward into Steps 2 and 3.
-2. Research unknown or questionable topics via internet; ask user about ambiguities
-3. Document architecture using `templates/architecture.md` as structure
-4. Document system flows using `templates/system-flows.md` as structure
-
-**Self-verification**:
-- [ ] Architecture covers all capabilities mentioned in solution.md
-- [ ] System flows cover all main user/system interactions
-- [ ] No contradictions with problem.md or restrictions.md
-- [ ] Technology choices are justified
-
-**Save action**: Write `architecture.md` and `system-flows.md`
-
-**BLOCKING**: Present architecture summary to user. Do NOT proceed until user confirms.
 
 ---
 
-### Step 2: Component Decomposition
+### Step 2: Solution Analysis
 
-**Role**: Professional software architect
+Read and follow `steps/02_solution-analysis.md`.
-**Goal**: Decompose the architecture into components with detailed specs
-**Constraints**: No code; only names, interfaces, inputs/outputs. Follow SRP strictly.
-
-1. Identify components from the architecture; think about separation, reusability, and communication patterns
-2. If additional components are needed (data preparation, shared helpers), create them
-3. For each component, write a spec using `templates/component-spec.md` as structure
-4. Generate diagrams:
-   - draw.io component diagram showing relations (minimize line intersections, group semantically coherent components, place external users near their components)
-   - Mermaid flowchart per main control flow
-5. Components can share and reuse common logic, same for multiple components. Hence for such occurences common-helpers folder is specified. 
-
-**Self-verification**:
-- [ ] Each component has a single, clear responsibility
-- [ ] No functionality is spread across multiple components
-- [ ] All inter-component interfaces are defined (who calls whom, with what)
-- [ ] Component dependency graph has no circular dependencies
-- [ ] All components from architecture.md are accounted for
-
-**Save action**: Write:
- - each component `components/[##]_[name]/description.md`
- - comomon helper `common-helpers/[##]_helper_[name].md`
- - diagrams `diagrams/`
-
-**BLOCKING**: Present component list with one-line summaries to user. Do NOT proceed until user confirms.
 
 ---
 
-### Step 3: Architecture Review & Risk Assessment
+### Step 3: Component Decomposition
 
-**Role**: Professional software architect and analyst
+Read and follow `steps/03_component-decomposition.md`.
-**Goal**: Validate all artifacts for consistency, then identify and mitigate risks
-**Constraints**: This is a review step — fix problems found, do not add new features
-
-#### 3a. Evaluator Pass (re-read ALL artifacts)
-
-Review checklist:
-- [ ] All components follow Single Responsibility Principle
-- [ ] All components follow dumb code / smart data principle
-- [ ] Inter-component interfaces are consistent (caller's output matches callee's input)
-- [ ] No circular dependencies in the dependency graph
-- [ ] No missing interactions between components
-- [ ] No over-engineering — is there a simpler decomposition?
-- [ ] Security considerations addressed in component design
-- [ ] Performance bottlenecks identified
-- [ ] API contracts are consistent across components
-
-Fix any issues found before proceeding to risk identification.
-
-#### 3b. Risk Identification
-
-1. Identify technical and project risks
-2. Assess probability and impact using `templates/risk-register.md`
-3. Define mitigation strategies
-4. Apply mitigations to architecture, flows, and component documents where applicable
-
-**Self-verification**:
-- [ ] Every High/Critical risk has a concrete mitigation strategy
-- [ ] Mitigations are reflected in the relevant component or architecture docs
-- [ ] No new risks introduced by the mitigations themselves
-
-**Save action**: Write `risk_mitigations.md`
-
-**BLOCKING**: Present risk summary to user. Ask whether assessment is sufficient.
-
-**Iterative**: If user requests another round, repeat Step 3 and write `risk_mitigations_##.md` (## as sequence number). Continue until user confirms.
 
 ---
 
-### Step 4: Test Specifications
+### Step 4: Architecture Review & Risk Assessment
 
-**Role**: Professional Quality Assurance Engineer
+Read and follow `steps/04_review-risk.md`.
-**Goal**: Write test specs for each component achieving minimum 75% acceptance criteria coverage
-**Constraints**: Test specs only — no test code. Each test must trace to an acceptance criterion.
-
-1. For each component, write tests using `templates/test-spec.md` as structure
-2. Cover all 4 types: integration, performance, security, acceptance
-3. Include test data management (setup, teardown, isolation)
-4. Verify traceability: every acceptance criterion from `acceptance_criteria.md` must be covered by at least one test
-
-**Self-verification**:
-- [ ] Every acceptance criterion has at least one test covering it
-- [ ] Test inputs are realistic and well-defined
-- [ ] Expected results are specific and measurable
-- [ ] No component is left without tests
-
-**Save action**: Write each `components/[##]_[name]/tests.md`
 
 ---
 
-### Step 4b: E2E Black-Box Test Infrastructure
+### Step 5: Test Specifications
 
-**Role**: Professional Quality Assurance Engineer
+Read and follow `steps/05_test-specifications.md`.
-**Goal**: Specify a separate consumer application and Docker environment for black-box end-to-end testing of the main system
-**Constraints**: Spec only — no test code. Consumer must treat the main system as a black box (no internal imports, no direct DB access).
-
-1. Define Docker environment: services (system under test, test DB, consumer app, dependencies), networks, volumes
-2. Specify consumer application: tech stack, entry point, communication interfaces with the main system
-3. Define E2E test scenarios from acceptance criteria — focus on critical end-to-end use cases that cross component boundaries
-4. Specify test data management: seed data, isolation strategy, external dependency mocks
-5. Define CI/CD integration: when to run, gate behavior, timeout
-6. Define reporting format (CSV: test ID, name, execution time, result, error message)
-
-Use `templates/e2e-test-infrastructure.md` as structure.
-
-**Self-verification**:
-- [ ] Critical acceptance criteria are covered by at least one E2E scenario
-- [ ] Consumer app has no direct access to system internals
-- [ ] Docker environment is self-contained (`docker compose up` sufficient)
-- [ ] External dependencies have mock/stub services defined
-
-**Save action**: Write `e2e_test_infrastructure.md`
 
 ---
 
-### Step 5: Jira Epics
+### Step 6: Jira Epics
 
-**Role**: Professional product manager
+Read and follow `steps/06_jira-epics.md`.
-**Goal**: Create Jira epics from components, ordered by dependency
-**Constraints**: Be concise — fewer words with the same meaning is better
-
-1. Generate Jira Epics from components using Jira MCP, structured per `templates/epic-spec.md`
-2. Order epics by dependency (which must be done first)
-3. Include effort estimation per epic (T-shirt size or story points range)
-4. Ensure each epic has clear acceptance criteria cross-referenced with component specs
-5. Generate updated draw.io diagram showing component-to-epic mapping
-
-**Self-verification**:
-- [ ] Every component maps to exactly one epic
-- [ ] Dependency order is respected (no epic depends on a later one)
-- [ ] Acceptance criteria are measurable
-- [ ] Effort estimates are realistic
-
-**Save action**: Epics created in Jira via MCP
 
 ---
 
-## Quality Checklist (before FINAL_report.md)
+### Final: Quality Checklist
 
-Before writing the final report, verify ALL of the following:
+Read and follow `steps/07_quality-checklist.md`.
-
-### Architecture
-- [ ] Covers all capabilities from solution.md
-- [ ] Technology choices are justified
-- [ ] Deployment model is defined
-
-### Components
-- [ ] Every component follows SRP
-- [ ] No circular dependencies
-- [ ] All inter-component interfaces are defined and consistent
-- [ ] No orphan components (unused by any flow)
-
-### Risks
-- [ ] All High/Critical risks have mitigations
-- [ ] Mitigations are reflected in component/architecture docs
-- [ ] User has confirmed risk assessment is sufficient
-
-### Tests
-- [ ] Every acceptance criterion is covered by at least one test
-- [ ] All 4 test types are represented per component (where applicable)
-- [ ] Test data management is defined
-
-### E2E Test Infrastructure
-- [ ] Critical use cases covered by E2E scenarios
-- [ ] Docker environment is self-contained
-- [ ] Consumer app treats main system as black box
-- [ ] CI/CD integration and reporting defined
-
-### Epics
-- [ ] Every component maps to an epic
-- [ ] Dependency order is correct
-- [ ] Acceptance criteria are measurable
-
-**Save action**: Write `FINAL_report.md` using `templates/final-report.md` as structure
 
 ## Common Mistakes
 
+- **Proceeding without input data**: all three data gate items (acceptance_criteria, restrictions, input_data) must be present before any planning begins
 - **Coding during planning**: this workflow produces documents, never code
 - **Multi-responsibility components**: if a component does two things, split it
 - **Skipping BLOCKING gates**: never proceed past a BLOCKING marker without user confirmation
@@ -355,13 +111,15 @@ Before writing the final report, verify ALL of the following:
 - **Copy-pasting problem.md**: the architecture doc should analyze and transform, not repeat the input
 - **Vague interfaces**: "component A talks to component B" is not enough; define the method, input, output
 - **Ignoring restrictions.md**: every constraint must be traceable in the architecture or risk register
+- **Ignoring blackbox test findings**: insights from Step 1 must feed into architecture (Step 2) and component decomposition (Step 3)
 
 ## Escalation Rules
 
 | Situation | Action |
 |-----------|--------|
+| Missing acceptance_criteria.md, restrictions.md, or input_data/ | **STOP** — planning cannot proceed |
 | Ambiguous requirements | ASK user |
-| Missing acceptance criteria | ASK user |
+| Input data coverage below 70% | Search internet for supplementary data, ASK user to validate |
 | Technology choice with multiple valid options | ASK user |
 | Component naming | PROCEED, confirm at next BLOCKING gate |
 | File structure within templates | PROCEED |
@@ -372,22 +130,26 @@ Before writing the final report, verify ALL of the following:
 
 ```
 ┌────────────────────────────────────────────────────────────────┐
-│                Solution Planning (5-Step Method)               │
+│              Solution Planning (6-Step + Final)                  │
 ├────────────────────────────────────────────────────────────────┤
-│ CONTEXT: Resolve mode (project vs standalone) + set paths      │
+│ PREREQ: Data Gate (BLOCKING)                                    │
-│ 1. Solution Analysis     → architecture.md, system-flows.md    │
+│   → verify AC, restrictions, input_data, solution exist         │
+│                                                                │
+│ 1. Blackbox Tests      → test-spec/SKILL.md                     │
+│    [BLOCKING: user confirms test coverage]                     │
+│ 2. Solution Analysis   → architecture, data model, deployment   │
 │    [BLOCKING: user confirms architecture]                      │
-│ 2. Component Decompose   → components/[##]_[name]/description  │
+│ 3. Component Decomp    → component specs + interfaces           │
-│    [BLOCKING: user confirms decomposition]                     │
+│    [BLOCKING: user confirms components]                        │
-│ 3. Review & Risk Assess  → risk_mitigations.md                 │
+│ 4. Review & Risk       → risk register, iterations              │
-│    [BLOCKING: user confirms risks, iterative]                  │
+│    [BLOCKING: user confirms mitigations]                       │
-│ 4. Test Specifications   → components/[##]_[name]/tests.md     │
+│ 5. Test Specifications → per-component test specs               │
-│ 4b.E2E Test Infra        → e2e_test_infrastructure.md          │
+│ 6. Jira Epics          → epic per component + bootstrap         │
-│ 5. Jira Epics            → Jira via MCP                        │
 │    ─────────────────────────────────────────────────           │
-│    Quality Checklist → FINAL_report.md                         │
+│ Final: Quality Checklist → FINAL_report.md                      │
 ├────────────────────────────────────────────────────────────────┤
-│ Principles: SRP · Dumb code/smart data · Save immediately      │
+│ Principles: Single Responsibility · Dumb code, smart data       │
-│             Ask don't assume · Plan don't code                 │
+│             Save immediately · Ask don't assume                │
+│             Plan don't code                                    │
 └────────────────────────────────────────────────────────────────┘
 ```

.cursor/skills/plan/steps/00_prerequisites.md

@@ -0,0 +1,27 @@
+## Prerequisite Checks (BLOCKING)
+
+Run sequentially before any planning step:
+
+### Prereq 1: Data Gate
+
+1. `_docs/00_problem/acceptance_criteria.md` exists and is non-empty — **STOP if missing**
+2. `_docs/00_problem/restrictions.md` exists and is non-empty — **STOP if missing**
+3. `_docs/00_problem/input_data/` exists and contains at least one data file — **STOP if missing**
+4. `_docs/00_problem/problem.md` exists and is non-empty — **STOP if missing**
+
+All four are mandatory. If any is missing or empty, STOP and ask the user to provide them. If the user cannot provide the required data, planning cannot proceed — just stop.
+
+### Prereq 2: Finalize Solution Draft
+
+Only runs after the Data Gate passes:
+
+1. Scan `_docs/01_solution/` for files matching `solution_draft*.md`
+2. Identify the highest-numbered draft (e.g. `solution_draft06.md`)
+3. **Rename** it to `_docs/01_solution/solution.md`
+4. If `solution.md` already exists, ask the user whether to overwrite or keep existing
+5. Verify `solution.md` is non-empty — **STOP if missing or empty**
+
+### Prereq 3: Workspace Setup
+
+1. Create DOCUMENT_DIR if it does not exist
+2. If DOCUMENT_DIR already contains artifacts, ask user: **resume from last checkpoint or start fresh?**

.cursor/skills/plan/steps/01_artifact-management.md

@@ -0,0 +1,87 @@
+## Artifact Management
+
+### Directory Structure
+
+All artifacts are written directly under DOCUMENT_DIR:
+
+```
+DOCUMENT_DIR/
+├── tests/
+│   ├── environment.md
+│   ├── test-data.md
+│   ├── blackbox-tests.md
+│   ├── performance-tests.md
+│   ├── resilience-tests.md
+│   ├── security-tests.md
+│   ├── resource-limit-tests.md
+│   └── traceability-matrix.md
+├── architecture.md
+├── system-flows.md
+├── data_model.md
+├── deployment/
+│   ├── containerization.md
+│   ├── ci_cd_pipeline.md
+│   ├── environment_strategy.md
+│   ├── observability.md
+│   └── deployment_procedures.md
+├── risk_mitigations.md
+├── risk_mitigations_02.md          (iterative, ## as sequence)
+├── components/
+│   ├── 01_[name]/
+│   │   ├── description.md
+│   │   └── tests.md
+│   ├── 02_[name]/
+│   │   ├── description.md
+│   │   └── tests.md
+│   └── ...
+├── common-helpers/
+│   ├── 01_helper_[name]/
+│   ├── 02_helper_[name]/
+│   └── ...
+├── diagrams/
+│   ├── components.drawio
+│   └── flows/
+│       ├── flow_[name].md          (Mermaid)
+│       └── ...
+└── FINAL_report.md
+```
+
+### Save Timing
+
+| Step | Save immediately after | Filename |
+|------|------------------------|----------|
+| Step 1 | Blackbox test environment spec | `tests/environment.md` |
+| Step 1 | Blackbox test data spec | `tests/test-data.md` |
+| Step 1 | Blackbox tests | `tests/blackbox-tests.md` |
+| Step 1 | Blackbox performance tests | `tests/performance-tests.md` |
+| Step 1 | Blackbox resilience tests | `tests/resilience-tests.md` |
+| Step 1 | Blackbox security tests | `tests/security-tests.md` |
+| Step 1 | Blackbox resource limit tests | `tests/resource-limit-tests.md` |
+| Step 1 | Blackbox traceability matrix | `tests/traceability-matrix.md` |
+| Step 2 | Architecture analysis complete | `architecture.md` |
+| Step 2 | System flows documented | `system-flows.md` |
+| Step 2 | Data model documented | `data_model.md` |
+| Step 2 | Deployment plan complete | `deployment/` (5 files) |
+| Step 3 | Each component analyzed | `components/[##]_[name]/description.md` |
+| Step 3 | Common helpers generated | `common-helpers/[##]_helper_[name].md` |
+| Step 3 | Diagrams generated | `diagrams/` |
+| Step 4 | Risk assessment complete | `risk_mitigations.md` |
+| Step 5 | Tests written per component | `components/[##]_[name]/tests.md` |
+| Step 6 | Epics created in Jira | Jira via MCP |
+| Final | All steps complete | `FINAL_report.md` |
+
+### Save Principles
+
+1. **Save immediately**: write to disk as soon as a step completes; do not wait until the end
+2. **Incremental updates**: same file can be updated multiple times; append or replace
+3. **Preserve process**: keep all intermediate files even after integration into final report
+4. **Enable recovery**: if interrupted, resume from the last saved artifact (see Resumability)
+
+### Resumability
+
+If DOCUMENT_DIR already contains artifacts:
+
+1. List existing files and match them to the save timing table above
+2. Identify the last completed step based on which artifacts exist
+3. Resume from the next incomplete step
+4. Inform the user which steps are being skipped

.cursor/skills/plan/steps/02_solution-analysis.md

@@ -0,0 +1,74 @@
+## Step 2: Solution Analysis
+
+**Role**: Professional software architect
+**Goal**: Produce `architecture.md`, `system-flows.md`, `data_model.md`, and `deployment/` from the solution draft
+**Constraints**: No code, no component-level detail yet; focus on system-level view
+
+### Phase 2a: Architecture & Flows
+
+1. Read all input files thoroughly
+2. Incorporate findings, questions, and insights discovered during Step 1 (blackbox tests)
+3. Research unknown or questionable topics via internet; ask user about ambiguities
+4. Document architecture using `templates/architecture.md` as structure
+5. Document system flows using `templates/system-flows.md` as structure
+
+**Self-verification**:
+- [ ] Architecture covers all capabilities mentioned in solution.md
+- [ ] System flows cover all main user/system interactions
+- [ ] No contradictions with problem.md or restrictions.md
+- [ ] Technology choices are justified
+- [ ] Blackbox test findings are reflected in architecture decisions
+
+**Save action**: Write `architecture.md` and `system-flows.md`
+
+**BLOCKING**: Present architecture summary to user. Do NOT proceed until user confirms.
+
+### Phase 2b: Data Model
+
+**Role**: Professional software architect
+**Goal**: Produce a detailed data model document covering entities, relationships, and migration strategy
+
+1. Extract core entities from architecture.md and solution.md
+2. Define entity attributes, types, and constraints
+3. Define relationships between entities (Mermaid ERD)
+4. Define migration strategy: versioning tool (EF Core migrations / Alembic / sql-migrate), reversibility requirement, naming convention
+5. Define seed data requirements per environment (dev, staging)
+6. Define backward compatibility approach for schema changes (additive-only by default)
+
+**Self-verification**:
+- [ ] Every entity mentioned in architecture.md is defined
+- [ ] Relationships are explicit with cardinality
+- [ ] Migration strategy specifies reversibility requirement
+- [ ] Seed data requirements defined
+- [ ] Backward compatibility approach documented
+
+**Save action**: Write `data_model.md`
+
+### Phase 2c: Deployment Planning
+
+**Role**: DevOps / Platform engineer
+**Goal**: Produce deployment plan covering containerization, CI/CD, environment strategy, observability, and deployment procedures
+
+Use the `/deploy` skill's templates as structure for each artifact:
+
+1. Read architecture.md and restrictions.md for infrastructure constraints
+2. Research Docker best practices for the project's tech stack
+3. Define containerization plan: Dockerfile per component, docker-compose for dev and tests
+4. Define CI/CD pipeline: stages, quality gates, caching, parallelization
+5. Define environment strategy: dev, staging, production with secrets management
+6. Define observability: structured logging, metrics, tracing, alerting
+7. Define deployment procedures: strategy, health checks, rollback, checklist
+
+**Self-verification**:
+- [ ] Every component has a Docker specification
+- [ ] CI/CD pipeline covers lint, test, security, build, deploy
+- [ ] Environment strategy covers dev, staging, production
+- [ ] Observability covers logging, metrics, tracing, alerting
+- [ ] Deployment procedures include rollback and health checks
+
+**Save action**: Write all 5 files under `deployment/`:
+- `containerization.md`
+- `ci_cd_pipeline.md`
+- `environment_strategy.md`
+- `observability.md`
+- `deployment_procedures.md`

.cursor/skills/plan/steps/03_component-decomposition.md

@@ -0,0 +1,29 @@
+## Step 3: Component Decomposition
+
+**Role**: Professional software architect
+**Goal**: Decompose the architecture into components with detailed specs
+**Constraints**: No code; only names, interfaces, inputs/outputs. Follow SRP strictly.
+
+1. Identify components from the architecture; think about separation, reusability, and communication patterns
+2. Use blackbox test scenarios from Step 1 to validate component boundaries
+3. If additional components are needed (data preparation, shared helpers), create them
+4. For each component, write a spec using `templates/component-spec.md` as structure
+5. Generate diagrams:
+   - draw.io component diagram showing relations (minimize line intersections, group semantically coherent components, place external users near their components)
+   - Mermaid flowchart per main control flow
+6. Components can share and reuse common logic, same for multiple components. Hence for such occurences common-helpers folder is specified.
+
+**Self-verification**:
+- [ ] Each component has a single, clear responsibility
+- [ ] No functionality is spread across multiple components
+- [ ] All inter-component interfaces are defined (who calls whom, with what)
+- [ ] Component dependency graph has no circular dependencies
+- [ ] All components from architecture.md are accounted for
+- [ ] Every blackbox test scenario can be traced through component interactions
+
+**Save action**: Write:
+ - each component `components/[##]_[name]/description.md`
+ - common helper `common-helpers/[##]_helper_[name].md`
+ - diagrams `diagrams/`
+
+**BLOCKING**: Present component list with one-line summaries to user. Do NOT proceed until user confirms.

.cursor/skills/plan/steps/04_review-risk.md

@@ -0,0 +1,38 @@
+## Step 4: Architecture Review & Risk Assessment
+
+**Role**: Professional software architect and analyst
+**Goal**: Validate all artifacts for consistency, then identify and mitigate risks
+**Constraints**: This is a review step — fix problems found, do not add new features
+
+### 4a. Evaluator Pass (re-read ALL artifacts)
+
+Review checklist:
+- [ ] All components follow Single Responsibility Principle
+- [ ] All components follow dumb code / smart data principle
+- [ ] Inter-component interfaces are consistent (caller's output matches callee's input)
+- [ ] No circular dependencies in the dependency graph
+- [ ] No missing interactions between components
+- [ ] No over-engineering — is there a simpler decomposition?
+- [ ] Security considerations addressed in component design
+- [ ] Performance bottlenecks identified
+- [ ] API contracts are consistent across components
+
+Fix any issues found before proceeding to risk identification.
+
+### 4b. Risk Identification
+
+1. Identify technical and project risks
+2. Assess probability and impact using `templates/risk-register.md`
+3. Define mitigation strategies
+4. Apply mitigations to architecture, flows, and component documents where applicable
+
+**Self-verification**:
+- [ ] Every High/Critical risk has a concrete mitigation strategy
+- [ ] Mitigations are reflected in the relevant component or architecture docs
+- [ ] No new risks introduced by the mitigations themselves
+
+**Save action**: Write `risk_mitigations.md`
+
+**BLOCKING**: Present risk summary to user. Ask whether assessment is sufficient.
+
+**Iterative**: If user requests another round, repeat Step 4 and write `risk_mitigations_##.md` (## as sequence number). Continue until user confirms.

.cursor/skills/plan/steps/05_test-specifications.md

@@ -0,0 +1,20 @@
+## Step 5: Test Specifications
+
+**Role**: Professional Quality Assurance Engineer
+
+**Goal**: Write test specs for each component achieving minimum 75% acceptance criteria coverage
+
+**Constraints**: Test specs only — no test code. Each test must trace to an acceptance criterion.
+
+1. For each component, write tests using `templates/test-spec.md` as structure
+2. Cover all 4 types: integration, performance, security, acceptance
+3. Include test data management (setup, teardown, isolation)
+4. Verify traceability: every acceptance criterion from `acceptance_criteria.md` must be covered by at least one test
+
+**Self-verification**:
+- [ ] Every acceptance criterion has at least one test covering it
+- [ ] Test inputs are realistic and well-defined
+- [ ] Expected results are specific and measurable
+- [ ] No component is left without tests
+
+**Save action**: Write each `components/[##]_[name]/tests.md`

.cursor/skills/plan/steps/06_jira-epics.md

@@ -0,0 +1,48 @@
+## Step 6: Work Item Epics
+
+**Role**: Professional product manager
+
+**Goal**: Create epics from components, ordered by dependency
+
+**Constraints**: Epic descriptions must be **comprehensive and self-contained** — a developer reading only the epic should understand the full context without needing to open separate files.
+
+1. **Create "Bootstrap & Initial Structure" epic first** — this epic will parent the `01_initial_structure` task created by the decompose skill. It covers project scaffolding: folder structure, shared models, interfaces, stubs, CI/CD config, DB migrations setup, test structure.
+2. Generate epics for each component using the configured work item tracker (Jira MCP or Azure DevOps MCP — see `autopilot/protocols.md`), structured per `templates/epic-spec.md`
+3. Order epics by dependency (Bootstrap epic is always first, then components based on their dependency graph)
+4. Include effort estimation per epic (T-shirt size or story points range)
+5. Ensure each epic has clear acceptance criteria cross-referenced with component specs
+6. Generate Mermaid diagrams showing component-to-epic mapping and component relationships
+
+**CRITICAL — Epic description richness requirements**:
+
+Each epic description MUST include ALL of the following sections with substantial content:
+- **System context**: where this component fits in the overall architecture (include Mermaid diagram showing this component's position and connections)
+- **Problem / Context**: what problem this component solves, why it exists, current pain points
+- **Scope**: detailed in-scope and out-of-scope lists
+- **Architecture notes**: relevant ADRs, technology choices, patterns used, key design decisions
+- **Interface specification**: full method signatures, input/output types, error types (from component description.md)
+- **Data flow**: how data enters and exits this component (include Mermaid sequence or flowchart diagram)
+- **Dependencies**: epic dependencies (with Jira IDs) and external dependencies (libraries, hardware, services)
+- **Acceptance criteria**: measurable criteria with specific thresholds (from component tests.md)
+- **Non-functional requirements**: latency, memory, throughput targets with failure thresholds
+- **Risks & mitigations**: relevant risks from risk_mitigations.md with concrete mitigation strategies
+- **Effort estimation**: T-shirt size and story points range
+- **Child issues**: planned task breakdown with complexity points
+- **Key constraints**: from restrictions.md that affect this component
+- **Testing strategy**: summary of test types and coverage from tests.md
+
+Do NOT create minimal epics with just a summary and short description. The epic is the primary reference document for the implementation team.
+
+**Self-verification**:
+- [ ] "Bootstrap & Initial Structure" epic exists and is first in order
+- [ ] "Blackbox Tests" epic exists
+- [ ] Every component maps to exactly one epic
+- [ ] Dependency order is respected (no epic depends on a later one)
+- [ ] Acceptance criteria are measurable
+- [ ] Effort estimates are realistic
+- [ ] Every epic description includes architecture diagram, interface spec, data flow, risks, and NFRs
+- [ ] Epic descriptions are self-contained — readable without opening other files
+
+7. **Create "Blackbox Tests" epic** — this epic will parent the blackbox test tasks created by the `/decompose` skill. It covers implementing the test scenarios defined in `tests/`.
+
+**Save action**: Epics created via the configured tracker MCP. Also saved locally in `epics.md` with ticket IDs. If `tracker: local`, save locally only.

.cursor/skills/plan/steps/07_quality-checklist.md

@@ -0,0 +1,57 @@
+## Quality Checklist (before FINAL_report.md)
+
+Before writing the final report, verify ALL of the following:
+
+### Blackbox Tests
+- [ ] Every acceptance criterion is covered in traceability-matrix.md
+- [ ] Every restriction is verified by at least one test
+- [ ] Positive and negative scenarios are balanced
+- [ ] Docker environment is self-contained
+- [ ] Consumer app treats main system as black box
+- [ ] CI/CD integration and reporting defined
+
+### Architecture
+- [ ] Covers all capabilities from solution.md
+- [ ] Technology choices are justified
+- [ ] Deployment model is defined
+- [ ] Blackbox test findings are reflected in architecture decisions
+
+### Data Model
+- [ ] Every entity from architecture.md is defined
+- [ ] Relationships have explicit cardinality
+- [ ] Migration strategy with reversibility requirement
+- [ ] Seed data requirements defined
+- [ ] Backward compatibility approach documented
+
+### Deployment
+- [ ] Containerization plan covers all components
+- [ ] CI/CD pipeline includes lint, test, security, build, deploy stages
+- [ ] Environment strategy covers dev, staging, production
+- [ ] Observability covers logging, metrics, tracing, alerting
+- [ ] Deployment procedures include rollback and health checks
+
+### Components
+- [ ] Every component follows SRP
+- [ ] No circular dependencies
+- [ ] All inter-component interfaces are defined and consistent
+- [ ] No orphan components (unused by any flow)
+- [ ] Every blackbox test scenario can be traced through component interactions
+
+### Risks
+- [ ] All High/Critical risks have mitigations
+- [ ] Mitigations are reflected in component/architecture docs
+- [ ] User has confirmed risk assessment is sufficient
+
+### Tests
+- [ ] Every acceptance criterion is covered by at least one test
+- [ ] All 4 test types are represented per component (where applicable)
+- [ ] Test data management is defined
+
+### Epics
+- [ ] "Bootstrap & Initial Structure" epic exists
+- [ ] "Blackbox Tests" epic exists
+- [ ] Every component maps to an epic
+- [ ] Dependency order is correct
+- [ ] Acceptance criteria are measurable
+
+**Save action**: Write `FINAL_report.md` using `templates/final-report.md` as structure

.cursor/skills/plan/templates/architecture.md

@@ -1,6 +1,6 @@
 # Architecture Document Template
 
-Use this template for the architecture document. Save as `_docs/02_plans/<topic>/architecture.md`.
+Use this template for the architecture document. Save as `_docs/02_document/architecture.md`.
 
 ---
 

.cursor/skills/plan/templates/blackbox-tests.md

@@ -0,0 +1,78 @@
+# Blackbox Tests Template
+
+Save as `DOCUMENT_DIR/tests/blackbox-tests.md`.
+
+---
+
+```markdown
+# Blackbox Tests
+
+## Positive Scenarios
+
+### FT-P-01: [Scenario Name]
+
+**Summary**: [One sentence: what black-box use case this validates]
+**Traces to**: AC-[ID], AC-[ID]
+**Category**: [which AC category — e.g., Position Accuracy, Image Processing, etc.]
+
+**Preconditions**:
+- [System state required before test]
+
+**Input data**: [reference to specific data set or file from test-data.md]
+
+**Steps**:
+
+| Step | Consumer Action | Expected System Response |
+|------|----------------|------------------------|
+| 1 | [call / send / provide input] | [response / event / output] |
+| 2 | [call / send / provide input] | [response / event / output] |
+
+**Expected outcome**: [specific, measurable result]
+**Max execution time**: [e.g., 10s]
+
+---
+
+### FT-P-02: [Scenario Name]
+
+(repeat structure)
+
+---
+
+## Negative Scenarios
+
+### FT-N-01: [Scenario Name]
+
+**Summary**: [One sentence: what invalid/edge input this tests]
+**Traces to**: AC-[ID] (negative case), RESTRICT-[ID]
+**Category**: [which AC/restriction category]
+
+**Preconditions**:
+- [System state required before test]
+
+**Input data**: [reference to specific invalid data or edge case]
+
+**Steps**:
+
+| Step | Consumer Action | Expected System Response |
+|------|----------------|------------------------|
+| 1 | [provide invalid input / trigger edge case] | [error response / graceful degradation / fallback behavior] |
+
+**Expected outcome**: [system rejects gracefully / falls back to X / returns error Y]
+**Max execution time**: [e.g., 5s]
+
+---
+
+### FT-N-02: [Scenario Name]
+
+(repeat structure)
+```
+
+---
+
+## Guidance Notes
+
+- Blackbox tests should typically trace to at least one acceptance criterion or restriction. Tests without a trace are allowed but should have a clear justification.
+- Positive scenarios validate the system does what it should.
+- Negative scenarios validate the system rejects or handles gracefully what it shouldn't accept.
+- Expected outcomes must be specific and measurable — not "works correctly" but "returns position within 50m of ground truth."
+- Input data references should point to specific entries in test-data.md.

.cursor/skills/plan/templates/epic-spec.md

@@ -1,6 +1,6 @@
-# Jira Epic Template
+# Epic Template
 
-Use this template for each Jira epic. Create epics via Jira MCP.
+Use this template for each epic. Create epics via the configured work item tracker (Jira MCP or Azure DevOps MCP).
 
 ---
 
@@ -73,14 +73,14 @@ Link to architecture.md and relevant component spec.]
 
 ### Design & Architecture
 
-- Architecture doc: `_docs/02_plans/<topic>/architecture.md`
+- Architecture doc: `_docs/02_document/architecture.md`
-- Component spec: `_docs/02_plans/<topic>/components/[##]_[name]/description.md`
+- Component spec: `_docs/02_document/components/[##]_[name]/description.md`
-- System flows: `_docs/02_plans/<topic>/system-flows.md`
+- System flows: `_docs/02_document/system-flows.md`
 
 ### Definition of Done
 
 - [ ] All in-scope capabilities implemented
-- [ ] Automated tests pass (unit + integration + e2e)
+- [ ] Automated tests pass (unit + blackbox)
 - [ ] Minimum coverage threshold met (75%)
 - [ ] Runbooks written (if applicable)
 - [ ] Documentation updated

.cursor/skills/plan/templates/final-report.md

@@ -1,6 +1,6 @@
 # Final Planning Report Template
 
-Use this template after completing all 5 steps and the quality checklist. Save as `_docs/02_plans/<topic>/FINAL_report.md`.
+Use this template after completing all 6 steps and the quality checklist. Save as `_docs/02_document/FINAL_report.md`.
 
 ---
 

.cursor/skills/plan/templates/performance-tests.md

@@ -0,0 +1,35 @@
+# Performance Tests Template
+
+Save as `DOCUMENT_DIR/tests/performance-tests.md`.
+
+---
+
+```markdown
+# Performance Tests
+
+### NFT-PERF-01: [Test Name]
+
+**Summary**: [What performance characteristic this validates]
+**Traces to**: AC-[ID]
+**Metric**: [what is measured — latency, throughput, frame rate, etc.]
+
+**Preconditions**:
+- [System state, load profile, data volume]
+
+**Steps**:
+
+| Step | Consumer Action | Measurement |
+|------|----------------|-------------|
+| 1 | [action] | [what to measure and how] |
+
+**Pass criteria**: [specific threshold — e.g., p95 latency < 400ms]
+**Duration**: [how long the test runs]
+```
+
+---
+
+## Guidance Notes
+
+- Performance tests should run long enough to capture steady-state behavior, not just cold-start.
+- Define clear pass/fail thresholds with specific metrics (p50, p95, p99 latency, throughput, etc.).
+- Include warm-up preconditions to separate initialization cost from steady-state performance.

.cursor/skills/plan/templates/resilience-tests.md

@@ -0,0 +1,37 @@
+# Resilience Tests Template
+
+Save as `DOCUMENT_DIR/tests/resilience-tests.md`.
+
+---
+
+```markdown
+# Resilience Tests
+
+### NFT-RES-01: [Test Name]
+
+**Summary**: [What failure/recovery scenario this validates]
+**Traces to**: AC-[ID]
+
+**Preconditions**:
+- [System state before fault injection]
+
+**Fault injection**:
+- [What fault is introduced — process kill, network partition, invalid input sequence, etc.]
+
+**Steps**:
+
+| Step | Action | Expected Behavior |
+|------|--------|------------------|
+| 1 | [inject fault] | [system behavior during fault] |
+| 2 | [observe recovery] | [system behavior after recovery] |
+
+**Pass criteria**: [recovery time, data integrity, continued operation]
+```
+
+---
+
+## Guidance Notes
+
+- Resilience tests must define both the fault and the expected recovery — not just "system should recover."
+- Include specific recovery time expectations and data integrity checks.
+- Test both graceful degradation (partial failure) and full recovery scenarios.

.cursor/skills/plan/templates/resource-limit-tests.md

@@ -0,0 +1,31 @@
+# Resource Limit Tests Template
+
+Save as `DOCUMENT_DIR/tests/resource-limit-tests.md`.
+
+---
+
+```markdown
+# Resource Limit Tests
+
+### NFT-RES-LIM-01: [Test Name]
+
+**Summary**: [What resource constraint this validates]
+**Traces to**: AC-[ID], RESTRICT-[ID]
+
+**Preconditions**:
+- [System running under specified constraints]
+
+**Monitoring**:
+- [What resources to monitor — memory, CPU, GPU, disk, temperature]
+
+**Duration**: [how long to run]
+**Pass criteria**: [resource stays within limit — e.g., memory < 8GB throughout]
+```
+
+---
+
+## Guidance Notes
+
+- Resource limit tests must specify monitoring duration — short bursts don't prove sustained compliance.
+- Define specific numeric limits that can be programmatically checked.
+- Include both the monitoring method and the threshold in the pass criteria.

.cursor/skills/plan/templates/risk-register.md

@@ -1,6 +1,6 @@
 # Risk Register Template
 
-Use this template for risk assessment. Save as `_docs/02_plans/<topic>/risk_mitigations.md`.
+Use this template for risk assessment. Save as `_docs/02_document/risk_mitigations.md`.
 Subsequent iterations: `risk_mitigations_02.md`, `risk_mitigations_03.md`, etc.
 
 ---

.cursor/skills/plan/templates/security-tests.md

@@ -0,0 +1,30 @@
+# Security Tests Template
+
+Save as `DOCUMENT_DIR/tests/security-tests.md`.
+
+---
+
+```markdown
+# Security Tests
+
+### NFT-SEC-01: [Test Name]
+
+**Summary**: [What security property this validates]
+**Traces to**: AC-[ID], RESTRICT-[ID]
+
+**Steps**:
+
+| Step | Consumer Action | Expected Response |
+|------|----------------|------------------|
+| 1 | [attempt unauthorized access / injection / etc.] | [rejection / no data leak / etc.] |
+
+**Pass criteria**: [specific security outcome]
+```
+
+---
+
+## Guidance Notes
+
+- Security tests at blackbox level focus on black-box attacks (unauthorized API calls, malformed input), not code-level vulnerabilities.
+- Verify the system remains operational after security-related edge cases (no crash, no hang).
+- Test authentication/authorization boundaries from the consumer's perspective.

.cursor/skills/plan/templates/system-flows.md

@@ -1,7 +1,7 @@
 # System Flows Template
 
-Use this template for the system flows document. Save as `_docs/02_plans/<topic>/system-flows.md`.
+Use this template for the system flows document. Save as `_docs/02_document/system-flows.md`.
-Individual flow diagrams go in `_docs/02_plans/<topic>/diagrams/flows/flow_[name].md`.
+Individual flow diagrams go in `_docs/02_document/diagrams/flows/flow_[name].md`.
 
 ---
 

.cursor/skills/plan/templates/test-data.md

@@ -0,0 +1,55 @@
+# Test Data Template
+
+Save as `DOCUMENT_DIR/tests/test-data.md`.
+
+---
+
+```markdown
+# Test Data Management
+
+## Seed Data Sets
+
+| Data Set | Description | Used by Tests | How Loaded | Cleanup |
+|----------|-------------|---------------|-----------|---------|
+| [name] | [what it contains] | [test IDs] | [SQL script / API call / fixture file / volume mount] | [how removed after test] |
+
+## Data Isolation Strategy
+
+[e.g., each test run gets a fresh container restart, or transactions are rolled back, or namespaced data, or separate DB per test group]
+
+## Input Data Mapping
+
+| Input Data File | Source Location | Description | Covers Scenarios |
+|-----------------|----------------|-------------|-----------------|
+| [filename] | `_docs/00_problem/input_data/[filename]` | [what it contains] | [test IDs that use this data] |
+
+## Expected Results Mapping
+
+| Test Scenario ID | Input Data | Expected Result | Comparison Method | Tolerance | Expected Result Source |
+|-----------------|------------|-----------------|-------------------|-----------|----------------------|
+| [test ID] | `input_data/[filename]` | [quantifiable expected output] | [exact / tolerance / pattern / threshold / file-diff] | [± value or N/A] | `input_data/expected_results/[filename]` or inline |
+
+## External Dependency Mocks
+
+| External Service | Mock/Stub | How Provided | Behavior |
+|-----------------|-----------|-------------|----------|
+| [service name] | [mock type] | [Docker service / in-process stub / recorded responses] | [what it returns / simulates] |
+
+## Data Validation Rules
+
+| Data Type | Validation | Invalid Examples | Expected System Behavior |
+|-----------|-----------|-----------------|------------------------|
+| [type] | [rules] | [invalid input examples] | [how system should respond] |
+```
+
+---
+
+## Guidance Notes
+
+- Every seed data set should be traceable to specific test scenarios.
+- Input data from `_docs/00_problem/input_data/` should be mapped to test scenarios that use it.
+- Every input data item MUST have a corresponding expected result in the Expected Results Mapping table.
+- Expected results MUST be quantifiable: exact values, numeric tolerances, pattern matches, thresholds, or reference files. "Works correctly" is never acceptable.
+- For complex expected outputs, provide machine-readable reference files (JSON, CSV) in `_docs/00_problem/input_data/expected_results/` and reference them in the mapping.
+- External mocks must be deterministic — same input always produces same output.
+- Data isolation must guarantee no test can affect another test's outcome.

.cursor/skills/plan/templates/test-environment.md

@@ -1,17 +1,16 @@
-# E2E Black-Box Test Infrastructure Template
+# Test Environment Template
 
-Describes a separate consumer application that tests the main system as a black box.
+Save as `DOCUMENT_DIR/tests/environment.md`.
-Save as `PLANS_DIR/<topic>/e2e_test_infrastructure.md`.
 
 ---
 
 ```markdown
-# E2E Test Infrastructure
+# Test Environment
 
 ## Overview
 
-**System under test**: [main system name and entry points — API URLs, message queues, etc.]
+**System under test**: [main system name and entry points — API URLs, message queues, serial ports, etc.]
-**Consumer app purpose**: Standalone application that exercises the main system through its public interfaces, validating end-to-end use cases without access to internals.
+**Consumer app purpose**: Standalone application that exercises the main system through its public interfaces, validating black-box use cases without access to internals.
 
 ## Docker Environment
 
@@ -22,7 +21,7 @@ Save as `PLANS_DIR/<topic>/e2e_test_infrastructure.md`.
 | system-under-test | [main app image or build context] | The main system being tested | [ports] |
 | test-db | [postgres/mysql/etc.] | Database for the main system | [ports] |
 | e2e-consumer | [build context for consumer app] | Black-box test runner | — |
-| [dependency] | [image] | [purpose — cache, queue, etc.] | [ports] |
+| [dependency] | [image] | [purpose — cache, queue, mock, etc.] | [ports] |
 
 ### Networks
 
@@ -68,54 +67,6 @@ services:
 - No internal module imports
 - No shared memory or file system with the main system
 
-## E2E Test Scenarios
-
-### Acceptance Criteria Traceability
-
-| AC ID | Acceptance Criterion | E2E Test IDs | Coverage |
-|-------|---------------------|-------------|----------|
-| AC-01 | [criterion] | E2E-01 | Covered |
-| AC-02 | [criterion] | E2E-02, E2E-03 | Covered |
-| AC-03 | [criterion] | — | NOT COVERED — [reason] |
-
-### E2E-01: [Scenario Name]
-
-**Summary**: [One sentence: what end-to-end use case this validates]
-
-**Traces to**: AC-01
-
-**Preconditions**:
-- [System state required before test]
-
-**Steps**:
-
-| Step | Consumer Action | Expected System Response |
-|------|----------------|------------------------|
-| 1 | [call / send] | [response / event] |
-| 2 | [call / send] | [response / event] |
-
-**Max execution time**: [e.g., 10s]
-
----
-
-### E2E-02: [Scenario Name]
-
-(repeat structure)
-
----
-
-## Test Data Management
-
-**Seed data**:
-
-| Data Set | Description | How Loaded | Cleanup |
-|----------|-------------|-----------|---------|
-| [name] | [what it contains] | [SQL script / API call / fixture file] | [how removed after test] |
-
-**Isolation strategy**: [e.g., each test run gets a fresh DB via container restart, or transactions are rolled back, or namespaced data]
-
-**External dependencies**: [any external APIs that need mocking or sandbox environments]
-
 ## CI/CD Integration
 
 **When to run**: [e.g., on PR merge to dev, nightly, before production deploy]
@@ -134,8 +85,6 @@ services:
 
 ## Guidance Notes
 
-- Every E2E test MUST trace to at least one acceptance criterion. If it doesn't, question whether it's needed.
 - The consumer app must treat the main system as a true black box — no internal imports, no direct DB queries against the main system's database.
-- Keep the number of E2E tests focused on critical use cases. Exhaustive testing belongs in per-component tests (Step 4).
 - Docker environment should be self-contained — `docker compose up` must be sufficient to run the full suite.
 - If the main system requires external services (payment gateways, third-party APIs), define mock/stub services in the Docker environment.

.cursor/skills/plan/templates/test-spec.md

@@ -17,7 +17,7 @@ Use this template for each component's test spec. Save as `components/[##]_[name
 
 ---
 
-## Integration Tests
+## Blackbox Tests
 
 ### IT-01: [Test Name]
 
@@ -169,4 +169,4 @@ Use this template for each component's test spec. Save as `components/[##]_[name
 - If an acceptance criterion has no test covering it, mark it as NOT COVERED and explain why (e.g., "requires manual verification", "deferred to phase 2").
 - Performance test targets should come from the NFR section in `architecture.md`.
 - Security tests should cover at minimum: authentication bypass, authorization escalation, injection attacks relevant to this component.
-- Not every component needs all 4 test types. A stateless utility component may only need integration tests.
+- Not every component needs all 4 test types. A stateless utility component may only need blackbox tests.

.cursor/skills/plan/templates/traceability-matrix.md

@@ -0,0 +1,47 @@
+# Traceability Matrix Template
+
+Save as `DOCUMENT_DIR/tests/traceability-matrix.md`.
+
+---
+
+```markdown
+# Traceability Matrix
+
+## Acceptance Criteria Coverage
+
+| AC ID | Acceptance Criterion | Test IDs | Coverage |
+|-------|---------------------|----------|----------|
+| AC-01 | [criterion text] | FT-P-01, NFT-PERF-01 | Covered |
+| AC-02 | [criterion text] | FT-P-02, FT-N-01 | Covered |
+| AC-03 | [criterion text] | — | NOT COVERED — [reason and mitigation] |
+
+## Restrictions Coverage
+
+| Restriction ID | Restriction | Test IDs | Coverage |
+|---------------|-------------|----------|----------|
+| RESTRICT-01 | [restriction text] | FT-N-02, NFT-RES-LIM-01 | Covered |
+| RESTRICT-02 | [restriction text] | — | NOT COVERED — [reason and mitigation] |
+
+## Coverage Summary
+
+| Category | Total Items | Covered | Not Covered | Coverage % |
+|----------|-----------|---------|-------------|-----------|
+| Acceptance Criteria | [N] | [N] | [N] | [%] |
+| Restrictions | [N] | [N] | [N] | [%] |
+| **Total** | [N] | [N] | [N] | [%] |
+
+## Uncovered Items Analysis
+
+| Item | Reason Not Covered | Risk | Mitigation |
+|------|-------------------|------|-----------|
+| [AC/Restriction ID] | [why it cannot be tested at blackbox level] | [what could go wrong] | [how risk is addressed — e.g., covered by component tests in Step 5] |
+```
+
+---
+
+## Guidance Notes
+
+- Every acceptance criterion must appear in the matrix — either covered or explicitly marked as not covered with a reason.
+- Every restriction must appear in the matrix.
+- NOT COVERED items must have a reason and a mitigation strategy (e.g., "covered at component test level" or "requires real hardware").
+- Coverage percentage should be at least 75% for acceptance criteria at the blackbox test level.

.cursor/skills/problem/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: problem
+description: |
+  Interactive problem gathering skill that builds _docs/00_problem/ through structured interview.
+  Iteratively asks probing questions until the problem, restrictions, acceptance criteria, and input data
+  are fully understood. Produces all required files for downstream skills (research, plan, etc.).
+  Trigger phrases:
+  - "problem", "define problem", "problem gathering"
+  - "what am I building", "describe problem"
+  - "start project", "new project"
+category: build
+tags: [problem, gathering, interview, requirements, acceptance-criteria]
+disable-model-invocation: true
+---
+
+# Problem Gathering
+
+Build a complete problem definition through structured, interactive interview with the user. Produces all required files in `_docs/00_problem/` that downstream skills (research, plan, decompose, implement, deploy) depend on.
+
+## Core Principles
+
+- **Ask, don't assume**: never infer requirements the user hasn't stated
+- **Exhaust before writing**: keep asking until all dimensions are covered; do not write files prematurely
+- **Concrete over vague**: push for measurable values, specific constraints, real numbers
+- **Save immediately**: once the user confirms, write all files at once
+- **User is the authority**: the AI suggests, the user decides
+
+## Context Resolution
+
+Fixed paths:
+
+- OUTPUT_DIR: `_docs/00_problem/`
+- INPUT_DATA_DIR: `_docs/00_problem/input_data/`
+
+## Prerequisite Checks
+
+1. If OUTPUT_DIR already exists and contains files, present what exists and ask user: **resume and fill gaps, overwrite, or skip?**
+2. If overwrite or fresh start, create OUTPUT_DIR and INPUT_DATA_DIR
+
+## Completeness Criteria
+
+The interview is complete when the AI can write ALL of these:
+
+| File | Complete when |
+|------|--------------|
+| `problem.md` | Clear problem statement: what is being built, why, for whom, what it does |
+| `restrictions.md` | All constraints identified: hardware, software, environment, operational, regulatory, budget, timeline |
+| `acceptance_criteria.md` | Measurable success criteria with specific numeric targets grouped by category |
+| `input_data/` | At least one reference data file or detailed data description document. Must include `expected_results.md` with input→output pairs for downstream test specification |
+| `security_approach.md` | (optional) Security requirements identified, or explicitly marked as not applicable |
+
+## Interview Protocol
+
+### Phase 1: Open Discovery
+
+Start with broad, open questions. Let the user describe the problem in their own words.
+
+**Opening**: Ask the user to describe what they are building and what problem it solves. Do not interrupt or narrow down yet.
+
+After the user responds, summarize what you understood and ask: "Did I get this right? What did I miss?"
+
+### Phase 2: Structured Probing
+
+Work through each dimension systematically. For each dimension, ask only what the user hasn't already covered. Skip dimensions that were fully answered in Phase 1.
+
+**Dimension checklist:**
+
+1. **Problem & Goals**
+   - What exactly does the system do?
+   - What problem does it solve? Why does it need to exist?
+   - Who are the users / operators / stakeholders?
+   - What is the expected usage pattern (frequency, load, environment)?
+
+2. **Scope & Boundaries**
+   - What is explicitly IN scope?
+   - What is explicitly OUT of scope?
+   - Are there related systems this integrates with?
+   - What does the system NOT do (common misconceptions)?
+
+3. **Hardware & Environment**
+   - What hardware does it run on? (CPU, GPU, memory, storage)
+   - What operating system / platform?
+   - What is the deployment environment? (cloud, edge, embedded, on-prem)
+   - Any physical constraints? (power, thermal, size, connectivity)
+
+4. **Software & Tech Constraints**
+   - Required programming languages or frameworks?
+   - Required protocols or interfaces?
+   - Existing systems it must integrate with?
+   - Libraries or tools that must or must not be used?
+
+5. **Acceptance Criteria**
+   - What does "done" look like?
+   - Performance targets: latency, throughput, accuracy, error rates?
+   - Quality bars: reliability, availability, recovery time?
+   - Push for specific numbers: "less than Xms", "above Y%", "within Z meters"
+   - Edge cases: what happens when things go wrong?
+   - Startup and shutdown behavior?
+
+6. **Input Data**
+   - What data does the system consume?
+   - Formats, schemas, volumes, update frequency?
+   - Does the user have sample/reference data to provide?
+   - If no data exists yet, what would representative data look like?
+
+7. **Security** (optional, probe gently)
+   - Authentication / authorization requirements?
+   - Data sensitivity (PII, classified, proprietary)?
+   - Communication security (encryption, TLS)?
+   - If the user says "not a concern", mark as N/A and move on
+
+8. **Operational Constraints**
+   - Budget constraints?
+   - Timeline constraints?
+   - Team size / expertise constraints?
+   - Regulatory or compliance requirements?
+   - Geographic restrictions?
+
+### Phase 3: Gap Analysis
+
+After all dimensions are covered:
+
+1. Internally assess completeness against the Completeness Criteria table
+2. Present a completeness summary to the user:
+
+```
+Completeness Check:
+- problem.md:             READY / GAPS: [list missing aspects]
+- restrictions.md:        READY / GAPS: [list missing aspects]
+- acceptance_criteria.md: READY / GAPS: [list missing aspects]
+- input_data/:            READY / GAPS: [list missing aspects]
+- security_approach.md:   READY / N/A / GAPS: [list missing aspects]
+```
+
+3. If gaps exist, ask targeted follow-up questions for each gap
+4. Repeat until all required files show READY
+
+### Phase 4: Draft & Confirm
+
+1. Draft all files in the conversation (show the user what will be written)
+2. Present each file's content for review
+3. Ask: "Should I save these files? Any changes needed?"
+4. Apply any requested changes
+5. Save all files to OUTPUT_DIR
+
+## Output File Formats
+
+### problem.md
+
+Free-form text. Clear, concise description of:
+- What is being built
+- What problem it solves
+- How it works at a high level
+- Key context the reader needs to understand the problem
+
+No headers required. Paragraph format. Should be readable by someone unfamiliar with the project.
+
+### restrictions.md
+
+Categorized constraints with markdown headers and bullet points:
+
+```markdown
+# [Category Name]
+
+- Constraint description with specific values where applicable
+- Another constraint
+```
+
+Categories are derived from the interview (hardware, software, environment, operational, etc.). Each restriction should be specific and testable.
+
+### acceptance_criteria.md
+
+Categorized measurable criteria with markdown headers and bullet points:
+
+```markdown
+# [Category Name]
+
+- Criterion with specific numeric target
+- Another criterion with measurable threshold
+```
+
+Every criterion must have a measurable value. Vague criteria like "should be fast" are not acceptable — push for "less than 400ms end-to-end".
+
+### input_data/
+
+At least one file. Options:
+- User provides actual data files (CSV, JSON, images, etc.) — save as-is
+- User describes data parameters — save as `data_parameters.md`
+- User provides URLs to data — save as `data_sources.md` with links and descriptions
+- `expected_results.md` — expected outputs for given inputs (required by downstream test-spec skill). During the Acceptance Criteria dimension, probe for concrete input→output pairs and save them here. Format: use the template from `.cursor/skills/test-spec/templates/expected-results.md`.
+
+### security_approach.md (optional)
+
+If security requirements exist, document them. If the user says security is not a concern for this project, skip this file entirely.
+
+## Progress Tracking
+
+Create a TodoWrite with phases 1-4. Update as each phase completes.
+
+## Escalation Rules
+
+| Situation | Action |
+|-----------|--------|
+| User cannot provide acceptance criteria numbers | Suggest industry benchmarks, ASK user to confirm or adjust |
+| User has no input data at all | ASK what representative data would look like, create a `data_parameters.md` describing expected data |
+| User says "I don't know" to a critical dimension | Research the domain briefly, suggest reasonable defaults, ASK user to confirm |
+| Conflicting requirements discovered | Present the conflict, ASK user which takes priority |
+| User wants to skip a required file | Explain why downstream skills need it, ASK if they want a minimal placeholder |
+
+## Common Mistakes
+
+- **Writing files before the interview is complete**: gather everything first, then write
+- **Accepting vague criteria**: "fast", "accurate", "reliable" are not acceptance criteria without numbers
+- **Assuming technical choices**: do not suggest specific technologies unless the user constrains them
+- **Over-engineering the problem statement**: problem.md should be concise, not a dissertation
+- **Inventing restrictions**: only document what the user actually states as a constraint
+- **Skipping input data**: downstream skills (especially research and plan) need concrete data context
+
+## Methodology Quick Reference
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│           Problem Gathering (4-Phase Interview)                 │
+├────────────────────────────────────────────────────────────────┤
+│ PREREQ: Check if _docs/00_problem/ exists (resume/overwrite?)  │
+│                                                                │
+│ Phase 1: Open Discovery                                        │
+│   → "What are you building?" → summarize → confirm             │
+│ Phase 2: Structured Probing                                    │
+│   → 8 dimensions: problem, scope, hardware, software,          │
+│     acceptance criteria, input data, security, operations       │
+│   → skip what Phase 1 already covered                          │
+│ Phase 3: Gap Analysis                                          │
+│   → assess completeness per file → fill gaps iteratively       │
+│ Phase 4: Draft & Confirm                                       │
+│   → show all files → user confirms → save to _docs/00_problem/ │
+├────────────────────────────────────────────────────────────────┤
+│ Principles: Ask don't assume · Concrete over vague             │
+│             Exhaust before writing · User is authority          │
+└────────────────────────────────────────────────────────────────┘
+```

.cursor/skills/refactor/SKILL.md

@@ -10,6 +10,8 @@ description: |
   - "refactor", "refactoring", "improve code"
   - "analyze coupling", "decoupling", "technical debt"
   - "refactoring assessment", "code quality improvement"
+category: evolve
+tags: [refactoring, coupling, technical-debt, performance, hardening]
 disable-model-invocation: true
 ---
 
@@ -32,15 +34,14 @@ Determine the operating mode based on invocation before any other logic runs.
 **Project mode** (no explicit input file provided):
 - PROBLEM_DIR: `_docs/00_problem/`
 - SOLUTION_DIR: `_docs/01_solution/`
-- COMPONENTS_DIR: `_docs/02_components/`
+- COMPONENTS_DIR: `_docs/02_document/components/`
-- TESTS_DIR: `_docs/02_tests/`
+- DOCUMENT_DIR: `_docs/02_document/`
 - REFACTOR_DIR: `_docs/04_refactoring/`
 - All existing guardrails apply.
 
 **Standalone mode** (explicit input file provided, e.g. `/refactor @some_component.md`):
 - INPUT_FILE: the provided file (treated as component/area description)
-- Derive `<topic>` from the input filename (without extension)
+- REFACTOR_DIR: `_standalone/refactoring/`
-- REFACTOR_DIR: `_standalone/<topic>/refactoring/`
 - Guardrails relaxed: only INPUT_FILE must exist and be non-empty
 - `acceptance_criteria.md` is optional — warn if absent
 
@@ -154,7 +155,7 @@ Store in PROBLEM_DIR.
 
 | Metric Category | What to Capture |
 |----------------|-----------------|
-| **Coverage** | Overall, unit, integration, critical paths |
+| **Coverage** | Overall, unit, blackbox, critical paths |
 | **Complexity** | Cyclomatic complexity (avg + top 5 functions), LOC, tech debt ratio |
 | **Code Smells** | Total, critical, major |
 | **Performance** | Response times (P50/P95/P99), CPU/memory, throughput |
@@ -209,7 +210,7 @@ Write:
 
 Also copy to project standard locations if in project mode:
 - `SOLUTION_DIR/solution.md`
-- `COMPONENTS_DIR/system_flows.md`
+- `DOCUMENT_DIR/system_flows.md`
 
 **Self-verification**:
 - [ ] Every component in the codebase is documented
@@ -275,14 +276,14 @@ Write `REFACTOR_DIR/analysis/refactoring_roadmap.md`:
 
 #### 3a. Design Test Specs
 
-Coverage requirements (must meet before refactoring):
+Coverage requirements (must meet before refactoring — see `.cursor/rules/cursor-meta.mdc` Quality Thresholds):
 - Minimum overall coverage: 75%
 - Critical path coverage: 90%
-- All public APIs must have integration tests
+- All public APIs must have blackbox tests
 - All error handling paths must be tested
 
 For each critical area, write test specs to `REFACTOR_DIR/test_specs/[##]_[test_name].md`:
-- Integration tests: summary, current behavior, input data, expected result, max expected time
+- Blackbox tests: summary, current behavior, input data, expected result, max expected time
 - Acceptance tests: summary, preconditions, steps with expected results
 - Coverage analysis: current %, target %, uncovered critical paths
 
@@ -296,7 +297,7 @@ For each critical area, write test specs to `REFACTOR_DIR/test_specs/[##]_[test_
 **Self-verification**:
 - [ ] Coverage requirements met (75% overall, 90% critical paths)
 - [ ] All tests pass on current codebase
-- [ ] All public APIs have integration tests
+- [ ] All public APIs have blackbox tests
 - [ ] Test data fixtures are configured
 
 **Save action**: Write test specs; implemented tests go into the project's test folder
@@ -331,7 +332,7 @@ Write `REFACTOR_DIR/coupling_analysis.md`:
 For each change in the decoupling strategy:
 
 1. Implement the change
-2. Run integration tests
+2. Run blackbox tests
 3. Fix any failures
 4. Commit with descriptive message
 

.cursor/skills/research/references/comparison-frameworks.md

@@ -0,0 +1,34 @@
+# Comparison & Analysis Frameworks — Reference
+
+## General Dimensions (select as needed)
+
+1. Goal / What problem does it solve
+2. Working mechanism / Process
+3. Input / Output / Boundaries
+4. Advantages / Disadvantages / Trade-offs
+5. Applicable scenarios / Boundary conditions
+6. Cost / Benefit / Risk
+7. Historical evolution / Future trends
+8. Security / Permissions / Controllability
+
+## Concept Comparison Specific Dimensions
+
+1. Definition & essence
+2. Trigger / invocation method
+3. Execution agent
+4. Input/output & type constraints
+5. Determinism & repeatability
+6. Resource & context management
+7. Composition & reuse patterns
+8. Security boundaries & permission control
+
+## Decision Support Specific Dimensions
+
+1. Solution overview
+2. Implementation cost
+3. Maintenance cost
+4. Risk assessment
+5. Expected benefit
+6. Applicable scenarios
+7. Team capability requirements
+8. Migration difficulty

.cursor/skills/research/references/novelty-sensitivity.md

@@ -0,0 +1,75 @@
+# Novelty Sensitivity Assessment — Reference
+
+## Novelty Sensitivity Classification
+
+| Sensitivity Level | Typical Domains | Source Time Window | Description |
+|-------------------|-----------------|-------------------|-------------|
+| **Critical** | AI/LLMs, blockchain, cryptocurrency | 3-6 months | Technology iterates extremely fast; info from months ago may be completely outdated |
+| **High** | Cloud services, frontend frameworks, API interfaces | 6-12 months | Frequent version updates; must confirm current version |
+| **Medium** | Programming languages, databases, operating systems | 1-2 years | Relatively stable but still evolving |
+| **Low** | Algorithm fundamentals, design patterns, theoretical concepts | No limit | Core principles change slowly |
+
+## Critical Sensitivity Domain Special Rules
+
+When the research topic involves the following domains, special rules must be enforced:
+
+**Trigger word identification**:
+- AI-related: LLM, GPT, Claude, Gemini, AI Agent, RAG, vector database, prompt engineering
+- Cloud-native: Kubernetes new versions, Serverless, container runtimes
+- Cutting-edge tech: Web3, quantum computing, AR/VR
+
+**Mandatory rules**:
+
+1. **Search with time constraints**:
+   - Use `time_range: "month"` or `time_range: "week"` to limit search results
+   - Prefer `start_date: "YYYY-MM-DD"` set to within the last 3 months
+
+2. **Elevate official source priority**:
+   - Must first consult official documentation, official blogs, official Changelogs
+   - GitHub Release Notes, official X/Twitter announcements
+   - Academic papers (arXiv and other preprint platforms)
+
+3. **Mandatory version number annotation**:
+   - Any technical description must annotate the current version number
+   - Example: "Claude 3.5 Sonnet (claude-3-5-sonnet-20241022) supports..."
+   - Prohibit vague statements like "the latest version supports..."
+
+4. **Outdated information handling**:
+   - Technical blogs/tutorials older than 6 months -> historical reference only, cannot serve as factual evidence
+   - Version inconsistency found -> must verify current version before using
+   - Obviously outdated descriptions (e.g., "will support in the future" but now already supported) -> discard directly
+
+5. **Cross-validation**:
+   - Highly sensitive information must be confirmed from at least 2 independent sources
+   - Priority: Official docs > Official blogs > Authoritative tech media > Personal blogs
+
+6. **Official download/release page direct verification (BLOCKING)**:
+   - Must directly visit official download pages to verify platform support (don't rely on search engine caches)
+   - Use `WebFetch` to directly extract download page content
+   - Search results about "coming soon" or "planned support" may be outdated; must verify in real time
+   - Platform support is frequently changing information; cannot infer from old sources
+
+7. **Product-specific protocol/feature name search (BLOCKING)**:
+   - Beyond searching the product name, must additionally search protocol/standard names the product supports
+   - Common protocols/standards to search:
+     - AI tools: MCP, ACP (Agent Client Protocol), LSP, DAP
+     - Cloud services: OAuth, OIDC, SAML
+     - Data exchange: GraphQL, gRPC, REST
+   - Search format: `"<product_name> <protocol_name> support"` or `"<product_name> <protocol_name> integration"`
+
+## Timeliness Assessment Output Template
+
+```markdown
+## Timeliness Sensitivity Assessment
+
+- **Research Topic**: [topic]
+- **Sensitivity Level**: Critical / High / Medium / Low
+- **Rationale**: [why this level]
+- **Source Time Window**: [X months/years]
+- **Priority official sources to consult**:
+  1. [Official source 1]
+  2. [Official source 2]
+- **Key version information to verify**:
+  - [Product/technology 1]: Current version ____
+  - [Product/technology 2]: Current version ____
+```

.cursor/skills/research/references/quality-checklists.md

@@ -0,0 +1,72 @@
+# Quality Checklists — Reference
+
+## General Quality
+
+- [ ] All core conclusions have L1/L2 tier factual support
+- [ ] No use of vague words like "possibly", "probably" without annotating uncertainty
+- [ ] Comparison dimensions are complete with no key differences missed
+- [ ] At least one real use case validates conclusions
+- [ ] References are complete with accessible links
+- [ ] Every citation can be directly verified by the user (source verifiability)
+- [ ] Structure hierarchy is clear; executives can quickly locate information
+
+## Internet Search Depth
+
+- [ ] Every sub-question was searched with at least 3-5 different query variants
+- [ ] At least 3 perspectives from the Perspective Rotation were applied and searched
+- [ ] Search saturation reached: last searches stopped producing new substantive information
+- [ ] Adjacent fields and analogous problems were searched, not just direct matches
+- [ ] Contrarian viewpoints were actively sought ("why not X", "X criticism", "X failure")
+- [ ] Practitioner experience was searched (production use, real-world results, lessons learned)
+- [ ] Iterative deepening completed: follow-up questions from initial findings were searched
+- [ ] No sub-question relies solely on training data without web verification
+
+## Mode A Specific
+
+- [ ] Phase 1 completed: AC assessment was presented to and confirmed by user
+- [ ] AC assessment consistent: Solution draft respects the (possibly adjusted) acceptance criteria and restrictions
+- [ ] Competitor analysis included: Existing solutions were researched
+- [ ] All components have comparison tables: Each component lists alternatives with tools, advantages, limitations, security, cost
+- [ ] Tools/libraries verified: Suggested tools actually exist and work as described
+- [ ] Testing strategy covers AC: Tests map to acceptance criteria
+- [ ] Tech stack documented (if Phase 3 ran): `tech_stack.md` has evaluation tables, risk assessment, and learning requirements
+- [ ] Security analysis documented (if Phase 4 ran): `security_analysis.md` has threat model and per-component controls
+
+## Mode B Specific
+
+- [ ] Findings table complete: All identified weak points documented with solutions
+- [ ] Weak point categories covered: Functional, security, and performance assessed
+- [ ] New draft is self-contained: Written as if from scratch, no "updated" markers
+- [ ] Performance column included: Mode B comparison tables include performance characteristics
+- [ ] Previous draft issues addressed: Every finding in the table is resolved in the new draft
+
+## Timeliness Check (High-Sensitivity Domain BLOCKING)
+
+When the research topic has Critical or High sensitivity level:
+
+- [ ] Timeliness sensitivity assessment completed: `00_question_decomposition.md` contains a timeliness assessment section
+- [ ] Source timeliness annotated: Every source has publication date, timeliness status, version info
+- [ ] No outdated sources used as factual evidence (Critical: within 6 months; High: within 1 year)
+- [ ] Version numbers explicitly annotated for all technical products/APIs/SDKs
+- [ ] Official sources prioritized: Core conclusions have support from official documentation/blogs
+- [ ] Cross-validation completed: Key technical information confirmed from at least 2 independent sources
+- [ ] Download page directly verified: Platform support info comes from real-time extraction of official download pages
+- [ ] Protocol/feature names searched: Searched for product-supported protocol names (MCP, ACP, etc.)
+- [ ] GitHub Issues mined: Reviewed product's GitHub Issues popular discussions
+- [ ] Community hotspots identified: Identified and recorded feature points users care most about
+
+## Target Audience Consistency Check (BLOCKING)
+
+- [ ] Research boundary clearly defined: `00_question_decomposition.md` has clear population/geography/timeframe/level boundaries
+- [ ] Every source has target audience annotated in `01_source_registry.md`
+- [ ] Mismatched sources properly handled (excluded, annotated, or marked reference-only)
+- [ ] No audience confusion in fact cards: Every fact has target audience consistent with research boundary
+- [ ] No audience confusion in the report: Policies/research/data cited have consistent target audiences
+
+## Source Verifiability
+
+- [ ] All cited links are publicly accessible (annotate `[login required]` if not)
+- [ ] Citations include exact section/page/timestamp for long documents
+- [ ] Cited facts have corresponding statements in the original text (no over-interpretation)
+- [ ] Source publication/update dates annotated; technical docs include version numbers
+- [ ] Unverifiable information annotated `[limited source]` and not sole support for core conclusions

.cursor/skills/research/references/source-tiering.md

@@ -0,0 +1,121 @@
+# Source Tiering & Authority Anchoring — Reference
+
+## Source Tiers
+
+| Tier | Source Type | Purpose | Credibility |
+|------|------------|---------|-------------|
+| **L1** | Official docs, papers, specs, RFCs | Definitions, mechanisms, verifiable facts | High |
+| **L2** | Official blogs, tech talks, white papers | Design intent, architectural thinking | High |
+| **L3** | Authoritative media, expert commentary, tutorials | Supplementary intuition, case studies | Medium |
+| **L4** | Community discussions, personal blogs, forums | Discover blind spots, validate understanding | Low |
+
+## L4 Community Source Specifics (mandatory for product comparison research)
+
+| Source Type | Access Method | Value |
+|------------|---------------|-------|
+| **GitHub Issues** | Visit `github.com/<org>/<repo>/issues` | Real user pain points, feature requests, bug reports |
+| **GitHub Discussions** | Visit `github.com/<org>/<repo>/discussions` | Feature discussions, usage insights, community consensus |
+| **Reddit** | Search `site:reddit.com "<product_name>"` | Authentic user reviews, comparison discussions |
+| **Hacker News** | Search `site:news.ycombinator.com "<product_name>"` | In-depth technical community discussions |
+| **Discord/Telegram** | Product's official community channels | Active user feedback (must annotate [limited source]) |
+
+## Principles
+
+- Conclusions must be traceable to L1/L2
+- L3/L4 serve only as supplementary and validation
+- L4 community discussions are used to discover "what users truly care about"
+- Record all information sources
+- **Search broadly before searching deeply** — cast a wide net with multiple query variants before diving deep into any single source
+- **Cross-domain search** — when direct results are sparse, search adjacent fields, analogous problems, and related industries
+- **Never rely on a single search** — each sub-question requires multiple searches from different angles (synonyms, negations, practitioner language, academic language)
+
+## Timeliness Filtering Rules (execute based on Step 0.5 sensitivity level)
+
+| Sensitivity Level | Source Filtering Rule | Suggested Search Parameters |
+|-------------------|----------------------|-----------------------------|
+| Critical | Only accept sources within 6 months as factual evidence | `time_range: "month"` or `start_date` set to last 3 months |
+| High | Prefer sources within 1 year; annotate if older than 1 year | `time_range: "year"` |
+| Medium | Sources within 2 years used normally; older ones need validity check | Default search |
+| Low | No time limit | Default search |
+
+## High-Sensitivity Domain Search Strategy
+
+```
+1. Round 1: Targeted official source search
+   - Use include_domains to restrict to official domains
+   - Example: include_domains: ["anthropic.com", "openai.com", "docs.xxx.com"]
+
+2. Round 2: Official download/release page direct verification (BLOCKING)
+   - Directly visit official download pages; don't rely on search caches
+   - Use tavily-extract or WebFetch to extract page content
+   - Verify: platform support, current version number, release date
+
+3. Round 3: Product-specific protocol/feature search (BLOCKING)
+   - Search protocol names the product supports (MCP, ACP, LSP, etc.)
+   - Format: "<product_name> <protocol_name>" site:official_domain
+
+4. Round 4: Time-limited broad search
+   - time_range: "month" or start_date set to recent
+   - Exclude obviously outdated sources
+
+5. Round 5: Version verification
+   - Cross-validate version numbers from search results
+   - If inconsistency found, immediately consult official Changelog
+
+6. Round 6: Community voice mining (BLOCKING - mandatory for product comparison research)
+   - Visit the product's GitHub Issues page, review popular/pinned issues
+   - Search Issues for key feature terms (e.g., "MCP", "plugin", "integration")
+   - Review discussion trends from the last 3-6 months
+   - Identify the feature points and differentiating characteristics users care most about
+```
+
+## Community Voice Mining Detailed Steps
+
+```
+GitHub Issues Mining Steps:
+1. Visit github.com/<org>/<repo>/issues
+2. Sort by "Most commented" to view popular discussions
+3. Search keywords:
+   - Feature-related: feature request, enhancement, MCP, plugin, API
+   - Comparison-related: vs, compared to, alternative, migrate from
+4. Review issue labels: enhancement, feature, discussion
+5. Record frequently occurring feature demands and user pain points
+
+Value Translation:
+- Frequently discussed features -> likely differentiating highlights
+- User complaints/requests -> likely product weaknesses
+- Comparison discussions -> directly obtain user-perspective difference analysis
+```
+
+## Source Registry Entry Template
+
+For each source consulted, immediately append to `01_source_registry.md`:
+```markdown
+## Source #[number]
+- **Title**: [source title]
+- **Link**: [URL]
+- **Tier**: L1/L2/L3/L4
+- **Publication Date**: [YYYY-MM-DD]
+- **Timeliness Status**: Currently valid / Needs verification / Outdated (reference only)
+- **Version Info**: [If involving a specific version, must annotate]
+- **Target Audience**: [Explicitly annotate the group/geography/level this source targets]
+- **Research Boundary Match**: Full match / Partial overlap / Reference only
+- **Summary**: [1-2 sentence key content]
+- **Related Sub-question**: [which sub-question this corresponds to]
+```
+
+## Target Audience Verification (BLOCKING)
+
+Before including each source, verify that its target audience matches the research boundary:
+
+| Source Type | Target audience to verify | Verification method |
+|------------|---------------------------|---------------------|
+| **Policy/Regulation** | Who is it for? (K-12/university/all) | Check document title, scope clauses |
+| **Academic Research** | Who are the subjects? (vocational/undergraduate/graduate) | Check methodology/sample description sections |
+| **Statistical Data** | Which population is measured? | Check data source description |
+| **Case Reports** | What type of institution is involved? | Confirm institution type |
+
+Handling mismatched sources:
+- Target audience completely mismatched -> do not include
+- Partially overlapping -> include but annotate applicable scope
+- Usable as analogous reference -> include but explicitly annotate "reference only"

.cursor/skills/research/references/usage-examples.md

@@ -0,0 +1,56 @@
+# Usage Examples — Reference
+
+## Example 1: Initial Research (Mode A)
+
+```
+User: Research this problem and find the best solution
+```
+
+Execution flow:
+1. Context resolution: no explicit file -> project mode (INPUT_DIR=`_docs/00_problem/`, OUTPUT_DIR=`_docs/01_solution/`)
+2. Guardrails: verify INPUT_DIR exists with required files
+3. Mode detection: no `solution_draft*.md` -> Mode A
+4. Phase 1: Assess acceptance criteria and restrictions, ask user about unclear parts
+5. BLOCKING: present AC assessment, wait for user confirmation
+6. Phase 2: Full 8-step research — competitors, components, state-of-the-art solutions
+7. Output: `OUTPUT_DIR/solution_draft01.md`
+8. (Optional) Phase 3: Tech stack consolidation -> `tech_stack.md`
+9. (Optional) Phase 4: Security deep dive -> `security_analysis.md`
+
+## Example 2: Solution Assessment (Mode B)
+
+```
+User: Assess the current solution draft
+```
+
+Execution flow:
+1. Context resolution: no explicit file -> project mode
+2. Guardrails: verify INPUT_DIR exists
+3. Mode detection: `solution_draft03.md` found in OUTPUT_DIR -> Mode B, read it as input
+4. Full 8-step research — weak points, security, performance, solutions
+5. Output: `OUTPUT_DIR/solution_draft04.md` with findings table + revised draft
+
+## Example 3: Standalone Research
+
+```
+User: /research @my_problem.md
+```
+
+Execution flow:
+1. Context resolution: explicit file -> standalone mode (INPUT_FILE=`my_problem.md`, OUTPUT_DIR=`_standalone/my_problem/01_solution/`)
+2. Guardrails: verify INPUT_FILE exists and is non-empty, warn about missing restrictions/AC
+3. Mode detection + full research flow as in Example 1, scoped to standalone paths
+4. Output: `_standalone/my_problem/01_solution/solution_draft01.md`
+5. Move `my_problem.md` into `_standalone/my_problem/`
+
+## Example 4: Force Initial Research (Override)
+
+```
+User: Research from scratch, ignore existing drafts
+```
+
+Execution flow:
+1. Context resolution: no explicit file -> project mode
+2. Mode detection: drafts exist, but user explicitly requested initial research -> Mode A
+3. Phase 1 + Phase 2 as in Example 1
+4. Output: `OUTPUT_DIR/solution_draft##.md` (incremented from highest existing)

.cursor/skills/research/steps/00_project-integration.md

@@ -0,0 +1,103 @@
+## Project Integration
+
+### Prerequisite Guardrails (BLOCKING)
+
+Before any research begins, verify the input context exists. **Do not proceed if guardrails fail.**
+
+**Project mode:**
+1. Check INPUT_DIR exists — **STOP if missing**, ask user to create it and provide problem files
+2. Check `problem.md` in INPUT_DIR exists and is non-empty — **STOP if missing**
+3. Check `restrictions.md` in INPUT_DIR exists and is non-empty — **STOP if missing**
+4. Check `acceptance_criteria.md` in INPUT_DIR exists and is non-empty — **STOP if missing**
+5. Check `input_data/` in INPUT_DIR exists and contains at least one file — **STOP if missing**
+6. Read **all** files in INPUT_DIR to ground the investigation in the project context
+7. Create OUTPUT_DIR and RESEARCH_DIR if they don't exist
+
+**Standalone mode:**
+1. Check INPUT_FILE exists and is non-empty — **STOP if missing**
+2. Resolve BASE_DIR: use the caller-specified directory if provided; otherwise default to `_standalone/`
+3. Resolve OUTPUT_DIR (`BASE_DIR/01_solution/`) and RESEARCH_DIR (`BASE_DIR/00_research/`)
+4. Warn if no `restrictions.md` or `acceptance_criteria.md` were provided alongside INPUT_FILE — proceed if user confirms
+5. Create BASE_DIR, OUTPUT_DIR, and RESEARCH_DIR if they don't exist
+
+### Mode Detection
+
+After guardrails pass, determine the execution mode:
+
+1. Scan OUTPUT_DIR for files matching `solution_draft*.md`
+2. **No matches found** → **Mode A: Initial Research**
+3. **Matches found** → **Mode B: Solution Assessment** (use the highest-numbered draft as input)
+4. **User override**: if the user explicitly says "research from scratch" or "initial research", force Mode A regardless of existing drafts
+
+Inform the user which mode was detected and confirm before proceeding.
+
+### Solution Draft Numbering
+
+All final output is saved as `OUTPUT_DIR/solution_draft##.md` with a 2-digit zero-padded number:
+
+1. Scan existing files in OUTPUT_DIR matching `solution_draft*.md`
+2. Extract the highest existing number
+3. Increment by 1
+4. Zero-pad to 2 digits (e.g., `01`, `02`, ..., `10`, `11`)
+
+Example: if `solution_draft01.md` through `solution_draft10.md` exist, the next output is `solution_draft11.md`.
+
+### Working Directory & Intermediate Artifact Management
+
+#### Directory Structure
+
+At the start of research, **must** create a working directory under RESEARCH_DIR:
+
+```
+RESEARCH_DIR/
+├── 00_ac_assessment.md            # Mode A Phase 1 output: AC & restrictions assessment
+├── 00_question_decomposition.md   # Step 0-1 output
+├── 01_source_registry.md          # Step 2 output: all consulted source links
+├── 02_fact_cards.md               # Step 3 output: extracted facts
+├── 03_comparison_framework.md     # Step 4 output: selected framework and populated data
+├── 04_reasoning_chain.md          # Step 6 output: fact → conclusion reasoning
+├── 05_validation_log.md           # Step 7 output: use-case validation results
+└── raw/                           # Raw source archive (optional)
+    ├── source_1.md
+    └── source_2.md
+```
+
+### Save Timing & Content
+
+| Step | Save immediately after completion | Filename |
+|------|-----------------------------------|----------|
+| Mode A Phase 1 | AC & restrictions assessment tables | `00_ac_assessment.md` |
+| Step 0-1 | Question type classification + sub-question list | `00_question_decomposition.md` |
+| Step 2 | Each consulted source link, tier, summary | `01_source_registry.md` |
+| Step 3 | Each fact card (statement + source + confidence) | `02_fact_cards.md` |
+| Step 4 | Selected comparison framework + initial population | `03_comparison_framework.md` |
+| Step 6 | Reasoning process for each dimension | `04_reasoning_chain.md` |
+| Step 7 | Validation scenarios + results + review checklist | `05_validation_log.md` |
+| Step 8 | Complete solution draft | `OUTPUT_DIR/solution_draft##.md` |
+
+### Save Principles
+
+1. **Save immediately**: Write to the corresponding file as soon as a step is completed; don't wait until the end
+2. **Incremental updates**: Same file can be updated multiple times; append or replace new content
+3. **Preserve process**: Keep intermediate files even after their content is integrated into the final report
+4. **Enable recovery**: If research is interrupted, progress can be recovered from intermediate files
+
+### Output Files
+
+**Required files** (automatically generated through the process):
+
+| File | Content | When Generated |
+|------|---------|----------------|
+| `00_ac_assessment.md` | AC & restrictions assessment (Mode A only) | After Phase 1 completion |
+| `00_question_decomposition.md` | Question type, sub-question list | After Step 0-1 completion |
+| `01_source_registry.md` | All source links and summaries | Continuously updated during Step 2 |
+| `02_fact_cards.md` | Extracted facts and sources | Continuously updated during Step 3 |
+| `03_comparison_framework.md` | Selected framework and populated data | After Step 4 completion |
+| `04_reasoning_chain.md` | Fact → conclusion reasoning | After Step 6 completion |
+| `05_validation_log.md` | Use-case validation and review | After Step 7 completion |
+| `OUTPUT_DIR/solution_draft##.md` | Complete solution draft | After Step 8 completion |
+| `OUTPUT_DIR/tech_stack.md` | Tech stack evaluation and decisions | After Phase 3 (optional) |
+| `OUTPUT_DIR/security_analysis.md` | Threat model and security controls | After Phase 4 (optional) |
+
+**Optional files**:
+- `raw/*.md` - Raw source archives (saved when content is lengthy)

.cursor/skills/research/steps/01_mode-a-initial-research.md

@@ -0,0 +1,127 @@
+## Mode A: Initial Research
+
+Triggered when no `solution_draft*.md` files exist in OUTPUT_DIR, or when the user explicitly requests initial research.
+
+### Phase 1: AC & Restrictions Assessment (BLOCKING)
+
+**Role**: Professional software architect
+
+A focused preliminary research pass **before** the main solution research. The goal is to validate that the acceptance criteria and restrictions are realistic before designing a solution around them.
+
+**Input**: All files from INPUT_DIR (or INPUT_FILE in standalone mode)
+
+**Task**:
+1. Read all problem context files thoroughly
+2. **ASK the user about every unclear aspect** — do not assume:
+   - Unclear problem boundaries → ask
+   - Ambiguous acceptance criteria values → ask
+   - Missing context (no `security_approach.md`, no `input_data/`) → ask what they have
+   - Conflicting restrictions → ask which takes priority
+3. Research in internet **extensively** — use multiple search queries per question, rephrase, and search from different angles:
+   - How realistic are the acceptance criteria for this specific domain? Search for industry benchmarks, standards, and typical values
+   - How critical is each criterion? Search for case studies where criteria were relaxed or tightened
+   - What domain-specific acceptance criteria are we missing? Search for industry standards, regulatory requirements, and best practices in the specific domain
+   - Impact of each criterion value on the whole system quality — search for research papers and engineering reports
+   - Cost/budget implications of each criterion — search for pricing, total cost of ownership analyses, and comparable project budgets
+   - Timeline implications — search for project timelines, development velocity reports, and comparable implementations
+   - What do practitioners in this domain consider the most important criteria? Search forums, conference talks, and experience reports
+4. Research restrictions from multiple perspectives:
+   - Are the restrictions realistic? Search for comparable projects that operated under similar constraints
+   - Should any be tightened or relaxed? Search for what constraints similar projects actually ended up with
+   - Are there additional restrictions we should add? Search for regulatory, compliance, and safety requirements in this domain
+   - What restrictions do practitioners wish they had defined earlier? Search for post-mortem reports and lessons learned
+5. Verify findings with authoritative sources (official docs, papers, benchmarks) — each key finding must have at least 2 independent sources
+
+**Uses Steps 0-3 of the 8-step engine** (question classification, decomposition, source tiering, fact extraction) scoped to AC and restrictions assessment.
+
+**Save action**: Write `RESEARCH_DIR/00_ac_assessment.md` with format:
+
+```markdown
+# Acceptance Criteria Assessment
+
+## Acceptance Criteria
+
+| Criterion | Our Values | Researched Values | Cost/Timeline Impact | Status |
+|-----------|-----------|-------------------|---------------------|--------|
+| [name] | [current] | [researched range] | [impact] | Added / Modified / Removed |
+
+## Restrictions Assessment
+
+| Restriction | Our Values | Researched Values | Cost/Timeline Impact | Status |
+|-------------|-----------|-------------------|---------------------|--------|
+| [name] | [current] | [researched range] | [impact] | Added / Modified / Removed |
+
+## Key Findings
+[Summary of critical findings]
+
+## Sources
+[Key references used]
+```
+
+**BLOCKING**: Present the AC assessment tables to the user. Wait for confirmation or adjustments before proceeding to Phase 2. The user may update `acceptance_criteria.md` or `restrictions.md` based on findings.
+
+---
+
+### Phase 2: Problem Research & Solution Draft
+
+**Role**: Professional researcher and software architect
+
+Full 8-step research methodology. Produces the first solution draft.
+
+**Input**: All files from INPUT_DIR (possibly updated after Phase 1) + Phase 1 artifacts
+
+**Task** (drives the 8-step engine):
+1. Research existing/competitor solutions for similar problems — search broadly across industries and adjacent domains, not just the obvious competitors
+2. Research the problem thoroughly — all possible ways to solve it, split into components; search for how different fields approach analogous problems
+3. For each component, research all possible solutions and find the most efficient state-of-the-art approaches — use multiple query variants and perspectives from Step 1
+4. For each promising approach, search for real-world deployment experience: success stories, failure reports, lessons learned, and practitioner opinions
+5. Search for contrarian viewpoints — who argues against the common approaches and why? What failure modes exist?
+6. Verify that suggested tools/libraries actually exist and work as described — check official repos, latest releases, and community health (stars, recent commits, open issues)
+7. Include security considerations in each component analysis
+8. Provide rough cost estimates for proposed solutions
+
+Be concise in formulating. The fewer words, the better, but do not miss any important details.
+
+**Save action**: Write `OUTPUT_DIR/solution_draft##.md` using template: `templates/solution_draft_mode_a.md`
+
+---
+
+### Phase 3: Tech Stack Consolidation (OPTIONAL)
+
+**Role**: Software architect evaluating technology choices
+
+Focused synthesis step — no new 8-step cycle. Uses research already gathered in Phase 2 to make concrete technology decisions.
+
+**Input**: Latest `solution_draft##.md` from OUTPUT_DIR + all files from INPUT_DIR
+
+**Task**:
+1. Extract technology options from the solution draft's component comparison tables
+2. Score each option against: fitness for purpose, maturity, security track record, team expertise, cost, scalability
+3. Produce a tech stack summary with selection rationale
+4. Assess risks and learning requirements per technology choice
+
+**Save action**: Write `OUTPUT_DIR/tech_stack.md` with:
+- Requirements analysis (functional, non-functional, constraints)
+- Technology evaluation tables (language, framework, database, infrastructure, key libraries) with scores
+- Tech stack summary block
+- Risk assessment and learning requirements tables
+
+---
+
+### Phase 4: Security Deep Dive (OPTIONAL)
+
+**Role**: Security architect
+
+Focused analysis step — deepens the security column from the solution draft into a proper threat model and controls specification.
+
+**Input**: Latest `solution_draft##.md` from OUTPUT_DIR + `security_approach.md` from INPUT_DIR + problem context
+
+**Task**:
+1. Build threat model: asset inventory, threat actors, attack vectors
+2. Define security requirements and proposed controls per component (with risk level)
+3. Summarize authentication/authorization, data protection, secure communication, and logging/monitoring approach
+
+**Save action**: Write `OUTPUT_DIR/security_analysis.md` with:
+- Threat model (assets, actors, vectors)
+- Per-component security requirements and controls table
+- Security controls summary

.cursor/skills/research/steps/02_mode-b-solution-assessment.md

@@ -0,0 +1,27 @@
+## Mode B: Solution Assessment
+
+Triggered when `solution_draft*.md` files exist in OUTPUT_DIR.
+
+**Role**: Professional software architect
+
+Full 8-step research methodology applied to assessing and improving an existing solution draft.
+
+**Input**: All files from INPUT_DIR + the latest (highest-numbered) `solution_draft##.md` from OUTPUT_DIR
+
+**Task** (drives the 8-step engine):
+1. Read the existing solution draft thoroughly
+2. Research in internet extensively — for each component/decision in the draft, search for:
+   - Known problems and limitations of the chosen approach
+   - What practitioners say about using it in production
+   - Better alternatives that may have emerged recently
+   - Common failure modes and edge cases
+   - How competitors/similar projects solve the same problem differently
+3. Search specifically for contrarian views: "why not [chosen approach]", "[chosen approach] criticism", "[chosen approach] failure"
+4. Identify security weak points and vulnerabilities — search for CVEs, security advisories, and known attack vectors for each technology in the draft
+5. Identify performance bottlenecks — search for benchmarks, load test results, and scalability reports
+6. For each identified weak point, search for multiple solution approaches and compare them
+7. Based on findings, form a new solution draft in the same format
+
+**Save action**: Write `OUTPUT_DIR/solution_draft##.md` (incremented) using template: `templates/solution_draft_mode_b.md`
+
+**Optional follow-up**: After Mode B completes, the user can request Phase 3 (Tech Stack Consolidation) or Phase 4 (Security Deep Dive) using the revised draft. These phases work identically to their Mode A descriptions in `steps/01_mode-a-initial-research.md`.

.cursor/skills/research/steps/03_engine-investigation.md

@@ -0,0 +1,227 @@
+## Research Engine — Investigation Phase (Steps 0–3.5)
+
+### Step 0: Question Type Classification
+
+First, classify the research question type and select the corresponding strategy:
+
+| Question Type | Core Task | Focus Dimensions |
+|---------------|-----------|------------------|
+| **Concept Comparison** | Build comparison framework | Mechanism differences, applicability boundaries |
+| **Decision Support** | Weigh trade-offs | Cost, risk, benefit |
+| **Trend Analysis** | Map evolution trajectory | History, driving factors, predictions |
+| **Problem Diagnosis** | Root cause analysis | Symptoms, causes, evidence chain |
+| **Knowledge Organization** | Systematic structuring | Definitions, classifications, relationships |
+
+**Mode-specific classification**:
+
+| Mode / Phase | Typical Question Type |
+|--------------|----------------------|
+| Mode A Phase 1 | Knowledge Organization + Decision Support |
+| Mode A Phase 2 | Decision Support |
+| Mode B | Problem Diagnosis + Decision Support |
+
+### Step 0.5: Novelty Sensitivity Assessment (BLOCKING)
+
+Before starting research, assess the novelty sensitivity of the question (Critical/High/Medium/Low). This determines source time windows and filtering strategy.
+
+**For full classification table, critical-domain rules, trigger words, and assessment template**: Read `references/novelty-sensitivity.md`
+
+Key principle: Critical-sensitivity topics (AI/LLMs, blockchain) require sources within 6 months, mandatory version annotations, cross-validation from 2+ sources, and direct verification of official download pages.
+
+**Save action**: Append timeliness assessment to the end of `00_question_decomposition.md`
+
+---
+
+### Step 1: Question Decomposition & Boundary Definition
+
+**Mode-specific sub-questions**:
+
+**Mode A Phase 2** (Initial Research — Problem & Solution):
+- "What existing/competitor solutions address this problem?"
+- "What are the component parts of this problem?"
+- "For each component, what are the state-of-the-art solutions?"
+- "What are the security considerations per component?"
+- "What are the cost implications of each approach?"
+
+**Mode B** (Solution Assessment):
+- "What are the weak points and potential problems in the existing draft?"
+- "What are the security vulnerabilities in the proposed architecture?"
+- "Where are the performance bottlenecks?"
+- "What solutions exist for each identified issue?"
+
+**General sub-question patterns** (use when applicable):
+- **Sub-question A**: "What is X and how does it work?" (Definition & mechanism)
+- **Sub-question B**: "What are the dimensions of relationship/difference between X and Y?" (Comparative analysis)
+- **Sub-question C**: "In what scenarios is X applicable/inapplicable?" (Boundary conditions)
+- **Sub-question D**: "What are X's development trends/best practices?" (Extended analysis)
+
+#### Perspective Rotation (MANDATORY)
+
+For each research problem, examine it from **at least 3 different perspectives**. Each perspective generates its own sub-questions and search queries.
+
+| Perspective | What it asks | Example queries |
+|-------------|-------------|-----------------|
+| **End-user / Consumer** | What problems do real users encounter? What do they wish were different? | "X problems", "X frustrations reddit", "X user complaints" |
+| **Implementer / Engineer** | What are the technical challenges, gotchas, hidden complexities? | "X implementation challenges", "X pitfalls", "X lessons learned" |
+| **Business / Decision-maker** | What are the costs, ROI, strategic implications? | "X total cost of ownership", "X ROI case study", "X vs Y business comparison" |
+| **Contrarian / Devil's advocate** | What could go wrong? Why might this fail? What are critics saying? | "X criticism", "why not X", "X failures", "X disadvantages real world" |
+| **Domain expert / Academic** | What does peer-reviewed research say? What are theoretical limits? | "X research paper", "X systematic review", "X benchmarks academic" |
+| **Practitioner / Field** | What do people who actually use this daily say? What works in practice vs theory? | "X in production", "X experience report", "X after 1 year" |
+
+Select at least 3 perspectives relevant to the problem. Document the chosen perspectives in `00_question_decomposition.md`.
+
+#### Question Explosion (MANDATORY)
+
+For **each sub-question**, generate **at least 3-5 search query variants** before searching. This ensures broad coverage and avoids missing relevant information due to terminology differences.
+
+**Query variant strategies**:
+- **Specificity ladder**: broad ("indoor navigation systems") → narrow ("UWB-based indoor drone navigation accuracy")
+- **Negation/failure**: "X limitations", "X failure modes", "when X doesn't work"
+- **Comparison framing**: "X vs Y for Z", "X alternative for Z", "X or Y which is better for Z"
+- **Practitioner voice**: "X in production experience", "X real-world results", "X lessons learned"
+- **Temporal**: "X 2025", "X latest developments", "X roadmap"
+- **Geographic/domain**: "X in Europe", "X for defense applications", "X in agriculture"
+
+Record all planned queries in `00_question_decomposition.md` alongside each sub-question.
+
+**Research Subject Boundary Definition (BLOCKING - must be explicit)**:
+
+When decomposing questions, you must explicitly define the **boundaries of the research subject**:
+
+| Dimension | Boundary to define | Example |
+|-----------|--------------------|---------|
+| **Population** | Which group is being studied? | University students vs K-12 vs vocational students vs all students |
+| **Geography** | Which region is being studied? | Chinese universities vs US universities vs global |
+| **Timeframe** | Which period is being studied? | Post-2020 vs full historical picture |
+| **Level** | Which level is being studied? | Undergraduate vs graduate vs vocational |
+
+**Common mistake**: User asks about "university classroom issues" but sources include policies targeting "K-12 students" — mismatched target populations will invalidate the entire research.
+
+**Save action**:
+1. Read all files from INPUT_DIR to ground the research in the project context
+2. Create working directory `RESEARCH_DIR/`
+3. Write `00_question_decomposition.md`, including:
+   - Original question
+   - Active mode (A Phase 2 or B) and rationale
+   - Summary of relevant problem context from INPUT_DIR
+   - Classified question type and rationale
+   - **Research subject boundary definition** (population, geography, timeframe, level)
+   - List of decomposed sub-questions
+   - **Chosen perspectives** (at least 3 from the Perspective Rotation table) with rationale
+   - **Search query variants** for each sub-question (at least 3-5 per sub-question)
+4. Write TodoWrite to track progress
+
+---
+
+### Step 2: Source Tiering & Exhaustive Web Investigation
+
+Tier sources by authority, **prioritize primary sources** (L1 > L2 > L3 > L4). Conclusions must be traceable to L1/L2; L3/L4 serve as supplementary and validation.
+
+**For full tier definitions, search strategies, community mining steps, and source registry templates**: Read `references/source-tiering.md`
+
+**Tool Usage**:
+- Use `WebSearch` for broad searches; `WebFetch` to read specific pages
+- Use the `context7` MCP server (`resolve-library-id` then `get-library-docs`) for up-to-date library/framework documentation
+- Always cross-verify training data claims against live sources for facts that may have changed (versions, APIs, deprecations, security advisories)
+- When citing web sources, include the URL and date accessed
+
+#### Exhaustive Search Requirements (MANDATORY)
+
+Do not stop at the first few results. The goal is to build a comprehensive evidence base.
+
+**Minimum search effort per sub-question**:
+- Execute **all** query variants generated in Step 1's Question Explosion (at least 3-5 per sub-question)
+- Consult at least **2 different source tiers** per sub-question (e.g., L1 official docs + L4 community discussion)
+- If initial searches yield fewer than 3 relevant sources for a sub-question, **broaden the search** with alternative terms, related domains, or analogous problems
+
+**Search broadening strategies** (use when results are thin):
+- Try adjacent fields: if researching "drone indoor navigation", also search "robot indoor navigation", "warehouse AGV navigation"
+- Try different communities: academic papers, industry whitepapers, military/defense publications, hobbyist forums
+- Try different geographies: search in English + search for European/Asian approaches if relevant
+- Try historical evolution: "history of X", "evolution of X approaches", "X state of the art 2024 2025"
+- Try failure analysis: "X project failure", "X post-mortem", "X recall", "X incident report"
+
+**Search saturation rule**: Continue searching until new queries stop producing substantially new information. If the last 3 searches only repeat previously found facts, the sub-question is saturated.
+
+**Save action**:
+For each source consulted, **immediately** append to `01_source_registry.md` using the entry template from `references/source-tiering.md`.
+
+---
+
+### Step 3: Fact Extraction & Evidence Cards
+
+Transform sources into **verifiable fact cards**:
+
+```markdown
+## Fact Cards
+
+### Fact 1
+- **Statement**: [specific fact description]
+- **Source**: [link/document section]
+- **Confidence**: High/Medium/Low
+
+### Fact 2
+...
+```
+
+**Key discipline**:
+- Pin down facts first, then reason
+- Distinguish "what officials said" from "what I infer"
+- When conflicting information is found, annotate and preserve both sides
+- Annotate confidence level:
+  - ✅ High: Explicitly stated in official documentation
+  - ⚠️ Medium: Mentioned in official blog but not formally documented
+  - ❓ Low: Inference or from unofficial sources
+
+**Save action**:
+For each extracted fact, **immediately** append to `02_fact_cards.md`:
+```markdown
+## Fact #[number]
+- **Statement**: [specific fact description]
+- **Source**: [Source #number] [link]
+- **Phase**: [Phase 1 / Phase 2 / Assessment]
+- **Target Audience**: [which group this fact applies to, inherited from source or further refined]
+- **Confidence**: ✅/⚠️/❓
+- **Related Dimension**: [corresponding comparison dimension]
+```
+
+**Target audience in fact statements**:
+- If a fact comes from a "partially overlapping" or "reference only" source, the statement **must explicitly annotate the applicable scope**
+- Wrong: "The Ministry of Education banned phones in classrooms" (doesn't specify who)
+- Correct: "The Ministry of Education banned K-12 students from bringing phones into classrooms (does not apply to university students)"
+
+---
+
+### Step 3.5: Iterative Deepening — Follow-Up Investigation
+
+After initial fact extraction, review what you have found and identify **knowledge gaps and new questions** that emerged from the initial research. This step ensures the research doesn't stop at surface-level findings.
+
+**Process**:
+
+1. **Gap analysis**: Review fact cards and identify:
+   - Sub-questions with fewer than 3 high-confidence facts → need more searching
+   - Contradictions between sources → need tie-breaking evidence
+   - Perspectives (from Step 1) that have no or weak coverage → need targeted search
+   - Claims that rely only on L3/L4 sources → need L1/L2 verification
+
+2. **Follow-up question generation**: Based on initial findings, generate new questions:
+   - "Source X claims [fact] — is this consistent with other evidence?"
+   - "If [approach A] has [limitation], how do practitioners work around it?"
+   - "What are the second-order effects of [finding]?"
+   - "Who disagrees with [common finding] and why?"
+   - "What happened when [solution] was deployed at scale?"
+
+3. **Targeted deep-dive searches**: Execute follow-up searches focusing on:
+   - Specific claims that need verification
+   - Alternative viewpoints not yet represented
+   - Real-world case studies and experience reports
+   - Failure cases and edge conditions
+   - Recent developments that may change the picture
+
+4. **Update artifacts**: Append new sources to `01_source_registry.md`, new facts to `02_fact_cards.md`
+
+**Exit criteria**: Proceed to Step 4 when:
+- Every sub-question has at least 3 facts with at least one from L1/L2
+- At least 3 perspectives from Step 1 have supporting evidence
+- No unresolved contradictions remain (or they are explicitly documented as open questions)
+- Follow-up searches are no longer producing new substantive information

.cursor/skills/research/steps/04_engine-analysis.md

@@ -0,0 +1,146 @@
+## Research Engine — Analysis Phase (Steps 4–8)
+
+### Step 4: Build Comparison/Analysis Framework
+
+Based on the question type, select fixed analysis dimensions. **For dimension lists** (General, Concept Comparison, Decision Support): Read `references/comparison-frameworks.md`
+
+**Save action**:
+Write to `03_comparison_framework.md`:
+```markdown
+# Comparison Framework
+
+## Selected Framework Type
+[Concept Comparison / Decision Support / ...]
+
+## Selected Dimensions
+1. [Dimension 1]
+2. [Dimension 2]
+...
+
+## Initial Population
+| Dimension | X | Y | Factual Basis |
+|-----------|---|---|---------------|
+| [Dimension 1] | [description] | [description] | Fact #1, #3 |
+| ... | | | |
+```
+
+---
+
+### Step 5: Reference Point Baseline Alignment
+
+Ensure all compared parties have clear, consistent definitions:
+
+**Checklist**:
+- [ ] Is the reference point's definition stable/widely accepted?
+- [ ] Does it need verification, or can domain common knowledge be used?
+- [ ] Does the reader's understanding of the reference point match mine?
+- [ ] Are there ambiguities that need to be clarified first?
+
+---
+
+### Step 6: Fact-to-Conclusion Reasoning Chain
+
+Explicitly write out the "fact → comparison → conclusion" reasoning process:
+
+```markdown
+## Reasoning Process
+
+### Regarding [Dimension Name]
+
+1. **Fact confirmation**: According to [source], X's mechanism is...
+2. **Compare with reference**: While Y's mechanism is...
+3. **Conclusion**: Therefore, the difference between X and Y on this dimension is...
+```
+
+**Key discipline**:
+- Conclusions come from mechanism comparison, not "gut feelings"
+- Every conclusion must be traceable to specific facts
+- Uncertain conclusions must be annotated
+
+**Save action**:
+Write to `04_reasoning_chain.md`:
+```markdown
+# Reasoning Chain
+
+## Dimension 1: [Dimension Name]
+
+### Fact Confirmation
+According to [Fact #X], X's mechanism is...
+
+### Reference Comparison
+While Y's mechanism is... (Source: [Fact #Y])
+
+### Conclusion
+Therefore, the difference between X and Y on this dimension is...
+
+### Confidence
+✅/⚠️/❓ + rationale
+
+---
+## Dimension 2: [Dimension Name]
+...
+```
+
+---
+
+### Step 7: Use-Case Validation (Sanity Check)
+
+Validate conclusions against a typical scenario:
+
+**Validation questions**:
+- Based on my conclusions, how should this scenario be handled?
+- Is that actually the case?
+- Are there counterexamples that need to be addressed?
+
+**Review checklist**:
+- [ ] Are draft conclusions consistent with Step 3 fact cards?
+- [ ] Are there any important dimensions missed?
+- [ ] Is there any over-extrapolation?
+- [ ] Are conclusions actionable/verifiable?
+
+**Save action**:
+Write to `05_validation_log.md`:
+```markdown
+# Validation Log
+
+## Validation Scenario
+[Scenario description]
+
+## Expected Based on Conclusions
+If using X: [expected behavior]
+If using Y: [expected behavior]
+
+## Actual Validation Results
+[actual situation]
+
+## Counterexamples
+[yes/no, describe if yes]
+
+## Review Checklist
+- [x] Draft conclusions consistent with fact cards
+- [x] No important dimensions missed
+- [x] No over-extrapolation
+- [ ] Issue found: [if any]
+
+## Conclusions Requiring Revision
+[if any]
+```
+
+---
+
+### Step 8: Deliverable Formatting
+
+Make the output **readable, traceable, and actionable**.
+
+**Save action**:
+Integrate all intermediate artifacts. Write to `OUTPUT_DIR/solution_draft##.md` using the appropriate output template based on active mode:
+- Mode A: `templates/solution_draft_mode_a.md`
+- Mode B: `templates/solution_draft_mode_b.md`
+
+Sources to integrate:
+- Extract background from `00_question_decomposition.md`
+- Reference key facts from `02_fact_cards.md`
+- Organize conclusions from `04_reasoning_chain.md`
+- Generate references from `01_source_registry.md`
+- Supplement with use cases from `05_validation_log.md`
+- For Mode A: include AC assessment from `00_ac_assessment.md`

.cursor/skills/retrospective/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: retrospective
+description: |
+  Collect metrics from implementation batch reports and code review findings, analyze trends across cycles,
+  and produce improvement reports with actionable recommendations.
+  3-step workflow: collect metrics, analyze trends, produce report.
+  Outputs to _docs/06_metrics/.
+  Trigger phrases:
+  - "retrospective", "retro", "run retro"
+  - "metrics review", "feedback loop"
+  - "implementation metrics", "analyze trends"
+category: evolve
+tags: [retrospective, metrics, trends, improvement, feedback-loop]
+disable-model-invocation: true
+---
+
+# Retrospective
+
+Collect metrics from implementation artifacts, analyze trends across development cycles, and produce actionable improvement reports.
+
+## Core Principles
+
+- **Data-driven**: conclusions come from metrics, not impressions
+- **Actionable**: every finding must have a concrete improvement suggestion
+- **Cumulative**: each retrospective compares against previous ones to track progress
+- **Save immediately**: write artifacts to disk after each step
+- **Non-judgmental**: focus on process improvement, not blame
+
+## Context Resolution
+
+Fixed paths:
+
+- IMPL_DIR: `_docs/03_implementation/`
+- METRICS_DIR: `_docs/06_metrics/`
+- TASKS_DIR: `_docs/02_tasks/`
+
+Announce the resolved paths to the user before proceeding.
+
+## Prerequisite Checks (BLOCKING)
+
+1. `IMPL_DIR` exists and contains at least one `batch_*_report.md` — **STOP if missing** (nothing to analyze)
+2. Create METRICS_DIR if it does not exist
+3. Check for previous retrospective reports in METRICS_DIR to enable trend comparison
+
+## Artifact Management
+
+### Directory Structure
+
+```
+METRICS_DIR/
+├── retro_[YYYY-MM-DD].md
+├── retro_[YYYY-MM-DD].md
+└── ...
+```
+
+## Progress Tracking
+
+At the start of execution, create a TodoWrite with all steps (1 through 3). Update status as each step completes.
+
+## Workflow
+
+### Step 1: Collect Metrics
+
+**Role**: Data analyst
+**Goal**: Parse all implementation artifacts and extract quantitative metrics
+**Constraints**: Collection only — no interpretation yet
+
+#### Sources
+
+| Source | Metrics Extracted |
+|--------|------------------|
+| `batch_*_report.md` | Tasks per batch, batch count, task statuses (Done/Blocked/Partial) |
+| Code review sections in batch reports | PASS/FAIL/PASS_WITH_WARNINGS ratios, finding counts by severity and category |
+| Task spec files in TASKS_DIR | Complexity points per task, dependency count |
+| `FINAL_implementation_report.md` | Total tasks, total batches, overall duration |
+| Git log (if available) | Commits per batch, files changed per batch |
+
+#### Metrics to Compute
+
+**Implementation Metrics**:
+- Total tasks implemented
+- Total batches executed
+- Average tasks per batch
+- Average complexity points per batch
+- Total complexity points delivered
+
+**Quality Metrics**:
+- Code review pass rate (PASS / total reviews)
+- Code review findings by severity: Critical, High, Medium, Low counts
+- Code review findings by category: Bug, Spec-Gap, Security, Performance, Maintainability, Style, Scope
+- FAIL count (batches that required user intervention)
+
+**Efficiency Metrics**:
+- Blocked task count and reasons
+- Tasks completed on first attempt vs requiring fixes
+- Batch with most findings (identify problem areas)
+
+**Self-verification**:
+- [ ] All batch reports parsed
+- [ ] All metric categories computed
+- [ ] No batch reports missed
+
+---
+
+### Step 2: Analyze Trends
+
+**Role**: Process improvement analyst
+**Goal**: Identify patterns, recurring issues, and improvement opportunities
+**Constraints**: Analysis must be grounded in the metrics from Step 1
+
+1. If previous retrospective reports exist in METRICS_DIR, load the most recent one for comparison
+2. Identify patterns:
+   - **Recurring findings**: which code review categories appear most frequently?
+   - **Problem components**: which components/files generate the most findings?
+   - **Complexity accuracy**: do high-complexity tasks actually produce more issues?
+   - **Blocker patterns**: what types of blockers occur and can they be prevented?
+3. Compare against previous retrospective (if exists):
+   - Which metrics improved?
+   - Which metrics degraded?
+   - Were previous improvement actions effective?
+4. Identify top 3 improvement actions ranked by impact
+
+**Self-verification**:
+- [ ] Patterns are grounded in specific metrics
+- [ ] Comparison with previous retro included (if exists)
+- [ ] Top 3 actions are concrete and actionable
+
+---
+
+### Step 3: Produce Report
+
+**Role**: Technical writer
+**Goal**: Write a structured retrospective report with metrics, trends, and recommendations
+**Constraints**: Concise, data-driven, actionable
+
+Write `METRICS_DIR/retro_[YYYY-MM-DD].md` using `templates/retrospective-report.md` as structure.
+
+**Self-verification**:
+- [ ] All metrics from Step 1 included
+- [ ] Trend analysis from Step 2 included
+- [ ] Top 3 improvement actions clearly stated
+- [ ] Suggested rule/skill updates are specific
+
+**Save action**: Write `retro_[YYYY-MM-DD].md`
+
+Present the report summary to the user.
+
+---
+
+## Escalation Rules
+
+| Situation | Action |
+|-----------|--------|
+| No batch reports exist | **STOP** — nothing to analyze |
+| Batch reports have inconsistent format | **WARN user**, extract what is available |
+| No previous retrospective for comparison | PROCEED — report baseline metrics only |
+| Metrics suggest systemic issue (>50% FAIL rate) | **WARN user** — suggest immediate process review |
+
+## Methodology Quick Reference
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│              Retrospective (3-Step Method)                     │
+├────────────────────────────────────────────────────────────────┤
+│ PREREQ: batch reports exist in _docs/03_implementation/        │
+│                                                                │
+│ 1. Collect Metrics  → parse batch reports, compute metrics     │
+│ 2. Analyze Trends   → patterns, comparison, improvement areas  │
+│ 3. Produce Report   → _docs/06_metrics/retro_[date].md         │
+├────────────────────────────────────────────────────────────────┤
+│ Principles: Data-driven · Actionable · Cumulative              │
+│             Non-judgmental · Save immediately                  │
+└────────────────────────────────────────────────────────────────┘
+```

.cursor/skills/retrospective/templates/retrospective-report.md

@@ -0,0 +1,93 @@
+# Retrospective Report Template
+
+Save as `_docs/05_metrics/retro_[YYYY-MM-DD].md`.
+
+---
+
+```markdown
+# Retrospective — [YYYY-MM-DD]
+
+## Implementation Summary
+
+| Metric | Value |
+|--------|-------|
+| Total tasks | [count] |
+| Total batches | [count] |
+| Total complexity points | [sum] |
+| Avg tasks per batch | [value] |
+| Avg complexity per batch | [value] |
+
+## Quality Metrics
+
+### Code Review Results
+
+| Verdict | Count | Percentage |
+|---------|-------|-----------|
+| PASS | [count] | [%] |
+| PASS_WITH_WARNINGS | [count] | [%] |
+| FAIL | [count] | [%] |
+
+### Findings by Severity
+
+| Severity | Count |
+|----------|-------|
+| Critical | [count] |
+| High | [count] |
+| Medium | [count] |
+| Low | [count] |
+
+### Findings by Category
+
+| Category | Count | Top Files |
+|----------|-------|-----------|
+| Bug | [count] | [most affected files] |
+| Spec-Gap | [count] | [most affected files] |
+| Security | [count] | [most affected files] |
+| Performance | [count] | [most affected files] |
+| Maintainability | [count] | [most affected files] |
+| Style | [count] | [most affected files] |
+
+## Efficiency
+
+| Metric | Value |
+|--------|-------|
+| Blocked tasks | [count] |
+| Tasks requiring fixes after review | [count] |
+| Batch with most findings | Batch [N] — [reason] |
+
+### Blocker Analysis
+
+| Blocker Type | Count | Prevention |
+|-------------|-------|-----------|
+| [type] | [count] | [suggested prevention] |
+
+## Trend Comparison
+
+| Metric | Previous | Current | Change |
+|--------|----------|---------|--------|
+| Pass rate | [%] | [%] | [+/-] |
+| Avg findings per batch | [value] | [value] | [+/-] |
+| Blocked tasks | [count] | [count] | [+/-] |
+
+*Previous retrospective: [date or "N/A — first retro"]*
+
+## Top 3 Improvement Actions
+
+1. **[Action title]**: [specific, actionable description]
+   - Impact: [expected improvement]
+   - Effort: [low/medium/high]
+
+2. **[Action title]**: [specific, actionable description]
+   - Impact: [expected improvement]
+   - Effort: [low/medium/high]
+
+3. **[Action title]**: [specific, actionable description]
+   - Impact: [expected improvement]
+   - Effort: [low/medium/high]
+
+## Suggested Rule/Skill Updates
+
+| File | Change | Rationale |
+|------|--------|-----------|
+| [.cursor/rules/... or .cursor/skills/...] | [specific change] | [based on which metric] |
+```

.cursor/skills/security/SKILL.md

@@ -1,311 +1,347 @@
 ---
-name: security-testing
+name: security
-description: "Test for security vulnerabilities using OWASP principles. Use when conducting security audits, testing auth, or implementing security practices."
+description: |
-category: specialized-testing
+  OWASP-based security audit skill. Analyzes codebase for vulnerabilities across dependency scanning,
-priority: critical
+  static analysis, OWASP Top 10 review, and secrets detection. Produces a structured security report
-tokenEstimate: 1200
+  with severity-ranked findings and remediation guidance.
-agents: [qe-security-scanner, qe-api-contract-validator, qe-quality-analyzer]
+  Can be invoked standalone or as part of the autopilot flow (optional step before deploy).
-implementation_status: optimized
+  Trigger phrases:
-optimization_version: 1.0
+  - "security audit", "security scan", "OWASP review"
-last_optimized: 2025-12-02
+  - "vulnerability scan", "security check"
-dependencies: []
+  - "check for vulnerabilities", "pentest"
-quick_reference_card: true
+category: review
-tags: [security, owasp, sast, dast, vulnerabilities, auth, injection]
+tags: [security, owasp, sast, vulnerabilities, auth, injection, secrets]
-trust_tier: 3
+disable-model-invocation: true
-validation:
-  schema_path: schemas/output.json
-  validator_path: scripts/validate-config.json
-  eval_path: evals/security-testing.yaml
 ---
 
-# Security Testing
+# Security Audit
 
-<default_to_action>
+Analyze the codebase for security vulnerabilities using OWASP principles. Produces a structured report with severity-ranked findings, remediation suggestions, and a security checklist verdict.
-When testing security or conducting audits:
-1. TEST OWASP Top 10 vulnerabilities systematically
-2. VALIDATE authentication and authorization on every endpoint
-3. SCAN dependencies for known vulnerabilities (npm audit)
-4. CHECK for injection attacks (SQL, XSS, command)
-5. VERIFY secrets aren't exposed in code/logs
 
-**Quick Security Checks:**
+## Core Principles
-- Access control → Test horizontal/vertical privilege escalation
-- Crypto → Verify password hashing, HTTPS, no sensitive data exposed
-- Injection → Test SQL injection, XSS, command injection
-- Auth → Test weak passwords, session fixation, MFA enforcement
-- Config → Check error messages don't leak info
 
-**Critical Success Factors:**
+- **OWASP-driven**: use the current OWASP Top 10 as the primary framework — verify the latest version at https://owasp.org/www-project-top-ten/ at audit start
-- Think like an attacker, build like a defender
+- **Evidence-based**: every finding must reference a specific file, line, or configuration
-- Security is built in, not added at the end
+- **Severity-ranked**: findings sorted Critical > High > Medium > Low
-- Test continuously in CI/CD, not just before release
+- **Actionable**: every finding includes a concrete remediation suggestion
-</default_to_action>
+- **Save immediately**: write artifacts to disk after each phase; never accumulate unsaved work
+- **Complement, don't duplicate**: the `/code-review` skill does a lightweight security quick-scan; this skill goes deeper
 
-## Quick Reference Card
+## Context Resolution
 
-### When to Use
+**Project mode** (default):
-- Security audits and penetration testing
+- PROBLEM_DIR: `_docs/00_problem/`
-- Testing authentication/authorization
+- SOLUTION_DIR: `_docs/01_solution/`
-- Validating input sanitization
+- DOCUMENT_DIR: `_docs/02_document/`
-- Reviewing security configuration
+- SECURITY_DIR: `_docs/05_security/`
 
-### OWASP Top 10 (2021)
+**Standalone mode** (explicit target provided, e.g. `/security @src/api/`):
-| # | Vulnerability | Key Test |
+- TARGET: the provided path
-|---|---------------|----------|
+- SECURITY_DIR: `_standalone/security/`
-| 1 | Broken Access Control | User A accessing User B's data |
-| 2 | Cryptographic Failures | Plaintext passwords, HTTP |
-| 3 | Injection | SQL/XSS/command injection |
-| 4 | Insecure Design | Rate limiting, session timeout |
-| 5 | Security Misconfiguration | Verbose errors, exposed /admin |
-| 6 | Vulnerable Components | npm audit, outdated packages |
-| 7 | Auth Failures | Weak passwords, no MFA |
-| 8 | Integrity Failures | Unsigned updates, malware |
-| 9 | Logging Failures | No audit trail for breaches |
-| 10 | SSRF | Server fetching internal URLs |
 
-### Tools
+Announce the detected mode and resolved paths to the user before proceeding.
-| Type | Tool | Purpose |
-|------|------|---------|
-| SAST | SonarQube, Semgrep | Static code analysis |
-| DAST | OWASP ZAP, Burp | Dynamic scanning |
-| Deps | npm audit, Snyk | Dependency vulnerabilities |
-| Secrets | git-secrets, TruffleHog | Secret scanning |
 
-### Agent Coordination
+## Prerequisite Checks
-- `qe-security-scanner`: Multi-layer SAST/DAST scanning
+
-- `qe-api-contract-validator`: API security testing
+1. Codebase must contain source code files — **STOP if empty**
-- `qe-quality-analyzer`: Security code review
+2. Create SECURITY_DIR if it does not exist
+3. If SECURITY_DIR already contains artifacts, ask user: **resume, overwrite, or skip?**
+4. If `_docs/00_problem/security_approach.md` exists, read it for project-specific security requirements
+
+## Progress Tracking
+
+At the start of execution, create a TodoWrite with all phases (1 through 5). Update status as each phase completes.
+
+## Workflow
+
+### Phase 1: Dependency Scan
+
+**Role**: Security analyst
+**Goal**: Identify known vulnerabilities in project dependencies
+**Constraints**: Scan only — no code changes
+
+1. Detect the project's package manager(s): `requirements.txt`, `package.json`, `Cargo.toml`, `*.csproj`, `go.mod`
+2. Run the appropriate audit tool:
+   - Python: `pip audit` or `safety check`
+   - Node: `npm audit`
+   - Rust: `cargo audit`
+   - .NET: `dotnet list package --vulnerable`
+   - Go: `govulncheck`
+3. If no audit tool is available, manually inspect dependency files for known CVEs using WebSearch
+4. Record findings with CVE IDs, affected packages, severity, and recommended upgrade versions
+
+**Self-verification**:
+- [ ] All package manifests scanned
+- [ ] Each finding has a CVE ID or advisory reference
+- [ ] Upgrade paths identified for Critical/High findings
+
+**Save action**: Write `SECURITY_DIR/dependency_scan.md`
 
 ---
 
-## Key Vulnerability Tests
+### Phase 2: Static Analysis (SAST)
 
-### 1. Broken Access Control
+**Role**: Security engineer
-```javascript
+**Goal**: Identify code-level vulnerabilities through static analysis
-// Horizontal escalation - User A accessing User B's data
+**Constraints**: Analysis only — no code changes
-test('user cannot access another user\'s order', async () => {
-  const userAToken = await login('userA');
-  const userBOrder = await createOrder('userB');
 
-  const response = await api.get(`/orders/${userBOrder.id}`, {
+Scan the codebase for these vulnerability patterns:
-    headers: { Authorization: `Bearer ${userAToken}` }
-  });
-  expect(response.status).toBe(403);
-});
 
-// Vertical escalation - Regular user accessing admin
+**Injection**:
-test('regular user cannot access admin', async () => {
+- SQL injection via string interpolation or concatenation
-  const userToken = await login('regularUser');
+- Command injection (subprocess with shell=True, exec, eval, os.system)
-  expect((await api.get('/admin/users', {
+- XSS via unsanitized user input in HTML output
-    headers: { Authorization: `Bearer ${userToken}` }
+- Template injection
-  })).status).toBe(403);
-});
-```
 
-### 2. Injection Attacks
+**Authentication & Authorization**:
-```javascript
+- Hardcoded credentials, API keys, passwords, tokens
-// SQL Injection
+- Missing authentication checks on endpoints
-test('prevents SQL injection', async () => {
+- Missing authorization checks (horizontal/vertical escalation paths)
-  const malicious = "' OR '1'='1";
+- Weak password validation rules
-  const response = await api.get(`/products?search=${malicious}`);
-  expect(response.body.length).toBeLessThan(100); // Not all products
-});
 
-// XSS
+**Cryptographic Failures**:
-test('sanitizes HTML output', async () => {
+- Plaintext password storage (no hashing)
-  const xss = '<script>alert("XSS")</script>';
+- Weak hashing algorithms (MD5, SHA1 for passwords)
-  await api.post('/comments', { text: xss });
+- Hardcoded encryption keys or salts
+- Missing TLS/HTTPS enforcement
 
-  const html = (await api.get('/comments')).body;
+**Data Exposure**:
-  expect(html).toContain('&lt;script&gt;');
+- Sensitive data in logs or error messages (passwords, tokens, PII)
-  expect(html).not.toContain('<script>');
+- Sensitive fields in API responses (password hashes, SSNs)
-});
+- Debug endpoints or verbose error messages in production configs
-```
+- Secrets in version control (.env files, config with credentials)
 
-### 3. Cryptographic Failures
+**Insecure Deserialization**:
-```javascript
+- Pickle/marshal deserialization of untrusted data
-test('passwords are hashed', async () => {
+- JSON/XML parsing without size limits
-  await db.users.create({ email: 'test@example.com', password: 'MyPassword123' });
-  const user = await db.users.findByEmail('test@example.com');
 
-  expect(user.password).not.toBe('MyPassword123');
+**Self-verification**:
-  expect(user.password).toMatch(/^\$2[aby]\$\d{2}\$/); // bcrypt
+- [ ] All source directories scanned
-});
+- [ ] Each finding has file path and line number
+- [ ] No false positives from test files or comments
 
-test('no sensitive data in API response', async () => {
+**Save action**: Write `SECURITY_DIR/static_analysis.md`
-  const response = await api.get('/users/me');
-  expect(response.body).not.toHaveProperty('password');
-  expect(response.body).not.toHaveProperty('ssn');
-});
-```
-
-### 4. Security Misconfiguration
-```javascript
-test('errors don\'t leak sensitive info', async () => {
-  const response = await api.post('/login', { email: 'nonexistent@test.com', password: 'wrong' });
-  expect(response.body.error).toBe('Invalid credentials'); // Generic message
-});
-
-test('sensitive endpoints not exposed', async () => {
-  const endpoints = ['/debug', '/.env', '/.git', '/admin'];
-  for (let ep of endpoints) {
-    expect((await fetch(`https://example.com${ep}`)).status).not.toBe(200);
-  }
-});
-```
-
-### 5. Rate Limiting
-```javascript
-test('rate limiting prevents brute force', async () => {
-  const responses = [];
-  for (let i = 0; i < 20; i++) {
-    responses.push(await api.post('/login', { email: 'test@example.com', password: 'wrong' }));
-  }
-  expect(responses.filter(r => r.status === 429).length).toBeGreaterThan(0);
-});
-```
 
 ---
 
-## Security Checklist
+### Phase 3: OWASP Top 10 Review
+
+**Role**: Penetration tester
+**Goal**: Systematically review the codebase against current OWASP Top 10 categories
+**Constraints**: Review and document — no code changes
+
+1. Research the current OWASP Top 10 version at https://owasp.org/www-project-top-ten/
+2. For each OWASP category, assess the codebase:
+
+| Check | What to Look For |
+|-------|-----------------|
+| Broken Access Control | Missing auth middleware, IDOR vulnerabilities, CORS misconfiguration, directory traversal |
+| Cryptographic Failures | Weak algorithms, plaintext transmission, missing encryption at rest |
+| Injection | SQL, NoSQL, OS command, LDAP injection paths |
+| Insecure Design | Missing rate limiting, no input validation strategy, trust boundary violations |
+| Security Misconfiguration | Default credentials, unnecessary features enabled, missing security headers |
+| Vulnerable Components | Outdated dependencies (from Phase 1), unpatched frameworks |
+| Auth Failures | Brute force paths, weak session management, missing MFA |
+| Data Integrity Failures | Missing signature verification, insecure CI/CD, auto-update without verification |
+| Logging Failures | Missing audit logs, sensitive data in logs, no alerting for security events |
+| SSRF | Unvalidated URL inputs, internal network access from user-controlled URLs |
+
+3. Rate each category: PASS / FAIL / NOT_APPLICABLE
+4. If `security_approach.md` exists, cross-reference its requirements against findings
+
+**Self-verification**:
+- [ ] All current OWASP Top 10 categories assessed
+- [ ] Each FAIL has at least one specific finding with evidence
+- [ ] NOT_APPLICABLE categories have justification
+
+**Save action**: Write `SECURITY_DIR/owasp_review.md`
+
+---
+
+### Phase 4: Configuration & Infrastructure Review
+
+**Role**: DevSecOps engineer
+**Goal**: Review deployment configuration for security issues
+**Constraints**: Review only — no changes
+
+If Dockerfiles, CI/CD configs, or deployment configs exist:
+
+1. **Container security**: non-root user, minimal base images, no secrets in build args, health checks
+2. **CI/CD security**: secrets management, no credentials in pipeline files, artifact signing
+3. **Environment configuration**: .env handling, secrets injection method, environment separation
+4. **Network security**: exposed ports, TLS configuration, CORS settings, security headers
+
+If no deployment configs exist, skip this phase and note it in the report.
+
+**Self-verification**:
+- [ ] All Dockerfiles reviewed
+- [ ] All CI/CD configs reviewed
+- [ ] All environment/config files reviewed
+
+**Save action**: Write `SECURITY_DIR/infrastructure_review.md`
+
+---
+
+### Phase 5: Security Report
+
+**Role**: Security analyst
+**Goal**: Produce a consolidated security audit report
+**Constraints**: Concise, actionable, severity-ranked
+
+Consolidate findings from Phases 1-4 into a structured report:
+
+```markdown
+# Security Audit Report
+
+**Date**: [YYYY-MM-DD]
+**Scope**: [project name / target path]
+**Verdict**: PASS | PASS_WITH_WARNINGS | FAIL
+
+## Summary
+
+| Severity | Count |
+|----------|-------|
+| Critical | [N] |
+| High     | [N] |
+| Medium   | [N] |
+| Low      | [N] |
+
+## OWASP Top 10 Assessment
+
+| Category | Status | Findings |
+|----------|--------|----------|
+| [category] | PASS / FAIL / N/A | [count or —] |
+
+## Findings
+
+| # | Severity | Category | Location | Title |
+|---|----------|----------|----------|-------|
+| 1 | Critical | Injection | src/api.py:42 | SQL injection via f-string |
+
+### Finding Details
+
+**F1: [title]** (Severity / Category)
+- Location: `[file:line]`
+- Description: [what is vulnerable]
+- Impact: [what an attacker could do]
+- Remediation: [specific fix]
+
+## Dependency Vulnerabilities
+
+| Package | CVE | Severity | Fix Version |
+|---------|-----|----------|-------------|
+| [name] | [CVE-ID] | [sev] | [version] |
+
+## Recommendations
+
+### Immediate (Critical/High)
+- [action items]
+
+### Short-term (Medium)
+- [action items]
+
+### Long-term (Low / Hardening)
+- [action items]
+```
+
+**Self-verification**:
+- [ ] All findings from Phases 1-4 included
+- [ ] No duplicate findings
+- [ ] Every finding has remediation guidance
+- [ ] Verdict matches severity logic
+
+**Save action**: Write `SECURITY_DIR/security_report.md`
+
+**BLOCKING**: Present report summary to user.
+
+## Verdict Logic
+
+- **FAIL**: any Critical or High finding exists
+- **PASS_WITH_WARNINGS**: only Medium or Low findings
+- **PASS**: no findings
+
+## Security Checklist (Quick Reference)
 
 ### Authentication
 - [ ] Strong password requirements (12+ chars)
 - [ ] Password hashing (bcrypt, scrypt, Argon2)
 - [ ] MFA for sensitive operations
 - [ ] Account lockout after failed attempts
-- [ ] Session ID changes after login
+- [ ] Session timeout and rotation
-- [ ] Session timeout
 
 ### Authorization
 - [ ] Check authorization on every request
 - [ ] Least privilege principle
-- [ ] No horizontal escalation
+- [ ] No horizontal/vertical escalation paths
-- [ ] No vertical escalation
 
 ### Data Protection
 - [ ] HTTPS everywhere
 - [ ] Encrypted at rest
-- [ ] Secrets not in code/logs
+- [ ] Secrets not in code/logs/version control
 - [ ] PII compliance (GDPR)
 
 ### Input Validation
-- [ ] Server-side validation
+- [ ] Server-side validation on all inputs
 - [ ] Parameterized queries (no SQL injection)
 - [ ] Output encoding (no XSS)
-- [ ] Rate limiting
+- [ ] Rate limiting on sensitive endpoints
 
----
+### CI/CD Security
+- [ ] Dependency audit in pipeline
+- [ ] Secret scanning (git-secrets, TruffleHog)
+- [ ] SAST in pipeline (Semgrep, SonarQube)
+- [ ] No secrets in pipeline config files
 
-## CI/CD Integration
+## Escalation Rules
 
-```yaml
+| Situation | Action |
-# GitHub Actions
+|-----------|--------|
-security-checks:
+| Critical vulnerability found | **WARN user immediately** — do not defer to report |
-  steps:
+| No audit tools available | Use manual code review + WebSearch for CVEs |
-    - name: Dependency audit
+| Codebase too large for full scan | **ASK user** to prioritize areas (API endpoints, auth, data access) |
-      run: npm audit --audit-level=high
+| Finding requires runtime testing (DAST) | Note as "requires DAST verification" — this skill does static analysis only |
-
+| Conflicting security requirements | **ASK user** to prioritize |
-    - name: SAST scan
-      run: npm run sast
-
-    - name: Secret scan
-      uses: trufflesecurity/trufflehog@main
-
-    - name: DAST scan
-      if: github.ref == 'refs/heads/main'
-      run: docker run owasp/zap2docker-stable zap-baseline.py -t https://staging.example.com
-```
-
-**Pre-commit hooks:**
-```bash
-#!/bin/sh
-git-secrets --scan
-npm run lint:security
-```
-
----
-
-## Agent-Assisted Security Testing
-
-```typescript
-// Comprehensive multi-layer scan
-await Task("Security Scan", {
-  target: 'src/',
-  layers: { sast: true, dast: true, dependencies: true, secrets: true },
-  severity: ['critical', 'high', 'medium']
-}, "qe-security-scanner");
-
-// OWASP Top 10 testing
-await Task("OWASP Scan", {
-  categories: ['broken-access-control', 'injection', 'cryptographic-failures'],
-  depth: 'comprehensive'
-}, "qe-security-scanner");
-
-// Validate fix
-await Task("Validate Fix", {
-  vulnerability: 'CVE-2024-12345',
-  expectedResolution: 'upgrade package to v2.0.0',
-  retestAfterFix: true
-}, "qe-security-scanner");
-```
-
----
-
-## Agent Coordination Hints
-
-### Memory Namespace
-```
-aqe/security/
-├── scans/*           - Scan results
-├── vulnerabilities/* - Found vulnerabilities
-├── fixes/*           - Remediation tracking
-└── compliance/*      - Compliance status
-```
-
-### Fleet Coordination
-```typescript
-const securityFleet = await FleetManager.coordinate({
-  strategy: 'security-testing',
-  agents: [
-    'qe-security-scanner',
-    'qe-api-contract-validator',
-    'qe-quality-analyzer',
-    'qe-deployment-readiness'
-  ],
-  topology: 'parallel'
-});
-```
-
----
 
 ## Common Mistakes
 
-### ❌ Security by Obscurity
+- **Security by obscurity**: hiding admin at secret URLs instead of proper auth
-Hiding admin at `/super-secret-admin` → **Use proper auth**
+- **Client-side validation only**: JavaScript validation can be bypassed; always validate server-side
+- **Trusting user input**: assume all input is malicious until proven otherwise
+- **Hardcoded secrets**: use environment variables and secret management, never code
+- **Skipping dependency scan**: known CVEs in dependencies are the lowest-hanging fruit for attackers
 
-### ❌ Client-Side Validation Only
+## Trigger Conditions
-JavaScript validation can be bypassed → **Always validate server-side**
 
-### ❌ Trusting User Input
+When the user wants to:
-Assuming input is safe → **Sanitize, validate, escape all input**
+- Conduct a security audit of the codebase
+- Check for vulnerabilities before deployment
+- Review security posture after implementation
+- Validate security requirements from `security_approach.md`
 
-### ❌ Hardcoded Secrets
+**Keywords**: "security audit", "security scan", "OWASP", "vulnerability scan", "security check", "pentest"
-API keys in code → **Environment variables, secret management**
 
----
+**Differentiation**:
+- Lightweight security checks during implementation → handled by `/code-review` Phase 4
+- Full security audit → use this skill
+- Security requirements gathering → handled by `/problem` (security dimension)
 
-## Related Skills
+## Methodology Quick Reference
-- [agentic-quality-engineering](../agentic-quality-engineering/) - Security with agents
-- [api-testing-patterns](../api-testing-patterns/) - API security testing
-- [compliance-testing](../compliance-testing/) - GDPR, HIPAA, SOC2
 
----
+```
-
+┌────────────────────────────────────────────────────────────────┐
-## Remember
+│              Security Audit (5-Phase Method)                    │
-
+├────────────────────────────────────────────────────────────────┤
-**Think like an attacker:** What would you try to break? Test that.
+│ PREREQ: Source code exists, SECURITY_DIR created               │
-**Build like a defender:** Assume input is malicious until proven otherwise.
+│                                                                │
-**Test continuously:** Security testing is ongoing, not one-time.
+│ 1. Dependency Scan    → dependency_scan.md                     │
-
+│ 2. Static Analysis    → static_analysis.md                     │
-**With Agents:** Agents automate vulnerability scanning, track remediation, and validate fixes. Use agents to maintain security posture at scale.
+│ 3. OWASP Top 10      → owasp_review.md                        │
+│ 4. Infrastructure     → infrastructure_review.md               │
+│ 5. Security Report    → security_report.md                     │
+│    [BLOCKING: user reviews report]                             │
+├────────────────────────────────────────────────────────────────┤
+│ Verdict: PASS / PASS_WITH_WARNINGS / FAIL                      │
+│ Principles: OWASP-driven · Evidence-based · Severity-ranked    │
+│             Actionable · Save immediately                      │
+└────────────────────────────────────────────────────────────────┘
+```

.cursor/skills/security/evals/security-testing.yaml

@@ -1,789 +0,0 @@
-# =============================================================================
-# AQE Skill Evaluation Test Suite: Security Testing v1.0.0
-# =============================================================================
-#
-# Comprehensive evaluation suite for the security-testing skill per ADR-056.
-# Tests OWASP Top 10 2021 detection, severity classification, remediation
-# quality, and cross-model consistency.
-#
-# Schema: .claude/skills/.validation/schemas/skill-eval.schema.json
-# Validator: .claude/skills/security-testing/scripts/validate-config.json
-#
-# Coverage:
-# - OWASP A01:2021 - Broken Access Control
-# - OWASP A02:2021 - Cryptographic Failures
-# - OWASP A03:2021 - Injection (SQL, XSS, Command)
-# - OWASP A07:2021 - Identification and Authentication Failures
-# - Negative tests (no false positives on secure code)
-#
-# =============================================================================
-
-skill: security-testing
-version: 1.0.0
-description: >
-  Comprehensive evaluation suite for the security-testing skill.
-  Tests OWASP Top 10 2021 detection capabilities, CWE classification accuracy,
-  CVSS scoring, severity classification, and remediation quality.
-  Supports multi-model testing and integrates with ReasoningBank for
-  continuous improvement.
-
-# =============================================================================
-# Multi-Model Configuration
-# =============================================================================
-
-models_to_test:
-  - claude-3.5-sonnet    # Primary model (high accuracy expected)
-  - claude-3-haiku       # Fast model (minimum quality threshold)
-  - gpt-4o               # Cross-vendor validation
-
-# =============================================================================
-# MCP Integration Configuration
-# =============================================================================
-
-mcp_integration:
-  enabled: true
-  namespace: skill-validation
-
-  # Query existing security patterns before running evals
-  query_patterns: true
-
-  # Track each test outcome for learning feedback loop
-  track_outcomes: true
-
-  # Store successful patterns after evals complete
-  store_patterns: true
-
-  # Share learning with fleet coordinator agents
-  share_learning: true
-
-  # Update quality gate with validation metrics
-  update_quality_gate: true
-
-  # Target agents for learning distribution
-  target_agents:
-    - qe-learning-coordinator
-    - qe-queen-coordinator
-    - qe-security-scanner
-    - qe-security-auditor
-
-# =============================================================================
-# ReasoningBank Learning Configuration
-# =============================================================================
-
-learning:
-  store_success_patterns: true
-  store_failure_patterns: true
-  pattern_ttl_days: 90
-  min_confidence_to_store: 0.7
-  cross_model_comparison: true
-
-# =============================================================================
-# Result Format Configuration
-# =============================================================================
-
-result_format:
-  json_output: true
-  markdown_report: true
-  include_raw_output: false
-  include_timing: true
-  include_token_usage: true
-
-# =============================================================================
-# Environment Setup
-# =============================================================================
-
-setup:
-  required_tools:
-    - jq       # JSON parsing (required)
-    - npm      # Dependency audit (optional but recommended)
-
-  environment_variables:
-    SECURITY_SCAN_DEPTH: "deep"
-    OWASP_ENABLED: "true"
-    SEVERITY_THRESHOLD: "medium"
-
-  fixtures:
-    - name: vulnerable_express_app
-      path: fixtures/vulnerable-express-app.js
-      content: |
-        const express = require('express');
-        const app = express();
-
-        // SQL Injection vulnerability
-        app.get('/user', (req, res) => {
-          const query = `SELECT * FROM users WHERE id = ${req.params.id}`;
-          db.query(query);
-        });
-
-        // XSS vulnerability
-        app.get('/profile', (req, res) => {
-          res.send(`<h1>Hello ${req.query.name}</h1>`);
-        });
-
-        // Path Traversal vulnerability
-        app.get('/file', (req, res) => {
-          const path = './uploads/' + req.query.filename;
-          res.sendFile(path);
-        });
-
-# =============================================================================
-# TEST CASES
-# =============================================================================
-
-test_cases:
-  # ---------------------------------------------------------------------------
-  # CATEGORY: SQL Injection (OWASP A03:2021)
-  # ---------------------------------------------------------------------------
-
-  - id: tc001_sql_injection_string_concat
-    description: "Detect SQL injection via string concatenation in Node.js"
-    category: injection
-    priority: critical
-
-    input:
-      code: |
-        const express = require('express');
-        const mysql = require('mysql');
-        const app = express();
-
-        app.get('/api/users', (req, res) => {
-          const userId = req.params.id;
-          const query = `SELECT * FROM users WHERE id = ${userId}`;
-          db.query(query, (err, results) => {
-            res.json(results);
-          });
-        });
-      context:
-        language: javascript
-        framework: express
-        environment: production
-
-    expected_output:
-      must_contain:
-        - "SQL injection"
-        - "parameterized"
-      must_not_contain:
-        - "no vulnerabilities"
-        - "secure"
-      must_match_regex:
-        - "CWE-89|CWE-564"
-        - "A03:20[21][0-9]"
-      severity_classification: critical
-      finding_count:
-        min: 1
-        max: 3
-      recommendation_count:
-        min: 1
-
-    validation:
-      schema_check: true
-      keyword_match_threshold: 0.8
-      reasoning_quality_min: 0.7
-      grading_rubric:
-        completeness: 0.3
-        accuracy: 0.5
-        actionability: 0.2
-
-    timeout_ms: 30000
-
-  - id: tc002_sql_injection_parameterized_safe
-    description: "Verify parameterized queries are NOT flagged as vulnerable"
-    category: injection
-    priority: high
-
-    input:
-      code: |
-        app.get('/api/users', (req, res) => {
-          const userId = parseInt(req.params.id, 10);
-          db.query('SELECT * FROM users WHERE id = ?', [userId], (err, results) => {
-            res.json(results);
-          });
-        });
-      context:
-        language: javascript
-        framework: express
-
-    expected_output:
-      must_contain:
-        - "parameterized"
-        - "secure"
-      must_not_contain:
-        - "SQL injection"
-        - "critical"
-        - "vulnerable"
-      severity_classification: info
-      finding_count:
-        max: 1
-
-    validation:
-      schema_check: true
-      keyword_match_threshold: 0.7
-      allow_partial: true
-
-  # ---------------------------------------------------------------------------
-  # CATEGORY: Cross-Site Scripting (OWASP A03:2021)
-  # ---------------------------------------------------------------------------
-
-  - id: tc003_xss_reflected_html_output
-    description: "Detect reflected XSS in unescaped HTML output"
-    category: injection
-    priority: critical
-
-    input:
-      code: |
-        app.get('/profile', (req, res) => {
-          const name = req.query.name;
-          res.send(`
-            <html>
-              <body>
-                <h1>Welcome, ${name}!</h1>
-                <p>Your profile has been loaded.</p>
-              </body>
-            </html>
-          `);
-        });
-      context:
-        language: javascript
-        framework: express
-
-    expected_output:
-      must_contain:
-        - "XSS"
-        - "cross-site scripting"
-        - "sanitize"
-        - "escape"
-      must_match_regex:
-        - "CWE-79"
-      severity_classification: high
-      finding_count:
-        min: 1
-
-    validation:
-      schema_check: true
-      keyword_match_threshold: 0.8
-      reasoning_quality_min: 0.75
-
-  - id: tc004_xss_dom_based_innerhtml
-    description: "Detect DOM-based XSS via innerHTML assignment"
-    category: injection
-    priority: high
-
-    input:
-      code: |
-        // Client-side JavaScript
-        const params = new URLSearchParams(window.location.search);
-        const message = params.get('msg');
-        document.getElementById('output').innerHTML = message;
-      context:
-        language: javascript
-        framework: vanilla
-        environment: production
-
-    expected_output:
-      must_contain:
-        - "DOM"
-        - "XSS"
-        - "innerHTML"
-        - "textContent"
-      must_match_regex:
-        - "CWE-79"
-      severity_classification: high
-
-    validation:
-      schema_check: true
-      keyword_match_threshold: 0.7
-
-  # ---------------------------------------------------------------------------
-  # CATEGORY: Authentication Failures (OWASP A07:2021)
-  # ---------------------------------------------------------------------------
-
-  - id: tc005_hardcoded_credentials
-    description: "Detect hardcoded credentials and API keys"
-    category: authentication
-    priority: critical
-
-    input:
-      code: |
-        const ADMIN_PASSWORD = 'admin123';
-        const API_KEY = 'sk-1234567890abcdef';
-        const DATABASE_URL = 'postgres://admin:password123@localhost/db';
-
-        app.post('/login', (req, res) => {
-          if (req.body.password === ADMIN_PASSWORD) {
-            req.session.isAdmin = true;
-            res.send('Login successful');
-          }
-        });
-      context:
-        language: javascript
-        framework: express
-
-    expected_output:
-      must_contain:
-        - "hardcoded"
-        - "credentials"
-        - "secret"
-        - "environment variable"
-      must_match_regex:
-        - "CWE-798|CWE-259"
-      severity_classification: critical
-      finding_count:
-        min: 2
-
-    validation:
-      schema_check: true
-      keyword_match_threshold: 0.8
-      reasoning_quality_min: 0.8
-
-  - id: tc006_weak_password_hashing
-    description: "Detect weak password hashing algorithms (MD5, SHA1)"
-    category: authentication
-    priority: high
-
-    input:
-      code: |
-        const crypto = require('crypto');
-
-        function hashPassword(password) {
-          return crypto.createHash('md5').update(password).digest('hex');
-        }
-
-        function verifyPassword(password, hash) {
-          return hashPassword(password) === hash;
-        }
-      context:
-        language: javascript
-        framework: nodejs
-
-    expected_output:
-      must_contain:
-        - "MD5"
-        - "weak"
-        - "bcrypt"
-        - "argon2"
-      must_match_regex:
-        - "CWE-327|CWE-328|CWE-916"
-      severity_classification: high
-      finding_count:
-        min: 1
-
-    validation:
-      schema_check: true
-      keyword_match_threshold: 0.8
-
-  # ---------------------------------------------------------------------------
-  # CATEGORY: Broken Access Control (OWASP A01:2021)
-  # ---------------------------------------------------------------------------
-
-  - id: tc007_idor_missing_authorization
-    description: "Detect IDOR vulnerability with missing authorization check"
-    category: authorization
-    priority: critical
-
-    input:
-      code: |
-        app.get('/api/users/:id/profile', (req, res) => {
-          // No authorization check - any user can access any profile
-          const userId = req.params.id;
-          db.query('SELECT * FROM profiles WHERE user_id = ?', [userId])
-            .then(profile => res.json(profile));
-        });
-
-        app.delete('/api/users/:id', (req, res) => {
-          // No check if requesting user owns this account
-          db.query('DELETE FROM users WHERE id = ?', [req.params.id]);
-          res.send('User deleted');
-        });
-      context:
-        language: javascript
-        framework: express
-
-    expected_output:
-      must_contain:
-        - "authorization"
-        - "access control"
-        - "IDOR"
-        - "ownership"
-      must_match_regex:
-        - "CWE-639|CWE-284|CWE-862"
-        - "A01:2021"
-      severity_classification: critical
-
-    validation:
-      schema_check: true
-      keyword_match_threshold: 0.7
-
-  # ---------------------------------------------------------------------------
-  # CATEGORY: Cryptographic Failures (OWASP A02:2021)
-  # ---------------------------------------------------------------------------
-
-  - id: tc008_weak_encryption_des
-    description: "Detect use of weak encryption algorithms (DES, RC4)"
-    category: cryptography
-    priority: high
-
-    input:
-      code: |
-        const crypto = require('crypto');
-
-        function encryptData(data, key) {
-          const cipher = crypto.createCipher('des', key);
-          return cipher.update(data, 'utf8', 'hex') + cipher.final('hex');
-        }
-
-        function decryptData(data, key) {
-          const decipher = crypto.createDecipher('des', key);
-          return decipher.update(data, 'hex', 'utf8') + decipher.final('utf8');
-        }
-      context:
-        language: javascript
-        framework: nodejs
-
-    expected_output:
-      must_contain:
-        - "DES"
-        - "weak"
-        - "deprecated"
-        - "AES"
-      must_match_regex:
-        - "CWE-327|CWE-328"
-        - "A02:2021"
-      severity_classification: high
-
-    validation:
-      schema_check: true
-      keyword_match_threshold: 0.7
-
-  - id: tc009_plaintext_password_storage
-    description: "Detect plaintext password storage"
-    category: cryptography
-    priority: critical
-
-    input:
-      code: |
-        class User {
-          constructor(email, password) {
-            this.email = email;
-            this.password = password;  // Stored in plaintext!
-          }
-
-          save() {
-            db.query('INSERT INTO users (email, password) VALUES (?, ?)',
-                     [this.email, this.password]);
-          }
-        }
-      context:
-        language: javascript
-        framework: nodejs
-
-    expected_output:
-      must_contain:
-        - "plaintext"
-        - "password"
-        - "hash"
-        - "bcrypt"
-      must_match_regex:
-        - "CWE-256|CWE-312"
-        - "A02:2021"
-      severity_classification: critical
-
-    validation:
-      schema_check: true
-      keyword_match_threshold: 0.8
-
-  # ---------------------------------------------------------------------------
-  # CATEGORY: Path Traversal (Related to A01:2021)
-  # ---------------------------------------------------------------------------
-
-  - id: tc010_path_traversal_file_access
-    description: "Detect path traversal vulnerability in file access"
-    category: injection
-    priority: critical
-
-    input:
-      code: |
-        const fs = require('fs');
-
-        app.get('/download', (req, res) => {
-          const filename = req.query.file;
-          const filepath = './uploads/' + filename;
-          res.sendFile(filepath);
-        });
-
-        app.get('/read', (req, res) => {
-          const content = fs.readFileSync('./data/' + req.params.name);
-          res.send(content);
-        });
-      context:
-        language: javascript
-        framework: express
-
-    expected_output:
-      must_contain:
-        - "path traversal"
-        - "directory traversal"
-        - "../"
-        - "sanitize"
-      must_match_regex:
-        - "CWE-22|CWE-23"
-      severity_classification: critical
-
-    validation:
-      schema_check: true
-      keyword_match_threshold: 0.7
-
-  # ---------------------------------------------------------------------------
-  # CATEGORY: Negative Tests (No False Positives)
-  # ---------------------------------------------------------------------------
-
-  - id: tc011_secure_code_no_false_positives
-    description: "Verify secure code is NOT flagged as vulnerable"
-    category: negative
-    priority: critical
-
-    input:
-      code: |
-        const express = require('express');
-        const helmet = require('helmet');
-        const rateLimit = require('express-rate-limit');
-        const bcrypt = require('bcrypt');
-        const validator = require('validator');
-
-        const app = express();
-        app.use(helmet());
-        app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));
-
-        app.post('/api/users', async (req, res) => {
-          const { email, password } = req.body;
-
-          // Input validation
-          if (!validator.isEmail(email)) {
-            return res.status(400).json({ error: 'Invalid email' });
-          }
-
-          // Secure password hashing
-          const hashedPassword = await bcrypt.hash(password, 12);
-
-          // Parameterized query
-          await db.query(
-            'INSERT INTO users (email, password) VALUES ($1, $2)',
-            [email, hashedPassword]
-          );
-
-          res.status(201).json({ message: 'User created' });
-        });
-      context:
-        language: javascript
-        framework: express
-        environment: production
-
-    expected_output:
-      must_contain:
-        - "secure"
-        - "best practice"
-      must_not_contain:
-        - "SQL injection"
-        - "XSS"
-        - "critical vulnerability"
-        - "high severity"
-      finding_count:
-        max: 2  # Allow informational findings only
-
-    validation:
-      schema_check: true
-      keyword_match_threshold: 0.6
-      allow_partial: true
-
-  - id: tc012_secure_auth_implementation
-    description: "Verify secure authentication is recognized as safe"
-    category: negative
-    priority: high
-
-    input:
-      code: |
-        const bcrypt = require('bcrypt');
-        const jwt = require('jsonwebtoken');
-
-        async function login(email, password) {
-          const user = await User.findByEmail(email);
-          if (!user) {
-            return { error: 'Invalid credentials' };
-          }
-
-          const match = await bcrypt.compare(password, user.passwordHash);
-          if (!match) {
-            return { error: 'Invalid credentials' };
-          }
-
-          const token = jwt.sign(
-            { userId: user.id },
-            process.env.JWT_SECRET,
-            { expiresIn: '1h' }
-          );
-
-          return { token };
-        }
-      context:
-        language: javascript
-        framework: nodejs
-
-    expected_output:
-      must_contain:
-        - "bcrypt"
-        - "jwt"
-        - "secure"
-      must_not_contain:
-        - "vulnerable"
-        - "critical"
-        - "hardcoded"
-      severity_classification: info
-
-    validation:
-      schema_check: true
-      allow_partial: true
-
-  # ---------------------------------------------------------------------------
-  # CATEGORY: Python Security (Multi-language Support)
-  # ---------------------------------------------------------------------------
-
-  - id: tc013_python_sql_injection
-    description: "Detect SQL injection in Python Flask application"
-    category: injection
-    priority: critical
-
-    input:
-      code: |
-        from flask import Flask, request
-        import sqlite3
-
-        app = Flask(__name__)
-
-        @app.route('/user')
-        def get_user():
-            user_id = request.args.get('id')
-            conn = sqlite3.connect('users.db')
-            cursor = conn.cursor()
-            cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")
-            return str(cursor.fetchone())
-      context:
-        language: python
-        framework: flask
-
-    expected_output:
-      must_contain:
-        - "SQL injection"
-        - "parameterized"
-        - "f-string"
-      must_match_regex:
-        - "CWE-89"
-      severity_classification: critical
-      finding_count:
-        min: 1
-
-    validation:
-      schema_check: true
-      keyword_match_threshold: 0.7
-
-  - id: tc014_python_ssti_jinja
-    description: "Detect Server-Side Template Injection in Jinja2"
-    category: injection
-    priority: critical
-
-    input:
-      code: |
-        from flask import Flask, request, render_template_string
-
-        app = Flask(__name__)
-
-        @app.route('/render')
-        def render():
-            template = request.args.get('template')
-            return render_template_string(template)
-      context:
-        language: python
-        framework: flask
-
-    expected_output:
-      must_contain:
-        - "SSTI"
-        - "template injection"
-        - "render_template_string"
-        - "Jinja2"
-      must_match_regex:
-        - "CWE-94|CWE-1336"
-      severity_classification: critical
-
-    validation:
-      schema_check: true
-      keyword_match_threshold: 0.7
-
-  - id: tc015_python_pickle_deserialization
-    description: "Detect insecure deserialization with pickle"
-    category: injection
-    priority: critical
-
-    input:
-      code: |
-        import pickle
-        from flask import Flask, request
-
-        app = Flask(__name__)
-
-        @app.route('/load')
-        def load_data():
-            data = request.get_data()
-            obj = pickle.loads(data)
-            return str(obj)
-      context:
-        language: python
-        framework: flask
-
-    expected_output:
-      must_contain:
-        - "pickle"
-        - "deserialization"
-        - "untrusted"
-        - "RCE"
-      must_match_regex:
-        - "CWE-502"
-        - "A08:2021"
-      severity_classification: critical
-
-    validation:
-      schema_check: true
-      keyword_match_threshold: 0.7
-
-# =============================================================================
-# SUCCESS CRITERIA
-# =============================================================================
-
-success_criteria:
-  # Overall pass rate (90% of tests must pass)
-  pass_rate: 0.9
-
-  # Critical tests must ALL pass (100%)
-  critical_pass_rate: 1.0
-
-  # Average reasoning quality score
-  avg_reasoning_quality: 0.75
-
-  # Maximum suite execution time (5 minutes)
-  max_execution_time_ms: 300000
-
-  # Maximum variance between model results (15%)
-  cross_model_variance: 0.15
-
-# =============================================================================
-# METADATA
-# =============================================================================
-
-metadata:
-  author: "qe-security-auditor"
-  created: "2026-02-02"
-  last_updated: "2026-02-02"
-  coverage_target: >
-    OWASP Top 10 2021: A01 (Broken Access Control), A02 (Cryptographic Failures),
-    A03 (Injection - SQL, XSS, SSTI, Command), A07 (Authentication Failures),
-    A08 (Software Integrity - Deserialization). Covers JavaScript/Node.js
-    Express apps and Python Flask apps. 15 test cases with 90% pass rate
-    requirement and 100% critical pass rate.

.cursor/skills/security/schemas/output.json

@@ -1,879 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://agentic-qe.dev/schemas/security-testing-output.json",
-  "title": "AQE Security Testing Skill Output Schema",
-  "description": "Schema for security-testing skill output validation. Extends the base skill-output template with OWASP Top 10 categories, CWE identifiers, and CVSS scoring.",
-  "type": "object",
-  "required": ["skillName", "version", "timestamp", "status", "trustTier", "output"],
-  "properties": {
-    "skillName": {
-      "type": "string",
-      "const": "security-testing",
-      "description": "Must be 'security-testing'"
-    },
-    "version": {
-      "type": "string",
-      "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9]+)?$",
-      "description": "Semantic version of the skill"
-    },
-    "timestamp": {
-      "type": "string",
-      "format": "date-time",
-      "description": "ISO 8601 timestamp of output generation"
-    },
-    "status": {
-      "type": "string",
-      "enum": ["success", "partial", "failed", "skipped"],
-      "description": "Overall execution status"
-    },
-    "trustTier": {
-      "type": "integer",
-      "const": 3,
-      "description": "Trust tier 3 indicates full validation with eval suite"
-    },
-    "output": {
-      "type": "object",
-      "required": ["summary", "findings", "owaspCategories"],
-      "properties": {
-        "summary": {
-          "type": "string",
-          "minLength": 50,
-          "maxLength": 2000,
-          "description": "Human-readable summary of security findings"
-        },
-        "score": {
-          "$ref": "#/$defs/securityScore",
-          "description": "Overall security score"
-        },
-        "findings": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/securityFinding"
-          },
-          "maxItems": 500,
-          "description": "List of security vulnerabilities discovered"
-        },
-        "recommendations": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/securityRecommendation"
-          },
-          "maxItems": 100,
-          "description": "Prioritized remediation recommendations with code examples"
-        },
-        "metrics": {
-          "$ref": "#/$defs/securityMetrics",
-          "description": "Security scan metrics and statistics"
-        },
-        "owaspCategories": {
-          "$ref": "#/$defs/owaspCategoryBreakdown",
-          "description": "OWASP Top 10 2021 category breakdown"
-        },
-        "artifacts": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/artifact"
-          },
-          "maxItems": 50,
-          "description": "Generated security reports and scan artifacts"
-        },
-        "timeline": {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/timelineEvent"
-          },
-          "description": "Scan execution timeline"
-        },
-        "scanConfiguration": {
-          "$ref": "#/$defs/scanConfiguration",
-          "description": "Configuration used for the security scan"
-        }
-      }
-    },
-    "metadata": {
-      "$ref": "#/$defs/metadata"
-    },
-    "validation": {
-      "$ref": "#/$defs/validationResult"
-    },
-    "learning": {
-      "$ref": "#/$defs/learningData"
-    }
-  },
-  "$defs": {
-    "securityScore": {
-      "type": "object",
-      "required": ["value", "max"],
-      "properties": {
-        "value": {
-          "type": "number",
-          "minimum": 0,
-          "maximum": 100,
-          "description": "Security score (0=critical issues, 100=no issues)"
-        },
-        "max": {
-          "type": "number",
-          "const": 100,
-          "description": "Maximum score is always 100"
-        },
-        "grade": {
-          "type": "string",
-          "pattern": "^[A-F][+-]?$",
-          "description": "Letter grade: A (90-100), B (80-89), C (70-79), D (60-69), F (<60)"
-        },
-        "trend": {
-          "type": "string",
-          "enum": ["improving", "stable", "declining", "unknown"],
-          "description": "Trend compared to previous scans"
-        },
-        "riskLevel": {
-          "type": "string",
-          "enum": ["critical", "high", "medium", "low", "minimal"],
-          "description": "Overall risk level assessment"
-        }
-      }
-    },
-    "securityFinding": {
-      "type": "object",
-      "required": ["id", "title", "severity", "owasp"],
-      "properties": {
-        "id": {
-          "type": "string",
-          "pattern": "^SEC-\\d{3,6}$",
-          "description": "Unique finding identifier (e.g., SEC-001)"
-        },
-        "title": {
-          "type": "string",
-          "minLength": 10,
-          "maxLength": 200,
-          "description": "Finding title describing the vulnerability"
-        },
-        "description": {
-          "type": "string",
-          "maxLength": 2000,
-          "description": "Detailed description of the vulnerability"
-        },
-        "severity": {
-          "type": "string",
-          "enum": ["critical", "high", "medium", "low", "info"],
-          "description": "Severity: critical (CVSS 9.0-10.0), high (7.0-8.9), medium (4.0-6.9), low (0.1-3.9), info (0)"
-        },
-        "owasp": {
-          "type": "string",
-          "pattern": "^A(0[1-9]|10):20(21|25)$",
-          "description": "OWASP Top 10 category (e.g., A01:2021, A03:2025)"
-        },
-        "owaspCategory": {
-          "type": "string",
-          "enum": [
-            "A01:2021-Broken-Access-Control",
-            "A02:2021-Cryptographic-Failures",
-            "A03:2021-Injection",
-            "A04:2021-Insecure-Design",
-            "A05:2021-Security-Misconfiguration",
-            "A06:2021-Vulnerable-Components",
-            "A07:2021-Identification-Authentication-Failures",
-            "A08:2021-Software-Data-Integrity-Failures",
-            "A09:2021-Security-Logging-Monitoring-Failures",
-            "A10:2021-Server-Side-Request-Forgery"
-          ],
-          "description": "Full OWASP category name"
-        },
-        "cwe": {
-          "type": "string",
-          "pattern": "^CWE-\\d{1,4}$",
-          "description": "CWE identifier (e.g., CWE-79 for XSS, CWE-89 for SQLi)"
-        },
-        "cvss": {
-          "type": "object",
-          "properties": {
-            "score": {
-              "type": "number",
-              "minimum": 0,
-              "maximum": 10,
-              "description": "CVSS v3.1 base score"
-            },
-            "vector": {
-              "type": "string",
-              "pattern": "^CVSS:3\\.1/AV:[NALP]/AC:[LH]/PR:[NLH]/UI:[NR]/S:[UC]/C:[NLH]/I:[NLH]/A:[NLH]$",
-              "description": "CVSS v3.1 vector string"
-            },
-            "severity": {
-              "type": "string",
-              "enum": ["None", "Low", "Medium", "High", "Critical"],
-              "description": "CVSS severity rating"
-            }
-          }
-        },
-        "location": {
-          "$ref": "#/$defs/location",
-          "description": "Location of the vulnerability"
-        },
-        "evidence": {
-          "type": "string",
-          "maxLength": 5000,
-          "description": "Evidence: code snippet, request/response, or PoC"
-        },
-        "remediation": {
-          "type": "string",
-          "maxLength": 2000,
-          "description": "Specific fix instructions for this finding"
-        },
-        "references": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "required": ["title", "url"],
-            "properties": {
-              "title": { "type": "string" },
-              "url": { "type": "string", "format": "uri" }
-            }
-          },
-          "maxItems": 10,
-          "description": "External references (OWASP, CWE, CVE, etc.)"
-        },
-        "falsePositive": {
-          "type": "boolean",
-          "default": false,
-          "description": "Potential false positive flag"
-        },
-        "confidence": {
-          "type": "number",
-          "minimum": 0,
-          "maximum": 1,
-          "description": "Confidence in finding accuracy (0.0-1.0)"
-        },
-        "exploitability": {
-          "type": "string",
-          "enum": ["trivial", "easy", "moderate", "difficult", "theoretical"],
-          "description": "How easy is it to exploit this vulnerability"
-        },
-        "affectedVersions": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "Affected package/library versions for dependency vulnerabilities"
-        },
-        "cve": {
-          "type": "string",
-          "pattern": "^CVE-\\d{4}-\\d{4,}$",
-          "description": "CVE identifier if applicable"
-        }
-      }
-    },
-    "securityRecommendation": {
-      "type": "object",
-      "required": ["id", "title", "priority", "owaspCategories"],
-      "properties": {
-        "id": {
-          "type": "string",
-          "pattern": "^REC-\\d{3,6}$",
-          "description": "Unique recommendation identifier"
-        },
-        "title": {
-          "type": "string",
-          "minLength": 10,
-          "maxLength": 200,
-          "description": "Recommendation title"
-        },
-        "description": {
-          "type": "string",
-          "maxLength": 2000,
-          "description": "Detailed recommendation description"
-        },
-        "priority": {
-          "type": "string",
-          "enum": ["critical", "high", "medium", "low"],
-          "description": "Remediation priority"
-        },
-        "effort": {
-          "type": "string",
-          "enum": ["trivial", "low", "medium", "high", "major"],
-          "description": "Estimated effort: trivial(<1hr), low(1-4hr), medium(1-3d), high(1-2wk), major(>2wk)"
-        },
-        "impact": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 10,
-          "description": "Security impact if implemented (1-10)"
-        },
-        "relatedFindings": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "pattern": "^SEC-\\d{3,6}$"
-          },
-          "description": "IDs of findings this addresses"
-        },
-        "owaspCategories": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "pattern": "^A(0[1-9]|10):20(21|25)$"
-          },
-          "description": "OWASP categories this recommendation addresses"
-        },
-        "codeExample": {
-          "type": "object",
-          "properties": {
-            "before": {
-              "type": "string",
-              "maxLength": 2000,
-              "description": "Vulnerable code example"
-            },
-            "after": {
-              "type": "string",
-              "maxLength": 2000,
-              "description": "Secure code example"
-            },
-            "language": {
-              "type": "string",
-              "description": "Programming language"
-            }
-          },
-          "description": "Before/after code examples for remediation"
-        },
-        "resources": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "required": ["title", "url"],
-            "properties": {
-              "title": { "type": "string" },
-              "url": { "type": "string", "format": "uri" }
-            }
-          },
-          "maxItems": 10,
-          "description": "External resources and documentation"
-        },
-        "automatable": {
-          "type": "boolean",
-          "description": "Can this fix be automated?"
-        },
-        "fixCommand": {
-          "type": "string",
-          "description": "CLI command to apply fix if automatable"
-        }
-      }
-    },
-    "owaspCategoryBreakdown": {
-      "type": "object",
-      "description": "OWASP Top 10 2021 category scores and findings",
-      "properties": {
-        "A01:2021": {
-          "$ref": "#/$defs/owaspCategoryScore",
-          "description": "A01:2021 - Broken Access Control"
-        },
-        "A02:2021": {
-          "$ref": "#/$defs/owaspCategoryScore",
-          "description": "A02:2021 - Cryptographic Failures"
-        },
-        "A03:2021": {
-          "$ref": "#/$defs/owaspCategoryScore",
-          "description": "A03:2021 - Injection"
-        },
-        "A04:2021": {
-          "$ref": "#/$defs/owaspCategoryScore",
-          "description": "A04:2021 - Insecure Design"
-        },
-        "A05:2021": {
-          "$ref": "#/$defs/owaspCategoryScore",
-          "description": "A05:2021 - Security Misconfiguration"
-        },
-        "A06:2021": {
-          "$ref": "#/$defs/owaspCategoryScore",
-          "description": "A06:2021 - Vulnerable and Outdated Components"
-        },
-        "A07:2021": {
-          "$ref": "#/$defs/owaspCategoryScore",
-          "description": "A07:2021 - Identification and Authentication Failures"
-        },
-        "A08:2021": {
-          "$ref": "#/$defs/owaspCategoryScore",
-          "description": "A08:2021 - Software and Data Integrity Failures"
-        },
-        "A09:2021": {
-          "$ref": "#/$defs/owaspCategoryScore",
-          "description": "A09:2021 - Security Logging and Monitoring Failures"
-        },
-        "A10:2021": {
-          "$ref": "#/$defs/owaspCategoryScore",
-          "description": "A10:2021 - Server-Side Request Forgery (SSRF)"
-        }
-      },
-      "additionalProperties": false
-    },
-    "owaspCategoryScore": {
-      "type": "object",
-      "required": ["tested", "score"],
-      "properties": {
-        "tested": {
-          "type": "boolean",
-          "description": "Whether this category was tested"
-        },
-        "score": {
-          "type": "number",
-          "minimum": 0,
-          "maximum": 100,
-          "description": "Category score (100 = no issues, 0 = critical)"
-        },
-        "grade": {
-          "type": "string",
-          "pattern": "^[A-F][+-]?$",
-          "description": "Letter grade for this category"
-        },
-        "findingCount": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Number of findings in this category"
-        },
-        "criticalCount": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Number of critical findings"
-        },
-        "highCount": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Number of high severity findings"
-        },
-        "status": {
-          "type": "string",
-          "enum": ["pass", "fail", "warn", "skip"],
-          "description": "Category status"
-        },
-        "description": {
-          "type": "string",
-          "description": "Category description and context"
-        },
-        "cwes": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "pattern": "^CWE-\\d{1,4}$"
-          },
-          "description": "CWEs found in this category"
-        }
-      }
-    },
-    "securityMetrics": {
-      "type": "object",
-      "properties": {
-        "totalFindings": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Total vulnerabilities found"
-        },
-        "criticalCount": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Critical severity findings"
-        },
-        "highCount": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "High severity findings"
-        },
-        "mediumCount": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Medium severity findings"
-        },
-        "lowCount": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Low severity findings"
-        },
-        "infoCount": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Informational findings"
-        },
-        "filesScanned": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Number of files analyzed"
-        },
-        "linesOfCode": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Lines of code scanned"
-        },
-        "dependenciesChecked": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Number of dependencies checked"
-        },
-        "owaspCategoriesTested": {
-          "type": "integer",
-          "minimum": 0,
-          "maximum": 10,
-          "description": "OWASP Top 10 categories tested"
-        },
-        "owaspCategoriesPassed": {
-          "type": "integer",
-          "minimum": 0,
-          "maximum": 10,
-          "description": "OWASP Top 10 categories with no findings"
-        },
-        "uniqueCwes": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Unique CWE identifiers found"
-        },
-        "falsePositiveRate": {
-          "type": "number",
-          "minimum": 0,
-          "maximum": 1,
-          "description": "Estimated false positive rate"
-        },
-        "scanDurationMs": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Total scan duration in milliseconds"
-        },
-        "coverage": {
-          "type": "object",
-          "properties": {
-            "sast": {
-              "type": "boolean",
-              "description": "Static analysis performed"
-            },
-            "dast": {
-              "type": "boolean",
-              "description": "Dynamic analysis performed"
-            },
-            "dependencies": {
-              "type": "boolean",
-              "description": "Dependency scan performed"
-            },
-            "secrets": {
-              "type": "boolean",
-              "description": "Secret scanning performed"
-            },
-            "configuration": {
-              "type": "boolean",
-              "description": "Configuration review performed"
-            }
-          },
-          "description": "Scan coverage indicators"
-        }
-      }
-    },
-    "scanConfiguration": {
-      "type": "object",
-      "properties": {
-        "target": {
-          "type": "string",
-          "description": "Scan target (file path, URL, or package)"
-        },
-        "targetType": {
-          "type": "string",
-          "enum": ["source", "url", "package", "container", "infrastructure"],
-          "description": "Type of target being scanned"
-        },
-        "scanTypes": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "enum": ["sast", "dast", "dependency", "secret", "configuration", "container", "iac"]
-          },
-          "description": "Types of scans performed"
-        },
-        "severity": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "enum": ["critical", "high", "medium", "low", "info"]
-          },
-          "description": "Severity levels included in scan"
-        },
-        "owaspCategories": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "pattern": "^A(0[1-9]|10):20(21|25)$"
-          },
-          "description": "OWASP categories tested"
-        },
-        "tools": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "Security tools used"
-        },
-        "excludePatterns": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "File patterns excluded from scan"
-        },
-        "rulesets": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "Security rulesets applied"
-        }
-      }
-    },
-    "location": {
-      "type": "object",
-      "properties": {
-        "file": {
-          "type": "string",
-          "maxLength": 500,
-          "description": "File path relative to project root"
-        },
-        "line": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "Line number"
-        },
-        "column": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "Column number"
-        },
-        "endLine": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "End line for multi-line findings"
-        },
-        "endColumn": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "End column"
-        },
-        "url": {
-          "type": "string",
-          "format": "uri",
-          "description": "URL for web-based findings"
-        },
-        "endpoint": {
-          "type": "string",
-          "description": "API endpoint path"
-        },
-        "method": {
-          "type": "string",
-          "enum": ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"],
-          "description": "HTTP method for API findings"
-        },
-        "parameter": {
-          "type": "string",
-          "description": "Vulnerable parameter name"
-        },
-        "component": {
-          "type": "string",
-          "description": "Affected component or module"
-        }
-      }
-    },
-    "artifact": {
-      "type": "object",
-      "required": ["type", "path"],
-      "properties": {
-        "type": {
-          "type": "string",
-          "enum": ["report", "sarif", "data", "log", "evidence"],
-          "description": "Artifact type"
-        },
-        "path": {
-          "type": "string",
-          "maxLength": 500,
-          "description": "Path to artifact"
-        },
-        "format": {
-          "type": "string",
-          "enum": ["json", "sarif", "html", "md", "txt", "xml", "csv"],
-          "description": "Artifact format"
-        },
-        "description": {
-          "type": "string",
-          "maxLength": 500,
-          "description": "Artifact description"
-        },
-        "sizeBytes": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "File size in bytes"
-        },
-        "checksum": {
-          "type": "string",
-          "pattern": "^sha256:[a-f0-9]{64}$",
-          "description": "SHA-256 checksum"
-        }
-      }
-    },
-    "timelineEvent": {
-      "type": "object",
-      "required": ["timestamp", "event"],
-      "properties": {
-        "timestamp": {
-          "type": "string",
-          "format": "date-time",
-          "description": "Event timestamp"
-        },
-        "event": {
-          "type": "string",
-          "maxLength": 200,
-          "description": "Event description"
-        },
-        "type": {
-          "type": "string",
-          "enum": ["start", "checkpoint", "warning", "error", "complete"],
-          "description": "Event type"
-        },
-        "durationMs": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Duration since previous event"
-        },
-        "phase": {
-          "type": "string",
-          "enum": ["initialization", "sast", "dast", "dependency", "secret", "reporting"],
-          "description": "Scan phase"
-        }
-      }
-    },
-    "metadata": {
-      "type": "object",
-      "properties": {
-        "executionTimeMs": {
-          "type": "integer",
-          "minimum": 0,
-          "maximum": 3600000,
-          "description": "Execution time in milliseconds"
-        },
-        "toolsUsed": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "enum": ["semgrep", "npm-audit", "trivy", "owasp-zap", "bandit", "gosec", "eslint-security", "snyk", "gitleaks", "trufflehog", "bearer"]
-          },
-          "uniqueItems": true,
-          "description": "Security tools used"
-        },
-        "agentId": {
-          "type": "string",
-          "pattern": "^qe-[a-z][a-z0-9-]*$",
-          "description": "Agent ID (e.g., qe-security-scanner)"
-        },
-        "modelUsed": {
-          "type": "string",
-          "description": "LLM model used for analysis"
-        },
-        "inputHash": {
-          "type": "string",
-          "pattern": "^[a-f0-9]{64}$",
-          "description": "SHA-256 hash of input"
-        },
-        "targetUrl": {
-          "type": "string",
-          "format": "uri",
-          "description": "Target URL if applicable"
-        },
-        "targetPath": {
-          "type": "string",
-          "description": "Target path if applicable"
-        },
-        "environment": {
-          "type": "string",
-          "enum": ["development", "staging", "production", "ci"],
-          "description": "Execution environment"
-        },
-        "retryCount": {
-          "type": "integer",
-          "minimum": 0,
-          "maximum": 10,
-          "description": "Number of retries"
-        }
-      }
-    },
-    "validationResult": {
-      "type": "object",
-      "properties": {
-        "schemaValid": {
-          "type": "boolean",
-          "description": "Passes JSON schema validation"
-        },
-        "contentValid": {
-          "type": "boolean",
-          "description": "Passes content validation"
-        },
-        "confidence": {
-          "type": "number",
-          "minimum": 0,
-          "maximum": 1,
-          "description": "Confidence score"
-        },
-        "warnings": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "maxLength": 500
-          },
-          "maxItems": 20,
-          "description": "Validation warnings"
-        },
-        "errors": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "maxLength": 500
-          },
-          "maxItems": 20,
-          "description": "Validation errors"
-        },
-        "validatorVersion": {
-          "type": "string",
-          "pattern": "^\\d+\\.\\d+\\.\\d+$",
-          "description": "Validator version"
-        }
-      }
-    },
-    "learningData": {
-      "type": "object",
-      "properties": {
-        "patternsDetected": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "maxLength": 200
-          },
-          "maxItems": 20,
-          "description": "Security patterns detected (e.g., sql-injection-string-concat)"
-        },
-        "reward": {
-          "type": "number",
-          "minimum": 0,
-          "maximum": 1,
-          "description": "Reward signal for learning (0.0-1.0)"
-        },
-        "feedbackLoop": {
-          "type": "object",
-          "properties": {
-            "previousRunId": {
-              "type": "string",
-              "format": "uuid",
-              "description": "Previous run ID for comparison"
-            },
-            "improvement": {
-              "type": "number",
-              "minimum": -1,
-              "maximum": 1,
-              "description": "Improvement over previous run"
-            }
-          }
-        },
-        "newVulnerabilityPatterns": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "properties": {
-              "pattern": { "type": "string" },
-              "cwe": { "type": "string" },
-              "confidence": { "type": "number" }
-            }
-          },
-          "description": "New vulnerability patterns learned"
-        }
-      }
-    }
-  }
-}

.cursor/skills/security/scripts/validate-config.json

@@ -1,45 +0,0 @@
-{
-  "skillName": "security-testing",
-  "skillVersion": "1.0.0",
-  "requiredTools": [
-    "jq"
-  ],
-  "optionalTools": [
-    "npm",
-    "semgrep",
-    "trivy",
-    "ajv",
-    "jsonschema",
-    "python3"
-  ],
-  "schemaPath": "schemas/output.json",
-  "requiredFields": [
-    "skillName",
-    "status",
-    "output",
-    "output.summary",
-    "output.findings",
-    "output.owaspCategories"
-  ],
-  "requiredNonEmptyFields": [
-    "output.summary"
-  ],
-  "mustContainTerms": [
-    "OWASP",
-    "security",
-    "vulnerability"
-  ],
-  "mustNotContainTerms": [
-    "TODO",
-    "placeholder",
-    "FIXME"
-  ],
-  "enumValidations": {
-    ".status": [
-      "success",
-      "partial",
-      "failed",
-      "skipped"
-    ]
-  }
-}

.cursor/skills/test-run/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: test-run
+description: |
+  Run the project's test suite, report results, and handle failures.
+  Detects test runners automatically (pytest, dotnet test, cargo test, npm test)
+  or uses scripts/run-tests.sh if available.
+  Trigger phrases:
+  - "run tests", "test suite", "verify tests"
+category: build
+tags: [testing, verification, test-suite]
+disable-model-invocation: true
+---
+
+# Test Run
+
+Run the project's test suite and report results. This skill is invoked by the autopilot at verification checkpoints — after implementing tests, after implementing features, or at any point where the test suite must pass before proceeding.
+
+## Workflow
+
+### 1. Detect Test Runner
+
+Check in order — first match wins:
+
+1. `scripts/run-tests.sh` exists → use it
+2. `docker-compose.test.yml` or equivalent test environment exists → spin it up first, then detect runner below
+3. Auto-detect from project files:
+   - `pytest.ini`, `pyproject.toml` with `[tool.pytest]`, or `conftest.py` → `pytest`
+   - `*.csproj` or `*.sln` → `dotnet test`
+   - `Cargo.toml` → `cargo test`
+   - `package.json` with test script → `npm test`
+   - `Makefile` with `test` target → `make test`
+
+If no runner detected → report failure and ask user to specify.
+
+### 2. Run Tests
+
+1. Execute the detected test runner
+2. Capture output: passed, failed, skipped, errors
+3. If a test environment was spun up, tear it down after tests complete
+
+### 3. Report Results
+
+Present a summary:
+
+```
+══════════════════════════════════════
+ TEST RESULTS: [N passed, M failed, K skipped]
+══════════════════════════════════════
+```
+
+### 4. Handle Outcome
+
+**All tests pass** → return success to the autopilot for auto-chain.
+
+**Tests fail** → present using Choose format:
+
+```
+══════════════════════════════════════
+ TEST RESULTS: [N passed, M failed, K skipped]
+══════════════════════════════════════
+ A) Fix failing tests and re-run
+ B) Proceed anyway (not recommended)
+ C) Abort — fix manually
+══════════════════════════════════════
+ Recommendation: A — fix failures before proceeding
+══════════════════════════════════════
+```
+
+- If user picks A → attempt to fix failures, then re-run (loop back to step 2)
+- If user picks B → return success with warning to the autopilot
+- If user picks C → return failure to the autopilot
+
+## Trigger Conditions
+
+This skill is invoked by the autopilot at test verification checkpoints. It is not typically invoked directly by the user.

.cursor/skills/test-spec/SKILL.md

@@ -0,0 +1,469 @@
+---
+name: test-spec
+description: |
+  Test specification skill. Analyzes input data and expected results completeness,
+  then produces detailed test scenarios (blackbox, performance, resilience, security, resource limits)
+  that treat the system as a black box. Every test pairs input data with quantifiable expected results
+  so tests can verify correctness, not just execution.
+  4-phase workflow: input data + expected results analysis, test scenario specification, data + results validation gate,
+  test runner script generation. Produces 8 artifacts under tests/ and 2 shell scripts under scripts/.
+  Trigger phrases:
+  - "test spec", "test specification", "test scenarios"
+  - "blackbox test spec", "black box tests", "blackbox tests"
+  - "performance tests", "resilience tests", "security tests"
+category: build
+tags: [testing, black-box, blackbox-tests, test-specification, qa]
+disable-model-invocation: true
+---
+
+# Test Scenario Specification
+
+Analyze input data completeness and produce detailed black-box test specifications. Tests describe what the system should do given specific inputs — they never reference internals.
+
+## Core Principles
+
+- **Black-box only**: tests describe observable behavior through public interfaces; no internal implementation details
+- **Traceability**: every test traces to at least one acceptance criterion or restriction
+- **Save immediately**: write artifacts to disk after each phase; never accumulate unsaved work
+- **Ask, don't assume**: when requirements are ambiguous, ask the user before proceeding
+- **Spec, don't code**: this workflow produces test specifications, never test implementation code
+- **No test without data**: every test scenario MUST have concrete test data; tests without data are removed
+- **No test without expected result**: every test scenario MUST pair input data with a quantifiable expected result; a test that cannot compare actual output against a known-correct answer is not verifiable and must be removed
+
+## Context Resolution
+
+Fixed paths — no mode detection needed:
+
+- PROBLEM_DIR: `_docs/00_problem/`
+- SOLUTION_DIR: `_docs/01_solution/`
+- DOCUMENT_DIR: `_docs/02_document/`
+- TESTS_OUTPUT_DIR: `_docs/02_document/tests/`
+
+Announce the resolved paths to the user before proceeding.
+
+## Input Specification
+
+### Required Files
+
+| File | Purpose |
+|------|---------|
+| `_docs/00_problem/problem.md` | Problem description and context |
+| `_docs/00_problem/acceptance_criteria.md` | Measurable acceptance criteria |
+| `_docs/00_problem/restrictions.md` | Constraints and limitations |
+| `_docs/00_problem/input_data/` | Reference data examples, expected results, and optional reference files |
+| `_docs/01_solution/solution.md` | Finalized solution |
+
+### Expected Results Specification
+
+Every input data item MUST have a corresponding expected result that defines what the system should produce. Expected results MUST be **quantifiable** — the test must be able to programmatically compare actual system output against the expected result and produce a pass/fail verdict.
+
+Expected results live inside `_docs/00_problem/input_data/` in one or both of:
+
+1. **Mapping file** (`input_data/expected_results/results_report.md`): a table pairing each input with its quantifiable expected output, using the format defined in `.cursor/skills/test-spec/templates/expected-results.md`
+
+2. **Reference files folder** (`input_data/expected_results/`): machine-readable files (JSON, CSV, etc.) containing full expected outputs for complex cases, referenced from the mapping file
+
+```
+input_data/
+├── expected_results/            ← required: expected results folder
+│   ├── results_report.md        ← required: input→expected result mapping
+│   ├── image_01_expected.csv    ← per-file expected detections
+│   └── video_01_expected.csv
+├── image_01.jpg
+├── empty_scene.jpg
+└── data_parameters.md
+```
+
+**Quantifiability requirements** (see template for full format and examples):
+- Numeric values: exact value or value ± tolerance (e.g., `confidence ≥ 0.85`, `position ± 10px`)
+- Structured data: exact JSON/CSV values, or a reference file in `expected_results/`
+- Counts: exact counts (e.g., "3 detections", "0 errors")
+- Text/patterns: exact string or regex pattern to match
+- Timing: threshold (e.g., "response ≤ 500ms")
+- Error cases: expected error code, message pattern, or HTTP status
+
+### Optional Files (used when available)
+
+| File | Purpose |
+|------|---------|
+| `DOCUMENT_DIR/architecture.md` | System architecture for environment design |
+| `DOCUMENT_DIR/system-flows.md` | System flows for test scenario coverage |
+| `DOCUMENT_DIR/components/` | Component specs for interface identification |
+
+### Prerequisite Checks (BLOCKING)
+
+1. `acceptance_criteria.md` exists and is non-empty — **STOP if missing**
+2. `restrictions.md` exists and is non-empty — **STOP if missing**
+3. `input_data/` exists and contains at least one file — **STOP if missing**
+4. `input_data/expected_results/results_report.md` exists and is non-empty — **STOP if missing**. Prompt the user: *"Expected results mapping is required. Please create `_docs/00_problem/input_data/expected_results/results_report.md` pairing each input with its quantifiable expected output. Use `.cursor/skills/test-spec/templates/expected-results.md` as the format reference."*
+5. `problem.md` exists and is non-empty — **STOP if missing**
+6. `solution.md` exists and is non-empty — **STOP if missing**
+7. Create TESTS_OUTPUT_DIR if it does not exist
+8. If TESTS_OUTPUT_DIR already contains files, ask user: **resume from last checkpoint or start fresh?**
+
+## Artifact Management
+
+### Directory Structure
+
+```
+TESTS_OUTPUT_DIR/
+├── environment.md
+├── test-data.md
+├── blackbox-tests.md
+├── performance-tests.md
+├── resilience-tests.md
+├── security-tests.md
+├── resource-limit-tests.md
+└── traceability-matrix.md
+```
+
+### Save Timing
+
+| Phase | Save immediately after | Filename |
+|-------|------------------------|----------|
+| Phase 1 | Input data analysis (no file — findings feed Phase 2) | — |
+| Phase 2 | Environment spec | `environment.md` |
+| Phase 2 | Test data spec | `test-data.md` |
+| Phase 2 | Blackbox tests | `blackbox-tests.md` |
+| Phase 2 | Performance tests | `performance-tests.md` |
+| Phase 2 | Resilience tests | `resilience-tests.md` |
+| Phase 2 | Security tests | `security-tests.md` |
+| Phase 2 | Resource limit tests | `resource-limit-tests.md` |
+| Phase 2 | Traceability matrix | `traceability-matrix.md` |
+| Phase 3 | Updated test data spec (if data added) | `test-data.md` |
+| Phase 3 | Updated test files (if tests removed) | respective test file |
+| Phase 3 | Updated traceability matrix (if tests removed) | `traceability-matrix.md` |
+| Phase 4 | Test runner script | `scripts/run-tests.sh` |
+| Phase 4 | Performance test runner script | `scripts/run-performance-tests.sh` |
+
+### Resumability
+
+If TESTS_OUTPUT_DIR already contains files:
+
+1. List existing files and match them to the save timing table above
+2. Identify which phase/artifacts are complete
+3. Resume from the next incomplete artifact
+4. Inform the user which artifacts are being skipped
+
+## Progress Tracking
+
+At the start of execution, create a TodoWrite with all three phases. Update status as each phase completes.
+
+## Workflow
+
+### Phase 1: Input Data Completeness Analysis
+
+**Role**: Professional Quality Assurance Engineer
+**Goal**: Assess whether the available input data is sufficient to build comprehensive test scenarios
+**Constraints**: Analysis only — no test specs yet
+
+1. Read `_docs/01_solution/solution.md`
+2. Read `acceptance_criteria.md`, `restrictions.md`
+3. Read testing strategy from solution.md (if present)
+4. If `DOCUMENT_DIR/architecture.md` and `DOCUMENT_DIR/system-flows.md` exist, read them for additional context on system interfaces and flows
+5. Read `input_data/expected_results/results_report.md` and any referenced files in `input_data/expected_results/`
+6. Analyze `input_data/` contents against:
+   - Coverage of acceptance criteria scenarios
+   - Coverage of restriction edge cases
+   - Coverage of testing strategy requirements
+7. Analyze `input_data/expected_results/results_report.md` completeness:
+   - Every input data item has a corresponding expected result row in the mapping
+   - Expected results are quantifiable (contain numeric thresholds, exact values, patterns, or file references — not vague descriptions like "works correctly" or "returns result")
+   - Expected results specify a comparison method (exact match, tolerance range, pattern match, threshold) per the template
+   - Reference files in `input_data/expected_results/` that are cited in the mapping actually exist and are valid
+8. Present input-to-expected-result pairing assessment:
+
+| Input Data | Expected Result Provided? | Quantifiable? | Issue (if any) |
+|------------|--------------------------|---------------|----------------|
+| [file/data] | Yes/No | Yes/No | [missing, vague, no tolerance, etc.] |
+
+9. Threshold: at least 70% coverage of scenarios AND every covered scenario has a quantifiable expected result (see `.cursor/rules/cursor-meta.mdc` Quality Thresholds table)
+10. If coverage is low, search the internet for supplementary data, assess quality with user, and if user agrees, add to `input_data/` and update `input_data/expected_results/results_report.md`
+11. If expected results are missing or not quantifiable, ask user to provide them before proceeding
+
+**BLOCKING**: Do NOT proceed until user confirms both input data coverage AND expected results completeness are sufficient.
+
+---
+
+### Phase 2: Test Scenario Specification
+
+**Role**: Professional Quality Assurance Engineer
+**Goal**: Produce detailed black-box test specifications covering blackbox, performance, resilience, security, and resource limit scenarios
+**Constraints**: Spec only — no test code. Tests describe what the system should do given specific inputs, not how the system is built.
+
+Based on all acquired data, acceptance_criteria, and restrictions, form detailed test scenarios:
+
+1. Define test environment using `.cursor/skills/plan/templates/test-environment.md` as structure
+2. Define test data management using `.cursor/skills/plan/templates/test-data.md` as structure
+3. Write blackbox test scenarios (positive + negative) using `.cursor/skills/plan/templates/blackbox-tests.md` as structure
+4. Write performance test scenarios using `.cursor/skills/plan/templates/performance-tests.md` as structure
+5. Write resilience test scenarios using `.cursor/skills/plan/templates/resilience-tests.md` as structure
+6. Write security test scenarios using `.cursor/skills/plan/templates/security-tests.md` as structure
+7. Write resource limit test scenarios using `.cursor/skills/plan/templates/resource-limit-tests.md` as structure
+8. Build traceability matrix using `.cursor/skills/plan/templates/traceability-matrix.md` as structure
+
+**Self-verification**:
+- [ ] Every acceptance criterion is covered by at least one test scenario
+- [ ] Every restriction is verified by at least one test scenario
+- [ ] Every test scenario has a quantifiable expected result from `input_data/expected_results/results_report.md`
+- [ ] Expected results use comparison methods from `.cursor/skills/test-spec/templates/expected-results.md`
+- [ ] Positive and negative scenarios are balanced
+- [ ] Consumer app has no direct access to system internals
+- [ ] Docker environment is self-contained (`docker compose up` sufficient)
+- [ ] External dependencies have mock/stub services defined
+- [ ] Traceability matrix has no uncovered AC or restrictions
+
+**Save action**: Write all files under TESTS_OUTPUT_DIR:
+- `environment.md`
+- `test-data.md`
+- `blackbox-tests.md`
+- `performance-tests.md`
+- `resilience-tests.md`
+- `security-tests.md`
+- `resource-limit-tests.md`
+- `traceability-matrix.md`
+
+**BLOCKING**: Present test coverage summary (from traceability-matrix.md) to user. Do NOT proceed until confirmed.
+
+Capture any new questions, findings, or insights that arise during test specification — these feed forward into downstream skills (plan, refactor, etc.).
+
+---
+
+### Phase 3: Test Data Validation Gate (HARD GATE)
+
+**Role**: Professional Quality Assurance Engineer
+**Goal**: Ensure every test scenario produced in Phase 2 has concrete, sufficient test data. Remove tests that lack data. Verify final coverage stays above 70%.
+**Constraints**: This phase is MANDATORY and cannot be skipped.
+
+#### Step 1 — Build the test-data and expected-result requirements checklist
+
+Scan `blackbox-tests.md`, `performance-tests.md`, `resilience-tests.md`, `security-tests.md`, and `resource-limit-tests.md`. For every test scenario, extract:
+
+| # | Test Scenario ID | Test Name | Required Input Data | Required Expected Result | Result Quantifiable? | Comparison Method | Input Provided? | Expected Result Provided? |
+|---|-----------------|-----------|---------------------|-------------------------|---------------------|-------------------|----------------|--------------------------|
+| 1 | [ID] | [name] | [data description] | [what system should output] | [Yes/No] | [exact/tolerance/pattern/threshold] | [Yes/No] | [Yes/No] |
+
+Present this table to the user.
+
+#### Step 2 — Ask user to provide missing test data AND expected results
+
+For each row where **Input Provided?** is **No** OR **Expected Result Provided?** is **No**, ask the user:
+
+> **Option A — Provide the missing items**: Supply what is missing:
+> - **Missing input data**: Place test data files in `_docs/00_problem/input_data/` or indicate the location.
+> - **Missing expected result**: Provide the quantifiable expected result for this input. Update `_docs/00_problem/input_data/expected_results/results_report.md` with a row mapping the input to its expected output. If the expected result is complex, provide a reference CSV file in `_docs/00_problem/input_data/expected_results/`. Use `.cursor/skills/test-spec/templates/expected-results.md` for format guidance.
+>
+> Expected results MUST be quantifiable — the test must be able to programmatically compare actual vs expected. Examples:
+> - "3 detections with bounding boxes [(x1,y1,x2,y2), ...] ± 10px"
+> - "HTTP 200 with JSON body matching `expected_response_01.json`"
+> - "Processing time < 500ms"
+> - "0 false positives in the output set"
+>
+> **Option B — Skip this test**: If you cannot provide the data or expected result, this test scenario will be **removed** from the specification.
+
+**BLOCKING**: Wait for the user's response for every missing item.
+
+#### Step 3 — Validate provided data and expected results
+
+For each item where the user chose **Option A**:
+
+**Input data validation**:
+1. Verify the data file(s) exist at the indicated location
+2. Verify **quality**: data matches the format, schema, and constraints described in the test scenario (e.g., correct image resolution, valid JSON structure, expected value ranges)
+3. Verify **quantity**: enough data samples to cover the scenario (e.g., at least N images for a batch test, multiple edge-case variants)
+
+**Expected result validation**:
+4. Verify the expected result exists in `input_data/expected_results/results_report.md` or as a referenced file in `input_data/expected_results/`
+5. Verify **quantifiability**: the expected result can be evaluated programmatically — it must contain at least one of:
+   - Exact values (counts, strings, status codes)
+   - Numeric values with tolerance (e.g., `± 10px`, `≥ 0.85`)
+   - Pattern matches (regex, substring, JSON schema)
+   - Thresholds (e.g., `< 500ms`, `≤ 5% error rate`)
+   - Reference file for structural comparison (JSON diff, CSV diff)
+6. Verify **completeness**: the expected result covers all outputs the test checks (not just one field when the test validates multiple)
+7. Verify **consistency**: the expected result is consistent with the acceptance criteria it traces to
+
+If any validation fails, report the specific issue and loop back to Step 2 for that item.
+
+#### Step 4 — Remove tests without data or expected results
+
+For each item where the user chose **Option B**:
+
+1. Warn the user: `⚠️ Test scenario [ID] "[Name]" will be REMOVED from the specification due to missing test data or expected result.`
+2. Remove the test scenario from the respective test file
+3. Remove corresponding rows from `traceability-matrix.md`
+4. Update `test-data.md` to reflect the removal
+
+**Save action**: Write updated files under TESTS_OUTPUT_DIR:
+- `test-data.md`
+- Affected test files (if tests removed)
+- `traceability-matrix.md` (if tests removed)
+
+#### Step 5 — Final coverage check
+
+After all removals, recalculate coverage:
+
+1. Count remaining test scenarios that trace to acceptance criteria
+2. Count total acceptance criteria + restrictions
+3. Calculate coverage percentage: `covered_items / total_items * 100`
+
+| Metric | Value |
+|--------|-------|
+| Total AC + Restrictions | ? |
+| Covered by remaining tests | ? |
+| **Coverage %** | **?%** |
+
+**Decision**:
+
+- **Coverage ≥ 70%** → Phase 3 **PASSED**. Present final summary to user.
+- **Coverage < 70%** → Phase 3 **FAILED**. Report:
+  > ❌ Test coverage dropped to **X%** (minimum 70% required). The removed test scenarios left gaps in the following acceptance criteria / restrictions:
+  >
+  > | Uncovered Item | Type (AC/Restriction) | Missing Test Data Needed |
+  > |---|---|---|
+  >
+  > **Action required**: Provide the missing test data for the items above, or add alternative test scenarios that cover these items with data you can supply.
+
+  **BLOCKING**: Loop back to Step 2 with the uncovered items. Do NOT finalize until coverage ≥ 70%.
+
+#### Phase 3 Completion
+
+When coverage ≥ 70% and all remaining tests have validated data AND quantifiable expected results:
+
+1. Present the final coverage report
+2. List all removed tests (if any) with reasons
+3. Confirm every remaining test has: input data + quantifiable expected result + comparison method
+4. Confirm all artifacts are saved and consistent
+
+---
+
+### Phase 4: Test Runner Script Generation
+
+**Role**: DevOps engineer
+**Goal**: Generate executable shell scripts that run the specified tests, so the autopilot and CI can invoke them consistently.
+**Constraints**: Scripts must be idempotent, portable across dev/CI, and exit with non-zero on failure.
+
+#### Step 1 — Detect test infrastructure
+
+1. Identify the project's test runner from manifests and config files:
+   - Python: `pytest` (pyproject.toml, setup.cfg, pytest.ini)
+   - .NET: `dotnet test` (*.csproj, *.sln)
+   - Rust: `cargo test` (Cargo.toml)
+   - Node: `npm test` or `vitest` / `jest` (package.json)
+2. Identify docker-compose files for integration/blackbox tests (`docker-compose.test.yml`, `e2e/docker-compose*.yml`)
+3. Identify performance/load testing tools from dependencies (k6, locust, artillery, wrk, or built-in benchmarks)
+4. Read `TESTS_OUTPUT_DIR/environment.md` for infrastructure requirements
+
+#### Step 2 — Generate `scripts/run-tests.sh`
+
+Create `scripts/run-tests.sh` at the project root using `.cursor/skills/test-spec/templates/run-tests-script.md` as structural guidance. The script must:
+
+1. Set `set -euo pipefail` and trap cleanup on EXIT
+2. Optionally accept a `--unit-only` flag to skip blackbox tests
+3. Run unit tests using the detected test runner
+4. If blackbox tests exist: spin up docker-compose environment, wait for health checks, run blackbox test suite, tear down
+5. Print a summary of passed/failed/skipped tests
+6. Exit 0 on all pass, exit 1 on any failure
+
+#### Step 3 — Generate `scripts/run-performance-tests.sh`
+
+Create `scripts/run-performance-tests.sh` at the project root. The script must:
+
+1. Set `set -euo pipefail` and trap cleanup on EXIT
+2. Read thresholds from `_docs/02_document/tests/performance-tests.md` (or accept as CLI args)
+3. Spin up the system under test (docker-compose or local)
+4. Run load/performance scenarios using the detected tool
+5. Compare results against threshold values from the test spec
+6. Print a pass/fail summary per scenario
+7. Exit 0 if all thresholds met, exit 1 otherwise
+
+#### Step 4 — Verify scripts
+
+1. Verify both scripts are syntactically valid (`bash -n scripts/run-tests.sh`)
+2. Mark both scripts as executable (`chmod +x`)
+3. Present a summary of what each script does to the user
+
+**Save action**: Write `scripts/run-tests.sh` and `scripts/run-performance-tests.sh` to the project root.
+
+---
+
+## Escalation Rules
+
+| Situation | Action |
+|-----------|--------|
+| Missing acceptance_criteria.md, restrictions.md, or input_data/ | **STOP** — specification cannot proceed |
+| Missing input_data/expected_results/results_report.md | **STOP** — ask user to provide expected results mapping using the template |
+| Ambiguous requirements | ASK user |
+| Input data coverage below 70% (Phase 1) | Search internet for supplementary data, ASK user to validate |
+| Expected results missing or not quantifiable (Phase 1) | ASK user to provide quantifiable expected results before proceeding |
+| Test scenario conflicts with restrictions | ASK user to clarify intent |
+| System interfaces unclear (no architecture.md) | ASK user or derive from solution.md |
+| Test data or expected result not provided for a test scenario (Phase 3) | WARN user and REMOVE the test |
+| Final coverage below 70% after removals (Phase 3) | BLOCK — require user to supply data or accept reduced spec |
+
+## Common Mistakes
+
+- **Referencing internals**: tests must be black-box — no internal module names, no direct DB queries against the system under test
+- **Vague expected outcomes**: "works correctly" is not a test outcome; use specific measurable values
+- **Missing expected results**: input data without a paired expected result is useless — the test cannot determine pass/fail without knowing what "correct" looks like
+- **Non-quantifiable expected results**: "should return good results" is not verifiable; expected results must have exact values, tolerances, thresholds, or pattern matches that code can evaluate
+- **Missing negative scenarios**: every positive scenario category should have corresponding negative/edge-case tests
+- **Untraceable tests**: every test should trace to at least one AC or restriction
+- **Writing test code**: this skill produces specifications, never implementation code
+- **Tests without data**: every test scenario MUST have concrete test data AND a quantifiable expected result; a test spec without either is not executable and must be removed
+
+## Trigger Conditions
+
+When the user wants to:
+- Specify blackbox tests before implementation or refactoring
+- Analyze input data completeness for test coverage
+- Produce test scenarios from acceptance criteria
+
+**Keywords**: "test spec", "test specification", "blackbox test spec", "black box tests", "blackbox tests", "test scenarios"
+
+## Methodology Quick Reference
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│              Test Scenario Specification (4-Phase)                   │
+├──────────────────────────────────────────────────────────────────────┤
+│ PREREQ: Data Gate (BLOCKING)                                         │
+│   → verify AC, restrictions, input_data (incl. expected_results.md)  │
+│                                                                      │
+│ Phase 1: Input Data & Expected Results Completeness Analysis         │
+│   → assess input_data/ coverage vs AC scenarios (≥70%)               │
+│   → verify every input has a quantifiable expected result            │
+│   → present input→expected-result pairing assessment                 │
+│   [BLOCKING: user confirms input data + expected results coverage]   │
+│                                                                      │
+│ Phase 2: Test Scenario Specification                                 │
+│   → environment.md                                                   │
+│   → test-data.md (with expected results mapping)                     │
+│   → blackbox-tests.md (positive + negative)                          │
+│   → performance-tests.md                                             │
+│   → resilience-tests.md                                              │
+│   → security-tests.md                                                │
+│   → resource-limit-tests.md                                          │
+│   → traceability-matrix.md                                           │
+│   [BLOCKING: user confirms test coverage]                            │
+│                                                                      │
+│ Phase 3: Test Data & Expected Results Validation Gate (HARD GATE)    │
+│   → build test-data + expected-result requirements checklist         │
+│   → ask user: provide data+result (A) or remove test (B)             │
+│   → validate input data (quality + quantity)                         │
+│   → validate expected results (quantifiable + comparison method)     │
+│   → remove tests without data or expected result, warn user          │
+│   → final coverage check (≥70% or FAIL + loop back)                  │
+│   [BLOCKING: coverage ≥ 70% required to pass]                        │
+│                                                                      │
+│ Phase 4: Test Runner Script Generation                               │
+│   → detect test runner + docker-compose + load tool                  │
+│   → scripts/run-tests.sh (unit + blackbox)                           │
+│   → scripts/run-performance-tests.sh (load/perf scenarios)           │
+│   → verify scripts are valid and executable                          │
+├──────────────────────────────────────────────────────────────────────┤
+│ Principles: Black-box only · Traceability · Save immediately         │
+│             Ask don't assume · Spec don't code                       │
+│             No test without data · No test without expected result   │
+└──────────────────────────────────────────────────────────────────────┘
+```

.cursor/skills/test-spec/templates/expected-results.md

@@ -0,0 +1,135 @@
+# Expected Results Template
+
+Save as `_docs/00_problem/input_data/expected_results/results_report.md`.
+For complex expected outputs, place reference CSV files alongside it in `_docs/00_problem/input_data/expected_results/`.
+Referenced by the test-spec skill (`.cursor/skills/test-spec/SKILL.md`).
+
+---
+
+```markdown
+# Expected Results
+
+Maps every input data item to its quantifiable expected result.
+Tests use this mapping to compare actual system output against known-correct answers.
+
+## Result Format Legend
+
+| Result Type | When to Use | Example |
+|-------------|-------------|---------|
+| Exact value | Output must match precisely | `status_code: 200`, `detection_count: 3` |
+| Tolerance range | Numeric output with acceptable variance | `confidence: 0.92 ± 0.05`, `bbox_x: 120 ± 10px` |
+| Threshold | Output must exceed or stay below a limit | `latency < 500ms`, `confidence ≥ 0.85` |
+| Pattern match | Output must match a string/regex pattern | `error_message contains "invalid format"` |
+| File reference | Complex output compared against a reference file | `match expected_results/case_01.json` |
+| Schema match | Output structure must conform to a schema | `response matches DetectionResultSchema` |
+| Set/count | Output must contain specific items or counts | `classes ⊇ {"car", "person"}`, `detections.length == 5` |
+
+## Comparison Methods
+
+| Method | Description | Tolerance Syntax |
+|--------|-------------|-----------------|
+| `exact` | Actual == Expected | N/A |
+| `numeric_tolerance` | abs(actual - expected) ≤ tolerance | `± <value>` or `± <percent>%` |
+| `range` | min ≤ actual ≤ max | `[min, max]` |
+| `threshold_min` | actual ≥ threshold | `≥ <value>` |
+| `threshold_max` | actual ≤ threshold | `≤ <value>` |
+| `regex` | actual matches regex pattern | regex string |
+| `substring` | actual contains substring | substring |
+| `json_diff` | structural comparison against reference JSON | diff tolerance per field |
+| `set_contains` | actual output set contains expected items | subset notation |
+| `file_reference` | compare against reference file in expected_results/ | file path |
+
+## Input → Expected Result Mapping
+
+### [Scenario Group Name, e.g. "Single Image Detection"]
+
+| # | Input | Input Description | Expected Result | Comparison | Tolerance | Reference File |
+|---|-------|-------------------|-----------------|------------|-----------|---------------|
+| 1 | `[file or parameters]` | [what this input represents] | [quantifiable expected output] | [method from table above] | [± value, range, or N/A] | [path in expected_results/ or N/A] |
+
+#### Example — Object Detection
+
+| # | Input | Input Description | Expected Result | Comparison | Tolerance | Reference File |
+|---|-------|-------------------|-----------------|------------|-----------|---------------|
+| 1 | `image_01.jpg` | Aerial photo, 3 vehicles visible | `detection_count: 3`, classes: `["ArmorVehicle", "ArmorVehicle", "Truck"]` | exact (count), set_contains (classes) | N/A | N/A |
+| 2 | `image_01.jpg` | Same image, bbox positions | bboxes: `[(120,80,340,290), (400,150,580,310), (50,400,200,520)]` | numeric_tolerance | ± 15px per coordinate | `expected_results/image_01_detections.json` |
+| 3 | `image_01.jpg` | Same image, confidence scores | confidences: `[0.94, 0.88, 0.91]` | threshold_min | each ≥ 0.85 | N/A |
+| 4 | `empty_scene.jpg` | Aerial photo, no objects | `detection_count: 0`, empty detections array | exact | N/A | N/A |
+| 5 | `corrupted.dat` | Invalid file format | HTTP 400, body contains `"error"` key | exact (status), substring (body) | N/A | N/A |
+
+#### Example — Performance
+
+| # | Input | Input Description | Expected Result | Comparison | Tolerance | Reference File |
+|---|-------|-------------------|-----------------|------------|-----------|---------------|
+| 1 | `standard_image.jpg` | 1920x1080 single image | Response time | threshold_max | ≤ 2000ms | N/A |
+| 2 | `large_image.jpg` | 8000x6000 tiled image | Response time | threshold_max | ≤ 10000ms | N/A |
+
+#### Example — Error Handling
+
+| # | Input | Input Description | Expected Result | Comparison | Tolerance | Reference File |
+|---|-------|-------------------|-----------------|------------|-----------|---------------|
+| 1 | `POST /detect` with no file | Missing required input | HTTP 422, message matches `"file.*required"` | exact (status), regex (message) | N/A | N/A |
+| 2 | `POST /detect` with `probability_threshold: 5.0` | Out-of-range config | HTTP 422 or clamped to valid range | exact (status) or range [0.0, 1.0] | N/A | N/A |
+
+## Expected Result Reference Files
+
+When the expected output is too complex for an inline table cell (e.g., full JSON response with nested objects), place a reference file in `_docs/00_problem/input_data/expected_results/`.
+
+### File Naming Convention
+
+`<input_name>_expected.<format>`
+
+Examples:
+- `image_01_detections.json`
+- `batch_A_results.csv`
+- `video_01_annotations.json`
+
+### Reference File Requirements
+
+- Must be machine-readable (JSON, CSV, YAML — not prose)
+- Must contain only the expected output structure and values
+- Must include tolerance annotations where applicable (as metadata fields or comments)
+- Must be valid and parseable by standard libraries
+
+### Reference File Example (JSON)
+
+File: `expected_results/image_01_detections.json`
+
+​```json
+{
+  "input": "image_01.jpg",
+  "expected": {
+    "detection_count": 3,
+    "detections": [
+      {
+        "class": "ArmorVehicle",
+        "confidence": { "min": 0.85 },
+        "bbox": { "x1": 120, "y1": 80, "x2": 340, "y2": 290, "tolerance_px": 15 }
+      },
+      {
+        "class": "ArmorVehicle",
+        "confidence": { "min": 0.85 },
+        "bbox": { "x1": 400, "y1": 150, "x2": 580, "y2": 310, "tolerance_px": 15 }
+      },
+      {
+        "class": "Truck",
+        "confidence": { "min": 0.85 },
+        "bbox": { "x1": 50, "y1": 400, "x2": 200, "y2": 520, "tolerance_px": 15 }
+      }
+    ]
+  }
+}
+​```
+```
+
+---
+
+## Guidance Notes
+
+- Every row in the mapping table must have at least one quantifiable comparison — no row should say only "should work" or "returns result".
+- Use `exact` comparison for counts, status codes, and discrete values.
+- Use `numeric_tolerance` for floating-point values and spatial coordinates where minor variance is expected.
+- Use `threshold_min`/`threshold_max` for performance metrics and confidence scores.
+- Use `file_reference` when the expected output has more than ~3 fields or nested structures.
+- Reference files must be committed alongside input data — they are part of the test specification.
+- When the system has non-deterministic behavior (e.g., model inference variance across hardware), document the expected tolerance explicitly and justify it.

.cursor/skills/test-spec/templates/run-tests-script.md

@@ -0,0 +1,88 @@
+# Test Runner Script Structure
+
+Reference for generating `scripts/run-tests.sh` and `scripts/run-performance-tests.sh`.
+
+## `scripts/run-tests.sh`
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+UNIT_ONLY=false
+RESULTS_DIR="$PROJECT_ROOT/test-results"
+
+for arg in "$@"; do
+  case $arg in
+    --unit-only) UNIT_ONLY=true ;;
+  esac
+done
+
+cleanup() {
+  # tear down docker-compose if it was started
+}
+trap cleanup EXIT
+
+mkdir -p "$RESULTS_DIR"
+
+# --- Unit Tests ---
+# [detect runner: pytest / dotnet test / cargo test / npm test]
+# [run and capture exit code]
+# [save results to $RESULTS_DIR/unit-results.*]
+
+# --- Blackbox Tests (skip if --unit-only) ---
+# if ! $UNIT_ONLY; then
+#   [docker compose -f <compose-file> up -d]
+#   [wait for health checks]
+#   [run blackbox test suite]
+#   [save results to $RESULTS_DIR/blackbox-results.*]
+# fi
+
+# --- Summary ---
+# [print passed / failed / skipped counts]
+# [exit 0 if all passed, exit 1 otherwise]
+```
+
+## `scripts/run-performance-tests.sh`
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+RESULTS_DIR="$PROJECT_ROOT/test-results"
+
+cleanup() {
+  # tear down test environment if started
+}
+trap cleanup EXIT
+
+mkdir -p "$RESULTS_DIR"
+
+# --- Start System Under Test ---
+# [docker compose up -d or start local server]
+# [wait for health checks]
+
+# --- Run Performance Scenarios ---
+# [detect tool: k6 / locust / artillery / wrk / built-in]
+# [run each scenario from performance-tests.md]
+# [capture metrics: latency P50/P95/P99, throughput, error rate]
+
+# --- Compare Against Thresholds ---
+# [read thresholds from test spec or CLI args]
+# [print per-scenario pass/fail]
+
+# --- Summary ---
+# [exit 0 if all thresholds met, exit 1 otherwise]
+```
+
+## Key Requirements
+
+- Both scripts must be idempotent (safe to run multiple times)
+- Both scripts must work in CI (no interactive prompts, no GUI)
+- Use `trap cleanup EXIT` to ensure teardown even on failure
+- Exit codes: 0 = all pass, 1 = failures detected
+- Write results to `test-results/` directory (add to `.gitignore` if not already present)
+- The actual commands depend on the detected tech stack — fill them in during Phase 4 of the test-spec skill

.cursor/skills/ui-design/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: ui-design
+description: |
+  End-to-end UI design workflow: requirements gathering → design system synthesis → HTML+CSS mockup generation → visual verification → iterative refinement.
+  Zero external dependencies. Optional MCP enhancements (RenderLens, AccessLint).
+  Two modes:
+  - Full workflow: phases 0-8 for complex design tasks
+  - Quick mode: skip to code generation for simple requests
+  Command entry points:
+  - /design-audit — quality checks on existing mockup
+  - /design-polish — final refinement pass
+  - /design-critique — UX review with feedback
+  - /design-regen — regenerate with different direction
+  Trigger phrases:
+  - "design a UI", "create a mockup", "build a page"
+  - "make a landing page", "design a dashboard"
+  - "mockup", "design system", "UI design"
+category: create
+tags: [ui-design, mockup, html, css, tailwind, design-system, accessibility]
+disable-model-invocation: true
+---
+
+# UI Design Skill
+
+End-to-end UI design workflow producing production-quality HTML+CSS mockups entirely within Cursor, with zero external tool dependencies.
+
+## Core Principles
+
+- **Design intent over defaults**: never settle for generic AI output; every visual choice must trace to user requirements
+- **Verify visually**: AI must see what it generates whenever possible (browser screenshots)
+- **Tokens over hardcoded values**: use CSS custom properties with semantic naming, not raw hex
+- **Restraint over decoration**: less is more; every visual element must earn its place
+- **Ask, don't assume**: when design direction is ambiguous, STOP and ask the user
+- **One screen at a time**: generate individual screens, not entire applications at once
+
+## Context Resolution
+
+Determine the operating mode based on invocation before any other logic runs.
+
+**Project mode** (default — `_docs/` structure exists):
+- MOCKUPS_DIR: `_docs/02_document/ui_mockups/`
+
+**Standalone mode** (explicit input file provided, e.g. `/ui-design @some_brief.md`):
+- INPUT_FILE: the provided file (treated as design brief)
+- MOCKUPS_DIR: `_standalone/ui_mockups/`
+
+Create MOCKUPS_DIR if it does not exist. Announce the detected mode and resolved path to the user.
+
+## Output Directory
+
+All generated artifacts go to `MOCKUPS_DIR`:
+
+```
+MOCKUPS_DIR/
+├── DESIGN.md              # Generated design system (three-layer tokens)
+├── index.html             # Main mockup (or named per page)
+└── [page-name].html       # Additional pages if multi-page
+```
+
+## Complexity Detection (Phase 0)
+
+Before starting the workflow, classify the request:
+
+**Quick mode** — skip to Phase 5 (Code Generation):
+- Request is a single component or screen
+- User provides enough style context in their message
+- `MOCKUPS_DIR/DESIGN.md` already exists
+- Signals: "just make a...", "quick mockup of...", single component name, less than 2 sentences
+
+**Full mode** — run phases 1-8:
+- Multi-page request
+- Brand-specific requirements
+- "design system for...", complex layouts, dashboard/admin panel
+- No existing DESIGN.md
+
+Announce the detected mode to the user.
+
+## Phase 1: Context Check
+
+1. Check for existing project documentation: PRD, design specs, README with design notes
+2. Check for existing `MOCKUPS_DIR/DESIGN.md`
+3. Check for existing mockups in `MOCKUPS_DIR/`
+4. If DESIGN.md exists → announce "Using existing design system" → skip to Phase 5
+5. If project docs with design info exist → extract requirements from them, skip to Phase 3
+
+## Phase 2: Requirements Gathering
+
+Use the AskQuestion tool for structured input. Adapt based on what Phase 1 found — only ask for what's missing.
+
+**Round 1 — Structural:**
+
+Ask using AskQuestion with these questions:
+- **Page type**: landing, dashboard, form, settings, profile, admin panel, e-commerce, blog, documentation, other
+- **Target audience**: developers, business users, consumers, internal team, general public
+- **Platform**: web desktop-first, web mobile-first
+- **Key sections**: header, hero, sidebar, main content, cards grid, data table, form, footer (allow multiple)
+
+**Round 2 — Design Intent:**
+
+Ask using AskQuestion with these questions:
+- **Visual atmosphere**: Airy & spacious / Dense & data-rich / Warm & approachable / Sharp & technical / Luxurious & premium
+- **Color mood**: Cool blues & grays / Warm earth tones / Bold & vibrant / Monochrome / Dark mode / Let AI choose based on atmosphere / Custom (specify brand colors)
+- **Typography mood**: Geometric (modern, clean) / Humanist (friendly, readable) / Monospace (technical, code-like) / Serif (editorial, premium)
+
+Then ask in free-form:
+- "Name an app or website whose look you admire" (optional, helps anchor style)
+- "Any specific content, copy, or data to include?"
+
+## Phase 3: Direction Exploration
+
+Generate 2-3 text-based direction summaries. Each direction is 3-5 sentences describing:
+- Visual approach and mood
+- Color palette direction (specific hues, not just "blue")
+- Layout strategy (grid type, density, whitespace approach)
+- Typography choice (specific font suggestions, not just "sans-serif")
+
+Present to user: "Here are 2-3 possible directions. Which resonates? Or describe a blend."
+
+Wait for user to pick before proceeding.
+
+## Phase 4: Design System Synthesis
+
+Generate `MOCKUPS_DIR/DESIGN.md` using the template from `templates/design-system.md`.
+
+The generated DESIGN.md must include all 6 sections:
+1. Visual Atmosphere — descriptive mood (never "clean and modern")
+2. Color System — three-layer CSS custom properties (primitives → semantic → component)
+3. Typography — specific font family, weight hierarchy, size scale with rem values
+4. Spacing & Layout — base unit, spacing scale, grid, breakpoints
+5. Component Styling Defaults — buttons, cards, inputs, navigation with all states
+6. Interaction States — loading, error, empty, hover, focus, disabled patterns
+
+Read `references/design-vocabulary.md` for atmosphere descriptors and style vocabulary to use when writing the DESIGN.md.
+
+## Phase 5: Code Generation
+
+Construct the generation by combining context from multiple sources:
+
+1. Read `MOCKUPS_DIR/DESIGN.md` for the design system
+2. Read `references/components.md` for component best practices relevant to the page type
+3. Read `references/anti-patterns.md` for explicit avoidance instructions
+
+Generate `MOCKUPS_DIR/[page-name].html` as a single file with:
+- `<script src="https://cdn.tailwindcss.com"></script>` for Tailwind
+- `<style>` block with all CSS custom properties from DESIGN.md
+- Tailwind config override in `<script>` to map tokens to Tailwind theme
+- Semantic HTML (nav, main, section, article, footer)
+- Mobile-first responsive design
+- All interactive elements with hover, focus, active states
+- At least one loading skeleton example
+- Proper heading hierarchy (single h1)
+
+**Anti-AI-Slop guard clauses** (MANDATORY — read `references/anti-patterns.md` for full list):
+- Do NOT use Inter or Roboto unless user explicitly requested them
+- Do NOT default to purple/indigo accent color
+- Do NOT create "card soup" — vary layout patterns
+- Do NOT make all buttons equal weight
+- Do NOT over-decorate
+- Use the actual tokens from DESIGN.md, not hardcoded values
+
+For quick mode without DESIGN.md: use a sensible default design system matching the request context. Still follow all anti-slop rules.
+
+## Phase 6: Visual Verification
+
+Tiered verification — use the best available tool:
+
+**Layer 1 — Structural Check** (always runs):
+Read `references/quality-checklist.md` and verify against the structural checklist.
+
+**Layer 2 — Visual Check** (when browser tool is available):
+1. Open the generated HTML file using the browser tool
+2. Take screenshots at desktop (1440px) width
+3. Examine the screenshot for: spacing consistency, alignment, color rendering, typography hierarchy, overall visual balance
+4. Compare against DESIGN.md's intended atmosphere
+5. Flag issues: cramped areas, orphan text, broken layouts, invisible elements
+
+**Layer 3 — Compliance Check** (when MCP tools are available):
+- If AccessLint MCP is configured: audit HTML for WCAG violations, auto-fix flagged issues
+- If RenderLens MCP is configured: render + audit (Lighthouse + WCAG scores) + diff
+
+Auto-fix any issues found. Re-verify after fixes.
+
+## Phase 7: User Review
+
+1. Open mockup in browser for the user:
+   - Primary: use Cursor browser tool (AI can see and discuss the same view)
+   - Fallback: use OS-appropriate command (`open` on macOS, `xdg-open` on Linux, `start` on Windows)
+2. Present assessment summary: structural check results, visual observations, compliance scores if available
+3. Ask: "How does this look? What would you like me to change?"
+
+## Phase 8: Iteration
+
+1. Parse user feedback into specific changes
+2. Apply targeted edits via StrReplace (not full regeneration unless user requests a fundamentally different direction)
+3. Re-run visual verification (Phase 6)
+4. Present changes to user
+5. Repeat until user approves
+
+## Command Entry Points
+
+These commands bypass the full workflow for targeted operations on existing mockups:
+
+### /design-audit
+Run quality checks on an existing mockup in `MOCKUPS_DIR/`.
+1. Read the HTML file
+2. Run structural checklist from `references/quality-checklist.md`
+3. If browser tool available: take screenshot and visual check
+4. If AccessLint MCP available: WCAG audit
+5. Report findings with severity levels
+
+### /design-polish
+Final refinement pass on an existing mockup.
+1. Read the HTML file and DESIGN.md
+2. Check token usage (no hardcoded values that should be tokens)
+3. Verify all interaction states are present
+4. Refine spacing consistency, typography hierarchy
+5. Apply micro-improvements (subtle shadows, transitions, hover states)
+
+### /design-critique
+UX review with specific feedback.
+1. Read the HTML file
+2. Evaluate: information hierarchy, call-to-action clarity, cognitive load, navigation flow
+3. Check against anti-patterns from `references/anti-patterns.md`
+4. Provide a structured critique with specific improvement suggestions
+
+### /design-regen
+Regenerate mockup with a different design direction.
+1. Keep the existing page structure and content
+2. Ask user what direction to change (atmosphere, colors, layout, typography)
+3. Update DESIGN.md tokens accordingly
+4. Regenerate the HTML with the new design system
+
+## Optional MCP Enhancements
+
+When configured, these MCP servers enhance the workflow:
+
+| MCP Server | Phase | What It Adds |
+|------------|-------|-------------|
+| RenderLens | 6 | HTML→screenshot, Lighthouse audit, pixel-level diff |
+| AccessLint | 6 | WCAG violation detection + auto-fix (99.5% fix rate) |
+| Playwright | 6 | Screenshot at multiple viewports, visual regression |
+
+The skill works fully without any MCP servers. MCPs are enhancements, not requirements.
+
+## Escalation Rules
+
+| Situation | Action |
+|-----------|--------|
+| Unclear design direction | **ASK user** — present direction options |
+| Conflicting requirements (e.g., "minimal but feature-rich") | **ASK user** which to prioritize |
+| User asks for a framework-specific output (React, Vue) | **WARN**: this skill generates HTML+CSS mockups; suggest adapting after approval |
+| Generated mockup looks wrong in visual verification | Auto-fix if possible; **ASK user** if the issue is subjective |
+| User requests multi-page site | Generate one page at a time; maintain DESIGN.md consistency across pages |
+| Accessibility audit fails | Auto-fix violations; **WARN user** about remaining manual-check items |

.cursor/skills/ui-design/references/anti-patterns.md

@@ -0,0 +1,69 @@
+# Anti-Patterns — AI Slop Prevention
+
+Read this file before generating any HTML/CSS. These are explicit instructions for what NOT to do.
+
+## Typography Anti-Patterns
+
+- **Do NOT default to Inter or Roboto.** These are the #1 signal of AI-generated UI. Choose a font that matches the atmosphere from `design-vocabulary.md`. Only use Inter/Roboto if the user explicitly requests them.
+- **Do NOT use the same font weight everywhere.** Establish a clear weight hierarchy: 600-700 for headings, 400 for body, 500 for UI elements.
+- **Do NOT set body text smaller than 14px (0.875rem).** Prefer 16px (1rem) for body.
+- **Do NOT skip heading levels.** Go h1 → h2 → h3, never h1 → h3.
+- **Do NOT use placeholder-only form fields.** Labels above inputs are mandatory; placeholders are hints only.
+
+## Color Anti-Patterns
+
+- **Do NOT default to purple or indigo accent colors.** Purple/indigo is the second-biggest AI-slop signal. Use the accent color from DESIGN.md tokens.
+- **Do NOT use more than 1 strong accent color** in the same view. Secondary accents should be muted or derived from the primary.
+- **Do NOT use gray text on colored backgrounds** without checking contrast. WCAG AA requires 4.5:1 for normal text, 3:1 for large text.
+- **Do NOT use rainbow color coding** for categories. Limit to 5-6 carefully chosen, distinguishable colors.
+- **Do NOT apply background gradients to text** (gradient text is fragile and often unreadable).
+
+## Layout Anti-Patterns
+
+- **Do NOT create "card soup"** — rows of identical cards with no visual break. Vary layout patterns: full-width sections, split layouts, featured items, asymmetric grids.
+- **Do NOT center everything.** Left-align body text. Center only headings, short captions, and CTAs.
+- **Do NOT use fixed pixel widths** for layout. Use relative units (%, fr, auto, minmax).
+- **Do NOT nest excessive containers.** Avoid "div soup" — use semantic elements (nav, main, section, article, aside, footer).
+- **Do NOT ignore mobile.** Design mobile-first; every component must work at 375px width.
+
+## Component Anti-Patterns
+
+- **Do NOT make all buttons equal weight.** Establish clear hierarchy: one primary (filled), secondary (outline), ghost (text-only) per visible area.
+- **Do NOT use spinners for content with known layout.** Use skeleton loaders that match the shape of the content.
+- **Do NOT put a modal inside a modal.** If you need nested interaction, use a slide-over or expand the current modal.
+- **Do NOT disable buttons without explanation.** Every disabled button needs a title attribute or adjacent text explaining why.
+- **Do NOT use "Click here" as link text.** Links should describe the destination: "View documentation", "Download report".
+- **Do NOT show hamburger menus on desktop.** Hamburgers are for mobile only; use full navigation on desktop.
+- **Do NOT use equal-weight buttons in a pair.** One must be visually primary, the other secondary.
+
+## Interaction Anti-Patterns
+
+- **Do NOT skip hover states on interactive elements.** Every clickable element needs a visible hover change.
+- **Do NOT skip focus states.** Keyboard users need visible focus indicators on every interactive element.
+- **Do NOT omit loading states.** If data loads asynchronously, show a skeleton or progress indicator.
+- **Do NOT omit empty states.** When a list or section has no data, show an illustration + explanation + action CTA.
+- **Do NOT omit error states.** Form validation errors need inline messages below the field with an icon.
+- **Do NOT use bare alert() for messages.** Use toast notifications or inline banners.
+
+## Decoration Anti-Patterns
+
+- **Do NOT over-decorate.** Restraint over decoration. Every visual element must earn its place.
+- **Do NOT apply shadows AND borders AND background fills simultaneously** on the same element. Pick one or two.
+- **Do NOT use generic stock-photo placeholder images.** Use SVG illustrations, solid color blocks with icons, or real content.
+- **Do NOT use decorative backgrounds** that reduce text readability.
+- **Do NOT animate everything.** Use motion sparingly and purposefully: transitions for state changes (200-300ms), not decorative animation.
+
+## Spacing Anti-Patterns
+
+- **Do NOT use inconsistent spacing.** Stick to the spacing scale from DESIGN.md (multiples of 4px or 8px base unit).
+- **Do NOT use zero padding inside containers.** Minimum 12-16px padding for any content container.
+- **Do NOT crowd elements.** When in doubt, add more whitespace, not less.
+- **Do NOT use different spacing systems** in different parts of the same page. One scale for the whole page.
+
+## Accessibility Anti-Patterns
+
+- **Do NOT rely on color alone** to convey information. Add icons, text, or patterns.
+- **Do NOT use thin font weights (100-300) for body text.** Minimum 400 for readability.
+- **Do NOT create custom controls** without proper ARIA attributes. Prefer native HTML elements.
+- **Do NOT trap keyboard focus** outside of modals. Only modals should have focus traps.
+- **Do NOT auto-play media** without user consent and a visible stop/mute control.

.cursor/skills/ui-design/references/components.md

@@ -0,0 +1,307 @@
+# Component Reference
+
+Use this reference when generating UI mockups. Each component includes best practices, required states, and accessibility requirements.
+
+## Navigation
+
+### Top Navigation Bar
+- Fixed or sticky at top; z-index above content
+- Logo/brand left, primary nav center or right, actions (search, profile, CTA) far right
+- Active state: underline, background highlight, or bold — pick one, be consistent
+- Mobile: collapse to hamburger menu at `md` breakpoint; never show hamburger on desktop
+- Height: 56-72px; padding inline 16-24px
+- Aliases: navbar, header nav, app bar, top bar
+
+### Sidebar Navigation
+- Width: 240-280px expanded, 64-72px collapsed
+- Sections with labels; icons + text for each item
+- Active item: background fill + accent color text/icon
+- Collapse/expand toggle; responsive: overlay on mobile
+- Scroll independently from main content if taller than viewport
+- Aliases: side nav, drawer, rail
+
+### Breadcrumbs
+- Show hierarchy path; separator: `/` or `>`
+- Current page is plain text (not a link); parent pages are links
+- Truncate with ellipsis if more than 4-5 levels
+- Aliases: path indicator, navigation trail
+
+### Tabs
+- Use for switching between related content views within the same context
+- Active tab: border-bottom accent or filled background
+- Never nest tabs inside tabs
+- Scrollable when too many to fit; show scroll indicators
+- Aliases: tab bar, segmented control, view switcher
+
+### Pagination
+- Show current page, first, last, and 2-3 surrounding pages
+- Previous/Next buttons always visible; disabled at boundaries
+- Show total count when available: "Showing 1-20 of 342"
+- Aliases: pager, page navigation
+
+## Content Display
+
+### Card
+- Border-radius: 8-12px; subtle shadow or border (not both unless intentional)
+- Padding: 16-24px; consistent within the same card grid
+- Content order: image/visual → title → description → metadata → actions
+- Hover: subtle shadow lift or border-color change (not both)
+- Never stack more than 3 cards vertically without visual break
+- Aliases: tile, panel, content block
+
+### Data Table
+- Header row: sticky, slightly bolder background, sort indicators
+- Row hover: subtle background change
+- Striped rows optional; alternate between base and surface colors
+- Cell padding: 12-16px vertical, 16px horizontal
+- Truncate long text with ellipsis + tooltip on hover
+- Responsive: horizontal scroll with frozen first column, or stack to card layout on mobile
+- Include empty state when no data
+- Aliases: grid, spreadsheet, list view
+
+### List
+- Consistent item height or padding
+- Dividers between items: subtle border or spacing (not both)
+- Interactive lists: hover state on entire row
+- Leading element (icon/avatar) + content (title + subtitle) + trailing element (action/badge)
+- Aliases: item list, feed, timeline
+
+### Stat/Metric Card
+- Large number/value prominently displayed
+- Label above or below the value; comparison/trend indicator optional
+- Color-code trends: green up, red down, gray neutral
+- Aliases: KPI card, metric tile, stat block
+
+### Avatar
+- Circular; sizes: 24/32/40/48/64px
+- Fallback: initials on colored background when no image
+- Status indicator: small circle at bottom-right (green=online, gray=offline)
+- Group: overlap with z-index stacking; show "+N" for overflow
+- Aliases: profile picture, user icon
+
+### Badge/Tag
+- Small, pill-shaped or rounded-rectangle
+- Color indicates category or status; limit to 5-6 distinct colors
+- Text: short (1-3 words); truncate if longer
+- Removable variant: include x button
+- Aliases: chip, label, status indicator
+
+### Hero Section
+- Full-width; height 400-600px or viewport-relative
+- Strong headline (h1) + supporting text + primary CTA
+- Background: gradient, image with overlay, or solid color — not all three
+- Text must have sufficient contrast over any background
+- Aliases: banner, jumbotron, splash
+
+### Empty State
+- Illustration or icon (not a generic placeholder)
+- Explanatory text: what this area will contain
+- Primary action CTA: "Create your first...", "Add...", "Import..."
+- Never show just blank space
+- Aliases: zero state, no data, blank slate
+
+### Skeleton Loader
+- Match the shape and layout of the content being loaded
+- Animate with subtle pulse or shimmer (left-to-right gradient)
+- Show for predictable content; use progress bar for uploads/processes
+- Never use spinning loaders for content that has a known layout
+- Aliases: placeholder, loading state, content loader
+
+## Forms & Input
+
+### Text Input
+- Height: 40-48px; padding inline 12-16px
+- Label above the input (not placeholder-only); placeholder as hint only
+- States: default, hover, focus (accent ring), error (red border + message), disabled (reduced opacity)
+- Error message below the field with icon; don't use red placeholder
+- Aliases: text field, input box, form field
+
+### Textarea
+- Minimum height: 80-120px; resizable vertically
+- Character count when there's a limit
+- Same states as text input
+- Aliases: multiline input, text area, comment box
+
+### Select/Dropdown
+- Match text input height and styling
+- Chevron indicator on the right
+- Options list: max height with scroll; selected item checkmark
+- Search/filter for lists longer than 10 items
+- Aliases: combo box, picker, dropdown menu
+
+### Checkbox
+- Size: 16-20px; rounded corners (2-4px)
+- Label to the right; clickable area includes the label
+- States: unchecked, checked (accent fill + white check), indeterminate (dash), disabled
+- Group: vertical stack with 8-12px gap
+- Aliases: check box, toggle option, multi-select
+
+### Radio Button
+- Size: 16-20px; circular
+- Same interaction patterns as checkbox but single-select
+- Group: vertical stack; minimum 2 options
+- Aliases: radio, option button, single-select
+
+### Toggle/Switch
+- Width: 40-52px; height: 20-28px; thumb is circular
+- Off: gray track; On: accent color track
+- Label to the left or right; describe the "on" state
+- Never use for actions that require a submit; toggles are instant
+- Aliases: switch, on/off toggle
+
+### File Upload
+- Drop zone with dashed border; icon + "Drag & drop or click to upload"
+- Show file type restrictions and size limit
+- Progress indicator during upload
+- File list after upload: name, size, remove button
+- Aliases: file picker, upload area, attachment
+
+### Form Layout
+- Single column for most forms; two columns only for related short fields (first/last name, city/state)
+- Group related fields with section headings
+- Required field indicator: asterisk after label
+- Submit button: right-aligned or full-width; clearly primary
+- Inline validation: show errors on blur, not on every keystroke
+
+## Actions
+
+### Button
+- Primary: filled accent color, white text; one per visible area
+- Secondary: outline or subtle background; supports primary action
+- Ghost/tertiary: text-only with hover background
+- Sizes: sm (32px), md (40px), lg (48px); padding inline 16-24px
+- States: default, hover (darken/lighten 10%), active (darken 15%), focus (ring), disabled (opacity 0.5 + not-allowed cursor)
+- Disabled buttons must have a title attribute explaining why
+- Icon-only buttons: need aria-label; minimum 40px touch target
+- Aliases: action, CTA, submit
+
+### Icon Button
+- Circular or rounded-square; minimum 40px for touch targets
+- Tooltip on hover showing the action name
+- Visually lighter than text buttons
+- Aliases: toolbar button, action icon
+
+### Dropdown Menu
+- Trigger: button or icon button
+- Menu: elevated surface (shadow), rounded corners
+- Items: 36-44px height; icon + label; hover background
+- Dividers between groups; section labels for grouped items
+- Keyboard navigable: arrow keys, enter to select, escape to close
+- Aliases: context menu, action menu, overflow menu
+
+### Floating Action Button (FAB)
+- Circular, 56px; elevated with shadow
+- One per screen maximum; bottom-right placement
+- Primary creation action only
+- Extended variant: pill-shape with icon + label
+- Aliases: FAB, add button, create button
+
+## Feedback
+
+### Toast/Notification
+- Position: top-right or bottom-right; stack vertically
+- Auto-dismiss: 4-6 seconds for info; persist for errors until dismissed
+- Types: success (green), error (red), warning (amber), info (blue)
+- Content: icon + message + optional action link + close button
+- Maximum 3 visible at once; queue the rest
+- Aliases: snackbar, alert toast, flash message
+
+### Alert/Banner
+- Full-width within its container; not floating
+- Types: info, success, warning, error with corresponding colors
+- Icon left, message center, dismiss button right
+- Persistent until user dismisses or condition changes
+- Aliases: notice, inline alert, status banner
+
+### Modal/Dialog
+- Centered; overlay dims background (opacity 0.5 black)
+- Max width: 480-640px for standard, 800px for complex
+- Header (title + close button) + body + footer (actions)
+- Actions: right-aligned; primary right, secondary left
+- Close on overlay click and Escape key
+- Never put a modal inside a modal
+- Focus trap: tab cycles within modal while open
+- Aliases: popup, dialog box, lightbox
+
+### Tooltip
+- Appears on hover after 300-500ms delay; disappears on mouse leave
+- Position: above element by default; flip if near viewport edge
+- Max width: 200-280px; short text only
+- Arrow/caret pointing to trigger element
+- Aliases: hint, info popup, hover text
+
+### Progress Indicator
+- Linear bar: for known duration/percentage; show percentage text
+- Skeleton: for content loading with known layout
+- Spinner: only for indeterminate short waits (< 3 seconds) where layout is unknown
+- Step indicator: for multi-step flows; show completed/current/upcoming
+- Aliases: loading bar, progress bar, stepper
+
+## Layout
+
+### Page Shell
+- Max content width: 1200-1440px; centered with auto margins
+- Sidebar + main content pattern: sidebar fixed, main scrolls
+- Header/footer outside max-width for full-bleed effect
+- Consistent padding: 16px mobile, 24px tablet, 32px desktop
+
+### Grid
+- CSS Grid or Flexbox; 12-column system or auto-fit with minmax
+- Gap: 16-24px between items
+- Responsive: 1 column mobile, 2 columns tablet, 3-4 columns desktop
+- Never rely on fixed pixel widths; use fr units or percentages
+
+### Section Divider
+- Use spacing (48-96px margin) as primary divider; use lines sparingly
+- If using lines: subtle (1px, border color); full-width or indented
+- Alternate section backgrounds (base/surface) for clear separation without lines
+
+### Responsive Breakpoints
+- sm: 640px (large phone landscape)
+- md: 768px (tablet)
+- lg: 1024px (small laptop)
+- xl: 1280px (desktop)
+- Design mobile-first: base styles are mobile, layer up with breakpoints
+
+## Specialized
+
+### Pricing Table
+- 2-4 tiers side by side; highlight recommended tier
+- Feature comparison with checkmarks; group features by category
+- CTA button per tier; recommended tier has primary button, others secondary
+- Monthly/annual toggle if applicable
+- Aliases: pricing cards, plan comparison
+
+### Testimonial
+- Quote text (large, italic or with quotation marks)
+- Attribution: avatar + name + title/company
+- Layout: single featured or carousel/grid of multiple
+- Aliases: review, customer quote, social proof
+
+### Footer
+- Full-width; darker background than body
+- Column layout: links grouped by category; 3-5 columns
+- Bottom row: copyright, legal links, social icons
+- Responsive: columns stack on mobile
+- Aliases: site footer, bottom navigation
+
+### Search
+- Input with search icon; expand on focus or always visible
+- Results: dropdown with highlighted matching text
+- Recent searches and suggestions
+- Keyboard shortcut hint (Cmd+K / Ctrl+K)
+- Aliases: search bar, omnibar, search field
+
+### Date Picker
+- Input that opens a calendar dropdown
+- Navigate months with arrows; today highlighted
+- Range selection: two calendars side by side
+- Presets: "Today", "Last 7 days", "This month"
+- Aliases: calendar picker, date selector
+
+### Chart/Graph Placeholder
+- Container with appropriate aspect ratio (16:9 for line/bar, 1:1 for pie)
+- Include chart title, legend, and axis labels in the mockup
+- Use representative fake data; label as "Sample Data"
+- Tooltip placeholder on hover
+- Aliases: data visualization, graph, analytics chart

.cursor/skills/ui-design/references/design-vocabulary.md

@@ -0,0 +1,139 @@
+# Design Vocabulary
+
+Use this reference when writing DESIGN.md files and constructing generation prompts. Replace vague descriptors with specific, actionable terms.
+
+## Atmosphere Descriptors
+
+Use these instead of "clean and modern":
+
+| Atmosphere | Characteristics | Font Direction | Color Direction | Spacing |
+|------------|----------------|---------------|-----------------|---------|
+| **Airy & Spacious** | Generous whitespace, light backgrounds, floating elements, subtle shadows | Thin/light weights, generous letter-spacing | Soft pastels, whites, muted accents | Large margins, open padding |
+| **Dense & Data-Rich** | Compact spacing, information-heavy, efficient use of space | Medium weights, tighter line-heights, smaller sizes | Neutral grays, high-contrast data colors | Tight but consistent padding |
+| **Warm & Approachable** | Rounded corners, friendly illustrations, organic shapes | Rounded/humanist typefaces, comfortable sizes | Earth tones, warm neutrals, amber/coral accents | Medium spacing, generous touch targets |
+| **Sharp & Technical** | Crisp edges, precise alignment, monospace elements, dark themes | Geometric or monospace, precise sizing | Cool grays, electric blues/greens, dark backgrounds | Grid-strict, mathematical spacing |
+| **Luxurious & Premium** | Generous space, refined details, serif accents, subtle animations | Serif or elegant sans-serif, generous sizing | Deep darks, gold/champagne accents, rich jewel tones | Expansive whitespace, dramatic padding |
+| **Playful & Creative** | Asymmetric layouts, bold colors, hand-drawn elements, motion | Display fonts, variable weights, expressive sizing | Bright saturated colors, unexpected combinations | Dynamic, deliberately uneven |
+| **Corporate & Enterprise** | Structured grids, predictable patterns, dense but organized | System fonts or conservative sans-serif | Brand blues/grays, accent for status indicators | Systematic, spec-driven |
+| **Editorial & Content** | Typography-forward, reading-focused, long-form layout | Serif for body text, sans for UI elements | Near-monochrome, sparse accent color | Generous line-height, wide columns |
+
+## Style-Specific Vocabulary
+
+### When user says... → Use these terms in DESIGN.md
+
+| Vague Input | Professional Translation |
+|-------------|------------------------|
+| "clean" | Restrained palette, generous whitespace, consistent alignment grid |
+| "modern" | Current design patterns (2024-2026), subtle depth, micro-interactions |
+| "minimal" | Single accent color, maximum negative space, typography-driven hierarchy |
+| "professional" | Structured grid, conservative palette, system fonts, clear navigation |
+| "fun" | Saturated palette, rounded elements, playful illustrations, motion |
+| "elegant" | Serif typography, muted palette, generous spacing, refined details |
+| "techy" | Dark theme, monospace accents, neon highlights, sharp corners |
+| "bold" | High contrast, large type, strong color blocks, dramatic layout |
+| "friendly" | Rounded corners (12-16px), humanist fonts, warm colors, illustrations |
+| "corporate" | Blue-gray palette, structured grid, conventional layout, data tables |
+
+## Color Mood Palettes
+
+### Cool Blues & Grays
+- Background: #f8fafc → #f1f5f9
+- Surface: #ffffff
+- Text: #0f172a → #475569
+- Accent: #2563eb (blue-600)
+- Pairs well with: Airy, Sharp, Corporate atmospheres
+
+### Warm Earth Tones
+- Background: #faf8f5 → #f5f0eb
+- Surface: #ffffff
+- Text: #292524 → #78716c
+- Accent: #c2410c (orange-700) or #b45309 (amber-700)
+- Pairs well with: Warm, Editorial atmospheres
+
+### Bold & Vibrant
+- Background: #fafafa → #f5f5f5
+- Surface: #ffffff
+- Text: #171717 → #525252
+- Accent: #dc2626 (red-600) or #7c3aed (violet-600) or #059669 (emerald-600)
+- Pairs well with: Playful, Creative atmospheres
+
+### Monochrome
+- Background: #fafafa → #f5f5f5
+- Surface: #ffffff
+- Text: #171717 → #737373
+- Accent: #171717 (black) with #e5e5e5 borders
+- Pairs well with: Minimal, Luxurious, Editorial atmospheres
+
+### Dark Mode
+- Background: #09090b → #18181b
+- Surface: #27272a → #3f3f46
+- Text: #fafafa → #a1a1aa
+- Accent: #3b82f6 (blue-500) or #22d3ee (cyan-400)
+- Pairs well with: Sharp, Technical, Dense atmospheres
+
+## Typography Mood Mapping
+
+### Geometric (Modern, Clean)
+Fonts: DM Sans, Plus Jakarta Sans, Outfit, General Sans, Satoshi
+- Characteristics: even stroke weight, circular letter forms, precise geometry
+- Best for: SaaS, tech products, dashboards, landing pages
+
+### Humanist (Friendly, Readable)
+Fonts: Source Sans 3, Nunito, Lato, Open Sans, Noto Sans
+- Characteristics: organic curves, varying stroke, warm feel
+- Best for: consumer apps, health/wellness, education, community platforms
+
+### Monospace (Technical, Code-Like)
+Fonts: JetBrains Mono, Fira Code, IBM Plex Mono, Space Mono
+- Characteristics: fixed-width, technical aesthetic, raw precision
+- Best for: developer tools, terminals, data displays, documentation
+
+### Serif (Editorial, Premium)
+Fonts: Playfair Display, Lora, Merriweather, Crimson Pro, Libre Baskerville
+- Characteristics: traditional elegance, reading comfort, authority
+- Best for: blogs, magazines, luxury brands, portfolio sites
+
+### Display (Expressive, Bold)
+Fonts: Cabinet Grotesk, Clash Display, Archivo Black, Space Grotesk
+- Characteristics: high impact, personality-driven, attention-grabbing
+- Best for: hero sections, headlines, creative portfolios, marketing pages
+- Use for headings only; pair with a readable body font
+
+## Shape & Depth Vocabulary
+
+### Border Radius Scale
+| Term | Value | Use for |
+|------|-------|---------|
+| Sharp | 0-2px | Technical, enterprise, data-heavy |
+| Subtle | 4-6px | Professional, balanced |
+| Rounded | 8-12px | Friendly, modern SaaS |
+| Pill | 16-24px or full | Playful, badges, tags |
+| Circle | 50% | Avatars, icon buttons |
+
+### Shadow Scale
+| Term | Value | Use for |
+|------|-------|---------|
+| None | none | Flat design, minimal |
+| Whisper | 0 1px 2px rgba(0,0,0,0.05) | Subtle elevation, cards |
+| Soft | 0 4px 6px rgba(0,0,0,0.07) | Standard cards, dropdowns |
+| Medium | 0 10px 15px rgba(0,0,0,0.1) | Elevated elements, modals |
+| Strong | 0 20px 25px rgba(0,0,0,0.15) | Floating elements, popovers |
+
+### Surface Hierarchy
+1. **Background** — deepest layer, covers viewport
+2. **Surface** — content containers (cards, panels) sitting on background
+3. **Elevated** — elements above surface (modals, dropdowns, tooltips)
+4. **Overlay** — dimming layer between surface and elevated elements
+
+## Layout Pattern Names
+
+| Pattern | Description | Best for |
+|---------|-------------|----------|
+| **Holy grail** | Header + sidebar + main + footer | Admin dashboards, apps |
+| **Magazine** | Multi-column with varied widths | Content sites, blogs |
+| **Single column** | Centered narrow content | Landing pages, articles, forms |
+| **Split screen** | Two equal or 60/40 halves | Comparison pages, sign-up flows |
+| **Card grid** | Uniform grid of cards | Product listings, portfolios |
+| **Asymmetric** | Deliberately unequal columns | Creative, editorial layouts |
+| **Full bleed** | Edge-to-edge sections, no max-width | Marketing pages, portfolios |
+| **Dashboard** | Stat cards + charts + tables in grid | Analytics, admin panels |

.cursor/skills/ui-design/references/quality-checklist.md

@@ -0,0 +1,109 @@
+# Quality Checklist
+
+Run through this checklist after generating or modifying a mockup. Three layers; run all that apply.
+
+## Layer 1: Structural Check (Always Run)
+
+### Semantic HTML
+- [ ] Uses `nav`, `main`, `section`, `article`, `aside`, `footer` — not just `div`
+- [ ] Single `h1` per page
+- [ ] Heading hierarchy follows h1 → h2 → h3 without skipping levels
+- [ ] Lists use `ul`/`ol`/`li`, not styled `div`s
+- [ ] Interactive elements are `button` or `a`, not clickable `div`s
+
+### Design Tokens
+- [ ] CSS custom properties defined in `<style>` block
+- [ ] Colors in HTML reference tokens (e.g., `var(--color-accent)`) not raw hex
+- [ ] Spacing follows the defined scale, not arbitrary pixel values
+- [ ] Font family matches DESIGN.md, not browser default or Inter/Roboto
+
+### Responsive Design
+- [ ] Mobile-first: base styles work at 375px
+- [ ] Content readable without horizontal scroll at all breakpoints
+- [ ] Navigation adapts: full nav on desktop, collapsed on mobile
+- [ ] Images/media have max-width: 100%
+- [ ] Touch targets minimum 44px on mobile
+
+### Interaction States
+- [ ] All buttons have hover, focus, active states
+- [ ] All links have hover and focus states
+- [ ] At least one loading state example (skeleton loader preferred)
+- [ ] At least one empty state with illustration + CTA
+- [ ] Disabled elements have visual indicator + explanation (title attribute)
+- [ ] Form inputs have focus ring using accent color
+
+### Component Quality
+- [ ] Button hierarchy: one primary per visible area, secondary and ghost variants present
+- [ ] Forms: labels above inputs, not placeholder-only
+- [ ] Error states: inline message below field with icon
+- [ ] No hamburger menu on desktop
+- [ ] No modal inside modal
+- [ ] No "Click here" links
+
+### Code Quality
+- [ ] Valid HTML (no unclosed tags, no duplicate IDs)
+- [ ] Tailwind classes are valid (no made-up utilities)
+- [ ] No inline styles that duplicate token values
+- [ ] File is self-contained (single HTML file, no external dependencies except Tailwind CDN)
+- [ ] Total file size under 50KB
+
+## Layer 2: Visual Check (When Browser Tool Available)
+
+Take a screenshot and examine:
+
+### Spacing & Alignment
+- [ ] Consistent margins between sections
+- [ ] Elements within the same row are vertically aligned
+- [ ] Padding within cards/containers is consistent
+- [ ] No orphan text (single word on its own line in headings)
+- [ ] Grid alignment: elements on the same row have matching heights or intentional variation
+
+### Typography
+- [ ] Heading sizes create clear hierarchy (visible difference between h1, h2, h3)
+- [ ] Body text is comfortable reading size (not tiny)
+- [ ] Font rendering looks correct (font loaded or appropriate fallback)
+- [ ] Line length: body text 50-75 characters per line
+
+### Color & Contrast
+- [ ] Primary accent is visible but not overwhelming
+- [ ] Text is readable over all backgrounds
+- [ ] No elements blend into their backgrounds
+- [ ] Status colors (success/error/warning) are distinguishable
+
+### Overall Composition
+- [ ] Visual weight is balanced (not all content on one side)
+- [ ] Clear focal point on the page (hero, headline, or primary CTA)
+- [ ] Appropriate whitespace: not cramped, not excessively empty
+- [ ] Consistent visual language throughout the page
+
+### Atmosphere Match
+- [ ] Overall feel matches the DESIGN.md atmosphere description
+- [ ] Not generic "AI generated" look
+- [ ] Color palette is cohesive (no unexpected color outliers)
+- [ ] Typography choice matches the intended mood
+
+## Layer 3: Compliance Check (When MCP Tools Available)
+
+### AccessLint MCP
+- [ ] Run `audit_html` on the generated file
+- [ ] Fix all violations with fixability "fixable" or "potentially_fixable"
+- [ ] Document any remaining violations that require manual judgment
+- [ ] Re-run `diff_html` to confirm fixes resolved violations
+
+### RenderLens MCP
+- [ ] Render at 1440px and 375px widths
+- [ ] Lighthouse accessibility score ≥ 80
+- [ ] Lighthouse performance score ≥ 70
+- [ ] Lighthouse best practices score ≥ 80
+- [ ] If iterating: run diff between previous and current version
+
+## Severity Classification
+
+When reporting issues found during the checklist:
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| **Critical** | Broken layout, invisible content, no mobile support | Fix immediately before showing to user |
+| **High** | Missing interaction states, accessibility violations, token misuse | Fix before showing to user |
+| **Medium** | Minor spacing inconsistency, non-ideal font weight, slight alignment issue | Note in assessment, fix if easy |
+| **Low** | Style preference, minor polish opportunity | Note in assessment, fix during /design-polish |

.cursor/skills/ui-design/templates/design-system.md

@@ -0,0 +1,199 @@
+# Design System: [Project Name]
+
+## 1. Visual Atmosphere
+
+[Describe the mood, density, and aesthetic philosophy in 2-3 sentences. Be specific — never use "clean and modern". Reference the atmosphere type from design-vocabulary.md. Example: "A spacious, light-filled interface with generous whitespace that feels calm and unhurried. Elements float on a near-white canvas with subtle shadows providing depth. The overall impression is sophisticated simplicity — premium without being cold."]
+
+## 2. Color System
+
+### Primitives
+
+```css
+:root {
+  --white: #ffffff;
+  --black: #000000;
+
+  --gray-50: #______;
+  --gray-100: #______;
+  --gray-200: #______;
+  --gray-300: #______;
+  --gray-400: #______;
+  --gray-500: #______;
+  --gray-600: #______;
+  --gray-700: #______;
+  --gray-800: #______;
+  --gray-900: #______;
+  --gray-950: #______;
+
+  --accent-50: #______;
+  --accent-100: #______;
+  --accent-200: #______;
+  --accent-300: #______;
+  --accent-400: #______;
+  --accent-500: #______;
+  --accent-600: #______;
+  --accent-700: #______;
+  --accent-800: #______;
+  --accent-900: #______;
+
+  --red-500: #______;
+  --red-600: #______;
+  --green-500: #______;
+  --green-600: #______;
+  --amber-500: #______;
+  --amber-600: #______;
+}
+```
+
+### Semantic Tokens
+
+```css
+:root {
+  --color-bg-primary: var(--gray-50);
+  --color-bg-secondary: var(--gray-100);
+  --color-bg-surface: var(--white);
+  --color-bg-inverse: var(--gray-900);
+
+  --color-text-primary: var(--gray-900);
+  --color-text-secondary: var(--gray-500);
+  --color-text-tertiary: var(--gray-400);
+  --color-text-inverse: var(--white);
+  --color-text-link: var(--accent-600);
+
+  --color-accent: var(--accent-600);
+  --color-accent-hover: var(--accent-700);
+  --color-accent-light: var(--accent-50);
+
+  --color-border: var(--gray-200);
+  --color-border-strong: var(--gray-300);
+  --color-divider: var(--gray-100);
+
+  --color-error: var(--red-600);
+  --color-error-light: var(--red-500);
+  --color-success: var(--green-600);
+  --color-success-light: var(--green-500);
+  --color-warning: var(--amber-600);
+  --color-warning-light: var(--amber-500);
+}
+```
+
+### Component Tokens
+
+```css
+:root {
+  --button-primary-bg: var(--color-accent);
+  --button-primary-text: var(--color-text-inverse);
+  --button-primary-hover: var(--color-accent-hover);
+  --button-secondary-bg: transparent;
+  --button-secondary-border: var(--color-border-strong);
+  --button-secondary-text: var(--color-text-primary);
+
+  --card-bg: var(--color-bg-surface);
+  --card-border: var(--color-border);
+  --card-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
+
+  --input-bg: var(--color-bg-surface);
+  --input-border: var(--color-border);
+  --input-border-focus: var(--color-accent);
+  --input-text: var(--color-text-primary);
+  --input-placeholder: var(--color-text-tertiary);
+
+  --nav-bg: var(--color-bg-surface);
+  --nav-active-bg: var(--color-accent-light);
+  --nav-active-text: var(--color-accent);
+}
+```
+
+## 3. Typography
+
+- **Font family**: [Specific font name], [fallback], system-ui, sans-serif
+- **Font source**: Google Fonts link or system font
+
+| Level | Element | Size | Weight | Line Height | Letter Spacing |
+|-------|---------|------|--------|-------------|----------------|
+| Display | Hero headlines | 3rem (48px) | 700 | 1.1 | -0.02em |
+| H1 | Page title | 2.25rem (36px) | 700 | 1.2 | -0.01em |
+| H2 | Section title | 1.5rem (24px) | 600 | 1.3 | 0 |
+| H3 | Subsection | 1.25rem (20px) | 600 | 1.4 | 0 |
+| H4 | Card/group title | 1.125rem (18px) | 600 | 1.4 | 0 |
+| Body | Default text | 1rem (16px) | 400 | 1.5 | 0 |
+| Small | Captions, meta | 0.875rem (14px) | 400 | 1.5 | 0.01em |
+| XS | Labels, badges | 0.75rem (12px) | 500 | 1.4 | 0.02em |
+
+## 4. Spacing & Layout
+
+- **Base unit**: 4px (0.25rem)
+- **Spacing scale**: 1 (4px), 2 (8px), 3 (12px), 4 (16px), 5 (20px), 6 (24px), 8 (32px), 10 (40px), 12 (48px), 16 (64px), 20 (80px), 24 (96px)
+- **Content max-width**: [1200px / 1280px / 1440px]
+- **Grid**: [12-column / auto-fit] with [16px / 24px] gap
+
+| Breakpoint | Name | Min Width | Columns | Padding |
+|------------|------|-----------|---------|---------|
+| Mobile | sm | 0 | 1 | 16px |
+| Tablet | md | 768px | 2 | 24px |
+| Laptop | lg | 1024px | 3-4 | 32px |
+| Desktop | xl | 1280px | 4+ | 32px |
+
+## 5. Component Styling Defaults
+
+### Buttons
+- Border radius: [6px / 8px / full]
+- Padding: 10px 20px (md), 8px 16px (sm), 12px 24px (lg)
+- Font weight: 500
+- Transition: background-color 150ms ease, box-shadow 150ms ease
+- Focus: 2px ring with 2px offset using `--color-accent`
+- Disabled: opacity 0.5, cursor not-allowed
+
+### Cards
+- Border radius: [8px / 12px]
+- Border: 1px solid var(--card-border)
+- Shadow: var(--card-shadow)
+- Padding: 20-24px
+- Hover (if interactive): shadow increase or border-color change
+
+### Inputs
+- Height: 40px (md), 36px (sm), 48px (lg)
+- Border radius: 6px
+- Border: 1px solid var(--input-border)
+- Padding: 0 12px
+- Focus: border-color var(--input-border-focus) + 2px ring
+- Error: border-color var(--color-error) + error message below
+
+### Navigation
+- Item height: 40px
+- Active: background var(--nav-active-bg), text var(--nav-active-text)
+- Hover: background var(--color-bg-secondary)
+- Transition: background-color 150ms ease
+
+## 6. Interaction States (MANDATORY)
+
+### Loading
+- Use skeleton loaders matching content shape
+- Pulse animation: opacity 0.4 → 1.0, duration 1.5s, ease-in-out
+- Background: var(--color-bg-secondary)
+
+### Error
+- Inline message below the element
+- Icon (circle-exclamation) + red text using var(--color-error)
+- Border change on the input/container to var(--color-error)
+
+### Empty
+- Centered illustration or icon (64-96px)
+- Heading: "No [items] yet" or similar
+- Descriptive text: one sentence explaining what will appear
+- Primary CTA button: "Create first...", "Add...", "Import..."
+
+### Hover
+- Interactive elements: subtle background shift or underline
+- Cards: shadow increase or border-color change
+- Transition: 150ms ease
+
+### Focus
+- Visible ring: 2px solid var(--color-accent), 2px offset
+- Applied to all interactive elements (buttons, inputs, links, tabs)
+- Never remove outline without providing alternative focus indicator
+
+### Disabled
+- Opacity: 0.5
+- Cursor: not-allowed
+- Title attribute explaining why the element is disabled