@phuc1403/musketeer 0.1.0

package/template/.claude/skills/architecture-characteristic-writer/references/characteristics-catalog.md

@@ -0,0 +1,106 @@
+# Architecture Characteristics Catalog
+
+Based on Mark Richards' Architecture Characteristics Worksheet (DeveloperToArchitect.com, March 2024) and "Software Architecture" reference material.
+
+## Common Architecture Characteristics
+
+| Characteristic | Definition | Related |
+|---|---|---|
+| **performance** | Time it takes for system to process a business request | a |
+| **responsiveness** | Time it takes to get a response to the user | a |
+| **availability** | Uptime of a system; usually measured in 9's (e.g., 99.9%) | b |
+| **fault tolerance** | When fatal errors occur, other parts of system continue to function | b |
+| **scalability** | System capacity and growth over time; as users/requests increase, responsiveness, performance, and error rates remain constant | c |
+| **elasticity** | System can expand and respond quickly to unexpected or anticipated extreme loads (e.g., 20 to 250,000 users instantly) | c |
+| **data integrity** | Data across the system is correct and there is no data loss | d |
+| **data consistency** | Data across the system is in sync and consistent across databases and tables | d |
+| **adaptability** | Ease in which system can adapt to changes in environment and functionality | e |
+| **extensibility** | Ease in which system can be extended with additional features and functionality | e |
+| **concurrency** | Ability to process simultaneous requests, usually in the same order received; implied when scalability and elasticity are supported | |
+| **interoperability** | Ability to interface and interact with other systems to complete a business request | |
+| **deployability** | Amount of ceremony involved with releasing software, frequency of releases, and overall risk of deployment | |
+| **testability** | Ease of and completeness of testing | |
+| **abstraction** | Level at which parts of system are isolated from other parts (internal and external interactions) | |
+| **workflow** | Ability to manage complex workflows requiring multiple parts (services) to complete a business request | |
+| **configurability** | Ability to support multiple configurations, custom on-demand configurations and configuration updates | |
+| **recoverability** | Ability to start where it left off in the event of a system crash | |
+
+**Related pairs (a/b):** Some systems only need one, others may need both.
+
+## Implicit Characteristics (Always Considered)
+
+| Characteristic | Definition |
+|---|---|
+| **feasibility (cost/time)** | Taking into account timeframes, budgets, and developer skills when making architectural choices; tight timeframes and budgets make this a driving characteristic |
+| **security** | Ability to restrict access to sensitive information or functionality |
+| **maintainability** | Level of effort required to locate and apply changes to the system |
+| **observability** | Ability to make available and stream metrics such as overall health, uptime, response times, performance, etc. |
+
+Implicit characteristics become **driving** characteristics if they are critical concerns.
+
+## Composite Architecture Characteristics
+
+| Composite | Components |
+|---|---|
+| **agility** | maintainability + testability + deployability |
+| **reliability** | availability + testability + data integrity + data consistency + fault tolerance |
+
+## Category Groupings (from reference material)
+
+### Process Characteristics
+modularity, testability, agility, deployability, decouple-ability, extensibility
+
+### Structural Characteristics
+security, maintainability, extensibility, portability, localization
+
+### Operational Characteristics
+scalability, recoverability, robustness, performance, reliability/safety, availability
+
+### Cross-cutting Characteristics
+security, legal, authentication/authorization, privacy, accessibility, usability
+
+## Guiding Questions by Category
+
+### Operational
+- How many concurrent users are expected? Peak vs average?
+- What uptime SLA is required? (99.9%? 99.99%?)
+- Is traffic steady or bursty? (e.g., seasonal spikes, flash sales)
+- How fast must the system respond? (ms? seconds?)
+- What happens if the system goes down? Business impact?
+
+### Structural
+- How frequently will new features be added?
+- How many external systems need integration?
+- How large is the development team? Multiple teams?
+- How often will the system be deployed?
+- Is the codebase expected to grow significantly?
+
+### Cross-cutting
+- Does the system handle sensitive/personal data?
+- Are there compliance requirements? (GDPR, HIPAA, PCI-DSS, SOC2)
+- Does it need to work across regions/languages?
+- Who are the end users? Technical sophistication?
+- Are there legal/regulatory constraints?
+
+### Environment & Feasibility
+- Startup (agility-first) or enterprise (stability-first)?
+- Budget and timeline constraints?
+- Team expertise — what technologies are they comfortable with?
+- Existing infrastructure that must be leveraged?
+
+## Custom Characteristics
+
+If no existing characteristic fits, create a custom one:
+- Name MUST end in `-ility` (e.g., `auditability`, `portability`, `learnability`)
+- Provide a clear, one-sentence definition following the pattern: "The ability/ease/level of [what the system can do]"
+- Assign to the most appropriate category
+- Document why existing characteristics don't cover this concern
+
+### Examples of Custom Characteristics
+| Characteristic | Definition | Category |
+|---|---|---|
+| **auditability** | The ability to trace and record all system actions for compliance review | Cross-cutting |
+| **portability** | The ease in which the system can be moved to a different environment or platform | Structural |
+| **learnability** | The ease in which new developers can understand and contribute to the system | Process |
+| **debuggability** | The ease in which issues can be identified and diagnosed in production | Operational |
+| **reproducibility** | The ability to consistently reproduce system behavior across environments | Process |

