@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/skills/developer-like-execution/SKILL.md

@@ -0,0 +1,293 @@
+---
+model_tier: inherit
+name: developer-like-execution
+description: "Use when implementing, debugging, refactoring, or reviewing code — enforces the think → analyze → verify → execute workflow — even when the user just says 'implement X' without naming it."
+domain: process
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# developer-like-execution
+
+## When to use
+
+- Implementing features
+- Fixing bugs
+- Refactoring code
+- Analyzing unexpected behavior
+- Debugging backend or frontend issues
+- Creating or refactoring skills, rules, commands, or agent docs
+- Working with APIs, frontend, or backend logic
+
+Do NOT use when only explaining concepts or writing pure reference documentation without execution.
+
+## Goal
+
+Act like a real developer: think before acting, analyze before coding, verify before concluding.
+Avoid unnecessary trial-and-error. Minimize output, token usage, and irrelevant data.
+Develop against expected behavior, ideally test-first.
+
+## Core principles
+
+- Never start coding before understanding the affected system
+- Prefer analysis over guessing
+- Prefer targeted queries over large output dumps
+- Avoid unnecessary loops, retries, and blind experimentation
+- Always verify behavior with real execution when possible
+- Prefer tests first when expected behavior can be defined
+- If requirements are unclear, ask a precise question instead of filling gaps with assumptions
+
+## Tool priority
+
+Use the smallest, most targeted tool that gives the needed evidence.
+If a tool is available as MCP server, prefer it over manual alternatives.
+
+### Verification tool mapping
+
+| What changed | Primary tool | MCP alternative |
+|---|---|---|
+| **Backend/API endpoint** | `curl -s \| jq` | Postman MCP (if configured) |
+| **Frontend/UI** | Manual browser check | Playwright MCP (`navigate` + `snapshot`) |
+| **Execution flow/debugging** | Print statements, logs | Xdebug MCP (breakpoints, variable inspection) |
+| **CLI commands/jobs** | Run command, check exit code | — |
+| **Database** | SQL query, migration status | — |
+| **External APIs** | `Http::fake()` in tests | Postman MCP for manual checks |
+
+### Xdebug workflow (when available)
+
+If Xdebug is available (as MCP or IDE integration):
+
+1. Set breakpoints at the suspected code path
+2. Trigger the request (curl, browser, test)
+3. Inspect variables at breakpoint — don't guess values from reading code
+4. Step through to verify actual execution flow vs. assumed flow
+5. Check: is the data what you expected? Is the branch taken what you expected?
+
+Use Xdebug **before** adding print statements or debug logging.
+It's faster and leaves no cleanup work.
+
+### Playwright for frontend verification
+
+When UI changes are involved:
+
+1. Navigate to the affected page
+2. Take a snapshot of the rendered state
+3. Verify the expected elements are present and interactive
+4. Check console/network for errors
+5. Compare before/after if refactoring
+
+### Prefer targeted output
+
+- `jq` for JSON: `curl -s /api/users | jq '.[0] | {id, email}'` — never the full response
+- `rg`, `grep` for text: specific patterns, not full files
+- `head`, `tail`, `cut`, `sort`, `uniq` for narrowing results
+- `--filter`, `--json`, `--format` flags on CLI tools — always use them
+- Route lookup — Laravel `php artisan route:list --json | jq '…'`, Rails `bin/rails routes | grep users`, Express `console.log(app._router.stack)`, FastAPI `app.routes`, Symfony `bin/console debug:router`.
+- Logs — `rg "request_id=abc123" <log-dir>` — never `cat <log-file>`. Log dirs by stack: Laravel `storage/logs/`, Rails `log/`, Node `./logs/` or `journalctl`, Python `./logs/` or `journalctl`, Docker `docker compose logs <svc> --since 5m`.
+
+### Avoid large output by default
+
+Do NOT:
+
+- Dump full JSON if one field is enough
+- Load full route lists when filtering one route is enough
+- Inspect full log files when one request ID or timestamp can isolate the case
+- Re-run broad commands repeatedly without narrowing
+- Load full database tables when a WHERE clause is enough
+
+## Procedure
+
+### 1. Understand the task
+
+- Read the request carefully
+- Identify expected outcome
+- Identify affected system area
+- Identify whether the task is implementation, debugging, refactoring, or analysis
+
+### 2. Check whether requirements are complete
+
+Before acting, verify:
+
+- Expected behavior is clear
+- Acceptance criteria are clear
+- Edge cases are known
+- Affected user flow or API contract is known
+
+If important information is missing:
+
+- Stop execution planning
+- Output a precise clarification request
+- Do NOT silently assume missing requirements
+
+### 3. Analyze BEFORE acting
+
+- Read the affected files
+- Trace data flow and execution path
+- Compare with requirements, tickets, current behavior, tests, existing patterns
+- Identify likely cause and smallest correct change
+- **Consult memory — invariants and prior decisions.** Via
+  [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md), call
+  `retrieve(types=["domain-invariants"], keys=<touched paths>, limit=3)`.
+  A matching `domain-invariant` is a hard constraint — violating it = regression,
+  surface the conflict to the user before proceeding. For architectural rationale
+  (*why* the current shape exists), check the ADR index
+  [`docs/decisions/INDEX.md`](../../../docs/decisions/INDEX.md); plan around it, do
+  not silently overturn it. Cite matching `id`s / ADR numbers in the plan.
+  See [`engineering-memory-data-format`](../../../docs/guidelines/agent-infra/engineering-memory-data-format.md)
+  for the schema.
+
+### 4. Define expected behavior first
+
+Prefer test-driven or test-first development whenever practical.
+
+Before changing code, define:
+
+- What should happen
+- What should not happen
+- How success will be verified
+
+Prefer: write or update failing test first → implement against it → run tests again.
+
+If full TDD is not practical: at least write down the expected output before coding.
+
+### 5. Use targeted tools like a real developer
+
+#### Backend examples
+
+```bash
+# Route lookup — pick the project's framework
+php artisan route:list --json | jq '.[] | select(.uri == "api/users") | {method, uri, name, action, middleware}'   # Laravel
+bin/console debug:router --format=json | jq '.[] | select(.path == "/api/users")'                                  # Symfony
+bin/rails routes -g users                                                                                          # Rails
+curl -s http://localhost:3000/__routes | jq '.[] | select(.path == "/api/users")'                                  # Express custom-introspection
+curl -s http://localhost:8000/openapi.json | jq '.paths["/api/users"]'                                             # FastAPI
+
+# Config inspection
+php artisan config:show app | grep env       # Laravel
+bin/console debug:config framework            # Symfony
+bin/rails runner 'puts Rails.application.config_for(:database)'  # Rails
+
+# API inspection — extract only what you need
+curl -s http://localhost/api/users | jq '.[0] | {id, email, status}'
+curl -s http://localhost/api/users/1 | jq '{id, name, roles: [.roles[].name]}'
+
+# Recent logs — targeted, not full dump
+tail -n 200 storage/logs/laravel.log | rg "payment|timeout"             # Laravel
+tail -n 200 log/development.log | rg "payment|timeout"                   # Rails
+docker compose logs api --since 5m --no-color | rg "payment|timeout"     # any container stack
+journalctl -u myapp --since "5 min ago" | rg "payment|timeout"           # systemd
+
+# DB-state probe — targeted single record, not full table
+php artisan tinker --execute="User::where('email','x@y')->first(['id','email','status'])"   # Laravel
+bin/rails runner "p User.where(email: 'x@y').first&.slice(:id,:email,:status)"               # Rails
+bin/console doctrine:query:sql "SELECT id,email,status FROM users WHERE email='x@y' LIMIT 1" # Symfony
+psql -d mydb -c "SELECT id,email,status FROM users WHERE email='x@y' LIMIT 1"                 # raw SQL fallback
+```
+
+#### Debugging with Xdebug
+
+When available (MCP or IDE), prefer over print/log debugging:
+
+```
+1. Set breakpoint at suspected method
+2. Trigger request: curl -s http://localhost/api/endpoint
+3. Inspect variables at breakpoint
+4. Step through execution to verify actual flow
+5. Remove breakpoint when done — zero cleanup
+```
+
+#### Frontend verification with Playwright
+
+When UI is affected, verify with Playwright (MCP or direct):
+
+- Navigate to affected page
+- Snapshot the rendered state
+- Check: correct elements visible? Interactions work? Console errors?
+- Compare before/after for refactoring
+
+#### General shell filtering
+
+Use `rg` over broad grep, `jq` for JSON, `cut`/`awk`/`sort`/`uniq` to reduce noise.
+Never load full output into context when a filter gives you the answer.
+
+### 6. Form a plan
+
+- What will be changed
+- What will not be changed
+- Which test or verification proves success
+- Which tool gives the smallest useful evidence
+
+### 7. Implement
+
+- Apply focused changes only
+- Follow existing patterns
+- Avoid unrelated rewrites
+- Keep changes scoped to the actual problem
+
+### 8. Write or update tests
+
+Tests are mandatory when behavior changes or bugs are fixed.
+
+Prefer: failing test first → implementation → passing test.
+
+Test types: unit (isolated logic), feature/integration (behavior), UI (frontend), regression (bugs).
+
+If a test cannot be added: state exactly why and explain what verification replaces it.
+
+### 9. Verify with real execution (MANDATORY)
+
+Never trust "it should work" — execute and observe.
+
+| What | How | MCP alternative |
+|---|---|---|
+| Backend/API | `curl -s \| jq`, test endpoint | Postman MCP |
+| Frontend/UI | Browser check | Playwright MCP (navigate + snapshot) |
+| Execution flow | Logs, print debug | Xdebug MCP (breakpoints, step-through) |
+| CLI/Jobs | Run command, check exit code | — |
+| Database | Query result, migration status | — |
+| Skills/rules | Lint, structure check | — |
+
+If a debugging/testing tool is available as MCP server — **prefer it** over manual alternatives.
+
+### 10. Validate
+
+- Result matches requirement
+- Edge cases handled
+- Test coverage sufficient
+- No unnecessary output, retries, or brute force used
+- No important assumption remains hidden
+
+## Output format
+
+1. Task understanding
+2. Analysis summary
+3. Planned change
+4. Test strategy
+5. Implemented change
+6. Verification result
+7. Risks, open questions, or follow-up
+
+## Gotchas
+
+- The model tends to start coding too early → always analyze first
+- The model tends to over-fetch data → always reduce output first
+- The model tends to brute-force retries → prefer targeted inspection
+- The model may skip tests if the fix looks obvious → do not skip them
+- The model may fill unclear requirements with assumptions → ask instead
+
+## Do NOT
+
+- Start coding without understanding the affected system
+- Guess behavior without verifying
+- Load full datasets when partial extraction is enough
+- Rely on long trial-and-error loops
+- Skip tests when behavior changes
+- Skip real verification after changes
+- Modify unrelated parts of the system
+- Hide requirement gaps behind assumptions

