@kennethsolomon/shipkit 3.19.0 → 3.21.0

package/skills/sk:e2e/SKILL.md

@@ -6,9 +6,7 @@ model: sonnet
 
 # /sk:e2e
 
-E2E behavioral verification — the final quality gate before `/sk:finish-feature`. Runs after Review to verify the complete, reviewed, secure implementation works end-to-end from a user's perspective.
-
-**Hard gate:** all scenarios must pass. Zero failures allowed.
+E2E behavioral verification — the final quality gate before `/sk:finish-feature`. Runs after Review. **Hard gate:** all scenarios must pass. Zero failures allowed.
 
 ## Allowed Tools
 
@@ -18,31 +16,25 @@ Bash, Read, Glob, Grep
 
 ### 1. Read Context
 
-Read these files to understand what to test:
+Read to understand what to test:
 - `tasks/todo.md` — planned features and acceptance criteria
 - `tasks/findings.md` — design decisions and expected behaviors
 - `tasks/progress.md` — implementation notes
 
 ### 2. Detect E2E Runner
 
-Check which runner is available, in priority order:
-
 **Priority 1 — Playwright (preferred)**
 
 ```bash
 ls playwright.config.ts 2>/dev/null || ls playwright.config.js 2>/dev/null
 ```
 
-If a Playwright config exists → use Playwright CLI (Step 3a). This is the preferred path because:
-- Uses headless Chromium (no conflict with system Chrome)
-- No additional global install required (`@playwright/test` in devDeps)
-- Test files in `e2e/` or `tests/e2e/` are picked up automatically
-- `webServer` in `playwright.config.ts` auto-starts the dev server
+If config exists → use Playwright CLI (Step 3a). Advantages: headless Chromium, no system Chrome conflict, `@playwright/test` in devDeps, auto-picks `e2e/` or `tests/e2e/`, `webServer` auto-starts dev server.
 
-**Playwright config requirements** (verify before running):
-- `headless: true` must be set under `use:`
-- `channel: undefined` (or omitted) — must NOT be `'chrome'` or `'msedge'` to avoid system browser conflicts
-- `webServer.reuseExistingServer: true` — avoids double-starting the dev server
+**Config requirements (verify before running):**
+- `headless: true` under `use:`
+- `channel: undefined` (omit) — NOT `'chrome'` or `'msedge'`
+- `webServer.reuseExistingServer: true`
 
 If config has `channel: 'chrome'` or `headless: false`, warn:
 > "playwright.config.ts uses system Chrome or headed mode — this may conflict with a running browser. Consider setting `headless: true` and `channel: undefined`."
@@ -53,12 +45,11 @@ If config has `channel: 'chrome'` or `headless: false`, warn:
 agent-browser --version
 ```
 
-Only use `agent-browser` if NO `playwright.config.ts` / `playwright.config.js` exists.
-
-If `agent-browser` is also not found, AND no Playwright config exists:
+Only use if NO Playwright config exists.
 
+If neither is found:
 ```
-Neither Playwright nor agent-browser is configured. To fix permanently:
+Neither Playwright nor agent-browser is configured.
 
 Option A (recommended) — Playwright:
   npm install -D @playwright/test
@@ -82,9 +73,9 @@ ls tests/e2e/ 2>/dev/null
 find . -name "*.spec.ts" -not -path "*/node_modules/*"
 ```
 
-If spec files exist, run them:
+If spec files exist:
 ```bash
-npx playwright test --reporter=list
+npx playwright test --reporter=list 2>&1
 ```
 
 To run a specific file:
@@ -92,148 +83,105 @@ To run a specific file:
 npx playwright test e2e/my-feature.spec.ts --reporter=list
 ```
 
-To run with visible output on failure:
-```bash
-npx playwright test --reporter=list 2>&1
-```
-
 **Interpreting results:**
-- Exit code 0 = all tests passed
-- Exit code 1 = one or more tests failed (output includes which tests and why)
-- Each failing test shows: test name, expected vs. actual, screenshot path (if `trace: 'on-first-retry'` is set)
+- Exit 0 = all passed; Exit 1 = failures (shows test name, expected vs. actual, screenshot path if `trace: 'on-first-retry'`)
 
