@fro.bot/systematic 2.0.2 → 2.0.3

package/skills/file-todos/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: file-todos
-description: This skill should be used when managing the file-based todo tracking system in the todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with slash commands and code review processes.
+description: This skill should be used when managing the file-based todo tracking system in the .context/systematic/todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with code review processes.
 disable-model-invocation: true
 ---
 
@@ -8,26 +8,35 @@ disable-model-invocation: true
 
 ## Overview
 
-The `todos/` directory contains a file-based tracking system for managing code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter and structured sections.
+The `.context/systematic/todos/` directory contains a file-based tracking system for managing code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter and structured sections.
+
+> **Legacy support:** During the transition period, always check both `.context/systematic/todos/` (canonical) and `todos/` (legacy) when reading or searching for todos. Write new todos only to the canonical path. Unlike per-run scratch directories, `.context/systematic/todos/` has a multi-session lifecycle -- do not clean it up as part of post-run scratch cleanup.
 
 This skill should be used when:
 - Creating new todos from findings or feedback
-- Managing todo lifecycle (pending → ready → complete)
+- Managing todo lifecycle (pending -> ready -> complete)
 - Triaging pending items for approval
 - Checking or managing dependencies
 - Converting PR comments or code findings into tracked work
 - Updating work logs during todo execution
 
-## File Naming Convention
+## Directory Paths
+
+| Purpose | Path |
+|---------|------|
+| **Canonical (write here)** | `.context/systematic/todos/` |
+| **Legacy (read-only)** | `todos/` |
 
-Todo files follow this naming pattern:
+When searching or listing todos, always search both paths. When creating new todos, always write to the canonical path.
+
+## File Naming Convention
 
 ```
 {issue_id}-{status}-{priority}-{description}.md
 ```
 
 **Components:**
-- **issue_id**: Sequential number (001, 002, 003...) - never reused
+- **issue_id**: Sequential number (001, 002, 003...) -- never reused
 - **status**: `pending` (needs triage), `ready` (approved), `complete` (done)
 - **priority**: `p1` (critical), `p2` (important), `p3` (nice-to-have)
 - **description**: kebab-case, brief description
@@ -44,17 +53,17 @@ Todo files follow this naming pattern:
 Each todo is a markdown file with YAML frontmatter and structured sections. Use the template at [todo-template.md](./assets/todo-template.md) as a starting point when creating new todos.
 
 **Required sections:**
-- **Problem Statement** - What is broken, missing, or needs improvement?
-- **Findings** - Investigation results, root cause, key discoveries
-- **Proposed Solutions** - Multiple options with pros/cons, effort, risk
-- **Recommended Action** - Clear plan (filled during triage)
-- **Acceptance Criteria** - Testable checklist items
-- **Work Log** - Chronological record with date, actions, learnings
+- **Problem Statement** -- What is broken, missing, or needs improvement?
+- **Findings** -- Investigation results, root cause, key discoveries
+- **Proposed Solutions** -- Multiple options with pros/cons, effort, risk
+- **Recommended Action** -- Clear plan (filled during triage)
+- **Acceptance Criteria** -- Testable checklist items
+- **Work Log** -- Chronological record with date, actions, learnings
 
 **Optional sections:**