package/dist/agent-src/skills/error-handling-patterns/SKILL.md

@@ -0,0 +1,139 @@
+---
+model_tier: medium
+name: error-handling-patterns
+description: "Use when picking a failure-reporting strategy — exceptions vs Result types, recoverable vs not, retry / circuit-breaker / graceful degradation — decision framework only, catalogues externalized."
+domain: engineering
+status: active
+refresh_trigger: "≥30% of cited upstream pattern catalogues become deprecated, OR a new top-2 ecosystem (Python/JS/PHP/Go/Rust) ships a paradigm-shifting standard error model"
+sunset_criterion: "When the upstream framework docs (Laravel, FastAPI, Express, Axum, Effect-TS) all carry an equivalent in-tree decision framework AND consumer projects no longer cite this skill in PR reviews for two consecutive review cycles."
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# error-handling-patterns
+
+Decision framework for picking an error-handling strategy. **Catalogues of language-specific code live upstream** (links in § Provenance) — this skill is the predicate, not the pattern library. Sunset-policy compliant: large language-specific catalogues stay in authoritative upstream docs.
+
+## When to use
+
+- Designing how a new feature, API, or service reports failure.
+- Reviewing a diff that introduces a new exception class, `Result<T, E>`, or sentinel return.
+- Debugging production noise that traces back to inconsistent error semantics.
+- Choosing between retry, circuit-breaker, fallback, and fail-fast for an external dependency.
+
+Do NOT use when:
+
+- You only need the syntax for a `try/catch` in language X — read the upstream language guide directly.
+- The failure is a single-call Laravel validation error — route to [`laravel-validation`](../laravel-validation/SKILL.md).
+- The fix is a one-line null check in existing code — route to [`bug-analyzer`](../bug-analyzer/SKILL.md).
+
+## Decision framework
+
+### Step 1 — Classify the failure
+
+```
+Failure is:
+  caller's fault (bad input, missing auth)         → reject at boundary, structured error
+  expected operational (timeout, 404, rate-limit)  → Result-type / typed return; retry-aware
+  unexpected operational (DB down, OOM, deadlock)  → exception; observability + alert
+  programmer bug (null deref, off-by-one)          → crash early; do not catch
+```
+
+### Step 2 — Pick the reporting mechanism
+
+```
+IF failure is an EXPECTED, branchable outcome the caller will route on
+  → Result type / tagged union / typed error return.
+  Forces the caller to handle it; the type system is the proof.
+
+IF failure is UNEXPECTED and most callers cannot do anything useful
+  → exception, propagated to a single boundary handler.
+  One layer (HTTP, queue, CLI) translates exceptions to user-facing errors.
+
+IF failure is UNRECOVERABLE (invariant violated, data corruption)
+  → fail loud, fail fast. No catch-and-continue.
+  Log structured context, exit / panic / 500.
+
+IF the language idiom forces one choice (Go: errors are values; Rust: Result;
+   Python/PHP/JS: exceptions)
+  → follow the idiom. Inventing a foreign mechanism is more cost than the
+    correctness it buys.
+```
+
+### Step 3 — Pick the resilience strategy
+
+```
+External call?
+  Idempotent + transient failure mode  → retry with exponential backoff + jitter, cap.
+  Non-idempotent                       → no blind retry; require an idempotency key.
+  Repeated failure across instances    → circuit breaker; open → half-open probe → close.
+  Optional functionality               → graceful degradation (cached / default / null result).
+  Required functionality               → propagate; surface to user with a recovery hint.
+```
+
+### Step 4 — Shape the error payload
+
+Every produced error must carry: `code` (stable string), `message` (human-readable), `cause` (chained), `context` (sanitized inputs), `correlation_id` (request / trace).
+
+Forbidden: secrets, raw SQL, full stack traces in user-facing surfaces, internal class names leaked through API boundaries.
+
+### Step 5 — Define the boundary
+
+Exactly **one** layer translates internal errors to the egress format (HTTP status + body, queue requeue policy, CLI exit code). Anywhere else doing this duplication is the bug.
+
+## Procedure: Apply the framework to a new feature
+
+1. **Inspect** the feature surface — identify every failure mode (each external call, each invariant, each user input class) and write it down.
+2. Run Step 1 of the decision framework against each entry; write the classification next to it.
+3. Pick reporting mechanism per Step 2; reject combinations the language idiom rejects.
+4. For each external call, run Step 3 and write down the chosen resilience strategy.
+5. Sketch the error payload shape (Step 4) and the single boundary (Step 5).
+6. Hand the sketch to a reviewer **before** coding; cite this skill.
+
+## Output format
+
+1. The failure-mode table (mode · classification · mechanism · resilience strategy).
+2. The shared error payload definition (code, message, cause, context, correlation_id).
+3. The single boundary handler (file:line) where internal → egress translation happens.
+4. The retry / circuit-breaker config (attempts, base, jitter, breaker thresholds), if any.
+
+## Gotcha
+
+- "Catch everything, log it, return null" silently destroys signal — every catch must either rethrow, translate, or recover with a written reason.
+- Retries on non-idempotent calls are the second-most-common production incident; insist on idempotency keys before allowing retry.
+- Circuit breakers without a half-open probe never close — they degrade to permanent failure.
+- Mixing Result types and exceptions in the same module is worse than picking the wrong one — pick one per module and stay in it.
+- Upstream pattern catalogues drift; trust the link, not memory. Refresh per `refresh_trigger` above.
+
+## Do NOT
+
+- Do NOT introduce a custom error mechanism that fights the language idiom.
+- Do NOT swallow exceptions — every catch has a written purpose.
+- Do NOT leak stack traces, secrets, or internal class names across the boundary.
+- Do NOT retry without backoff + jitter + cap.
+- Do NOT inline language-specific code catalogues into this skill — externalize per Sunset Policy.
+
+## Auto-trigger keywords
+
+- error handling strategy
+- exceptions vs result
+- retry pattern
+- circuit breaker
+- graceful degradation
+- error payload shape
+
+## Provenance
+
+- Adopted from: an external reference (MIT, © 2025 an external reference) — **Sunset Policy applied**: 636-line source reduced to a ~150-line decision framework; language catalogues externalized to the upstream resources below.
+- Externalized catalogues:
+  - Python: https://docs.python.org/3/tutorial/errors.html · https://docs.python.org/3/library/exceptions.html
+  - PHP / Laravel: https://laravel.com/docs/errors · https://www.php.net/manual/en/language.exceptions.php
+  - JS / TS: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling · https://www.typescriptlang.org/docs/handbook/2/narrowing.html
+  - Go: https://go.dev/blog/error-handling-and-go · https://pkg.go.dev/errors
+  - Rust: https://doc.rust-lang.org/book/ch09-00-error-handling.html
+  - Resilience patterns: https://martinfowler.com/bliki/CircuitBreaker.html · https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/
+- Cross-linked: [`defense-in-depth`](../defense-in-depth/SKILL.md), [`laravel-validation`](../laravel-validation/SKILL.md), [`bug-analyzer`](../bug-analyzer/SKILL.md), [`api-design`](../api-design/SKILL.md).
+- Provenance registry: `agents/settings/contexts/skills-provenance.yml` (entry: `error-handling-patterns`).
+- Iron-Law floor: `verify-before-complete`, `skill-quality`, `non-destructive-by-default`.