-If no spec files exist → derive scenarios from `tasks/todo.md` acceptance criteria and write them to `e2e/<feature>.spec.ts` before running. Follow the test file patterns already present in the project (check `e2e/helpers/` for shared utilities).
+If no spec files exist → derive scenarios from `tasks/todo.md` acceptance criteria, write to `e2e/<feature>.spec.ts`, check `e2e/helpers/` for shared utilities, then run.
 
-After running, record for each test:
-- Test name / suite
-- Result: PASS or FAIL
-- On FAIL: error message and relevant snapshot
+Record per test: name/suite, PASS or FAIL, on FAIL: error + snapshot excerpt.
 
-Skip to **Step 5 (Report Results)**.
+Skip to **Step 5**.
 
-### 3b. Detect Local Server (agent-browser path only)
+### 3b. Detect Local Server (agent-browser only)
 
-Only needed if using agent-browser (Playwright's `webServer` handles this automatically).
+Playwright's `webServer` handles this automatically — only needed for agent-browser.
 
-Determine what URL to test against:
-- Check for a dev server command in `package.json` scripts (`dev`, `start`)
-- Check for `artisan serve` in Laravel projects (`php artisan serve`)
-- Check for `vite` or `next dev`
-- If a server is already running (check common ports: 3000, 5173, 8000, 8080), use it
-- If no server is running, start one in the background and note the URL
+- Check `package.json` scripts (`dev`, `start`), `artisan serve`, `vite`, `next dev`
+- Check common ports: 3000, 5173, 8000, 8080; use existing server or start one in background
 
-### 4. Locate E2E Test Files (agent-browser path only)
+### 4. Locate E2E Test Files (agent-browser only)
 
-Find E2E test scenarios written during the Write Tests step:
 ```bash
 find . -name "*.e2e.*" -o -name "*.spec.*" | grep -v node_modules
 ls tests/e2e/ 2>/dev/null
 ```
 
-If no E2E test files exist, derive scenarios from `tasks/todo.md` acceptance criteria and `tasks/findings.md`.
+If none exist, derive scenarios from `tasks/todo.md` and `tasks/findings.md`.
 
 ### 4b. Run E2E Scenarios via agent-browser
 
-For each scenario, use agent-browser following this core pattern:
-
 ```bash
-# Navigate to the page
 agent-browser open <url>
-
-# Get interactive elements (token-efficient ref-based snapshot)
-agent-browser snapshot -i
-
-# Interact using @refs (never CSS selectors)
-agent-browser click @e1
+agent-browser snapshot -i              # token-efficient ref-based snapshot
+agent-browser click @e1                # use @refs — never CSS selectors
 agent-browser fill @e2 "input value"
 agent-browser press Enter
-
-# Use semantic locators when @refs aren't stable
-agent-browser find role button
+agent-browser find role button         # semantic locators when @refs unstable
 agent-browser find text "Expected Text"
 agent-browser find label "Email"
-
-# Assert expected state
-agent-browser snapshot   # check content
+agent-browser snapshot                 # assert state
 agent-browser find text "Success Message"
 ```
 
-**Ref-based interaction is required.** Never use CSS selectors (`#id`, `.class`) — use semantic locators (`find role`, `find text`, `find label`, `find placeholder`) for stability.
+**Use @refs or semantic locators (`find role`, `find text`, `find label`, `find placeholder`). Never CSS selectors.**
 
-For each scenario, record:
-- Scenario name
-- Steps executed
-- Result: PASS or FAIL
-- On FAIL: what was expected vs. what was found (include snapshot excerpt)
+Record per scenario: name, steps, PASS/FAIL, on FAIL: expected vs. actual + snapshot excerpt.
 
 ### 5. Report Results
 
 ```
 E2E Runner: Playwright CLI  (or: agent-browser)
 E2E Results:
-  PASS  [scenario name]
   PASS  [scenario name]
   FAIL  [scenario name] — expected "X" but found "Y"
 
 Total: X passed, Y failed
 ```
 
-If all pass → proceed to Fix & Retest Protocol section (no action needed).
-If any fail → apply Fix & Retest Protocol.
+All pass → no action needed. Any fail → apply Fix & Retest Protocol.
 
 ## Fix & Retest Protocol
 
-When this gate requires a fix, classify it before committing:
+Classify before committing:
 
-**a. Style/config/wording change** (CSS tweak, copy change, selector fix) → include in the gate's squash commit and re-run `/sk:e2e`. Do not ask the user.
+| Type | Action |
+|------|--------|
+| Style/config/wording (CSS, copy, selector) | Include in gate's squash commit, re-run `/sk:e2e`. No user prompt. |
+| Logic change (branch, condition, data path, query, function, API) | 1) Update/add failing unit tests 2) `/sk:test` at 100% coverage 3) Commit tests + fix: `fix(e2e): [description]` 4) Re-run `/sk:e2e` from scratch |
+| Formatter auto-fixes | Never logic changes — bypass protocol automatically. |
 
