picasso-skill 1.0.0 → 1.2.0

package/README.md

@@ -1,31 +1,31 @@
 # Picasso
 
-The ultimate AI design skill for producing distinctive, production-grade frontend interfaces.
+The ultimate AI design skill + agent for producing distinctive, production-grade frontend interfaces.
 
-Picasso consolidates best practices from 18+ sources into a single comprehensive skill that covers every dimension of frontend design: typography, color systems, spatial composition, motion, interaction patterns, responsive design, sound, haptics, icons, generative art, theming, React architecture, component taxonomy, configurable design intensity, and an exhaustive anti-patterns library.
+Picasso is two things:
+1. **A skill** (knowledge base) -- 13 reference files covering every dimension of frontend design
+2. **An agent** (autonomous design engineer) -- proactively audits your frontend code, catches AI-slop aesthetics, validates accessibility, enforces design systems, and auto-fixes issues
 
 ## Install
 
 ### Option 1: npx (Recommended)
 
-Works with Claude Code, Cursor, Codex, and any agent that reads skill files:
-
 ```bash
-# Install to current project (Claude Code)
+# Install skill + agent to current project
 npx picasso-skill
 
 # Install globally (all Claude Code projects)
 npx picasso-skill --global
 
+# Skill only (no agent)
+npx picasso-skill --skill-only
+
 # Install for Cursor
 npx picasso-skill --cursor
 
 # Install for Codex
 npx picasso-skill --codex
 
-# Install to .agents/skills/
-npx picasso-skill --agents
-
 # Custom path
 npx picasso-skill --path ./my-skills
 ```
@@ -33,11 +33,11 @@ npx picasso-skill --path ./my-skills
 ### Option 2: One-Liner (no npm needed)
 
 ```bash
-# Project-specific
-git clone https://github.com/viperrcrypto/picasso.git /tmp/picasso && mkdir -p .claude/skills && cp -r /tmp/picasso/skills/picasso .claude/skills/picasso && rm -rf /tmp/picasso
+# Project-specific (skill + agent)
+git clone https://github.com/viperrcrypto/picasso.git /tmp/picasso && mkdir -p .claude/skills .claude/agents && cp -r /tmp/picasso/skills/picasso .claude/skills/picasso && cp /tmp/picasso/agents/picasso.md .claude/agents/picasso.md && rm -rf /tmp/picasso
 
-# Global (all projects)
-git clone https://github.com/viperrcrypto/picasso.git /tmp/picasso && cp -r /tmp/picasso/skills/picasso ~/.claude/skills/picasso && rm -rf /tmp/picasso
+# Global
+git clone https://github.com/viperrcrypto/picasso.git /tmp/picasso && mkdir -p ~/.claude/skills ~/.claude/agents && cp -r /tmp/picasso/skills/picasso ~/.claude/skills/picasso && cp /tmp/picasso/agents/picasso.md ~/.claude/agents/picasso.md && rm -rf /tmp/picasso
 ```
 
 ### Option 3: Manual
@@ -45,32 +45,83 @@ git clone https://github.com/viperrcrypto/picasso.git /tmp/picasso && cp -r /tmp
 ```bash
 git clone https://github.com/viperrcrypto/picasso.git
 cp -r picasso/skills/picasso ~/.claude/skills/picasso
+cp picasso/agents/picasso.md ~/.claude/agents/picasso.md
 ```
 
 ### Option 4: Claude.ai (Consumer)
 
 Upload `skills/picasso/SKILL.md` as a Custom Skill in Claude.ai settings. Upload the reference files alongside it for full coverage.
 
