bigpowers 2.42.1 → 2.43.1

package/.pi/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bigpowers",
-  "version": "2.42.1",
-  "description": "71 skills — 70 agent skills for spec-driven, test-first software development by solo developers",
+  "version": "2.43.1",
+  "description": "72 skills — 70 agent skills for spec-driven, test-first software development by solo developers",
   "keywords": [
     "pi-package"
   ],

package/.pi/prompts/extract-design.md

@@ -0,0 +1,131 @@
+---
+description: "Extract a Google DESIGN.md file from an HTML prototype (claude.ai/design or any styled page) using Puppeteer, producing machine-readable tokens and AI-generated prose. Use when the user has an HTML prototype and wants a DESIGN.md to anchor their project's visual identity, or when seed-conventions has just scaffolded a new project."
+---
+
+
+# Extract DESIGN.md from HTML
+
+> **HARD GATE** — Do NOT write DESIGN.md without Puppeteer dual-pass extraction. Tokens from static HTML (Cheerio, regex, string scanning) are invalid — they miss cascade, custom properties, and Tailwind resolution.
+>
+> **HARD GATE** — Do NOT claim certainty where evidence is thin. Low-confidence color roles, component classifications, and prose assertions MUST be flagged with `<!-- AGENT NOTE: uncertain — validate during grill-me. Evidence: [what was observed] -->`.
+>
+> **HARD GATE** — Do NOT ship DESIGN.md without running `npx @google/design.md lint`. Unvalidated output is unverified output. If lint is unavailable (offline), flag prominently in terminal and in DESIGN.md prose.
+
+## Quick Start
+
+```bash
+# First run — extract from HTML prototype
+node extract-design/scripts/extract.js --source ./prototype.html
+
+# From a published URL
+node extract-design/scripts/extract.js --source https://my-prototype.example.com
+
+# With a custom name
+node extract-design/scripts/extract.js --source ./proto.html --name "My Design System"
+
+# Update — re-extract from new HTML, diff against existing
+node extract-design/scripts/extract.js --source ./proto-v2.html
+
+# Lint-only — validate existing DESIGN.md without re-extraction
+node extract-design/scripts/extract.js --lint-only
+```
+
+## Flow
+
+1. **Launch Puppeteer** — dual-pass (light + dark) with retry + timeout. CI flags: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`.
+2. **Collect styles** — `page.evaluate()` collects computed styles from every element. Returns raw JSON to Node.js. Browser = sensor; Node = brain.
+3. **Classify tokens** — modular pipeline: colors (Material 3 roles), typography (scale detection), spacing (tolerance GCD), rounded (clustering), components (visual signature + pseudo-state variants).
+4. **Generate prose** — AI heuristics produce all 8 DESIGN.md sections. Overview and Do's/Don'ts flagged with agent notes.
+5. **Write + validate** — serialize to `specs/tech-architecture/DESIGN_LATEST.md`, run `npx @google/design.md lint`, report to terminal.
+6. **Handoff** — writes `handoff.next_skill: grill-me` to `specs/state.yaml` with uncertain decisions context.
+
+## Inputs
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--source <file\|url>` | First run: yes. Update: optional | HTML prototype path or URL |
+| `--name <string>` | No | Design system name (defaults to `<title>` or directory name) |
+| `--lint-only` | No | Validate existing DESIGN.md without re-extraction |
+
+## Output
+
+- `specs/tech-architecture/DESIGN_LATEST.md` — replaces `DESIGN_PLAN_LATEST.md` as the canonical design artifact
+- Terminal summary: token counts, component count, lint result, uncertain decisions
+- Structured JSON log to stderr: extraction events, timing, counts
+- `specs/state.yaml` → `handoff.next_skill: grill-me` with context
+
+## Error Tiers
+
+| Tier | Condition | Response |
+|------|-----------|----------|
+| Fatal | No Chrome, page load timeout after retries | Exit non-zero, suggest fixes |
+| Degraded | Zero colors, zero typography, SPA shell | Write DESIGN.md with degradation warning |
+| Warned | Lint errors, uncertain decisions | Write DESIGN.md, flag in terminal, hand off to grill-me |
+
+## Dependencies
+
+- **Puppeteer** (Chrome binary) — wrapped behind `BrowserExtractor` interface for testability
+- **`@google/design.md`** (soft, via `npx`) — wrapped behind `DesignValidator` interface. Warns and skips if offline.
+
+## verify
+
+```bash
+node extract-design/tests/test-extraction.js
+```
+
+See [REFERENCE.md](REFERENCE.md) for extraction algorithms and heuristics.
+
+---
+
+# Extract Design — Reference
+
+## Extraction Algorithms
+
+### Color Classification
+1. Collect unique computed `background-color`, `color`, `border-color` from every DOM element.
+2. Count frequency and context (text vs. bg vs. border vs. button).
+3. Classify using Material 3 roles: surface = largest-area bg, on-surface = most-used text, tertiary = highest-saturation on CTAs, error = reddish.
+4. Surface container levels: luminance-ordered. Hard-cap at 3 unless data supports 5.
+5. Low-confidence → `<!-- AGENT NOTE -->` in Colors prose.
+
+### Typography Classification
+1. Collect unique (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing) tuples.
+2. Cluster by fontSize (±2px) → type scale.
+3. Detect heading hierarchy from HTML tag + computed size.
+4. Name levels: display-lg, headline-lg/md/sm, title-lg, body-lg/md/sm, label-lg/md/sm.
+5. Parse `<link>` and `@font-face`; warn if computed font differs from declared.
+
+### Spacing Classification
+1. Collect unique padding, margin, gap values. Filter: ignore values < 3 occurrences.
+2. Compute tolerance-based GCD (0.5px tolerance).
+3. Declare base unit. Detect half-step if gcd/2 values present ≥3 times.
+4. Map: unit×1 → sm, ×2 → md, ×4 → lg, ×8 → xl.
+
+### Rounded Classification
+1. Collect unique border-radius values. Cluster (1px tolerance).
+2. Name: none (0), sm (smallest), md (median), lg (large), xl (largest), full (9999px).
+
+### Component Detection
+- Button: w<300px, h<64px, bg+radius set, short text. cursor:pointer is bonus.
+- Card: bg+radius+padding set, larger area.
+- Input: `<input>` or `<textarea>` tag.
+- Pseudo-state variants: force :hover, :active, :focus for high-confidence components.
+
+### Prose Generation
+Generates all 8 DESIGN.md sections. Overview and Do's/Don'ts flagged with `<!-- AGENT NOTE: Generated from visual analysis. Grill-me should validate. -->`.
+
+## Material 3 Token Conventions
+Colors: primary, on-primary, secondary, tertiary, error, surface, on-surface, surface-container-*, outline, background, on-background.
+Typography: display-lg/md/sm, headline-lg/md/sm, title-lg/md/sm, body-lg/md/sm, label-lg/md/sm.
+Rounded: none, xs, sm, md, lg, xl, full.
+
+## CI Compatibility
+Chrome flags: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`
+
+## Defensive Code
+Retry with backoff (3 attempts, 1s/2s/4s), Timeout (30s page load, 10s pseudo-state), Graceful degradation (Tier 2 on empty extraction).
+
+## Known Risks
+- DESIGN.md spec is alpha. Skill pins to current spec.
+- Puppeteer is heavy (~300MB Chrome). Document requirement clearly.
+- Prose quality depends on AI heuristics. grill-me is the validation gate.

package/.pi/skills/extract-design/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: extract-design
+description: "\"Extract a Google DESIGN.md file from an HTML prototype (claude.ai/design or any styled page) using Puppeteer, producing machine-readable tokens and AI-generated prose. Use when the user has an HTML prototype and wants a DESIGN.md to anchor their project's visual identity, or when seed-conventions has just scaffolded a new project.\""
+model: sonnet
+---
+
+
+# Extract DESIGN.md from HTML
+
+> **HARD GATE** — Do NOT write DESIGN.md without Puppeteer dual-pass extraction. Tokens from static HTML (Cheerio, regex, string scanning) are invalid — they miss cascade, custom properties, and Tailwind resolution.
+>
+> **HARD GATE** — Do NOT claim certainty where evidence is thin. Low-confidence color roles, component classifications, and prose assertions MUST be flagged with `<!-- AGENT NOTE: uncertain — validate during grill-me. Evidence: [what was observed] -->`.
+>
+> **HARD GATE** — Do NOT ship DESIGN.md without running `npx @google/design.md lint`. Unvalidated output is unverified output. If lint is unavailable (offline), flag prominently in terminal and in DESIGN.md prose.
+
+## Quick Start
+
+```bash
+# First run — extract from HTML prototype
+node extract-design/scripts/extract.js --source ./prototype.html
+
+# From a published URL
+node extract-design/scripts/extract.js --source https://my-prototype.example.com
+
+# With a custom name
+node extract-design/scripts/extract.js --source ./proto.html --name "My Design System"
+
+# Update — re-extract from new HTML, diff against existing
+node extract-design/scripts/extract.js --source ./proto-v2.html
+
+# Lint-only — validate existing DESIGN.md without re-extraction
+node extract-design/scripts/extract.js --lint-only
+```
+
+## Flow
+
+1. **Launch Puppeteer** — dual-pass (light + dark) with retry + timeout. CI flags: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`.
+2. **Collect styles** — `page.evaluate()` collects computed styles from every element. Returns raw JSON to Node.js. Browser = sensor; Node = brain.
+3. **Classify tokens** — modular pipeline: colors (Material 3 roles), typography (scale detection), spacing (tolerance GCD), rounded (clustering), components (visual signature + pseudo-state variants).
+4. **Generate prose** — AI heuristics produce all 8 DESIGN.md sections. Overview and Do's/Don'ts flagged with agent notes.
+5. **Write + validate** — serialize to `specs/tech-architecture/DESIGN_LATEST.md`, run `npx @google/design.md lint`, report to terminal.
+6. **Handoff** — writes `handoff.next_skill: grill-me` to `specs/state.yaml` with uncertain decisions context.
+
+## Inputs
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--source <file\|url>` | First run: yes. Update: optional | HTML prototype path or URL |
+| `--name <string>` | No | Design system name (defaults to `<title>` or directory name) |
+| `--lint-only` | No | Validate existing DESIGN.md without re-extraction |
+
+## Output
+
+- `specs/tech-architecture/DESIGN_LATEST.md` — replaces `DESIGN_PLAN_LATEST.md` as the canonical design artifact
+- Terminal summary: token counts, component count, lint result, uncertain decisions
+- Structured JSON log to stderr: extraction events, timing, counts
+- `specs/state.yaml` → `handoff.next_skill: grill-me` with context
+
+## Error Tiers
+
+| Tier | Condition | Response |
+|------|-----------|----------|
+| Fatal | No Chrome, page load timeout after retries | Exit non-zero, suggest fixes |
+| Degraded | Zero colors, zero typography, SPA shell | Write DESIGN.md with degradation warning |
+| Warned | Lint errors, uncertain decisions | Write DESIGN.md, flag in terminal, hand off to grill-me |
+
+## Dependencies
+
+- **Puppeteer** (Chrome binary) — wrapped behind `BrowserExtractor` interface for testability
+- **`@google/design.md`** (soft, via `npx`) — wrapped behind `DesignValidator` interface. Warns and skips if offline.
+
+## verify
+
+```bash
+node extract-design/tests/test-extraction.js
+```
+
+See [REFERENCE.md](REFERENCE.md) for extraction algorithms and heuristics.
+
+---
+
+# Extract Design — Reference
+
+## Extraction Algorithms
+
+### Color Classification
+1. Collect unique computed `background-color`, `color`, `border-color` from every DOM element.
+2. Count frequency and context (text vs. bg vs. border vs. button).
+3. Classify using Material 3 roles: surface = largest-area bg, on-surface = most-used text, tertiary = highest-saturation on CTAs, error = reddish.
+4. Surface container levels: luminance-ordered. Hard-cap at 3 unless data supports 5.
+5. Low-confidence → `<!-- AGENT NOTE -->` in Colors prose.
+
+### Typography Classification
+1. Collect unique (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing) tuples.
+2. Cluster by fontSize (±2px) → type scale.
+3. Detect heading hierarchy from HTML tag + computed size.
+4. Name levels: display-lg, headline-lg/md/sm, title-lg, body-lg/md/sm, label-lg/md/sm.
+5. Parse `<link>` and `@font-face`; warn if computed font differs from declared.
+
+### Spacing Classification
+1. Collect unique padding, margin, gap values. Filter: ignore values < 3 occurrences.
+2. Compute tolerance-based GCD (0.5px tolerance).
+3. Declare base unit. Detect half-step if gcd/2 values present ≥3 times.
+4. Map: unit×1 → sm, ×2 → md, ×4 → lg, ×8 → xl.
+
+### Rounded Classification
+1. Collect unique border-radius values. Cluster (1px tolerance).
+2. Name: none (0), sm (smallest), md (median), lg (large), xl (largest), full (9999px).
+
+### Component Detection
+- Button: w<300px, h<64px, bg+radius set, short text. cursor:pointer is bonus.
+- Card: bg+radius+padding set, larger area.
+- Input: `<input>` or `<textarea>` tag.
+- Pseudo-state variants: force :hover, :active, :focus for high-confidence components.
+
+### Prose Generation
+Generates all 8 DESIGN.md sections. Overview and Do's/Don'ts flagged with `<!-- AGENT NOTE: Generated from visual analysis. Grill-me should validate. -->`.
+
+## Material 3 Token Conventions
+Colors: primary, on-primary, secondary, tertiary, error, surface, on-surface, surface-container-*, outline, background, on-background.
+Typography: display-lg/md/sm, headline-lg/md/sm, title-lg/md/sm, body-lg/md/sm, label-lg/md/sm.
+Rounded: none, xs, sm, md, lg, xl, full.
+
+## CI Compatibility
+Chrome flags: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`
+
+## Defensive Code
+Retry with backoff (3 attempts, 1s/2s/4s), Timeout (30s page load, 10s pseudo-state), Graceful degradation (Tier 2 on empty extraction).
+
+## Known Risks
+- DESIGN.md spec is alpha. Skill pins to current spec.
+- Puppeteer is heavy (~300MB Chrome). Document requirement clearly.
+- Prose quality depends on AI heuristics. grill-me is the validation gate.

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.43.1](https://github.com/danielvm-git/bigpowers/compare/v2.43.0...v2.43.1) (2026-07-02)
+
+
+### Bug Fixes
+
+* **scripts:** replace declare -A with case for bash 3.2 compatibility ([92dacb6](https://github.com/danielvm-git/bigpowers/commit/92dacb6151a207f659edd2d4f48efc084936fc40))
+
+# [2.43.0](https://github.com/danielvm-git/bigpowers/compare/v2.42.1...v2.43.0) (2026-06-29)
+
+
+### Features
+
+* **skills:** add extract-design skill ([bda7ceb](https://github.com/danielvm-git/bigpowers/commit/bda7ceb113cba610d438dbb95af150b424e674b4))
+
 ## [2.42.1](https://github.com/danielvm-git/bigpowers/compare/v2.42.0...v2.42.1) (2026-06-29)
 
 

package/CONTRIBUTING.md

@@ -0,0 +1,119 @@
+# Contributing to bigpowers
+
+Thanks for your interest in contributing! bigpowers is an open-source system of 69+ AI agent skills for spec-driven, test-first software development. This guide will help you get started.
+
+## Code of Conduct
+
+Be respectful, constructive, and patient. We're building tools for developers — treat each other like the professionals we are.
+
+## Before You Start
+
+1. **Read the docs.** Start with [`README.md`](README.md), [`CLAUDE.md`](CLAUDE.md), and [`CONVENTIONS.md`](CONVENTIONS.md). These define the project's architecture, conventions, and engineering standards.
+2. **Run bigpowers.** Install with `npx bigpowers` and walk through the experience as a user before contributing as a developer.
+3. **Understand the lifecycle.** bigpowers follows a 6-phase methodology: Discover → Elaborate → Plan → Build → Verify → Release. Read [`docs/WORKFLOW-SOP-v2.md`](docs/WORKFLOW-SOP-v2.md) for the full SOP.
+
+## How to Contribute
+
+### Reporting Bugs
+
+- Search [existing issues](https://github.com/danielvm-git/bigpowers/issues) first.
+- Use the bug report template if one exists.
+- Include: what you did, what you expected, what happened, your OS, Node version, and any error output.
+- If the bug is in a specific skill, name the skill.
+
+### Proposing Features
+
+- Open a [discussion](https://github.com/danielvm-git/bigpowers/discussions) before opening a PR for a new feature. We want to align on the approach before you invest time.
+- New skills must follow the [verb-noun kebab-case naming convention](CONVENTIONS.md#skill-naming--conventions-and-exceptions) (ADR-0001).
+- New features should include: a description of the problem, the proposed solution, and any alternatives considered.
+
+### Proposing a New Skill
+
+Skills are the core of bigpowers. To propose a new one:
+
+1. **Check the index.** [`SKILL-INDEX.md`](SKILL-INDEX.md) lists all 69+ active skills. Make sure your idea doesn't overlap with an existing skill.
+2. **Identify the phase.** Every skill belongs to one of 7 phases: Discover, Design, Plan, Build, Verify, Release, Sustain.
+3. **Write a SKILL.md draft.** Follow the structure of existing skills. Every SKILL.md needs: a description, phase, instructions, and references.
+4. **Open a discussion.** Share your SKILL.md draft in a GitHub discussion. We'll review whether it fits the roadmap before you invest in a full PR.
+5. **Once approved,** open a PR with:
+   - A new directory: `[verb]-[noun]/` containing `SKILL.md`
+   - Evidence that you ran `bash scripts/sync-skills.sh` to regenerate artifacts
+   - A Conventional Commit: `feat(skills): add [verb]-[noun] skill`
+
+### Pull Request Process
+
+1. **Branch from main.** Use `kickoff-branch` or create a feature branch manually.
+2. **Follow CONVENTIONS.md.** F.I.R.S.T tests. SOLID. Boy Scout Rule. No `any` types. Functions under 20 lines.
+3. **Run sync.** After any SKILL.md change, run `bash scripts/sync-skills.sh` to regenerate generated artifacts. Do not edit `.cursor/rules` or `.gemini/extensions/` directly.
+4. **Validate YAML.** Run `bash scripts/validate-specs-yaml.sh` if you've changed any `specs/*.yaml` files.
+5. **Write Conventional Commits.** Format: `type(scope): description`. See [CONVENTIONS.md](CONVENTIONS.md#conventional-commits--semantic-versioning) for the full spec.
+6. **Open a PR.** Use `gh pr create`. Include: what you changed, why, how to verify, and any open questions.
+7. **Wait for review.** A maintainer will review within a few days. Be responsive to feedback.
+
+### Writing Documentation
+
+Documentation is a first-class contribution. You don't need to write code to help.
+
+- **README improvements:** Clearer install instructions, better examples, fixed typos.
+- **Skill docs:** Every SKILL.md should be clear enough for a new user to understand without asking.
+- **Guides and tutorials:** Walkthroughs for specific use cases (e.g., "Using bigpowers with a Next.js project").
+- **Translations:** Help make bigpowers accessible to non-English-speaking developers.
+
+## Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/danielvm-git/bigpowers.git
+cd bigpowers
+
+# Install dependencies + run postinstall sync
+npm install
+
+# Or manually:
+bash scripts/install.sh
+npm run sync
+```
+
+### Prerequisites
+
+- **Bash** — required for all scripts
+- **Node.js** v14+
+- **jq** — highly recommended for YAML validation scripts
+- **An AI coding tool** — Claude Code, Cursor, Gemini CLI, or pi (to test skills end-to-end)
+
+### Project Structure
+
+```
+bigpowers/
+├── [skill-name]/       # Each skill has its own directory with SKILL.md
+├── scripts/            # Install, sync, validation, and compliance scripts
+├── specs/              # YAML cockpit — state.yaml, release-plan.yaml, epics/
+├── docs/               # Guides and references
+├── profiles/           # Stack-specific conventions (TypeScript+Vue, Node Service, etc.)
+├── .cursor/rules/      # Generated — do not edit directly
+├── .gemini/extensions/ # Generated — do not edit directly
+└── .pi/skills/         # Generated — do not edit directly
+```
+
+**Never edit generated files.** Always edit the source `SKILL.md` and run `bash scripts/sync-skills.sh`.
+
+## Testing
+
+- **Skill validation:** `bash scripts/sync-skills.sh` validates SKILL.md syntax and structure.
+- **YAML validation:** `bash scripts/validate-specs-yaml.sh` checks the YAML cockpit for correctness.
+- **Compliance check:** `npm run compliance` runs a comprehensive check of the repo.
+- **Manual testing:** The best test of a skill is using it with an AI coding tool. After changes, run `survey-context` or invoke the skill to verify it works.
+
+## Getting Help
+
+- **Questions?** Open a [GitHub discussion](https://github.com/danielvm-git/bigpowers/discussions).
+- **Bug?** Open an [issue](https://github.com/danielvm-git/bigpowers/issues).
+- **Want to chat?** [Link to Discord/Slack — to be added]
+
+## Recognition
+
+All contributors are recognized in the README and release notes. Significant contributions (new skills, major features) get a shoutout in the changelog and on social media. We believe in giving credit where it's due.
+
+---
+
+*bigpowers is MIT-licensed. By contributing, you agree that your contributions will be licensed under the same terms.*

package/SKILL-INDEX.md

@@ -3,8 +3,8 @@
 > **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`.
 > Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate.
 
-**Generated:** 2026-06-29T16:11:17Z
-**Skills:** 71
+**Generated:** 2026-07-02T11:02:02Z
+**Skills:** 72
 
 ---
 

package/extract-design/REFERENCE.md

@@ -0,0 +1,52 @@
+# Extract Design — Reference
+
+## Extraction Algorithms
+
+### Color Classification
+1. Collect unique computed `background-color`, `color`, `border-color` from every DOM element.
+2. Count frequency and context (text vs. bg vs. border vs. button).
+3. Classify using Material 3 roles: surface = largest-area bg, on-surface = most-used text, tertiary = highest-saturation on CTAs, error = reddish.
+4. Surface container levels: luminance-ordered. Hard-cap at 3 unless data supports 5.
+5. Low-confidence → `<!-- AGENT NOTE -->` in Colors prose.
+
+### Typography Classification
+1. Collect unique (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing) tuples.
+2. Cluster by fontSize (±2px) → type scale.
+3. Detect heading hierarchy from HTML tag + computed size.
+4. Name levels: display-lg, headline-lg/md/sm, title-lg, body-lg/md/sm, label-lg/md/sm.
+5. Parse `<link>` and `@font-face`; warn if computed font differs from declared.
+
+### Spacing Classification
+1. Collect unique padding, margin, gap values. Filter: ignore values < 3 occurrences.
+2. Compute tolerance-based GCD (0.5px tolerance).
+3. Declare base unit. Detect half-step if gcd/2 values present ≥3 times.
+4. Map: unit×1 → sm, ×2 → md, ×4 → lg, ×8 → xl.
+
+### Rounded Classification
+1. Collect unique border-radius values. Cluster (1px tolerance).
+2. Name: none (0), sm (smallest), md (median), lg (large), xl (largest), full (9999px).
+
+### Component Detection
+- Button: w<300px, h<64px, bg+radius set, short text. cursor:pointer is bonus.
+- Card: bg+radius+padding set, larger area.
+- Input: `<input>` or `<textarea>` tag.
+- Pseudo-state variants: force :hover, :active, :focus for high-confidence components.
+
+### Prose Generation
+Generates all 8 DESIGN.md sections. Overview and Do's/Don'ts flagged with `<!-- AGENT NOTE: Generated from visual analysis. Grill-me should validate. -->`.
+
+## Material 3 Token Conventions
+Colors: primary, on-primary, secondary, tertiary, error, surface, on-surface, surface-container-*, outline, background, on-background.
+Typography: display-lg/md/sm, headline-lg/md/sm, title-lg/md/sm, body-lg/md/sm, label-lg/md/sm.
+Rounded: none, xs, sm, md, lg, xl, full.
+
+## CI Compatibility
+Chrome flags: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`
+
+## Defensive Code
+Retry with backoff (3 attempts, 1s/2s/4s), Timeout (30s page load, 10s pseudo-state), Graceful degradation (Tier 2 on empty extraction).
+
+## Known Risks
+- DESIGN.md spec is alpha. Skill pins to current spec.
+- Puppeteer is heavy (~300MB Chrome). Document requirement clearly.
+- Prose quality depends on AI heuristics. grill-me is the validation gate.

package/extract-design/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: extract-design
+description: "Extract a Google DESIGN.md file from an HTML prototype (claude.ai/design or any styled page) using Puppeteer, producing machine-readable tokens and AI-generated prose. Use when the user has an HTML prototype and wants a DESIGN.md to anchor their project's visual identity, or when seed-conventions has just scaffolded a new project."
+model: sonnet
+---
+
+# Extract DESIGN.md from HTML
+
+> **HARD GATE** — Do NOT write DESIGN.md without Puppeteer dual-pass extraction. Tokens from static HTML (Cheerio, regex, string scanning) are invalid — they miss cascade, custom properties, and Tailwind resolution.
+>
+> **HARD GATE** — Do NOT claim certainty where evidence is thin. Low-confidence color roles, component classifications, and prose assertions MUST be flagged with `<!-- AGENT NOTE: uncertain — validate during grill-me. Evidence: [what was observed] -->`.
+>
+> **HARD GATE** — Do NOT ship DESIGN.md without running `npx @google/design.md lint`. Unvalidated output is unverified output. If lint is unavailable (offline), flag prominently in terminal and in DESIGN.md prose.
+
+## Quick Start
+
+```bash
+# First run — extract from HTML prototype
+node extract-design/scripts/extract.js --source ./prototype.html
+
+# From a published URL
+node extract-design/scripts/extract.js --source https://my-prototype.example.com
+
+# With a custom name
+node extract-design/scripts/extract.js --source ./proto.html --name "My Design System"
+
+# Update — re-extract from new HTML, diff against existing
+node extract-design/scripts/extract.js --source ./proto-v2.html
+
+# Lint-only — validate existing DESIGN.md without re-extraction
+node extract-design/scripts/extract.js --lint-only
+```
+
+## Flow
+
+1. **Launch Puppeteer** — dual-pass (light + dark) with retry + timeout. CI flags: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`.
+2. **Collect styles** — `page.evaluate()` collects computed styles from every element. Returns raw JSON to Node.js. Browser = sensor; Node = brain.
+3. **Classify tokens** — modular pipeline: colors (Material 3 roles), typography (scale detection), spacing (tolerance GCD), rounded (clustering), components (visual signature + pseudo-state variants).
+4. **Generate prose** — AI heuristics produce all 8 DESIGN.md sections. Overview and Do's/Don'ts flagged with agent notes.
+5. **Write + validate** — serialize to `specs/tech-architecture/DESIGN_LATEST.md`, run `npx @google/design.md lint`, report to terminal.
+6. **Handoff** — writes `handoff.next_skill: grill-me` to `specs/state.yaml` with uncertain decisions context.
+
+## Inputs
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--source <file\|url>` | First run: yes. Update: optional | HTML prototype path or URL |
+| `--name <string>` | No | Design system name (defaults to `<title>` or directory name) |
+| `--lint-only` | No | Validate existing DESIGN.md without re-extraction |
+
+## Output
+
+- `specs/tech-architecture/DESIGN_LATEST.md` — replaces `DESIGN_PLAN_LATEST.md` as the canonical design artifact
+- Terminal summary: token counts, component count, lint result, uncertain decisions
+- Structured JSON log to stderr: extraction events, timing, counts
+- `specs/state.yaml` → `handoff.next_skill: grill-me` with context
+
+## Error Tiers
+
+| Tier | Condition | Response |
+|------|-----------|----------|
+| Fatal | No Chrome, page load timeout after retries | Exit non-zero, suggest fixes |
+| Degraded | Zero colors, zero typography, SPA shell | Write DESIGN.md with degradation warning |
+| Warned | Lint errors, uncertain decisions | Write DESIGN.md, flag in terminal, hand off to grill-me |
+
+## Dependencies
+
+- **Puppeteer** (Chrome binary) — wrapped behind `BrowserExtractor` interface for testability
+- **`@google/design.md`** (soft, via `npx`) — wrapped behind `DesignValidator` interface. Warns and skips if offline.
+
+## verify
+
+```bash
+node extract-design/tests/test-extraction.js
+```
+
+See [REFERENCE.md](REFERENCE.md) for extraction algorithms and heuristics.

package/extract-design/extract-design.feature

@@ -0,0 +1,23 @@
+Feature: Extract DESIGN.md from HTML prototype
+
+  Scenario: Extract tokens from a styled prototype
+    Given an HTML prototype with 3+ colors, 2+ font sizes, spacing values, and rounded corners
+    When extract-design runs on the prototype
+    Then DESIGN_LATEST.md contains a colors token group with at least 3 entries
+    And DESIGN_LATEST.md contains a typography token group with at least 2 levels
+    And all 8 prose sections are present
+
+  Scenario: Handle dark mode prototypes
+    Given an HTML prototype that responds to prefers-color-scheme: dark
+    When extract-design runs dual-pass extraction
+    Then DESIGN_LATEST.md contains a colors-dark token group
+
+  Scenario: Degrade gracefully on unstyleable HTML
+    Given an HTML file with no computed styles
+    When extract-design runs on the prototype
+    Then DESIGN_LATEST.md is written with a degradation warning
+
+  Scenario: Flag uncertain classifications
+    Given an HTML prototype where one color is used ambiguously
+    When extract-design classifies colors
+    Then the uncertain color's prose rationale contains an AGENT NOTE comment

package/extract-design/scripts/classify-colors.js

@@ -0,0 +1,21 @@
+function norm(c) { if (!c || c === 'transparent' || c === 'rgba(0, 0, 0, 0)') return null; return c.trim(); }
+function lum(c) { const m = c.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/); if (!m) return 0.5; const s = v => v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); return 0.2126 * s(parseInt(m[1]) / 255) + 0.7152 * s(parseInt(m[2]) / 255) + 0.0722 * s(parseInt(m[3]) / 255); }
+function isNeutral(c) { const m = c.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/); if (!m) return false; return Math.max(Math.abs(parseInt(m[1]) - parseInt(m[2])), Math.abs(parseInt(m[2]) - parseInt(m[3])), Math.abs(parseInt(m[1]) - parseInt(m[3]))) < 30; }
+
+export function classifyColors(styles, mode = 'light') {
+  const u = []; const colors = {}; const stats = new Map();
+  for (const el of styles) {
+    for (const [prop, usage] of [['backgroundColor','bg'],['color','text'],['borderColor','border']]) {
+      const k = norm(el[prop]); if (!k) continue;
+      const s = stats.get(k) || { usage: new Set(), area: 0, count: 0 }; s.usage.add(usage); if (prop === 'backgroundColor') s.area += (el.width||0)*(el.height||0); s.count++; stats.set(k, s);
+    }
+  }
+  const neutrals = [], accents = [];
+  for (const [c, s] of stats) { if (isNeutral(c)) neutrals.push({ color: c, ...s, luminance: lum(c) }); else accents.push({ color: c, ...s }); }
+  neutrals.sort((a,b) => b.area - a.area); accents.sort((a,b) => b.count - a.count);
+  if (neutrals.length) { colors.surface = neutrals[0].color; colors.background = neutrals[0].color; const txt = [...stats.entries()].filter(([,s]) => s.usage.has('text')).sort((a,b) => b[1].count - a[1].count); if (txt.length) colors['on-surface'] = txt[0][0]; }
+  const containers = neutrals.slice(1); if (containers.length) { const isDark = mode === 'dark'; containers.sort((a,b) => isDark ? b.luminance - a.luminance : a.luminance - b.luminance); const maxC = Math.min(containers.length >= 5 ? 5 : 3, containers.length); const lvls = ['surface-container-lowest','surface-container-low','surface-container','surface-container-high','surface-container-highest']; for (let i = 0; i < maxC; i++) colors[lvls[i]] = containers[i].color; }
+  if (accents.length) { colors.tertiary = accents[0].color; if (accents.length > 1) colors.secondary = accents[1].color; const err = accents.find(a => { const m = a.color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/); return m && parseInt(m[1]) > 180 && parseInt(m[2]) < 100 && parseInt(m[3]) < 100; }); if (err) colors.error = err.color; }
+  if (Object.keys(colors).length < 2) u.push('Fewer than 2 colors extracted.');
+  return { colors, uncertain: u };
+}

package/extract-design/scripts/classify-rounded.js

@@ -0,0 +1,10 @@
+function parseR(v) { if (!v || v === '0px' || v === '0') return 0; const m = v.match(/^([\d.]+)(px|rem)$/); return m ? parseFloat(m[1]) * (m[2] === 'rem' ? 16 : 1) : (parseFloat(v) || 0); }
+export function classifyRounded(styles) { const u = []; const r = {}; const cnt = new Map();
+  for (const el of styles) { const px = parseR(el.borderRadius); cnt.set(px, (cnt.get(px) || 0) + 1); }
+  const freq = [...cnt.entries()].filter(([,c]) => c >= 2).map(([px]) => px).sort((a,b) => a - b);
+  if (!freq.length) { r.none = '0px'; return { rounded: r, uncertain: [] }; }
+  r.none = '0px'; const reg = freq.filter(v => v < 9998 && v > 0); const full = freq.find(v => v >= 9998);
+  if (full) r.full = `${full}px`; if (reg.length === 1) r.sm = `${reg[0]}px`;
+  else if (reg.length >= 2) { r.sm = `${reg[0]}px`; r.md = `${reg[1]}px`; } if (reg.length >= 3) r.lg = `${reg[2]}px`;
+  return { rounded: r, uncertain: u };
+}

package/extract-design/scripts/classify-spacing.js

@@ -0,0 +1,14 @@
+function toPx(v) { if (!v) return 0; const m = v.match(/^([\d.]+)(px|rem|em)$/); if (!m) return 0; return parseFloat(m[1]) * (m[2] === 'rem' || m[2] === 'em' ? 16 : 1); }
+function tGcd(nums, tol = 0.5) { if (!nums.length) return null; let r = nums[0]; for (let i = 1; i < nums.length; i++) { let a = Math.abs(r), b = Math.abs(nums[i]); while (b > tol) { const t = b; b = a % b; a = t; } r = a; } return r; }
+function collect(css, counts) { if (!css) return; for (const p of css.split(/\s+/)) { const v = toPx(p); if (v > 0) counts.set(v, (counts.get(v) || 0) + 1); } }
+
+export function classifySpacing(styles) { const u = []; const s = {}; const counts = new Map();
+  for (const el of styles) { collect(el.padding, counts); collect(el.margin, counts); if (el.gap) collect(el.gap, counts); }
+  const freq = new Map(); for (const [v, c] of counts) { if (c >= 3) freq.set(v, c); }
+  if (freq.size < 3) u.push('Fewer than 3 spacing values.');
+  const nums = [...freq.keys()].map(toPx).filter(v => v > 0); const g = tGcd(nums, 0.5);
+  if (!g || g < 2) { const sorted = [...freq.entries()].sort((a,b) => b[1] - a[1]); s.unit = sorted.length ? `${toPx(sorted[0][0])}px` : '8px'; return { spacing: s, uncertain: u }; }
+  s.unit = `${g}px`; const half = g / 2; if (nums.filter(v => Math.abs(v - half) < 0.5).length >= 3) s.half = `${half}px`;
+  s.sm = `${g * 2}px`; s.md = `${g * 4}px`; s.lg = `${g * 8}px`; if (nums.some(v => v >= g * 16)) s.xl = `${g * 16}px`;
+  return { spacing: s, uncertain: u };
+}

package/extract-design/scripts/classify-typography.js

@@ -0,0 +1,9 @@
+function px(v) { if (!v) return 0; const n = parseFloat(v); return isNaN(n) ? 0 : n; }
+export function classifyTypography(styles) { const u = []; const t = {}; const txt = styles.filter(s => s.text && s.text.length > 0 && s.fontSize); const clusters = new Map();
+  for (const el of txt) { const s = Math.round(px(el.fontSize)); if (!s) continue; if (!clusters.has(s)) clusters.set(s, { fontFamily: el.fontFamily, fontWeight: el.fontWeight, lineHeight: el.lineHeight, letterSpacing: el.letterSpacing, tag: el.tag, count: 0 }); clusters.get(s).count++; }
+  const sorted = [...clusters.entries()].sort((a,b) => b[0] - a[0]); if (!sorted.length) { u.push('No typography detected.'); return { typography: {}, uncertain: u }; }
+  let di = 0, hi = 0, bi = 0;
+  for (const [sz, cl] of sorted) { const hd = /^h[1-6]$/.test(cl.tag) || sz >= 32; let n; if (sz >= 64 && di === 0) { n = 'display-lg'; di++; } else if (hd && sz >= 40) { n = hi === 0 ? 'headline-lg' : 'headline-md'; hi++; } else if (hd && sz >= 28) { n = hi <= 1 ? 'headline-md' : 'headline-sm'; hi++; } else if (hd) { n = 'title-lg'; } else if (sz <= 18 && bi === 0) { n = 'body-lg'; bi++; } else if (sz <= 18) { n = 'body-md'; bi++; } else if (sz <= 14) { n = 'label-md'; } else { n = 'body-sm'; }
+    t[n] = { fontFamily: cl.fontFamily, fontSize: `${sz}px`, fontWeight: String(cl.fontWeight || '400') }; if (cl.lineHeight && cl.lineHeight !== 'normal') t[n].lineHeight = cl.lineHeight; if (cl.letterSpacing && cl.letterSpacing !== 'normal' && cl.letterSpacing !== '0px') t[n].letterSpacing = cl.letterSpacing; }
+  return { typography: t, uncertain: u };
+}