-**b. Logic change** (new branch, modified condition, new data path, query change, new function, API change) → trigger protocol:
-1. Update or add failing unit tests for the new behavior
-2. Re-run `/sk:test` — must pass at 100% coverage
-3. Commit tests + fix together with `fix(e2e): [description]`.
-4. Re-run `/sk:e2e` from scratch
+Squash gate commits: collect all fixes, then one commit: `fix(e2e): resolve failing E2E scenarios`.
 
-**Exception:** Formatter auto-fixes are never logic changes — bypass protocol automatically.
-
-> Squash gate commits — collect all fixes for the pass, then one commit: `fix(e2e): resolve failing E2E scenarios`. Do not commit after each individual fix.
-
-**This gate cannot be skipped.** All scenarios must pass before proceeding to `/sk:update-task`.
+**This gate cannot be skipped.** All scenarios must pass before `/sk:update-task`.
 
 ### Pre-existing Issues
 
-If during E2E testing a bug is found in functionality **outside** the current feature being tested (pre-existing issue unrelated to this branch), do NOT fix it inline. Log it to `tasks/tech-debt.md`:
+If a bug is found outside the current feature, do NOT fix inline. Log to `tasks/tech-debt.md`:
 
 ```
 ### [YYYY-MM-DD] Found during: sk:e2e
 File: path/to/file.ext:line
-Issue: description of the pre-existing bug
+Issue: description
 Severity: critical | high | medium | low
 ```
 
-Continue testing the current feature. Pre-existing bugs do not block this gate unless they affect the current feature's scenarios.
+Pre-existing bugs don't block this gate unless they affect the current feature's scenarios.
 
 ## Next Steps
 
-If all scenarios pass:
-> "E2E gate clean. Run `/sk:update-task` to mark the task done."
->
-> No manual commit is needed — any fixes made during this gate were auto-committed.
-
-If failures remain after fixes:
-> "Re-running /sk:e2e — [N] scenarios still failing."
+- All pass: "E2E gate clean. Run `/sk:update-task` to mark the task done." (fixes were auto-committed)
+- Failures remain: "Re-running /sk:e2e — [N] scenarios still failing."
 
 ---
 
 ## Playwright Setup Reference
 
-When setting up Playwright for the first time in a project:
-
 ```bash
 npm install -D @playwright/test
 npx playwright install chromium
 ```
 
-Minimal `playwright.config.ts` (headless, no system Chrome conflict):
+Minimal `playwright.config.ts`:
 
 ```ts
 import { defineConfig, devices } from '@playwright/test'
@@ -263,7 +211,7 @@ export default defineConfig({
 })
 ```
 
-E2E test helpers go in `e2e/helpers/`. Auth helper pattern:
+E2E helpers go in `e2e/helpers/`. Auth helper pattern:
 
 ```ts
 // e2e/helpers/auth.ts
@@ -289,7 +237,7 @@ export const TEST_USERS = {
 }
 ```
 