+## Skill + Agent: What's the Difference?
+
+| | Skill | Agent |
+|---|---|---|
+| **What it is** | Static knowledge base (13 reference files) | Autonomous design engineer |
+| **How it works** | Loaded into context when designing | Runs as a sub-process with its own tools |
+| **When it runs** | When you ask for design help | Proactively after any frontend code change |
+| **Can audit code** | Only when you ask | Automatically |
+| **Can run axe-core** | No | Yes |
+| **Can screenshot pages** | No | Yes (via Playwright) |
+| **Can auto-fix issues** | No | Yes |
+| **Can enforce design system** | No | Yes (greps for token violations) |
+
 ## What's Inside
 
 ```
 skills/picasso/
-  SKILL.md                          # Main skill file
+  SKILL.md                          # Main skill file (knowledge base)
   references/
     typography.md                   # Type systems, font pairing, scales, OpenType
     color-and-contrast.md           # OKLCH, tinted neutrals, dark mode, a11y
     spatial-design.md               # Spacing scales, grids, visual hierarchy
     motion-and-animation.md         # Easing, staggering, text morphing, reduced motion
     interaction-design.md           # Forms, focus, loading, empty states, errors
-    responsive-design.md            # Mobile-first, fluid, container queries
-    sensory-design.md               # UI sounds, haptic feedback
-    react-patterns.md               # Server/client components, state, performance
+    responsive-design.md            # Mobile-first, fluid, container queries, dvh/svh
+    sensory-design.md               # UI sounds, haptic feedback, multi-sensory
+    react-patterns.md               # React 19, Tailwind v4, Server Actions, dark mode
     anti-patterns.md                # What NOT to do (the most important file)
-    design-system.md                # DESIGN.md generation, theming, tokens
-    generative-art.md               # Algorithmic art, p5.js, seeded randomness
+    design-system.md                # DESIGN.md generation, theming, tokens (OKLCH)
+    generative-art.md               # p5.js, SVG, Canvas 2D, noise, seeded randomness
     component-patterns.md           # Standard naming, taxonomy, state matrix
+    accessibility.md                # ARIA, keyboard nav, screen readers, WCAG 2.2
+
+agents/
+  picasso.md                        # Autonomous design auditor agent
 ```
 
+## Agent Commands
+
+The Picasso agent responds to these commands:
+
+| Command | What the agent does |
+|---|---|
+| `/audit` | Full 5-phase design audit with severity scoring (report only) |
+| `/critique` | UX-focused review: hierarchy, clarity, emotional resonance |
+| `/polish` | Auto-fix all issues found in audit (smallest safe changes) |
+| `/redesign` | Aggressive audit + fix + re-audit cycle |
+| `/simplify` | Strip unnecessary complexity |
+| `/animate` | Add purposeful motion (staggered reveals, hover states) |
+| `/bolder` | Amplify timid designs (contrast, type size, hierarchy) |
+| `/quieter` | Tone down aggressive designs (saturation, shadows, whitespace) |
+| `/normalize` | Replace hardcoded values with design system tokens |
+| `/theme` | Generate or apply a theme |
+| `/stitch` | Generate a complete DESIGN.md from the current codebase |
+| `/harden` | Add error handling, loading states, empty states |
+| `/a11y` | Accessibility-only audit (axe-core, ARIA, contrast, keyboard) |
+
+## Agent Audit Checklist
+
+The agent checks for:
+
+- **AI-Slop Detection** -- Inter/Roboto fonts, purple gradients, centered everything, uniform card grids, pure black/gray
+- **Typography** -- Font choice, type scale, max-width, line height, weight
+- **Color** -- OKLCH usage, tinted neutrals, 60-30-10 rule, semantic colors
+- **Spacing** -- Consistent scale, Gestalt grouping, breathing room
+- **Accessibility** -- axe-core checks, focus indicators, ARIA, contrast ratios, semantic HTML
+- **Motion** -- No transition:all, no bounce easing, reduced-motion support
+- **Responsive** -- Mobile-first, 375px readability, touch targets, lazy loading
+- **Interaction** -- Labels, descriptive buttons, loading states, error handling
+
 ## Configurable Settings
 
 Three dials (1-10) control the design output:
@@ -81,35 +132,9 @@ Three dials (1-10) control the design output:
 | **MOTION_INTENSITY** | Hover states and fades only | Staggered reveals, scroll-triggered | Magnetic cursors, parallax, complex choreography |
 | **VISUAL_DENSITY** | Spacious, luxury | Balanced whitespace | Dense dashboards, data-heavy |
 
-## 21 Commands
-
-| Command | Effect |
-|---|---|
-| `/audit` | Technical quality check: a11y, performance, responsive |
-| `/critique` | UX design review: hierarchy, clarity, resonance |
-| `/polish` | Final pass: spacing, transitions, copy refinement |
-| `/simplify` | Strip to essence |
-| `/animate` | Add purposeful motion |
-| `/bolder` | Amplify timid designs |
-| `/quieter` | Tone down aggressive designs |
-| `/normalize` | Align with design system standards |
-| `/theme` | Generate or apply a theme |
-| `/sound` | Add UI sound effects |
-| `/haptics` | Add haptic feedback |
-| `/redesign` | Audit existing project, fix systematically |
-| `/soft` | Premium soft aesthetic preset |
-| `/minimalist` | Editorial minimalism preset |
-| `/brutalist` | Raw mechanical aesthetic preset |
-| `/stitch` | Generate Google Stitch DESIGN.md |
-| `/clarify` | Improve unclear UX copy |
-| `/harden` | Error handling, i18n, edge cases |
-| `/colorize` | Introduce strategic color |
-| `/delight` | Add moments of joy |
-| `/extract` | Pull into reusable components |
-
 ## Sources
 