package/template/.claude/skills/code-review/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: code-review
+description: "Review code quality with adversarial rigor. Supports input modes: pending changes, PR number, commit hash, codebase scan. Always-on red-team analysis finds security holes, false assumptions, and failure modes."
+argument-hint: "[#PR | COMMIT | --pending | codebase [parallel]]"
+metadata:
+  author: claudekit
+  version: "3.0.0"
+---
+
+# Code Review
+
+Adversarial, evidence-based code review. Two stages: **Quality** then **Adversarial** (red-team). Be honest, brutal, concise. **YAGNI / KISS / DRY.** Verify before claiming; evidence before assertions.
+
+## 1. Resolve the input
+
+Parse arguments, first match wins, then get the diff:
+
+| Argument | Mode | Diff command |
+|----------|------|--------------|
+| `#123` / PR URL | PR | `gh pr diff <n>` (+ `gh pr view <n> --json title,body,baseRefName` for intent) |
+| `[0-9a-f]{7,40}` | Commit | `git show <sha>` |
+| `--pending` | Pending | `git diff HEAD` (staged + unstaged) — ask user for intent |
+| *(none, changes in context)* | Default | recent changes already in context |
+| `codebase` / `codebase parallel` | Codebase | full-codebase scan (see below) |
+| *(none, no context)* | Prompt | `AskUserQuestion`: pending / PR / commit / codebase |
+
+Errors: PR not found → "PR #N not found"; bad SHA → "commit not found — is it pushed?"; empty `git diff HEAD` → "no pending changes". Ambiguous PR-vs-commit → prefer PR, note the assumption.
+
+Always review **added/modified lines** (`+` in diff). Pre-existing code is out of scope unless the change makes it newly broken.
+
+## 2. Stage 1 — Quality review
+
+If the work implemented a plan/spec, first confirm compliance: list each requirement, mark PASS / MISSING / EXTRA. Missing requirements fail the review before quality matters — well-written code that doesn't match the spec is still wrong.
+
+Then review the diff for: correctness, standards, edge cases (null/empty/boundary/error paths), performance, and reuse/simplification. Dispatch a `code-reviewer` subagent for non-trivial diffs; review inline for small ones. Each finding: `file:line`, problem, fix.
+
+**Checklists (optional, for pre-landing / security audits):** detect project type — `package.json` with react/vue/next/etc → load `references/checklists/web-app.md`; `src/routes|api|controllers` → `references/checklists/api.md`; always load `references/checklists/base.md`. Run critical categories first (blocking), informational second. Honor the suppressions list at the bottom of `base.md`.
+
+## 3. Stage 2 — Adversarial review (always-on)
+
+**Skip only when ALL true:** ≤2 files changed, ≤30 lines, no security-sensitive files (auth/crypto/input-parsing/SQL/env), no new dependencies. When skipped, note `Adversarial: skipped (below threshold)`.
+
+**Never skip** when auth/middleware/security/crypto, a lockfile, env vars, DB schema, or an API route changed.
+
+Run the red-team pass per **`references/adversarial-review.md`** — spawn an adversarial `code-reviewer` whose only job is to break the code (security holes, false assumptions, failure modes, races, data corruption, supply chain, observability gaps). Then adjudicate each finding **Accept / Reject / Defer** with a reason — no silent dismissals; benefit of the doubt goes to the adversary. Critical accepted findings block merge. On re-review, pass only the fix diff.
+
+## Codebase modes
+
+- **`codebase`** — explore relevant files, dispatch parallel `code-reviewer` subagents by area, then run the always-on adversarial pass over the full scope. Report combined findings.
+- **`codebase parallel`** — first enumerate edge cases exhaustively (null, boundary, error, race, validation, security, leaks, untested paths), group into ≤6 categories, dispatch one `code-reviewer` per category to **verify** them, aggregate handled/unhandled, then run the adversarial pass.
+
+## Bottom line
+
+Resolve what you're reviewing → quality pass → adversarial pass (scope-gated) → adjudicate → fix Critical, then claim only with verification evidence.