-Test credentials go in `.env.local` (never hardcoded):
+Test credentials in `.env.local` (never hardcoded):
 ```
 E2E_USER_EMAIL=...
 E2E_USER_PASSWORD=...

package/skills/sk:features/SKILL.md

@@ -7,16 +7,9 @@ description: "Sync docs/sk:features/ specs with the current codebase. Auto-detec
 
 # /sk:features
 
-Keep feature specifications in `docs/sk:features/` in sync with the actual codebase.
-Works with **any project** — framework-agnostic, auto-discovers source structure.
+Keep feature specifications in `docs/sk:features/` in sync with the actual codebase. Framework-agnostic, auto-discovers source structure.
 
-## What This Does
-
-Maintains `docs/sk:features/` as a platform-agnostic feature specification system —
-the single source of truth shared between web, mobile, and any other platform
-that uses the same backend. Each spec covers: DB schema, business logic, API
-contract, permissions, edge cases, error states, web/mobile UI behavior, and
-platform divergences.
+Maintains `docs/sk:features/` as a platform-agnostic feature specification system — single source of truth for web, mobile, and any other platform sharing the same backend. Each spec covers: DB schema, business logic, API contract, permissions, edge cases, error states, web/mobile UI behavior, and platform divergences.
 
 ---
 
@@ -24,34 +17,24 @@ platform divergences.
 
 ### Step 1: Detect Project State
 
-Check what exists:
-
 ```bash
 ls docs/sk:features/ 2>/dev/null && echo "EXISTS" || echo "MISSING"
 ls docs/FEATURES.md 2>/dev/null && echo "INDEX_EXISTS" || echo "INDEX_MISSING"
 ```
 
-**If `docs/sk:features/` does not exist:**
-Ask the user: "No feature specification system found. Create one from scratch?"
-- Yes → jump to **[Create From Scratch](#create-from-scratch)** below
-- No → stop
-
-**If `docs/sk:features/` exists:**
-Continue to Step 2.
+- `docs/sk:features/` **missing** → ask user: "No feature specification system found. Create one from scratch?" → Yes: jump to [Create From Scratch](#create-from-scratch) / No: stop
+- `docs/sk:features/` **exists** → continue to Step 2
 
 ---
 
 ### Step 2: Determine Update Scope
 
-Present three options:
+Present three options and wait for choice:
 
-> **What would you like to update?**
 > **A. Auto-detect** *(recommended)* — scan recent git changes, update only affected specs
-> **B. Select features** — pick which specs to update from the list
+> **B. Select features** — pick which specs to update
 > **C. Refresh all** — update every spec from current source code
 
-Wait for the user's choice.
-
 ---
 
 ### Step 3A: Auto-detect Changed Features
@@ -60,24 +43,15 @@ Wait for the user's choice.
 git log --since="7 days ago" --name-only --pretty=format: | grep -v '^$' | sort -u
 ```
 
-Map changed file paths to feature specs using these rules:
-
-1. **Read `docs/FEATURES.md`** to get the list of all spec files and their names.
-2. For each changed file, determine which spec it belongs to:
-   - Match by **feature name similarity**: if the spec is `expenses.md`, look for changed files containing `expense` in their path.
-   - Match by **directory**: if the spec is `budgets.md`, match files under any `budgets/` or `budget/` directory.
-   - Match by **schema files**: if any migration file, `schema.sql`, `schema.prisma`, `database.ts`, or similar schema file changed → mark ALL specs as potentially affected (schema changes ripple everywhere).
-3. Deduplicate the affected spec list.
-4. Report which specs will be updated and ask for confirmation.
-
----
+Map changed files to specs:
+1. Read `docs/FEATURES.md` for the spec list.
+2. For each changed file, match by feature name similarity (e.g., `expenses.md` ↔ paths containing `expense`) or by directory (`budgets.md` ↔ `budgets/` or `budget/`).
+3. If any migration, `schema.sql`, `schema.prisma`, `database.ts`, or similar schema file changed → mark ALL specs as potentially affected.
+4. Deduplicate and report; ask for confirmation.
 
 ### Step 3B: User Selects Features
 
-List all `.md` files in `docs/sk:features/` (excluding `_template.md`).
-Let the user pick which ones to update.
-
----
+List all `.md` files in `docs/sk:features/` (excluding `_template.md`). Let user pick.
 
 ### Step 3C: Refresh All
 