-- **Technical Details** - Affected files, related components, DB changes
-- **Resources** - Links to errors, tests, PRs, documentation
-- **Notes** - Additional context or decisions
+- **Technical Details** -- Affected files, related components, DB changes
+- **Resources** -- Links to errors, tests, PRs, documentation
+- **Notes** -- Additional context or decisions
 
 **YAML frontmatter fields:**
 ```yaml
@@ -69,20 +78,21 @@ dependencies: ["001"]     # Issue IDs this is blocked by
 
 ## Common Workflows
 
-### Creating a New Todo
+> **Tool preference:** Use native file-search (e.g., Glob in OpenCode) and content-search (e.g., Grep in OpenCode) tools instead of shell commands for finding and reading todo files. This avoids unnecessary permission prompts in sub-agent workflows. Use shell only for operations that have no native equivalent (e.g., `mv` for renames, `mkdir -p` for directory creation).
 
-**To create a new todo from findings or feedback:**
+### Creating a New Todo
 
-1. Determine next issue ID: `ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1`
-2. Copy template: `cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.md`
-3. Edit and fill required sections:
+1. Ensure directory exists: `mkdir -p .context/systematic/todos/`
+2. Determine next issue ID by searching both canonical and legacy paths for files matching `[0-9]*-*.md` using the native file-search/glob tool. Extract the numeric prefix from each filename, find the highest, and increment by one. Zero-pad to 3 digits (e.g., `007`).
+3. Read the template at [todo-template.md](./assets/todo-template.md), then write it to `.context/systematic/todos/{NEXT_ID}-pending-{priority}-{description}.md` using the native file-write tool.
+4. Edit and fill required sections:
    - Problem Statement
    - Findings (if from investigation)
    - Proposed Solutions (multiple options)
    - Acceptance Criteria
    - Add initial Work Log entry
-4. Determine status: `pending` (needs triage) or `ready` (pre-approved)
-5. Add relevant tags for filtering
+5. Determine status: `pending` (needs triage) or `ready` (pre-approved)
+6. Add relevant tags for filtering
 
 **When to create a todo:**
 - Requires more than 15-20 minutes of work
@@ -101,21 +111,19 @@ dependencies: ["001"]     # Issue IDs this is blocked by
 
 ### Triaging Pending Items
 
-**To triage pending todos:**
-
-1. List pending items: `ls todos/*-pending-*.md`
+1. Find pending items using the native file-search/glob tool with pattern `*-pending-*.md` in both directory paths.
 2. For each todo:
    - Read Problem Statement and Findings
    - Review Proposed Solutions
    - Make decision: approve, defer, or modify priority
 3. Update approved todos:
    - Rename file: `mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md`
-   - Update frontmatter: `status: pending` → `status: ready`
+   - Update frontmatter: `status: pending` -> `status: ready`
    - Fill "Recommended Action" section with clear plan
    - Adjust priority if different from initial assessment
 4. Deferred todos stay in `pending` status
 
-**Use slash command:** `/triage` for interactive approval workflow
+Load the `triage` skill for an interactive approval workflow.
 
 ### Managing Dependencies
 
@@ -126,31 +134,20 @@ dependencies: ["002", "005"]  # This todo blocked by issues 002 and 005
 dependencies: []               # No blockers - can work immediately
 ```
 
-**To check what blocks a todo:**
-```bash
-grep "^dependencies:" todos/003-*.md
-```
+**To check what blocks a todo:** Use the native content-search tool (e.g., Grep in OpenCode) to search for `^dependencies:` in the todo file.
 
-**To find what a todo blocks:**
-```bash
-grep -l 'dependencies:.*"002"' todos/*.md
-```
+**To find what a todo blocks:** Search both directory paths for files containing `dependencies:.*"002"` using the native content-search tool.
 
-**To verify blockers are complete before starting:**
-```bash
-for dep in 001 002 003; do
-  [ -f "todos/${dep}-complete-*.md" ] || echo "Issue $dep not complete"
-done
-```
+**To verify blockers are complete before starting:** For each dependency ID, use the native file-search/glob tool to look for `{dep_id}-complete-*.md` in both directory paths. Any missing matches indicate incomplete blockers.
 
 ### Updating Work Logs
 
-**When working on a todo, always add a work log entry:**
+When working on a todo, always add a work log entry:
 
 ```markdown
 ### YYYY-MM-DD - Session Title
 
-**By:** OpenCode / Developer Name
+**By:** Agent name / Developer Name
 
 **Actions:**
 - Specific changes made (include file:line references)
@@ -172,82 +169,63 @@ Work logs serve as:
 
 ### Completing a Todo
 
-**To mark a todo as complete:**
-
 1. Verify all acceptance criteria checked off
 2. Update Work Log with final session and results
 3. Rename file: `mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md`
-4. Update frontmatter: `status: ready` → `status: complete`
-5. Check for unblocked work: `grep -l 'dependencies:.*"002"' todos/*-ready-*.md`
+4. Update frontmatter: `status: ready` -> `status: complete`
+5. Check for unblocked work: search both directory paths for `*-ready-*.md` files containing `dependencies:.*"{issue_id}"` using the native content-search tool
 6. Commit with issue reference: `feat: resolve issue 002`
 
 ## Integration with Development Workflows
 
 | Trigger | Flow | Tool |
 |---------|------|------|
-| Code review | `/ce:review` → Findings → `/triage` → Todos | Review agent + skill |
-| PR comments | `/resolve_pr_parallel` → Individual fixes → Todos | gh CLI + skill |
-| Code TODOs | `/resolve_todo_parallel` → Fixes + Complex todos | Agent + skill |
-| Planning | Brainstorm → Create todo → Work → Complete | Skill |
-| Feedback | Discussion → Create todo → Triage → Work | Skill + slash |
+| Code review | `/ce:review` -> Findings -> `/triage` -> Todos | Review agent + skill |
+| Beta autonomous review | `/ce:review-beta mode:autonomous` -> Downstream-resolver residual todos -> `/resolve-todo-parallel` | Review skill + todos |
+| PR comments | `/resolve_pr_parallel` -> Individual fixes -> Todos | gh CLI + skill |
+| Code TODOs | `/resolve-todo-parallel` -> Fixes + Complex todos | Agent + skill |
+| Planning | Brainstorm -> Create todo -> Work -> Complete | Skill |
+| Feedback | Discussion -> Create todo -> Triage -> Work | Skill |
 
-## Quick Reference Commands
+## Quick Reference Patterns
 
-**Finding work:**
-```bash
-# List highest priority unblocked work
-grep -l 'dependencies: \[\]' todos/*-ready-p1-*.md
+Use the native file-search/glob tool (e.g., Glob in OpenCode) and content-search tool (e.g., Grep in OpenCode) for these operations. Search both canonical and legacy directory paths.
 
-# List all pending items needing triage
-ls todos/*-pending-*.md
-
-# Find next issue ID
-ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}'
+**Finding work:**
 
-# Count by status
-for status in pending ready complete; do
-  echo "$status: $(ls -1 todos/*-$status-*.md 2>/dev/null | wc -l)"
-done
-```
+| Goal | Tool | Pattern |
+|------|------|---------|
+| List highest priority unblocked work | Content-search | `dependencies: \[\]` in `*-ready-p1-*.md` |
+| List all pending items needing triage | File-search | `*-pending-*.md` |
+| Find next issue ID | File-search | `[0-9]*-*.md`, extract highest numeric prefix |
+| Count by status | File-search | `*-pending-*.md`, `*-ready-*.md`, `*-complete-*.md` |
 
 **Dependency management:**
-```bash
-# What blocks this todo?
-grep "^dependencies:" todos/003-*.md
 
-# What does this todo block?
-grep -l 'dependencies:.*"002"' todos/*.md
-```
+| Goal | Tool | Pattern |
+|------|------|---------|
+| What blocks this todo? | Content-search | `^dependencies:` in the specific todo file |
+| What does this todo block? | Content-search | `dependencies:.*"{id}"` across all todo files |
 
 **Searching:**
-```bash
-# Search by tag
-grep -l "tags:.*rails" todos/*.md
 
-# Search by priority
-ls todos/*-p1-*.md
-
-# Full-text search
-grep -r "payment" todos/
-```
+| Goal | Tool | Pattern |
+|------|------|---------|
+| Search by tag | Content-search | `tags:.*{tag}` across all todo files |
+| Search by priority | File-search | `*-p1-*.md` (or p2, p3) |
+| Full-text search | Content-search | `{keyword}` across both directory paths |
 
 ## Key Distinctions
 
 **File-todos system (this skill):**
-- Markdown files in `todos/` directory
-- Development/project tracking
+- Markdown files in `.context/systematic/todos/` (legacy: `todos/`)
+- Development/project tracking across sessions and agents
 - Standalone markdown files with YAML frontmatter
-- Used by humans and agents
-
-**Rails Todo model:**
-- Database model in `app/models/todo.rb`
-- User-facing feature in the application
-- Active Record CRUD operations
-- Different from this file-based system
+- Persisted to disk, cross-agent accessible
 
-**todowrite tool:**
+**In-session task tracking (e.g., todowrite/TaskUpdate in OpenCode, update_plan in Codex):**
 - In-memory task tracking during agent sessions
 - Temporary tracking for single conversation
-- Not persisted to disk
-- Different from both systems above
+- Not persisted to disk after session ends
+- Different purpose: use for tracking steps within a session, not for durable cross-session work items
 

package/skills/frontend-design/SKILL.md

@@ -1,43 +1,259 @@
 ---
 name: frontend-design
-description: This skill should be used when creating distinctive, production-grade frontend interfaces with high design quality. It applies when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
-license: Complete terms in LICENSE.txt
+description: Build web interfaces with genuine design quality, not AI slop. Use for any frontend work - landing pages, web apps, dashboards, admin panels, components, interactive experiences. Activates for both greenfield builds and modifications to existing applications. Detects existing design systems and respects them. Covers composition, typography, color, motion, and copy. Verifies results via screenshots before declaring done.
 ---
 
-This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+# Frontend Design
 
-The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+Guide creation of distinctive, production-grade frontend interfaces that avoid generic AI aesthetics. This skill covers the full lifecycle: detect what exists, plan the design, build with intention, and verify visually.
 
-## Design Thinking
+## Authority Hierarchy
 
-Before coding, understand the context and 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.
-- **Constraints**: Technical requirements (framework, performance, accessibility).
-- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+Every rule in this skill is a default, not a mandate.
 
-**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+1. **Existing design system / codebase patterns** -- highest priority, always respected
+2. **User's explicit instructions** -- override skill defaults
+3. **Skill defaults** -- apply in greenfield work or when the user asks for design guidance
 
-Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
-- Production-grade and functional
-- Visually striking and memorable
-- Cohesive with a clear aesthetic point-of-view
-- Meticulously refined in every detail
+When working in an existing codebase with established patterns, follow those patterns. When the user specifies a direction that contradicts a default, follow the user.
 
-## Frontend Aesthetics Guidelines
+## Workflow
 
-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.
-- **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.
-- **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.
+```
+Detect context -> Plan the design -> Build -> Verify visually
+```
 
-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.
+---
+
+## Layer 0: Context Detection
+
+Before any design work, examine the codebase for existing design signals. This determines how much of the skill's opinionated guidance applies.
+
+### What to Look For
+
+- **Design tokens / CSS variables**: `--color-*`, `--spacing-*`, `--font-*` custom properties, theme files
+- **Component libraries**: shadcn/ui, Material UI, Chakra, Ant Design, Radix, or project-specific component directories
+- **CSS frameworks**: `tailwind.config.*`, `styled-components` theme, Bootstrap imports, CSS modules with consistent naming
+- **Typography**: Font imports in HTML/CSS, `@font-face` declarations, Google Fonts links
+- **Color palette**: Defined color scales, brand color files, design token exports
+- **Animation libraries**: Framer Motion, GSAP, anime.js, Motion One, Vue Transition imports
+- **Spacing / layout patterns**: Consistent spacing scale usage, grid systems, layout components
+
+Use the platform's native file-search and content-search tools (e.g., Glob/Grep in OpenCode) to scan for these signals. Do not use shell commands for routine file exploration.
+
+### Mode Classification
+
+Based on detected signals, choose a mode:
+
+- **Existing system** (4+ signals across multiple categories): Defer to it. The skill's aesthetic opinions (typography, color, motion) yield to the established system. Structural guidance (composition, copy, accessibility, verification) still applies.
+- **Partial system** (1-3 signals): Follow what exists; apply skill defaults only for areas where no convention was detected. For example, if Tailwind is configured but no component library exists, follow the Tailwind tokens and apply skill guidance for component structure.
+- **Greenfield** (no signals detected): Full skill guidance applies.
+- **Ambiguous** (signals are contradictory or unclear): Ask the user before proceeding.
+
+### Asking the User
+
+When context is ambiguous, use the platform's blocking question tool (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, assume "partial" mode and proceed conservatively.
+
+Example question: "I found [detected signals]. Should I follow your existing design patterns or create something distinctive?"
+
+---
+
+## Layer 1: Pre-Build Planning
+
+Before writing code, write three short statements. These create coherence and give the user a checkpoint to redirect before code is written.
+
+1. **Visual thesis** -- one sentence describing the mood, material, and energy
+   - Greenfield examples: "Clean editorial feel, lots of whitespace, serif headlines, muted earth tones" or "Dense data-forward dashboard, monospace accents, dark surface hierarchy"
+   - Existing codebase: Describe the *existing* aesthetic and how the new work will extend it
+
+2. **Content plan** -- what goes on the page and in what order
+   - Landing page: hero, support, detail, CTA
+   - App: primary workspace, nav, secondary context
+   - Component: what states it has, what it communicates
+
+3. **Interaction plan** -- 2-3 specific motion ideas that change the feel
+   - Not "add animations" but "staggered fade-in on hero load, parallax on scroll between sections, scale-up on card hover"
+   - In an existing codebase, describe only the interactions being added, using the existing motion library
+
+---
+
+## Layer 2: Design Guidance Core
+
+These principles apply across all context types. Each yields to existing design systems and user instructions per the authority hierarchy.
+
+### Typography
+
+- Choose distinctive, characterful fonts. Avoid the usual suspects (Inter, Roboto, Arial, system defaults) unless the existing codebase uses them.
+- Two typefaces maximum without a clear reason for more. Pair a display/headline font with a body font.
+- *Yields to existing font choices when detected in Layer 0.*
+
+### Color & Theme
+
+- Commit to a cohesive palette using CSS variables. A dominant color with sharp accents outperforms timid, evenly-distributed palettes.
+- No purple-on-white bias, no dark-mode bias. Vary between light and dark based on context.
+- One accent color by default unless the product already has a multi-color system.
+- *Yields to existing color tokens when detected.*
+
+### Composition
+
+- Start with composition, not components. Treat the first viewport as a poster, not a document.
+- Use whitespace, alignment, scale, cropping, and contrast before adding chrome (borders, shadows, cards).
+- Default to cardless layouts. Cards are allowed when they serve as the container for a user interaction (clickable item, draggable unit, selectable option). If removing the card styling would not hurt comprehension, it should not be a card.
+- *All composition rules are defaults. The user can override them.*
+
+### Motion
+
+- Ship 2-3 intentional motions for visually-led work: one entrance sequence, one scroll-linked or depth effect, one hover/reveal transition.
+- Use the project's existing animation library if one is present.
+- When no existing library is found, use framework-conditional defaults:
+  - **CSS animations** as the universal baseline
+  - **Framer Motion** for React projects
+  - **Vue Transition / Motion One** for Vue projects
+  - **Svelte transitions** for Svelte projects
+- Motion should be noticeable in a quick recording, smooth on mobile, and consistent across the page. Remove if purely ornamental.
+
+### Accessibility
+
+- Semantic HTML by default: `nav`, `main`, `section`, `article`, `button` -- not divs for everything.
+- Color contrast meeting WCAG AA minimum.
+- Focus states on all interactive elements.
+- Accessibility and aesthetics are not in tension when done well.
+
+### Imagery
+
+- When images are needed, prefer real or realistic photography over abstract gradients or fake 3D objects.
+- Choose or generate images with a stable tonal area for text overlay.
+- If image generation tools are available in the environment, use them to create contextually appropriate visuals rather than placeholder stock.
+
+---
+
+## Context Modules
+
+Select the module that fits what is being built. When working inside an existing application, default to Module C regardless of what the feature is.
+
+### Module A: Landing Pages & Marketing (Greenfield)
+
+**Default section sequence:**
+1. Hero -- brand/product, promise, CTA, one dominant visual
+2. Support -- one concrete feature, offer, or proof point
+3. Detail -- atmosphere, workflow, product depth, or story
+4. Final CTA -- convert, start, visit, or contact
+
+**Hero rules (defaults):**
+- One composition, not a dashboard. Full-bleed image or dominant visual plane.
+- Brand first, headline second, body third, CTA fourth.
+- Keep the text column narrow and anchored to a calm area of the image.
+- No more than 6 sections total without a clear reason.
+- One H1 headline. One primary CTA above the fold.
+
+**Copy:**
+- Let the headline carry the meaning. Supporting copy is usually one short sentence.
+- Write in product language, not design commentary. No prompt language or AI commentary in the UI.
+- Each section gets one job: explain, prove, deepen, or convert.
+- Every sentence should earn its place. Default to less copy, not more.
+
+### Module B: Apps & Dashboards (Greenfield)
+
+**Default patterns:**
+- Calm surface hierarchy, strong typography and spacing, few colors, dense but readable information, minimal chrome.
+- Organize around: primary workspace, navigation, secondary context/inspector, one clear accent for action or state.
+- Cards only when the card is the interaction (clickable item, draggable unit, selectable option). If a panel can become plain layout without losing meaning, remove the card treatment.
+
+**Copy (utility, not marketing):**
+- Prioritize orientation, status, and action over promise, mood, or brand voice.
+- Section headings should say what the area is or what the user can do there. Good: "Plan status", "Search metrics". Bad: "Unlock Your Potential".
+- If a sentence could appear in a homepage hero, rewrite it until it sounds like product UI.
+- Litmus: if an operator scans only headings, labels, and numbers, can they understand the page immediately?
+
+### Module C: Components & Features (Default in Existing Apps)
+
+For adding to an existing application:
+
+- Match the existing visual language. This module is about making something that belongs, not something that stands out.
+- Inherit spacing scale, border radius, color tokens, and typography from surrounding code.
+- Focus on interaction quality: clear states (default, hover, active, disabled, loading, error), smooth transitions between states, obvious affordances.
+- One new component should not introduce a new design system. If the existing app uses 4px border radius, do not add a component with 8px.
+
+---
+
+## Hard Rules & Anti-Patterns
+
+### Default Against (Overridable)
+
+These are the skill being opinionated. The user can override any of them.
+
+- Generic SaaS card grid as the first impression
+- Purple-on-white color schemes, dark-mode bias
+- Overused fonts (Inter, Roboto, Arial, Space Grotesk, system defaults) in greenfield work
+- Hero sections cluttered with stats, schedules, pill clusters, logo clouds
+- Sections that repeat the same mood statement in different words
+- Carousel with no narrative purpose
+- Multiple competing accent colors
+- Decorative gradients or abstract backgrounds standing in for real visual content
+- Copy that sounds like design commentary ("Experience the seamless integration")
+- Split-screen heroes where text sits on the busy side of an image
+
+### Always Avoid (Quality Floor)
+
+These are genuine quality failures no user would want.
+
+- Prompt language or AI commentary leaking into the UI
+- Broken contrast -- text unreadable over images or backgrounds
+- Interactive elements without visible focus states
+- Semantic div soup when proper HTML elements exist
+
+---
+
+## Litmus Checks
+
+Quick self-review before moving to visual verification. Not all checks apply in every context -- apply judgment about which are relevant.
+
+- Is the brand or product unmistakable in the first screen?
+- Is there one strong visual anchor?
+- Can the page be understood by scanning headlines only?
+- Does each section have one job?
+- Are cards actually necessary where they are used?
+- Does motion improve hierarchy or atmosphere, or is it just there?
+- Would the design feel premium if all decorative shadows were removed?
+- Does the copy sound like the product, not like a prompt?
+- Does the new work match the existing design system? (Module C)
+
+---
+
+## Visual Verification
+
+After implementing, verify visually. This is a sanity check, not a pixel-perfect review. One pass. If there is a glaring issue, fix it. If it looks solid, move on.
+
+### Tool Preference Cascade
+
+Use the first available option:
+
+1. **Existing project browser tooling** -- if Playwright, Puppeteer, Cypress, or similar is already in the project's dependencies, use it. Do not introduce new dependencies just for verification.
+2. **Browser MCP tools** -- if browser automation tools (e.g., claude-in-chrome) are available in the agent's environment, use them.
+3. **agent-browser CLI** -- if nothing else is available, this is the default. Load the `agent-browser` skill for installation and usage instructions.
+4. **Mental review** -- if no browser access is possible (headless CI, no permissions to install), apply the litmus checks as a self-review and note that visual verification was skipped.
+
+### What to Assess
+
+- Does the output match the visual thesis from the pre-build plan?
+- Are there obvious visual problems (broken layout, unreadable text, missing images)?
+- Does it look like the context module intended (landing page feels like a landing page, dashboard feels like a dashboard, component fits its surroundings)?
+
+### Scope Control
+
+One iteration. Take a screenshot, assess against the litmus checks, fix any glaring issues, and move on. Include the screenshot in the deliverable (PR description, conversation output, etc.).
+
+For iterative refinement beyond a single pass (multiple rounds of screenshot-assess-fix), see the `systematic:design:design-iterator` agent.
+
+---
+
+## Creative Energy
+
+This skill provides structure, but the goal is distinctive work that avoids AI slop -- not formulaic output.
 
-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.
+For greenfield work, commit to a bold aesthetic direction. Consider the tone: brutally minimal, maximalist, retro-futuristic, organic/natural, luxury/refined, playful, editorial, brutalist, art deco, soft/pastel, industrial -- or invent something that fits the context. There are endless flavors. Use these for inspiration but design one that is true to the project.
 
-**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+Ask: what makes this unforgettable? What is the one thing someone will remember?
 
-Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
+Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well, not from intensity.