package/template/.claude/skills/code-review/references/adversarial-review.md

@@ -0,0 +1,223 @@
+---
+name: adversarial-review
+description: Stage 3 red-team review that actively tries to break code — finds security holes, false assumptions, failure modes, race conditions. Spawns adversarial reviewer subagent with destructive mindset. Includes scope gate for trivial changes.
+---
+
+# Adversarial Review (Stage 3)
+
+Runs after every Stage 2 (Code Quality) pass. Subject to scope gate below.
+
+## Scope Gate
+
+Skip adversarial review when ALL of these are true:
+- Changed files <= 2
+- Lines changed <= 30
+- No security-sensitive files touched (auth, crypto, input parsing, SQL, env)
+- No new dependencies added
+
+When skipped, note: `Adversarial: skipped (below threshold)` in review output.
+
+**NEVER skip when:**
+- Any file in: `auth/`, `middleware/`, `security/`, `crypto/`
+- `package.json`, `package-lock.json`, or lockfile changed
+- Environment variables added/changed
+- Database schema modified
+- API route added/changed
+
+## Mindset
+
+> "You are hired to tear apart the implementer's work. Your job is to find every way this code can fail, be exploited, or produce incorrect results. Assume the implementer made mistakes. Prove it."
+
+This is NOT a standard code review. Standard reviews check if code meets requirements. Adversarial review assumes requirements are met and asks: **"How can this still break?"**
+
+## What to Attack
+
+### Security Holes
+- Injection vectors (SQL, command, XSS, template)
+- Auth bypass paths (missing checks, privilege escalation)
+- Secrets exposure (logs, error messages, stack traces)
+- Input trust boundaries (user input treated as safe)
+- SSRF, path traversal, deserialization attacks
+
+### False Assumptions
+- "This will never be null" -- prove it can be
+- "This list always has elements" -- find the empty case
+- "Users always call A before B" -- find the out-of-order path
+- "This config value exists" -- find the missing env var
+- "This third-party API always returns 200" -- find the failure mode
+- "This API shape won't change" -- find the breaking caller
+
+### Failure Modes & Resource Exhaustion
+- What happens when disk is full?
+- What happens when network times out mid-operation?
+- What happens when the database connection drops during a transaction?
+- Unbounded allocations from user-controlled input
+- Missing timeouts on external calls
+- Event loop blocking (sync operations in async context)
+- Connection/handle leaks on error paths
+- Regex catastrophic backtracking (ReDoS)
+
+### Race Conditions
+- Shared mutable state without locks
+- Time-of-check-to-time-of-use (TOCTOU)
+- Async operations with implicit ordering assumptions
+- Cache invalidation during concurrent writes
+
+### Data Corruption
+- Partial writes on failure (no transaction/rollback)
+- Type coercion surprises (string "0" as falsy)
+- Floating point comparison for equality
+- Timezone-naive datetime operations
+
+### Supply Chain & Dependencies
+- New dependencies: postinstall scripts, maintainer reputation, bundle size
+- Lockfile changes: version drift, removed integrity hashes
+- Transitive deps pulling in known-vulnerable packages
+
+### Observability Blind Spots
+- Swallowed errors (`catch {}` with no log)
+- Missing structured context in error logs
+- PII in log output
+
+## Process
+
+### 1. Spawn Adversarial Reviewer
+
+Dispatch `code-reviewer` subagent with adversarial prompt:
+
+```
+You are an adversarial code reviewer. Your ONLY job is to find ways this code
+can fail, be exploited, or produce incorrect results.
+
+DO NOT praise the code. DO NOT note what works well.
+ONLY report problems. If you find nothing, say "No findings" -- but try harder first.
+
+Focus on ADDED/MODIFIED lines (+ prefix in diff). Pre-existing code is out of scope
+unless the change makes it newly exploitable.
+
+Context (read for understanding, DO NOT review):
+{CONTEXT_FILES}
+
+Runtime: {RUNTIME} (e.g., Node.js single-threaded, browser, serverless)
+Framework: {FRAMEWORK} (e.g., Express with global error handler at app.ts:45)
+
+Review this diff:
+{DIFF}
+
+Changed files: {FILES}
+
+Attack vectors to check:
+1. Security holes (injection, auth bypass, secrets exposure)
+2. False assumptions (null, empty, ordering, config, API contracts)
+3. Failure modes + resource exhaustion (timeouts, leaks, unbounded input)
+4. Race conditions (shared state, TOCTOU, async ordering)
+5. Data corruption (partial writes, type coercion, encoding)
+6. Supply chain (new deps, lockfile changes, transitive vulns)
+7. Observability (swallowed errors, missing logs, PII in output)
+
+For each finding, report:
+- SEVERITY: Critical / Medium / Low
+- CATEGORY: Security / Assumption / Failure / Race / Data / Supply / Observability
+- LOCATION: file:line
+- ATTACK: How to trigger the problem
+- IMPACT: What happens when triggered
+- FIX: Describe the fix approach (e.g., "add null check before line 42").
+  Do NOT write implementation code -- the implementer has full context.
+```
+
+**If adversarial produces >10 findings on <100 lines changed:** likely too aggressive. Batch-reject noise, deep-review only Critical/Medium.
+
+### 2. Adjudicate Findings
+
+Main agent reviews each adversarial finding and assigns verdict:
+
+| Verdict | Meaning | Action |
+|---------|---------|--------|
+| **Accept** | Valid flaw, reproducible or clearly reasoned | Must fix before merge |
+| **Reject** | False positive, already handled, or impossible path | Document why, no action |
+| **Defer** | Valid but low-risk, tracked for later | Create GitHub issue for tracking |
+
+**Rules:**
+- Every finding gets a verdict -- no silent dismissals
+- Critical findings: Accept unless you can PROVE false positive
+- Benefit of doubt goes to the adversary (safer to fix than to dismiss)
+- If >50% of findings are Rejected, the adversary was too aggressive -- but still report all
+
+**Calibration examples:**
+
+| Verdict | Example | Reasoning |
+|---------|---------|-----------|
+| Accept | "SQL injection via string interpolation in query builder" | Clearly exploitable, concrete path shown |
+| Reject | "Missing null check on config.apiUrl" | Config loaded at startup with schema validation (see config.ts:12), cannot be null at runtime |
+| Defer | "No rate limiting on POST /api/upload" | Valid concern but internal-only tool currently; track for public exposure |
+
+### 3. Report Format
+
+```
+## Adversarial Review -- Stage 3
+
+### Summary
+- Findings: N total (X Critical, Y Medium, Z Low)
+- Accepted: A (must fix)
+- Rejected: B (false positive)
+- Deferred: C (tracked via GitHub issues)
+
+### Accepted Findings (Must Fix)
+
+#### [1] SEVERITY -- CATEGORY -- file:line
+**Attack:** How to trigger
+**Impact:** What happens
+**Fix:** Approach description
+**Verdict:** Accept -- [reason]
+
+### Rejected Findings
+
+#### [N] SEVERITY -- CATEGORY -- file:line
+**Attack:** Claimed vector
+**Verdict:** Reject -- [reason this is a false positive]
+
+### Deferred Findings
+
+#### [N] SEVERITY -- CATEGORY -- file:line
+**Attack:** How to trigger
+**Verdict:** Defer -- [reason] → GitHub issue #X
+```
+
+### 4. Fix Accepted Findings
+
+- Critical: Block merge. Fix immediately via `/fix` or manual edit.
+- Medium: Fix before merge if feasible. Defer only with explicit user approval.
+- Low: Track. Fix in follow-up if pattern repeats.
+
+### Re-review Optimization
+
+On fix cycles (re-running after accepted findings were fixed):
+- Only pass the FIX diff to adversarial, not the full original diff
+- Verify accepted findings are resolved
+- Check for regression: did the fix introduce new issues?
+
+## Integration with Pipeline
+
+```
+Stage 1 (Spec) → PASS
+  ↓
+Stage 2 (Quality) → PASS
+  ↓
+Scope gate → below threshold? → skip (note in report)
+  ↓ (above threshold)
+Stage 3 (Adversarial) → findings
+  ├─ 0 Accepted → PASS → proceed
+  ├─ Accepted Critical → BLOCK → fix → re-run Stage 3 (fix diff only)
+  └─ Accepted Medium/Low only → fix or defer → proceed
+```
+
+**Task pipeline update:** When using task-managed reviews, adversarial review gets its own task between "Review implementation" and "Fix critical issues".
+
+## What This Is NOT
+
+- NOT a style review (Stage 2 handles that)
+- NOT a spec compliance check (Stage 1 handles that)
+- NOT dependency graph analysis or import tracing (scout handles that)
+- NOT a general "suggestions for improvement" pass
+
+This is a focused, hostile attempt to break the code. If the code survives, it's ready to ship.