@@ -87,93 +61,72 @@ Set update list = all `.md` files in `docs/sk:features/` (excluding `_template.m
 
 ### Step 4: Update Each Affected Spec
 
-For each spec file to update, follow this sequence:
-
-#### 4a. Read the existing spec
-Understand its current content and section structure.
+#### 4a. Read existing spec — understand current content and section structure.
 
-#### 4b. Discover relevant source files
+#### 4b. Discover relevant source files (three-step, no hardcoded paths):
 
-Use a three-step lookup — no hardcoded paths:
-
-1. **Name-based search**: the feature name from the spec filename (e.g., `expenses.md` → feature name `expenses`). Search the repo:
+1. **Name-based search** — e.g., `expenses.md` → keyword `expenses`:
    ```bash
-   # Find files whose name contains the feature keyword
    find . -type f \( -name "*expense*" -o -name "*expenses*" \) \
      ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/docs/*" \
      2>/dev/null | head -30
    ```
-   Adjust the keyword to match the feature name.
-
-2. **Related Docs in spec**: read the `## Related Docs` section of the existing spec — it lists previously referenced files. Read those files too.
+2. **Related Docs section** — read previously referenced files listed in `## Related Docs`.
+3. **DB schema hint** — read table names from `## Database Schema`; search migrations/schema files for those names.
 
-3. **DB schema hint**: read the `## Database Schema` section — it names tables. Search migrations and schema files for those table names.
+#### 4c. Read all discovered source files.
 
-#### 4c. Read the source files
-Read all discovered source files to understand the current implementation.
-
-#### 4d. Identify what changed
-Compare the current source code against what the spec describes:
-- New or removed DB columns / tables / constraints
-- Changed business logic rules or state transitions
+#### 4d. Identify what changed — compare source vs spec:
+- New/removed DB columns, tables, constraints
+- Changed business logic or state transitions
 - New/changed API payloads or query patterns
 - Updated permission keys or tier requirements
 - New edge cases, error codes, or recovery paths
 
-#### 4e. Update only changed sections
-Rewrite only the sections that are out of date. **Preserve all unchanged sections verbatim.**
-Update the `> Status` block if the implementation status on either platform changed.
+#### 4e. Rewrite only out-of-date sections. Preserve unchanged sections verbatim. Update `> Status` block if platform implementation status changed.
 
 ---
 
 ### Step 5: Handle New Features
 
-If source code has a clear new feature (new hook, new route group, new major component) with no corresponding spec:
+If source has a new feature (hook, route group, major component) with no spec:
 
-1. Create `docs/sk:features/<feature-name>.md` using `docs/sk:features/_template.md` as base.
-   If `_template.md` doesn't exist, use this 11-section structure:
+1. Create `docs/sk:features/<feature-name>.md` using `_template.md`, or this 11-section structure if template missing:
    ```
    Status → Overview → Database Schema → Business Logic → API Contract
    → Permissions & Access Control → Edge Cases → Error States
    → UI/UX Behavior (### Web + ### Mobile) → Platform Notes → Related Docs
    ```
-2. Fill all 11 sections from current source code.
-3. Add the new spec to `docs/FEATURES.md` under the appropriate section.
+2. Fill all 11 sections from source code.
+3. Add to `docs/FEATURES.md` under the appropriate section.
 
 ---
 
 ### Step 6: Update Master Index
 
-Review `docs/FEATURES.md`:
-- Add links for any new specs
-- Update status columns (Web / Mobile) if implementation status changed
-- Update any tier/feature tables if permissions changed
+Review `docs/FEATURES.md` — add links for new specs, update status columns (Web/Mobile), update tier/feature tables if permissions changed.
 
 ---
 
 ### Step 7: Report and Commit
 
-Show a summary:
-- ✅ **Updated**: `spec-name.md` — what changed (1 sentence each)
-- ➕ **Added**: any new spec files
-- ⏭️ **Skipped**: specs with no detected changes
+Summary format:
+- Updated: `spec-name.md` — what changed (1 sentence)
+- Added: new spec files
+- Skipped: specs with no detected changes
 
 Ask: **"Commit the updated specs?"**
-- Yes → stage only files under `docs/` and commit:
-  `docs(features): update feature specs to reflect current implementation`
-- No → leave changes unstaged for the user to review
+- Yes → stage only `docs/` files and commit: `docs(features): update feature specs to reflect current implementation`
+- No → leave unstaged for review
 
 ---
 
 ## Create From Scratch
 
-When `docs/sk:features/` doesn't exist, discover and document all features:
-
 ### Discovery Phase
 
-1. **Detect source structure** — find where feature logic lives:
+1. **Detect source structure:**
    ```bash
-   # Look for hooks, services, controllers, models, routes
    ls src/ lib/ app/ 2>/dev/null
    find . -maxdepth 4 -type f \
      \( -name "use-*.ts" -o -name "use-*.js" \
@@ -182,7 +135,7 @@ When `docs/sk:features/` doesn't exist, discover and document all features:
      ! -path "*/node_modules/*" ! -path "*/.git/*" 2>/dev/null | head -50
    ```
 
-2. **Detect schema files** — migrations, ORM schemas:
+2. **Detect schema files:**
    ```bash
    find . -maxdepth 5 \
      \( -name "schema.sql" -o -name "*.schema.prisma" \
@@ -192,21 +145,15 @@ When `docs/sk:features/` doesn't exist, discover and document all features:
    ls prisma/ 2>/dev/null
    ```
 
-3. **Identify feature domains** from the discovered files — group related files into named features.
-
-4. **Report discovered features** and ask the user to confirm/adjust the list before creating anything.
+3. Group related files into named feature domains.
+4. Report discovered features; ask user to confirm/adjust before creating anything.
 
 ### Creation Phase
 
-For each confirmed feature:
-1. Read all relevant source files.
-2. Create `docs/sk:features/<feature-name>.md` with all 11 sections — based entirely on source code.
+For each confirmed feature: read all relevant source files, create `docs/sk:features/<feature-name>.md` with all 11 sections from source code.
 
 Also create:
-- `docs/FEATURES.md` — master index with:
-  - How-to-use section (web path + mobile path via `../project-name/docs/`)
-  - Feature table grouped by domain
-  - Tier/subscription overview (if the project has tiers)
+- `docs/FEATURES.md` — master index (how-to-use, feature table by domain, tier/subscription overview if applicable)
 - `docs/sk:features/_template.md` — 11-section template for future specs
 
 Commit: `docs: add feature specification system`
@@ -215,16 +162,14 @@ Commit: `docs: add feature specification system`
 
 ## Quality Rules (Always Apply)
 
-- **Source-verified only** — every claim must be findable in source code; never invent behavior
+- **Source-verified only** — every claim must be findable in source; never invent behavior
 - **No placeholders** — no `// TODO`, no `false // will be computed`, no assumed values
-- **Surgical updates** — only rewrite what changed; preserve unchanged sections verbatim
-- **Numeric JSX coercion** — when documenting frontend behavior, note `!!value` (not `value &&`) for numerics to avoid rendering `0` as text in React/React Native
-- **Local date, not UTC** — for any time-bounded query (current month, today, etc.), document that implementations must use local `new Date()`, not `toISOString()` which returns UTC and causes off-by-one for users in non-UTC timezones
+- **Surgical updates** — only rewrite changed sections; preserve unchanged sections verbatim
+- **Numeric JSX coercion** — note `!!value` (not `value &&`) for numerics to avoid rendering `0` as text in React/React Native
+- **Local date, not UTC** — time-bounded queries must use local `new Date()`, not `toISOString()` (UTC causes off-by-one for non-UTC users)
 - **All 11 sections required** — mark "N/A" only if genuinely not applicable
 
-## Source Discovery Heuristics (Reference)
-
-When locating source files for a feature named `<name>`:
+## Source Discovery Heuristics
 
 | What to look for | Search pattern |
 |---|---|

package/skills/sk:frontend-design/SKILL.md

@@ -6,37 +6,26 @@ license: Complete terms in LICENSE.txt
 
 ## CRITICAL: Design Phase Only — NO CODE
 
-**This skill is a design phase, not an implementation phase.**
+This skill produces design artifacts only. Implementation happens in `/sk:execute-plan`.
 
-- **DO NOT** write, edit, or generate any code (no React, no HTML/CSS/JS, no file edits)
-- **DO NOT** use file editing tools (Edit, Write, Bash)
-- **Pencil MCP tools ARE allowed** — they create visual design artifacts, not code
-- **DO produce** design direction, ASCII mockups, layout specs, component structure descriptions, color/typography decisions, and interaction notes
-- Implementation happens in `/sk:execute-plan` — not here
-
-This skill guides the design of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Output is a design artifact: a clear, decision-complete visual specification that `/sk:write-plan` and `/sk:execute-plan` can use to implement.
-
-The user provides frontend requirements: a component, page, application, or interface to design. They may include context about the purpose, audience, or technical constraints.
+- No code: no React, HTML/CSS/JS, file edits, or use of Edit/Write/Bash tools
+- Pencil MCP tools ARE allowed — they create visual design artifacts, not code
+- Produce: design direction, ASCII mockups, layout specs, component structure, color/typography decisions, interaction notes
 
 ## Before You Start
 
-1. If `tasks/findings.md` exists and has content, read it in full. Use the agreed
-   approach and requirements as the design brief — this replaces the need to ask the
-   user to re-explain what was already decided in brainstorming.
-
-2. If `tasks/lessons.md` exists, read it in full. Apply every active lesson as a
-   constraint during design — particularly any patterns flagged under **Bug** that
-   relate to frontend structure, component architecture, or styling conventions.
+1. If `tasks/findings.md` exists and has content, read it in full — use the agreed approach as the design brief.
+2. If `tasks/lessons.md` exists, read it in full — apply every active lesson as a constraint, especially Bug entries related to frontend structure, component architecture, or styling conventions.
 
 ## Design Thinking
 
-Before coding, understand the context and commit to a BOLD aesthetic direction:
+Before designing, commit to a BOLD aesthetic direction:
 - **Purpose**: What problem does this interface solve? Who uses it?
-- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc.
 - **Constraints**: Technical requirements (framework, performance, accessibility).
 - **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
 
-**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.
 
 Then produce a **design artifact** — not code — that includes:
 - ASCII or text-based layout mockups for key screens/states
@@ -48,24 +37,19 @@ Then produce a **design artifact** — not code — that includes:
 
 ## Frontend Aesthetics Guidelines
 
-Focus on:
-- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Typography**: Choose beautiful, unique, unexpected fonts. Avoid generic families (Arial, Inter, Roboto, Space Grotesk). Pair a distinctive display font with a refined body font.
 - **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
-- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Motion**: Animate for micro-interactions and effects. Prefer CSS-only for HTML; use Motion library for React. One well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
 - **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
-- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
-
-NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
-
-Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+- **Backgrounds & Visual Details**: Create atmosphere and depth. Add gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, grain overlays — match the aesthetic.
 
-**IMPORTANT**: Match design detail to the aesthetic vision. Maximalist designs need elaborate layout descriptions, rich animation notes, and dense component specs. Minimalist designs need precise spacing rules, restrained color notes, and careful typographic ratios. Elegance comes from committing to the vision fully.
+NEVER use generic AI aesthetics: overused fonts (Inter, Roboto, Arial, system fonts, Space Grotesk), cliched purple-gradient-on-white color schemes, predictable layouts, or cookie-cutter patterns. Vary between light/dark themes, different fonts, and different aesthetics across generations.
 
-Remember: Claude is capable of extraordinary creative thinking. Don't hold back on the design direction — show what can be envisioned when thinking outside the box and committing fully to a distinctive aesthetic.
+**IMPORTANT**: Match design detail to the aesthetic vision. Maximalist designs need elaborate layout descriptions, rich animation notes, and dense component specs. Minimalist designs need precise spacing rules, restrained color notes, and careful typographic ratios. Commit to the vision fully.
 
 ## UX Quality Constraints
 
-Apply these rules as hard constraints during design. They are organized by priority — address CRITICAL issues first, then HIGH, then MEDIUM. Skip categories irrelevant to the current design (e.g., Charts for a landing page).
+Hard constraints during design, ordered by priority. Skip categories irrelevant to the current design (e.g., Charts for a landing page).
 
 | Priority | Category | Impact | Key Rule |
 |---|---|---|---|
@@ -217,7 +201,7 @@ Apply these rules as hard constraints during design. They are organized by prior
 
 ## Professional UI Anti-Patterns
 
-These are frequently overlooked issues that make UI look unprofessional. Flag any of these in the design spec so implementation avoids them.
+Frequently overlooked issues that make UI look unprofessional. Flag any of these in the design spec.
 
 ### Icons & Visual Elements
 - **No emoji as icons** — use Heroicons, Lucide, or equivalent SVG sets