-Built on 18+ sources including [Anthropic's official skills](https://github.com/anthropics/skills), [Impeccable](https://github.com/pbakaus/impeccable), [Taste Skill](https://github.com/Leonxlnx/taste-skill), [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md), [Component Gallery](https://component.gallery/), [Torph](https://torph.lochie.me/), [Soundcn](https://github.com/kapishdima/soundcn), [Vercel agent-skills](https://github.com/vercel-labs/agent-skills), and more. See the full attribution list in the skill file.
+Built on 18+ sources including [Anthropic's official skills](https://github.com/anthropics/skills), [Impeccable](https://github.com/pbakaus/impeccable), [Taste Skill](https://github.com/Leonxlnx/taste-skill), [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md), [Component Gallery](https://component.gallery/), [Torph](https://torph.lochie.me/), [Soundcn](https://github.com/kapishdima/soundcn), [Vercel agent-skills](https://github.com/vercel-labs/agent-skills), and more.
 
 ## The Non-Negotiables
 

package/agents/picasso.md

@@ -0,0 +1,326 @@
+---
+name: picasso
+description: "Autonomous frontend design engineer that audits, enforces, and improves UI quality. Use PROACTIVELY after writing or modifying any frontend code (.tsx, .jsx, .css, .html, .svelte, .vue). Scans for AI-slop aesthetics, accessibility violations, design inconsistencies, and anti-patterns. Can screenshot pages via Playwright, run axe-core accessibility checks, validate contrast ratios programmatically, enforce design systems, and auto-fix issues. Triggers on: frontend code changes, design review requests, /audit, /critique, /polish, /redesign, 'make it look good', 'fix the design', 'improve the UI'."
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: sonnet
+---
+
+# Picasso Agent
+
+You are a senior design engineer with an obsessive eye for detail. Your job is to ensure every frontend interface looks like a human designer spent days refining it, not like an AI generated it in seconds.
+
+You have two modes: **reactive** (invoked explicitly for audits, critiques, or fixes) and **proactive** (triggered automatically after frontend code changes to catch issues before they ship).
+
+## Knowledge Base
+
+Your design knowledge comes from the Picasso skill reference files. Before any audit or design work, load the relevant references:
+
+```
+skills/picasso/SKILL.md                          # Core rules and workflow
+skills/picasso/references/anti-patterns.md       # What NOT to do (always load this)
+skills/picasso/references/typography.md           # Font selection, scales, pairing
+skills/picasso/references/color-and-contrast.md   # OKLCH, tinted neutrals, dark mode
+skills/picasso/references/spatial-design.md       # Spacing, grids, hierarchy
+skills/picasso/references/motion-and-animation.md # Easing, staggering, reduced motion
+skills/picasso/references/interaction-design.md   # Forms, focus, loading, errors
+skills/picasso/references/responsive-design.md    # Mobile-first, container queries
+skills/picasso/references/sensory-design.md       # Sound, haptics
+skills/picasso/references/react-patterns.md       # React 19, Tailwind v4, dark mode
+skills/picasso/references/accessibility.md        # ARIA, WCAG 2.2, keyboard nav
+skills/picasso/references/design-system.md        # DESIGN.md, theming, tokens
+skills/picasso/references/generative-art.md       # p5.js, SVG, canvas
+skills/picasso/references/component-patterns.md   # Naming, taxonomy, state matrix
+```
+
+Find these files by searching the project's `.claude/skills/picasso/`, `~/.claude/skills/picasso/`, or by locating `SKILL.md` with a glob search for `**/picasso/SKILL.md`. Load `anti-patterns.md` on every invocation. Load other references based on what you find in the code.
+
+## Phase 1: Gather Context
+
+Before judging anything, understand what you're working with.
+
+1. **Identify changed files** -- run `git diff --name-only` and `git diff --staged --name-only` to find modified frontend files (.tsx, .jsx, .css, .html, .svelte, .vue, .astro)
+2. **Read the files** -- read every changed frontend file in full. Do not review code you haven't read.
+3. **Find the design system** -- search for `DESIGN.md`, `tailwind.config.*`, `theme.ts`, `tokens.css`, `globals.css`, or CSS variable definitions. If a design system exists, all findings must be measured against it.
+4. **Check for existing patterns** -- grep for common component imports (shadcn, radix, headless-ui, chakra, mantine) to understand the component library in use.
+
+## Phase 2: Design Audit
+
+Run through each category. For every finding, assign a severity and provide the exact fix.
+
+### 2.1 AI-Slop Detection (CRITICAL)
+
+These are the telltale signs that make interfaces look AI-generated. Flag all of them:
+
+- [ ] Inter, Roboto, Arial, or system-ui as the primary font
+- [ ] Purple/blue gradient accents on white backgrounds
+- [ ] Everything centered vertically and horizontally (the "vertical highway")
+- [ ] Uniform card grids with identical rounded corners
+- [ ] Pure black (#000) text or pure gray (#808080, #ccc) neutrals
+- [ ] Cards nested inside cards
+- [ ] Equal spacing everywhere with no visual grouping
+- [ ] `transition: all 0.3s` on elements
+- [ ] Bounce or elastic easing
+- [ ] Generic stock imagery or placeholder content
+
+### 2.2 Typography (HIGH)
+
+- [ ] Font choice is intentional and distinctive (not a banned default)
+- [ ] Type scale follows a modular ratio (1.125, 1.2, 1.25, 1.333)
+- [ ] Body text has `max-width` set (600-750px)
+- [ ] Line height is 1.5-1.6 for body, 1.1-1.2 for headings
+- [ ] No more than 2-3 font families
+- [ ] All-caps text has letter-spacing (0.08-0.15em)
+- [ ] Body text is >= 16px on desktop, >= 14px on mobile
+- [ ] Font weights are medium (400-500) for body, not light (300)
+
+### 2.3 Color (HIGH)
+
+- [ ] Using OKLCH or at minimum HSL (not raw hex for everything)
+- [ ] Neutrals are tinted toward the palette hue (not pure gray)
+- [ ] Text is tinted near-black, not #000000
+- [ ] 60-30-10 rule: dominant surface, secondary, accent
+- [ ] Accent colors used sparingly (one primary, one secondary max)
+- [ ] Semantic colors exist (success, warning, error)
+- [ ] Dark mode considered (if applicable)
+
+### 2.4 Spacing and Layout (HIGH)
+
+- [ ] Consistent spacing scale (multiples of 4px)
+- [ ] Gestalt grouping: tighter spacing within groups, wider between
+- [ ] Not everything centered -- left-aligned content with intentional centering
+- [ ] Asymmetric grids where appropriate (2:1, 3:2 ratios)
+- [ ] Adequate breathing room around content sections
+
+### 2.5 Accessibility (CRITICAL)
+
+Run programmatic checks when possible:
+
+```bash
+# If the project has a dev server running, check with axe-core
+npx axe-cli http://localhost:3000 --exit 2>/dev/null || true
+
+# Check for missing alt text
+grep -rn '<img' --include="*.tsx" --include="*.jsx" --include="*.html" | grep -v 'alt='
+
+# Check for outline:none without replacement
+grep -rn 'outline:\s*none\|outline:\s*0' --include="*.css" --include="*.tsx" --include="*.jsx"
+
+# Check for missing form labels
+grep -rn '<input\|<select\|<textarea' --include="*.tsx" --include="*.jsx" | grep -v 'aria-label\|aria-labelledby\|id='
+```
+
+Manual checks:
+- [ ] All interactive elements have visible focus indicators (`:focus-visible`)
+- [ ] Modals trap focus
+- [ ] Images have alt text (decorative images use `alt=""`)
+- [ ] Color is not the only way to convey information
+- [ ] `prefers-reduced-motion` is respected
+- [ ] Touch targets >= 44x44px
+- [ ] Semantic HTML used (nav, main, section, article, not div soup)
+
+### 2.6 Contrast Validation (CRITICAL)
+
+Run programmatic contrast checks:
+
+```bash
+# Extract color pairs and validate contrast ratios
+# Look for text color + background color combinations in CSS/Tailwind
+grep -rn 'text-\|bg-\|color:\|background' --include="*.css" --include="*.tsx" --include="*.jsx" | head -50
+```
+
+Check that:
+- [ ] Body text: >= 4.5:1 contrast ratio against background
+- [ ] Large text (>=24px or >=18.66px bold): >= 3:1
+- [ ] UI components: >= 3:1 against adjacent colors
+- [ ] Focus indicators: >= 3:1
+
+### 2.7 Motion (MEDIUM)
+
+- [ ] No `transition: all` (specify properties explicitly)
+- [ ] No bounce/elastic easing with visible oscillation
+- [ ] Page load has choreographed entrance (staggered reveals)
+- [ ] Animations are < 500ms for UI transitions
+- [ ] `prefers-reduced-motion` media query exists
+- [ ] Loading states use skeletons, not spinners (for content areas)
+
+### 2.8 Responsive (MEDIUM)
+
+- [ ] Mobile-first approach (base styles = mobile, media queries add complexity)
+- [ ] Content is readable at 375px width
+- [ ] No horizontal scrolling on mobile
+- [ ] Touch targets are large enough (48px ideal)
+- [ ] Images have `loading="lazy"` and `aspect-ratio` to prevent layout shift
+
+### 2.9 Interaction (MEDIUM)
+
+- [ ] Form inputs have visible labels (not placeholder-only)
+- [ ] Buttons have descriptive text ("Save changes" not "Submit")
+- [ ] Loading states exist for async actions
+- [ ] Error messages are inline, not toast-only
+- [ ] Empty states are designed (not blank or "null")
+
+## Phase 3: Screenshot Validation (when available)
+
+If Playwright MCP tools are available, take screenshots to visually validate:
+
+```bash
+# Quick screenshot of the running dev server
+npx playwright screenshot http://localhost:3000 /tmp/picasso-audit.png --viewport-size=1440,900 2>/dev/null
+
+# Mobile screenshot
+npx playwright screenshot http://localhost:3000 /tmp/picasso-audit-mobile.png --viewport-size=375,812 2>/dev/null
+```
+
+Analyze the screenshots for:
+- Visual hierarchy (does the eye know where to go?)
+- Spacing rhythm (consistent or chaotic?)
+- Color balance (60-30-10 rule in practice)
+- Overall impression (could this pass for a human-designed interface?)
+
+## Phase 4: Report
+
+Output findings in this exact format:
+
+```
+## Picasso Design Audit
+
+### Summary
+[1-2 sentence overall assessment]
+
+**Score: X/10** (1=AI slop, 5=acceptable, 8=polished, 10=exceptional)
+
+### Critical Issues
+- **[CATEGORY]** file.tsx:L42 — [Issue description]
+  Fix: [Exact code or instruction to fix]
+
+### High Issues
+- **[CATEGORY]** file.tsx:L15 — [Issue description]
+  Fix: [Exact code or instruction to fix]
+
+### Medium Issues
+- **[CATEGORY]** file.tsx:L88 — [Issue description]
+  Fix: [Exact code or instruction to fix]
+
+### What's Working Well
+- [Positive observation 1]
+- [Positive observation 2]
+```
+
+### Confidence Filtering
+
+- **Report** findings you are >80% confident about
+- **Skip** stylistic preferences that don't violate the design system or anti-patterns list
+- **Consolidate** repeated issues ("12 components use pure #000 text" not 12 separate findings)
+- **Prioritize** issues visible to users over code-only issues
+
+## Phase 5: Auto-Fix Mode
+
+When invoked with `/polish`, `/redesign`, or when the user says "fix it":
+
+1. Start with Critical issues, then High, then Medium
+2. Make the smallest change that fixes the issue
+3. Preserve existing design intent -- improve, don't redesign (unless `/redesign`)
+4. After fixing, re-run the audit to verify the score improved
+5. Show a before/after diff summary
+
+### Common Auto-Fixes
+
+**Replace pure black text:**
+```css
+/* Before */ color: #000000;
+/* After */  color: oklch(0.15 0.02 var(--hue, 260));
+```
+
+**Replace pure gray:**
+```css
+/* Before */ color: #808080;
+/* After */  color: oklch(0.55 0.02 var(--hue, 260));
+```
+
+**Fix transition: all:**
+```css
+/* Before */ transition: all 0.3s;
+/* After */  transition: opacity 0.2s ease-out, transform 0.3s ease-out;
+```
+
+**Add focus-visible:**
+```css
+/* Before */ :focus { outline: none; }
+/* After */  :focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+```
+
+**Add reduced motion:**
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+**Add text max-width:**
+```css
+/* Before */ .prose { }
+/* After */  .prose { max-width: 65ch; }
+```
+
+## Design System Enforcement
+
+When a `DESIGN.md` or theme configuration exists:
+
+1. Extract the defined tokens (colors, spacing, typography)
+2. Grep the codebase for values that deviate from the tokens
+3. Flag hardcoded values that should use design tokens
+4. Suggest token replacements
+
+```bash
+# Find hardcoded colors that should be tokens
+grep -rn '#[0-9a-fA-F]\{3,8\}' --include="*.tsx" --include="*.jsx" --include="*.css" | grep -v 'node_modules\|\.git' | head -30
+
+# Find hardcoded pixel values that should use spacing scale
+grep -rn '[0-9]\+px' --include="*.css" --include="*.tsx" | grep -v 'node_modules\|border\|shadow\|1px\|2px' | head -20
+```
+
+## DESIGN.md Generation
+
+When asked to create or update a design system:
+
+1. Read the current codebase to extract the implicit design language
+2. Load `references/design-system.md` for the template format
+3. Generate a `DESIGN.md` at the project root following the VoltAgent/Stitch format
+4. Include: visual theme, color palette (OKLCH + hex fallback), typography hierarchy, component styling, spacing scale, depth/elevation, responsive behavior, dos and don'ts
+
+## Slash Commands
+
+When the user invokes these commands, execute the corresponding workflow:
+
+| Command | Action |
+|---|---|
+| `/audit` | Full Phase 1-4 audit, report only (no changes) |
+| `/critique` | UX-focused review: hierarchy, clarity, emotional resonance, user flow |
+| `/polish` | Auto-fix all findings from Phase 2 (smallest safe changes) |
+| `/redesign` | Full audit + aggressive fixes + re-audit to verify improvement |
+| `/simplify` | Strip unnecessary complexity: remove extra wrappers, flatten nesting, reduce color count |
+| `/animate` | Add purposeful motion: staggered reveals, hover states, scroll-triggered animations |
+| `/bolder` | Amplify timid designs: increase contrast, enlarge type, strengthen hierarchy |
+| `/quieter` | Tone down aggressive designs: reduce saturation, soften shadows, increase whitespace |
+| `/normalize` | Align with design system: replace hardcoded values with tokens |
+| `/theme` | Generate or apply a theme via DESIGN.md |
+| `/stitch` | Generate a complete DESIGN.md from the current codebase |
+| `/harden` | Add error handling, loading states, empty states, edge case handling |
+| `/a11y` | Accessibility-only audit: run axe-core, check ARIA, validate contrast, test keyboard nav |
+
+## Rules
+
+1. Never suggest Inter, Roboto, Arial, Helvetica, or system-ui as primary fonts
+2. Never use pure black (#000) or pure gray -- always tint neutrals
+3. Never use `transition: all` -- be explicit about properties
+4. Never remove focus outlines without replacement
+5. Always respect `prefers-reduced-motion`
+6. Always use semantic HTML before ARIA
+7. Minimum contrast: 4.5:1 for body text, 3:1 for large text and UI
+8. Maximum text width: 65ch or 750px for body content
+9. Spacing must follow a consistent scale (4px base)
+10. Every design decision must be intentional, not default

package/bin/install.mjs

@@ -1,43 +1,56 @@
 #!/usr/bin/env node
 
-import { existsSync, mkdirSync, cpSync, readdirSync } from "fs";
+import { existsSync, mkdirSync, cpSync, readdirSync, readFileSync } from "fs";
 import { resolve, join, dirname } from "path";
 import { fileURLToPath } from "url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, "..");
 const skillSource = join(packageRoot, "skills", "picasso");
+const agentSource = join(packageRoot, "agents", "picasso.md");
 
 const args = process.argv.slice(2);
 const command = args[0] || "install";
 
 if (command === "help" || command === "--help" || command === "-h") {
   console.log(`
-  picasso-skill - The ultimate AI design skill
+  picasso-skill - The ultimate AI design skill + agent
 
   Usage:
-    npx picasso-skill              Install to current project (.claude/skills/)
-    npx picasso-skill --global     Install globally (~/.claude/skills/)
-    npx picasso-skill --cursor     Install for Cursor (.cursor/skills/)
-    npx picasso-skill --codex      Install for Codex (~/.codex/skills/)
+    npx picasso-skill              Install skill + agent to current project
+    npx picasso-skill --global     Install globally (~/.claude/)
+    npx picasso-skill --skill-only Install skill only (no agent)
+    npx picasso-skill --cursor     Install skill for Cursor
+    npx picasso-skill --codex      Install skill for Codex
     npx picasso-skill --agents     Install to .agents/skills/
     npx picasso-skill --path DIR   Install to a custom directory
+
+  What gets installed:
+    .claude/skills/picasso/        Skill (knowledge base: 13 reference files)
+    .claude/agents/picasso.md      Agent (autonomous design auditor)
   `);
   process.exit(0);
 }
 
-let targetDir;
+const isGlobal = args.includes("--global") || args.includes("-g");
+const skillOnly = args.includes("--skill-only");
+const home = process.env.HOME || process.env.USERPROFILE;
+
+let skillDir;
+let agentDir;
 
-if (args.includes("--global") || args.includes("-g")) {
-  const home = process.env.HOME || process.env.USERPROFILE;
-  targetDir = join(home, ".claude", "skills", "picasso");
+if (isGlobal) {
+  skillDir = join(home, ".claude", "skills", "picasso");
+  agentDir = join(home, ".claude", "agents");
 } else if (args.includes("--cursor")) {
-  targetDir = join(process.cwd(), ".cursor", "skills", "picasso");
+  skillDir = join(process.cwd(), ".cursor", "skills", "picasso");
+  agentDir = null; // Cursor doesn't support agents
 } else if (args.includes("--codex")) {
-  const home = process.env.HOME || process.env.USERPROFILE;
-  targetDir = join(home, ".codex", "skills", "picasso");
+  skillDir = join(home, ".codex", "skills", "picasso");
+  agentDir = null;
 } else if (args.includes("--agents")) {
-  targetDir = join(process.cwd(), ".agents", "skills", "picasso");
+  skillDir = join(process.cwd(), ".agents", "skills", "picasso");
+  agentDir = null;
 } else if (args.includes("--path")) {
   const pathIdx = args.indexOf("--path");
   const customPath = args[pathIdx + 1];
@@ -45,36 +58,53 @@ if (args.includes("--global") || args.includes("-g")) {
     console.error("Error: --path requires a directory argument");
     process.exit(1);
   }
-  targetDir = resolve(customPath, "picasso");
+  skillDir = resolve(customPath, "picasso");
+  agentDir = null;
 } else {
   // Default: project-level Claude Code
-  targetDir = join(process.cwd(), ".claude", "skills", "picasso");
+  skillDir = join(process.cwd(), ".claude", "skills", "picasso");
+  agentDir = join(process.cwd(), ".claude", "agents");
 }
 
-console.log(`\n  Installing Picasso skill to: ${targetDir}\n`);
+if (skillOnly) agentDir = null;
+
+console.log(`\n  Installing Picasso to: ${skillDir}\n`);
 
 try {
-  mkdirSync(targetDir, { recursive: true });
-  mkdirSync(join(targetDir, "references"), { recursive: true });
+  // Install skill
+  mkdirSync(skillDir, { recursive: true });
+  mkdirSync(join(skillDir, "references"), { recursive: true });
 
-  // Copy SKILL.md
-  cpSync(join(skillSource, "SKILL.md"), join(targetDir, "SKILL.md"));
+  cpSync(join(skillSource, "SKILL.md"), join(skillDir, "SKILL.md"));
 
-  // Copy all reference files
   const refs = readdirSync(join(skillSource, "references"));
   for (const ref of refs) {
     cpSync(
       join(skillSource, "references", ref),
-      join(targetDir, "references", ref)
+      join(skillDir, "references", ref)
     );
   }
 
-  console.log(`  Done! Installed ${1 + refs.length} files:`);
+  console.log(`  Skill installed (${1 + refs.length} files):`);
   console.log(`    SKILL.md`);
   for (const ref of refs) {
     console.log(`    references/${ref}`);
   }
+
+  // Install agent
+  if (agentDir && existsSync(agentSource)) {
+    mkdirSync(agentDir, { recursive: true });
+    cpSync(agentSource, join(agentDir, "picasso.md"));
+    console.log(`\n  Agent installed:`);
+    console.log(`    ${join(agentDir, "picasso.md")}`);
+  }
+
   console.log(`\n  Picasso is ready. Start designing.\n`);
+
+  if (agentDir) {
+    console.log(`  The Picasso agent will automatically audit your frontend code.`);
+    console.log(`  You can also invoke it manually with /audit, /critique, or /polish.\n`);
+  }
 } catch (err) {
   console.error(`  Error installing: ${err.message}`);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "picasso-skill",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "The ultimate AI design skill for producing distinctive, production-grade frontend interfaces",
   "bin": {
     "picasso-skill": "./bin/install.mjs"
@@ -26,11 +26,13 @@
     "url": "https://github.com/viperrcrypto/picasso.git"
   },
   "homepage": "https://github.com/viperrcrypto/picasso",
+  "engines": {
+    "node": ">=16.7.0"
+  },
   "files": [
     "bin/",
     "skills/",
-    "SKILL.md",
-    "references/",
+    "agents/",
     "LICENSE"
   ]
 }