package/template/.claude/skills/code-review/references/checklists/api.md

@@ -0,0 +1,52 @@
+# API Review Checklist (Overlay)
+
+Additive to `base.md`. Apply when project exposes REST/GraphQL/gRPC APIs.
+
+## Detection
+
+Apply this overlay when any of these are true:
+- Project has route definitions (Express, FastAPI, NestJS, Django, Rails, Go chi/gin)
+- OpenAPI/Swagger spec file exists
+- `src/routes/`, `src/api/`, `src/controllers/` directories
+- GraphQL schema files in the diff
+
+---
+
+## Pass 1 — CRITICAL (additions to base)
+
+### Auth & Rate Limiting
+- Public endpoints missing rate limiting (login, registration, password reset)
+- API keys or tokens exposed in URL query parameters (use headers)
+- Missing auth middleware on new routes
+- Batch/bulk endpoints without per-item authorization checks
+
+### Input Validation
+- Request body accepted without schema validation (missing Zod, Joi, Pydantic, etc.)
+- Mass assignment: entire request body spread into database model
+- File upload without size/type restrictions
+- Array inputs without length limits (DoS via large payloads)
+
+### Data Exposure
+- Sensitive fields in API responses (password hashes, internal IDs, tokens)
+- Stack traces or internal error details in production error responses
+- Verbose error messages that leak schema/implementation details
+
+---
+
+## Pass 2 — INFORMATIONAL (additions to base)
+
+### API Design
+- List endpoints without pagination (LIMIT/OFFSET or cursor-based)
+- Missing consistent error response format across endpoints
+- Inconsistent naming conventions (camelCase vs snake_case in same API)
+- Missing request/response content-type headers
+
+### Observability
+- New endpoints without logging/metrics
+- Error paths that swallow exceptions silently
+- Missing correlation/request IDs for tracing
+
+### Versioning & Compatibility
+- Breaking changes to existing response shapes without version bump
+- Removed fields without deprecation notice
+- Changed field types (string → number) in existing responses