package/dist/agent-src/skills/existing-ui-audit/SKILL.md

@@ -0,0 +1,217 @@
+---
+model_tier: high
+name: existing-ui-audit
+description: "Use BEFORE writing or editing any non-trivial UI — inventories components, design tokens, shadcn primitives, and reusable patterns into state.ui_audit. Hard gate for the ui directive set."
+personas:
+  - frontend-engineer
+domain: discovery
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# existing-ui-audit
+
+> **Interplay:** this audit answers *what exists* (components, tokens,
+> primitives → `state.ui_audit`);
+> [`design-intelligence`](../design-intelligence/SKILL.md) answers *what to
+> build* (corpus-grounded style/token/typography/pattern selection).
+> Audit runs first; its reuse findings outrank corpus suggestions — never
+> let a grounded recommendation introduce a component the inventory
+> already covers.
+
+## When to use
+
+Use this skill when:
+- The dispatcher has routed work to `directive_set="ui"` (intent `ui-build` or `ui-improve`)
+- A `mixed` flow is about to enter its UI phase
+- The user asks "what UI do we already have for X?"
+
+Do NOT use when:
+- `directive_set="ui-trivial"` — the trivial path bypasses audit by precondition (≤1 file, ≤5 lines, no new component, no new state, no new dep)
+- `directive_set="backend"` — no UI surface to inventory
+- The audit findings already exist in `state.ui_audit` for this state-file (cached) — re-run only if `package.json` or `composer.json` mtime changed
+
+## Procedure: Audit the existing UI surface
+
+### 0. Inspect stack and input
+
+1. Read `state.stack.frontend` — set by `scripts/work_engine/stack/detect.py` (one of `blade-livewire-flux`, `react-shadcn`, `vue`, `plain`).
+2. Read `state.input` — the request being processed. The audit must answer: "what already exists that is similar to this request?"
+
+### 1. Enumerate components and templates
+
+| Stack | Where to look |
+|---|---|
+| `blade-livewire-flux` | `resources/views/components/`, `resources/views/livewire/`, `resources/views/partials/`, `resources/views/layouts/`, `app/View/Components/`, `app/Livewire/` |
+| `react-shadcn` | `components/`, `app/components/`, `src/components/`, `src/app/(routes)/`, plus any `app/**/page.tsx` for Next.js |
+| `vue` | `resources/js/components/`, `src/components/`, `pages/` |
+| `plain` | `resources/views/`, plus any `*.html` under `public/` |
+
+Capture each component/template as: `{path, name, kind: page|partial|component|layout, exports?: [props]}`.
+
+### 2. Identify the design system
+
+Detect markers, in order. **Stop at the first match** — projects rarely run more than one design system.
+
+| Marker | Signal | Where |
+|---|---|---|
+| Flux | `livewire/flux` in `composer.json`, `<flux:*>` tags in views | `composer.json`, grep `resources/views` |
+| shadcn/ui | `components.json` exists at repo root | `components.json` |
+| Headless UI | `@headlessui/react` or `@headlessui/vue` in `package.json` | `package.json` |
+| Radix | `@radix-ui/*` in `package.json` (without shadcn marker) | `package.json` |
+| Material/Chakra/Mantine/Ant | their package names in `package.json` | `package.json` |
+| Custom / none | none of the above match | — |
+
+### 3. Detect design tokens
+
+Write into `state.ui_audit.design_tokens` (object, never null — empty object is fine):
+
+| Source | What to extract |
+|---|---|
+| `tailwind.config.{js,ts,cjs,mjs}` | `theme.colors`, `theme.spacing`, `theme.fontFamily`, `theme.extend.*` |
+| `:root { --... }` blocks in `resources/css/`, `app/globals.css`, `src/app/globals.css` | every `--token-name: value` pair |
+| `theme.json` / `tokens.json` (any depth) | flat or nested token tree |
+| `app/css/variables.css`, `assets/scss/_tokens.scss` | SCSS `$var: value` and CSS custom properties |
+
+Group output by category: `colors`, `spacing`, `radius`, `font`, `shadow`, `breakpoint`, `other`.
+
+### 4. Detect shadcn inventory (only when `state.stack.frontend == "react-shadcn"`)
+
+Read `components.json` for the registered style + base color, then read `package.json` for `@radix-ui/*` and any locally vendored `components/ui/*.tsx` files. Write into `state.ui_audit.shadcn_inventory`:
+
+```
+{
+  version: <from package.json shadcn registry CLI version, or null>,
+  style: "default" | "new-york" | <other>,
+  base_color: "slate" | "zinc" | ...,
+  primitives: ["Button", "Dialog", "Form", "Table", ...],   // names of files in components/ui/
+  installed_radix: ["@radix-ui/react-dialog", ...]          // raw radix list
+}
+```
+
+### 5. List reusable patterns
+
+Categorize what already exists. Empty arrays are valid, never omit the keys.
+
+```
+state.ui_audit.patterns = {
+  forms: [<component path:str>, ...],     // any component with <form>, useForm, <flux:input>, <Input> + <Button type=submit>
+  tables: [...],                          // <table>, <flux:table>, DataTable, headless table primitives
+  modals: [...],                          // <flux:modal>, <Dialog>, AlertDialog, Sheet
+  empty_states: [...],                    // components matching grep "no results"|"empty"|"keine"|"nothing yet"
+  navigation: [...],                      // sidebar, breadcrumb, tabs
+  data_display: [...]                     // cards, lists, stat tiles
+}
+```
+
+### 6. Match candidates for the current input
+
+For each item in `state.ui_audit.components`, score similarity to `state.input.data` (fuzzy on filename + props/slots + co-occurring terms). Keep top 5 with `score >= 0.3`. Write into `state.ui_audit.candidates`:
+
+```
+[{path, name, score, reason: "matches 'settings' + 'toggle' in props"}, ...]
+```
+
+If `candidates` is empty, the user is building net-new. That is normal — record the empty list, do not halt.
+
+### 7. Greenfield branch
+
+If **all** are true:
+- `state.ui_audit.components` is empty
+- `state.ui_audit.design_system == "custom-or-none"`
+- `state.ui_audit.design_tokens` is empty (no Tailwind config customizations, no `:root`)
+
+then set `state.ui_audit.greenfield = true` and emit a halt:
+
+```
+> No existing UI surface detected — this looks like greenfield.
+>
+> 1. Scaffold a minimal token set + a base component primitive folder
+>    before building (recommended for projects with >1 planned screen)
+> 2. Proceed bare with Tailwind defaults (recommended for one-off prototypes)
+> 3. Point me at an external design-system reference (URL or file)
+
+**Recommendation: 1 — Scaffold tokens + primitives** — even one extra screen
+benefits from a shared base; the scaffold cost is ~10 min and saves
+re-doing every primitive on screen 2. Caveat: flip to 2 if this is a
+demo or single-page prototype that will not grow.
+```
+
+Record the user's pick in `state.ui_audit.greenfield_decision` (`scaffold` | `bare` | `external_reference`). Re-running the skill on the same state-file with `greenfield_decision` set is a no-op for the halt (audit findings stay).
+
+### 8. (Optional) Capture an a11y baseline
+
+The R4 visual-review-loop contract reads `state.ui_audit.a11y_baseline`
+when present; the review gate then filters incoming
+`state.ui_review.a11y.violations` against it so pre-existing
+violations stay informational and only NEW or CHANGED entries block
+the polish loop. Without a baseline the gate sees every violation as
+actionable — fine for greenfield, noisy for legacy surfaces.
+
+Capture the baseline when:
+
+- The audit covers components with known a11y debt the project does
+  not intend to fix in this run (legacy templates, third-party
+  embeds, vendor widgets).
+- The user says "don't block on existing a11y issues" or similar.
+
+Skip the baseline (omit the key, leave `state.ui_audit.a11y_baseline`
+unset) when:
+
+- The surface is greenfield — the review gate should treat every
+  violation as new.
+- The project's a11y posture is "zero known violations" and any
+  finding is by definition actionable.
+
+Shape (each entry must carry at least `rule` + `selector`; severity
+is optional but recommended so the review gate's severity-floor
+filter behaves the same on replay):
+
+```
+state.ui_audit.a11y_baseline = [
+  {rule: "color-contrast", selector: ".legacy-tab", severity: "moderate"},
+  {rule: "label",          selector: "form#search input[type=search]"},
+  ...
+]
+```
+
+Producer parity: the review skill that writes
+`state.ui_review.a11y.violations` MUST use the same `(rule, selector)`
+shape, otherwise the engine's de-dup will miss matches and pre-existing
+violations will surface as new findings on every run.
+
+### 9. Validate and write findings
+
+1. Verify every key in the **Output format** below is present in `state.ui_audit` (empty arrays/objects allowed; `null` only for `shadcn_inventory` outside the react-shadcn stack).
+2. Verify `state.ui_audit.greenfield == true` implies `state.ui_audit.greenfield_decision` is set.
+3. Write the full object back into the state-file. Audit completes with outcome `done` — the dispatcher's audit gate now passes.
+
+## Output format
+
+1. **`state.ui_audit.components`** — array of component/template descriptors (path, name, kind, exports)
+2. **`state.ui_audit.design_system`** — single string identifying the dominant system or `custom-or-none`
+3. **`state.ui_audit.design_tokens`** — object grouped by category (colors, spacing, radius, font, shadow, breakpoint, other)
+4. **`state.ui_audit.shadcn_inventory`** — object with version, style, base_color, primitives (only when stack is `react-shadcn`; `null` otherwise)
+5. **`state.ui_audit.patterns`** — object with forms, tables, modals, empty_states, navigation, data_display arrays
+6. **`state.ui_audit.candidates`** — top-5 similarity matches for the current input (may be empty)
+7. **`state.ui_audit.greenfield`** — boolean; when true, `greenfield_decision` MUST also be set before the dispatcher advances
+8. **`state.ui_audit.a11y_baseline`** *(optional)* — array of `{rule, selector, severity?}` entries documenting pre-existing a11y violations the review gate should treat as informational. Omit the key entirely when no baseline applies; do not write `[]` for "I checked and there are none" — that disables the gate's filter for every future run.
+
+## Gotcha
+
+- The model tends to skip the audit and start designing straight from the request — the dispatcher gate at `directives/ui/audit.py` enforces "no design without audit findings". Never treat this skill as optional for non-trivial UI.
+- The model tends to misidentify a single Tailwind utility as a "design token" — tokens come from the config or `:root`, not from class strings in templates.
+- Don't assume a Radix-only `package.json` means shadcn — shadcn requires `components.json` at repo root.
+- `state.ui_audit.shadcn_inventory.version` is often missing; the shadcn CLI does not always pin itself in `package.json`. Record `null` rather than guessing.
+- Greenfield is detected, not assumed — a project with one Blade layout and no components is still greenfield only if tokens AND design system markers AND components are all empty.
+- Re-running the skill on a stale state-file: cache by `(composer.json mtime, package.json mtime)`; if either changed, re-audit and overwrite.
+
+## Do NOT
+
+- Do NOT advance to `directives/ui/design.py` or `apply.py` if `state.ui_audit` is empty.
+- Do NOT advance to design or apply if `state.ui_audit.greenfield == true` and `state.ui_audit.greenfield_decision` is unset.
+- Do NOT silently skip the greenfield halt because "Tailwind has defaults" — the user picks the path explicitly.
+- Do NOT write paths outside the project root into the inventory.
+- Do NOT rewrite `state.ui_audit` once it is populated unless re-detection is triggered by mtime change — design and apply read from it.