package/template/.claude/skills/code-review/references/checklists/base.md

@@ -0,0 +1,100 @@
+# Base Review Checklist
+
+Universal checklist for all project types. Two-pass model: critical (blocking) + informational (non-blocking).
+
+## Instructions
+
+Review `git diff origin/main` for the issues below. Be specific — cite `file:line` and suggest fixes. Skip anything that's fine. Only flag real problems.
+
+**Output format:**
+
+```
+Pre-Landing Review: N issues (X critical, Y informational)
+
+**CRITICAL** (blocking):
+- [file:line] Problem description
+  Fix: suggested fix
+
+**Issues** (non-blocking):
+- [file:line] Problem description
+  Fix: suggested fix
+```
+
+If no issues: `Pre-Landing Review: No issues found.`
+
+Be terse. One line problem, one line fix. No preamble.
+
+---
+
+## Pass 1 — CRITICAL (blocking)
+
+### Injection & Data Safety
+- String interpolation in SQL/database queries (even with type casting — use parameterized queries)
+- Unsanitized user input written to database or rendered in HTML
+- Raw HTML output from user-controlled data (`innerHTML`, `dangerouslySetInnerHTML`, `html_safe`, `raw()`, `| safe`)
+- Command injection via string concatenation in shell commands (use argument arrays)
+- Path traversal via user input in file operations
+
+### Race Conditions & Concurrency
+- Read-check-write without atomic operations (check-then-set should be atomic WHERE + UPDATE)
+- Find-or-create without unique database constraint (concurrent calls create duplicates)
+- Status transitions without atomic WHERE old_status + UPDATE new_status
+- Shared mutable state accessed without synchronization
+
+### Security Boundaries
+- Missing authentication checks on new endpoints/routes
+- Privilege escalation paths (user can access/modify another user's data — IDOR)
+- Secrets in logs, error responses, or client-side code
+- LLM/AI output written to database or used in queries without validation
+- JWT/token comparison using `==` instead of constant-time comparison
+
+### Auth & Access Control
+- New API endpoints without auth middleware
+- Missing authorization check (authenticated but not authorized)
+- Admin-only operations accessible to regular users
+- Session fixation or token reuse vulnerabilities
+
+---
+
+## Pass 2 — INFORMATIONAL (non-blocking)
+
+### Conditional Side Effects
+- Code branches on condition but forgets side effect on one branch (e.g., sets status but not associated data)
+- Log messages claiming action happened but action was conditionally skipped
+
+### Magic Numbers & String Coupling
+- Bare numeric literals used in multiple files — should be named constants
+- Error message strings used as query filters elsewhere (grep for the string)
+
+### Dead Code & Consistency
+- Variables assigned but never read
+- Stale comments describing old behavior after code changed
+- Import/require statements for unused modules
+
+### Test Gaps
+- Missing negative-path tests (error cases, validation failures)
+- Assertions on type/status but not side effects (e.g., checks status but not that email was sent)
+- Missing integration tests for security enforcement (auth, rate limiting, access control)
+
+### Type Coercion at Boundaries
+- Values crossing language/system boundaries where type could change (string vs number)
+- Hash/digest inputs that don't normalize types before serialization
+
+### Performance
+- O(n*m) lookups in views/templates (array search inside loops — use hash/map lookup)
+- Missing pagination on list endpoints returning unbounded results
+- N+1 queries: loading associations inside loops without eager loading
+- Unbounded queries without LIMIT
+
+---
+
+## Suppressions — DO NOT flag these
+
+- Redundancy that aids readability (e.g., `present?` redundant with length check)
+- "Add comment explaining why this threshold was chosen" — thresholds change, comments rot
+- "This assertion could be tighter" when assertion already covers the behavior
+- Consistency-only changes (wrapping a value to match how another constant is guarded)
+- Harmless no-ops (e.g., `.filter()` on array that never contains the filtered value)
+- ANYTHING already addressed in the diff being reviewed — read the FULL diff before commenting
+- Style/formatting issues (use a linter for that)
+- "Consider using X instead of Y" when Y works fine

package/template/.claude/skills/code-review/references/checklists/web-app.md

@@ -0,0 +1,54 @@
+# Web App Review Checklist (Overlay)
+
+Additive to `base.md`. Apply when project has frontend framework (React, Vue, Svelte, Next.js, etc.).
+
+## Detection
+
+Apply this overlay when any of these are true:
+- `package.json` has `react`, `vue`, `svelte`, `next`, `nuxt`, `angular` dependency
+- Project has `src/pages/`, `src/app/`, `src/components/`, `src/views/` directories
+- HTML/JSX/TSX/Vue files in the diff
+
+---
+
+## Pass 1 — CRITICAL (additions to base)
+
+### XSS
+- `innerHTML` assignment from any non-static source
+- Template literals interpolated into DOM without escaping
+- URL parameters rendered without sanitization
+- `<a href={userInput}>` without protocol validation (javascript: protocol)
+- Server-rendered user content without HTML entity encoding
+
+### CSRF
+- State-changing endpoints (POST/PUT/DELETE) without CSRF token verification
+- Cookie-based auth without SameSite attribute
+- Form submissions to external URLs
+
+### N+1 Queries (server-rendered views)
+- Database queries inside loops rendering lists
+- Missing eager loading for associations rendered in views/pages
+- Sequential API calls that could be batched
+
+---
+
+## Pass 2 — INFORMATIONAL (additions to base)
+
+### Frontend Performance
+- Inline `<style>` blocks in components re-parsed every render
+- Missing `key` prop on list items
+- Large bundle imports that could be lazy-loaded (e.g., full lodash instead of lodash/get)
+- Images without width/height causing layout shift
+- Missing `loading="lazy"` on below-fold images
+
+### Accessibility
+- Interactive elements without keyboard support (onClick without onKeyDown)
+- Missing `alt` text on images
+- Form inputs without associated labels
+- Color-only indicators (no text/icon fallback)
+- Missing ARIA attributes on custom interactive components
+
+### Responsive / Layout
+- Fixed pixel widths that break on mobile
+- Missing viewport meta tag
+- Overflow hidden cutting off content on small screens

package/template/.claude/skills/context-map/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: context-map
+description: Write or update a DDD Context Map in CML (Context Mapper Language).
+---
+
+<what-to-do>
+
+Given a Context Map intent, produce or update the single `docs/bounded-contexts/context-map.cml` (one map per system, spanning every BC). The four intent shapes (use these exact labels):
+
+- **`BC`** — name, optional `type` / `domainVisionStatement` / `responsibilities`. Adds it to `contains` and appends a `BoundedContext <Name>` declaration.
+- **`peer-context`** — same shape as `BC`, named after an external system. Used for every `external_system` declared on the EventStorming wall.
+- **`relationship`** — upstream BC, downstream BC, shape (Partnership / Shared-Kernel / Upstream-Downstream / Customer-Supplier), role brackets, optional name, optional `{ implementationTechnology, downstreamRights, exposedAggregates }` attributes.
+- **`Aggregate`** — name + owning BC. Adds `Aggregate <Name>` inside the BC's `{ … }` body, creating the body if it was empty. Required when the name appears in any relationship's `exposedAggregates`. Maintain 1:1 sync with the wall JSON: every entry in `aggregates[]` on the BC's `docs/bounded-contexts/{bc}/event-storming.json` (or the general `docs/event-storming.json` before segregation) has a matching `Aggregate <Name>` inside its owning BC, written the same turn.
+
+Workflow:
+
+1. **Locate or scaffold the file.** If it doesn't exist, scaffold a minimal `ContextMap SystemContextMap { type = SYSTEM_LANDSCAPE state = AS_IS contains <BCs> }` block followed by one `BoundedContext <Name>` declaration per BC in `contains`. Use [example.cml](./example.cml) as a **syntax reference**, not a literal copy — its DDDSample BCs are illustrative.
+2. **Write the requested change.** Per intent shape: add the `contains` entry + `BoundedContext` declaration (`BC` / `peer-context`); add the relationship line (`relationship`); add `Aggregate <Name>` inside the owning BC's body (`Aggregate`). For every BC newly referenced anywhere, append a `BoundedContext <Name>` declaration — without it Xtext linker fails with `Couldn't resolve reference to BoundedContext '<Name>'`.
+3. **Lint.** A PostToolUse hook auto-runs Context Mapper validation on every `.cml` edit. Treat any `ERROR …` line in its output as blocking; `WARNING …` lines (e.g. ACL on Customer-Supplier per Semantic Rule #7) are allowed when intentional.
+4. **Hand-audit.** `cm validate` is necessary but not sufficient — see Limitations below. Audit three things by hand before reporting success: (i) every `exposedAggregates` name lives in the upstream BC of its relationship; (ii) every role bracket combo respects the 10 Semantic Rules; (iii) no Aggregate name is duplicated across BCs unless deliberate.
+5. **Report.** State the line(s) written and PASS/FAIL of `cm validate` (on FAIL, paste only the first `ERROR` line and where to fix). Call out anything the hand-audit flagged.
+
+If a piece of the intent is ambiguous (e.g. which side is upstream, which roles to use), ask the caller — don't invent. The skill's job is mechanical correctness, not design judgement.
+
+</what-to-do>
+
+<supporting-info>
+
+## File location
+
+`docs/bounded-contexts/context-map.cml` — a single map for the whole system, sitting beside the per-BC folders.
+
+## Reference (load lazily by intent shape)
+
+The reference is an Obsidian folder with `[[wikilinks]]` between files. Load in tiers — don't front-load everything:
+
+- **Always** (first invocation this session):
+  - `./reference/Context Map.md` — top-level grammar, relationship arrows, role brackets, attributes.
+  - `./reference/Semantic Rules.md` — the 10 combination rules.
+- **When writing a `BC` or `peer-context`** with non-trivial attributes:
+  - `./reference/Bounded Context/Bounded Context.md` — attribute docs (`implements`, `refines`, `domainVisionStatement`, `responsibilities`, `type`, `knowledgeLevel`, `businessModel`, `evolution`, `realizes`).
+- **When writing a `relationship`**:
+  - `./reference/Bounded Context Relationship/Bounded Context Relationship.md` — per-pattern pages (Partnership, Shared Kernel, Customer-Supplier, OHS, PL, CF, ACL).
+- **When writing an `Aggregate` or setting `exposedAggregates`**:
+  - `./reference/Aggregate/Aggregate.md` — Aggregate composition.
+- **When a BC uses `implements` / `refines`**:
+  - `./reference/Domain/Domain.md` — Domain / Subdomain framing.
+
+## Linting (mandatory before reporting success)
+
+Validation runs automatically via the PostToolUse `validate-cml-hook` on every `.cml` edit (Context Mapper CLI, self-bootstrapped from Maven on first run; requires Java 8+).
+
+**CML-specific failure modes to recognise:**
+
+- `Couldn't resolve reference to BoundedContext '<Name>'` + `The Bounded Context 'null' is not part of the Context Map.` — a name in `contains` or a relationship line has no `BoundedContext <Name>` declaration. Fix: append the missing declaration.
+- `ERROR in null on line N: no viable alternative at input '<token>'` — parse error. Re-read the grammar at the reported line.
+
+## Limitations of `cm validate` — hand-audit is required after it passes
+
+Confirmed-misses (tested against 6.12.0):
+
+| Catches                                                   | Misses                                                                                                                                                                       |
+| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Parse errors with line numbers                            | Semantic Rule violations from `Semantic Rules.md` (OHS on Customer-Supplier #6, CF on Customer-Supplier #5, ACL/CF/OHS/PL on symmetric relationships #4, etc.)               |
+| Linker errors when they fire                              | Duplicate Aggregate names across different BCs (CML scopes `exposedAggregates` by upstream BC, so duplicates resolve rather than collide — but they're semantically muddled) |
+| Resource-level diagnostics from `cmlResource.getErrors()` | Anything that needs the full Xtext `IResourceValidator` chain (Eclipse/VSCode extension surfaces these; the CLI does not)                                                    |
+
+After `cm validate` prints "without errors", audit by hand:
+
+1. Every `exposedAggregates` name resolves to an Aggregate declared inside the **upstream** BC of that relationship line.
+2. Every role bracket combo is allowed by the 10 Semantic Rules (consult `./reference/Semantic Rules.md`).
+3. No Aggregate name is duplicated across BCs unless deliberate.
+
+For deeper validation, open the file in VSCode with the Context Mapper extension installed.
+
+## Glossary
+
+Same `CONTEXT.md` convention as the EventStorming skills. Challenge BC names against the glossary before writing. If a relationship introduces a novel domain term, add a one-sentence definition in `CONTEXT.md` the same turn.
+
+</supporting-info>