aiox-core 5.0.3 → 5.0.5

package/pro/squads/design/tasks/ds-audit-codebase.md

@@ -1,273 +0,0 @@
-# Audit Codebase for UI Pattern Redundancy
-
-> Task ID: brad-audit-codebase
-> Agent: Brad (Design System Architect)
-> Version: 1.1.0
-> v4.0-compatible: true
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[]` · enables: `[ds-consolidate-patterns]` · workflow: `brownfield-audit`
-> **On Fail:** If scan finds 0 patterns → verify path and file extensions. If scan errors → check file permissions and memory limits (`--max-old-space-size=4096`). Do NOT proceed to consolidate with empty/corrupt inventory. Re-run audit after fixing root cause.
-
-## Description
-
-Scan codebase to detect UI pattern redundancies (buttons, colors, spacing, typography, forms) and quantify technical debt with hard metrics. Brad's specialty: showing you the horror show you've created. **v4.0: Also evaluates machine-readability for agentic DS workflows and motion token coverage.**
-
-## Output Schema
-- **produces:** `outputs/design-system/{project}/audit/pattern-inventory.json`
-- **format:** JSON data
-- **consumed_by:** ds-consolidate-patterns
-
-## Prerequisites
-
-- Codebase with UI code (React, Vue, HTML, or vanilla CSS)
-- Bash shell access
-- grep, find, awk utilities available
-- Reference: Read data/agentic-ds-principles.md for machine-readability checks
-- Reference: Read data/motion-tokens-guide.md for animation audit criteria
-
-## Workflow
-
-### Interactive Elicitation
-
-This task uses interactive elicitation to gather scan parameters.
-
-1. **Gather Scan Parameters**
-   - Ask for scan path (e.g., ./src, ./app, ./components)
-   - Detect frameworks automatically or ask for confirmation
-   - Confirm output directory (default: outputs/design-system/{project}/audit/)
-
-2. **Validate Scan Path**
-   - Run `test -d $path && test -r $path` and confirm both return exit code 0
-   - Count total files with `find $path -type f \( -name "*.tsx" -o -name "*.jsx" -o -name "*.vue" -o -name "*.css" \) | wc -l`
-   - Estimate scan time (100k LOC ~2 min)
-
-3. **Confirm and Execute**
-   - Show scan plan summary
-   - Ask for confirmation before starting
-   - Begin pattern detection
-
-### Steps
-
-1. **Validate Environment**
-   - Run `test -d $path` to confirm scan path exists; abort if exit code != 0
-   - Run `test -r $path` to confirm read permissions; abort if exit code != 0
-   - Create output directory structure with `mkdir -p`
-   - Check: `test -d $path && test -r $path` — abort with "Path not found or not readable: $path"
-
-2. **Detect Frameworks**
-   - Count React/JSX files (*.jsx, *.tsx)
-   - Count Vue files (*.vue)
-   - Count HTML files (*.html)
-   - Count CSS files (*.css, *.scss, *.sass)
-   - Check: file count > 0 for at least one of (.jsx, .tsx, .vue, .html, .css) — abort with "No UI files found in $path"
-
-3. **Scan Button Patterns**
-   - Detect button elements (<button, <Button, className="btn")
-   - Count total button instances across all files
-   - Extract unique button class names and patterns
-   - Calculate redundancy factor (instances / unique patterns)
-   - Check: button_count is integer >= 0 — log "Found {N} button patterns across {M} files"
-
-4. **Scan Color Usage**
-   - Extract hex colors (#RGB, #RRGGBB)
-   - Extract rgb/rgba colors
-   - Count unique color values
-   - Count total color usage instances
-   - Identify top 10 most-used colors
-   - Calculate redundancy factor
-   - Check: unique_colors array length > 0 OR log "No colors found — verify CSS/SCSS files exist in scan path"
-
-5. **Scan Spacing Patterns**
-   - Extract padding values (padding: Npx)
-   - Extract margin values (margin: Npx)
-   - Count unique spacing values
-   - Identify most common patterns
-   - Check: spacing_values array populated — log "{N} unique spacing values found"
-
-6. **Scan Typography**
-   - Extract font-family declarations
-   - Extract font-size values
-   - Extract font-weight values
-   - Count unique typography patterns
-   - Check: font_families count >= 1 AND font_sizes count >= 1 — log "{N} font families, {M} font sizes cataloged"
-
-7. **Scan Form Patterns**
-   - Count input elements
-   - Extract unique input class patterns
-   - Count form elements
-   - Extract unique form patterns
-   - Check: input_instances and form_instances are integers >= 0 — log "{N} input elements, {M} form elements found"
-
-8. **Generate Inventory Report**
-   - Create pattern-inventory.json with all metrics
-   - Include scan metadata (timestamp, path, file counts)
-   - Calculate redundancy factors for each pattern type
-   - Check: `python -m json.tool pattern-inventory.json` returns exit code 0 — abort with "Invalid JSON in pattern-inventory.json"
-
-9. **Create State File**
-   - Generate .state.yaml for Merovingian handoff
-   - Record all pattern counts and metrics
-   - Log agent history
-   - Set phase to "audit_complete"
-   - Write inventory summary to .state.yaml:
-     ```yaml
-     last_command: audit
-     audit_complete: true
-     inventory_file: pattern-inventory.json
-     scan_path: {path}
-     timestamp: {ISO-8601}
-     summary:
-       total_files: {count}
-       patterns_found: {count}
-       redundancy_score: {score}
-     ```
-   - Check: `test -f .state.yaml` AND YAML parses without error — abort with "State file missing or invalid YAML"
-
-## Output
-
-- **pattern-inventory.json**: Structured data with all pattern counts, redundancy factors, and usage statistics
-- **.state.yaml**: Brad's state file for handoff to Merovingian or next command
-- **Console summary**: Key metrics displayed for immediate review
-
-### Output Format
-
-```json
-{
-  "scan_metadata": {
-    "timestamp": "2025-10-27T12:00:00Z",
-    "scan_path": "./src",
-    "total_files": 487,
-    "frameworks_detected": {
-      "react": true,
-      "vue": false,
-      "html": false
-    }
-  },
-  "patterns": {
-    "buttons": {
-      "unique_patterns": 47,
-      "total_instances": 327,
-      "redundancy_factor": 6.96
-    },
-    "colors": {
-      "unique_hex": 82,
-      "unique_rgb": 7,
-      "total_unique": 89,
-      "total_instances": 1247,
-      "redundancy_factor": 14.01
-    },
-    "spacing": {
-      "unique_padding": 19,
-      "unique_margin": 15
-    },
-    "typography": {
-      "unique_font_families": 4,
-      "unique_font_sizes": 15,
-      "unique_font_weights": 6
-    },
-    "forms": {
-      "input_instances": 189,
-      "unique_input_patterns": 23,
-      "form_instances": 45,
-      "unique_form_patterns": 12
-    }
-  }
-}
-```
-
-## Anti-Patterns
-
-- **"Grep and pray"** — Running generic grep without framework-specific patterns. A React codebase needs JSX-aware scanning (`className=`, `styled.`), not just CSS selectors. Always detect framework FIRST
-- **"Color counting without context"** — Counting `#fff` and `#FFF` as different colors. Normalize all colors to lowercase hex before counting. Also convert `rgb(255,255,255)` to hex for deduplication
-- **"Ignoring dynamic patterns"** — Only scanning static CSS while missing Tailwind classes (`bg-blue-500`), CSS-in-JS (`styled.div`), or theme variables. Scan ALL style sources, not just .css files
-- **"Partial scan, full conclusions"** — Scanning only `/components` but making claims about the entire codebase. Always state scan scope clearly and don't extrapolate beyond scanned files
-- **"Redundancy without severity"** — Reporting "47 unique colors" without indicating which are close duplicates (e.g., #333 vs #343434). Use HSL clustering to group near-duplicates and show actual waste
-
-## Failure Handling
-
-- **Scan timeout (>5 min for <100k LOC):** Reduce scan scope — split into subdirectories and audit individually
-- **Zero patterns detected:** Verify scan path contains UI code. Try alternate file extensions. If truly zero, document as "clean codebase"
-- **Permission errors >10%:** Run with elevated permissions or exclude restricted directories. Document excluded paths
-- **Invalid JSON output:** Re-run scan step that failed. If persistent, generate partial report with available data
-
-## Success Criteria
-
-- [ ] Scan completes in <2 minutes for 100k LOC
-- [ ] All pattern types detected (buttons, colors, spacing, typography, forms)
-- [ ] Redundancy factors calculated for measurable patterns
-- [ ] Valid JSON output generated with complete data
-- [ ] State file created for next command (consolidate/tokenize)
-- [ ] No scan errors or missing permissions
-
-## Error Handling
-
-- **Scan path does not exist**: Exit with clear error message, suggest valid paths
-- **No UI files found**: Warn user, check if path is correct or files exist
-- **Permission denied**: Explain which directory needs read access
-- **Partial scan failure**: Log which files failed, continue with remaining files, report incomplete data
-
-## Security Considerations
-
-- Read-only access to codebase (no writes during scan)
-- No code execution during pattern detection
-- Validate file paths to prevent directory traversal
-- Handle malformed files gracefully (invalid CSS/JSX)
-- Skip binary files and large non-text files
-
-## Examples
-
-### Example 1: React Codebase Scan
-
-```bash
-*audit ./src
-```
-
-Output:
-```
-🔍 Brad: Scanning ./src for UI chaos...
-
-📊 Files found:
-  - React/JSX: 234
-  - CSS/SCSS: 89
-  - TOTAL: 323
-
-🔍 Scanning BUTTONS...
-📊 BUTTONS:
-  - Total instances: 327
-  - Unique patterns: 47
-  - Redundancy factor: 7.0x
-
-🎨 Scanning COLORS...
-📊 COLORS:
-  - Unique hex values: 82
-  - Total usage instances: 1247
-  - Redundancy factor: 15.2x
-
-✅ Inventory saved: outputs/design-system/my-app/audit/pattern-inventory.json
-✅ State saved: outputs/design-system/my-app/.state.yaml
-```
-
-### Example 2: Vue Codebase Scan
-
-```bash
-*audit ./components
-```
-
-Output shows Vue-specific patterns (v-btn, el-button, etc.)
-
-## Notes
-
-- Redundancy factor >3x indicates significant technical debt
-- Colors >50 unique values = major consolidation opportunity
-- Buttons >20 variations = serious pattern explosion
-- Run this audit periodically to prevent pattern regression
-- Brad recommends: If redundancy factors are high, run *consolidate next
-- For cost analysis of this waste, run *calculate-roi after audit
-- v4.0: Also scan for animation/transition values as motion token candidates
-- v4.0: Check machine-readability score (Storybook, structured tokens, docs) per agentic-ds-principles.md
-- v4.0: Use *motion-audit for deep animation analysis, *agentic-audit for full agentic readiness
-## Related Checklists
-
-- `squads/design/checklists/ds-component-quality-checklist.md`
-- `squads/design/checklists/ds-pattern-audit-checklist.md`
-

package/pro/squads/design/tasks/ds-build-component.md

@@ -1,349 +0,0 @@
-# Build Production-Ready Component
-
-> Task ID: atlas-build-component
-> Agent: Brad (Design System Architect)
-> Version: 1.1.0
-> v4.0-compatible: true
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[]` · enables: `[ds-compose-molecule, ds-extend-pattern]` · workflow: `greenfield`
-
-## Description
-
-Generate production-ready React TypeScript component from design tokens. Includes component file, styles (CSS Modules), tests, optional Storybook stories, and documentation. All styling uses tokens (zero hardcoded values). **v4.0: Supports Fluent 2 patterns as component blueprint option. Generates Storybook stories with Chromatic-ready visual test states.**
-
-## Output Schema
-- **produces:** `outputs/design-system/{project}/components/{Component}/`
-- **format:** TypeScript source (TSX, CSS Module, tests, stories, docs)
-- **consumed_by:** ds-compose-molecule, ds-extend-pattern
-
-## Prerequisites
-
-- Setup completed (*setup command run successfully)
-- Tokens loaded and accessible
-- React and TypeScript configured
-- Reference: Read data/fluent2-design-principles.md for Fluent 2 component patterns
-- Reference: Read data/ds-reference-architectures.md for cross-system component patterns
-
-## Workflow
-
-### Interactive Elicitation
-
-This task uses interactive elicitation to configure component.
-
-1. **Select Component Type**
-   - Atomic level (atom, molecule, organism)
-   - Component name (Button, Input, Card, etc)
-   - Confirm token availability for this component
-
-2. **Configure Component Features**
-   - Variants needed (primary, secondary, destructive)
-   - Sizes needed (sm, md, lg)
-   - States needed (hover, disabled, loading, error)
-   - Additional props
-
-3. **Review Generation Plan**
-   - Show files to be generated
-   - Confirm test coverage requirements
-   - Ask for Storybook stories (if enabled)
-
-### Steps
-
-1. **Validate Prerequisites**
-   - Run `test -f tokens.yaml` (or tokens.json) to confirm tokens file exists; abort with "Tokens not found — run *setup first" if missing
-   - Search for existing `{Component}.tsx` in the design-system directory; if found, prompt user to confirm overwrite
-   - Validate component name matches PascalCase regex `/^[A-Z][a-zA-Z]+$/`
-   - Check: tokens file exists AND component name is PascalCase (`/^[A-Z][a-zA-Z]+$/`) — abort if either fails
-
-2. **Load Token References**
-   - Identify which tokens this component needs
-   - Validate token availability
-   - Generate token import statements
-   - Check: grep each required token name in tokens file — list missing tokens if any
-
-3. **Generate Component File**
-   - Create TypeScript React component
-   - Add prop type definitions (strict typing)
-   - Implement variants, sizes, states
-   - Add accessibility attributes (ARIA)
-   - Use semantic HTML elements
-   - Check: `tsc --noEmit {component}.tsx` returns exit code 0 — fix type errors before proceeding
-
-4. **Generate Component Styles**
-   - Create CSS Module file ({Component}.module.css)
-   - Use CSS custom properties from tokens
-   - Implement all variants and states
-   - Add responsive styles if needed
-   - Zero hardcoded values (all from tokens)
-   - Check: zero hardcoded color/spacing values in CSS module — grep for `#[0-9a-f]` and `[0-9]+px` (excluding 0px)
-
-5. **Generate Unit Tests**
-   - Create test file ({Component}.test.tsx)
-   - Test all variants render correctly
-   - Test all sizes work
-   - Test disabled state
-   - Test onClick/events
-   - Aim for >80% coverage
-   - Check: `npm test -- --coverage {Component}.test.tsx` exits 0 AND coverage >= 80% — fix failing tests before proceeding
-
-6. **Generate Storybook Stories (Optional)**
-   - If Storybook enabled, create {Component}.stories.tsx
-   - Story for each variant
-   - Story for each size
-   - Interactive controls for props
-   - Check: stories file exports at least one named story AND `tsc --noEmit {Component}.stories.tsx` exits 0
-
-7. **Run Accessibility Checks**
-   - Confirm all interactive elements have `aria-label` or visible text by searching component source for button/a/input tags without labels
-   - Measure color contrast ratio for all foreground/background token pairs and confirm each >= 4.5:1 (use WCAG contrast formula)
-   - Tab through all interactive elements in render order and confirm focus moves logically without traps
-   - Add `:focus-visible` outline styles using `var(--color-focus)` token
-   - Check: all interactive elements have ARIA labels AND color contrast ratio >= 4.5:1 AND focus-visible styles present
-
-8. **Generate Component Documentation**
-   - Create {Component}.md in docs/
-   - Document props and types
-   - Show usage examples
-   - List variants and sizes
-   - Include accessibility notes
-   - Check: {Component}.md exists AND contains sections: Props, Usage Examples, Variants, Accessibility
-
-9. **Update Component Index**
-   - Add to design-system/index.ts
-   - Export component for easy import
-   - Update barrel exports
-   - Check: `grep -q "{Component}" index.ts` — abort with "{Component} not found in index.ts exports"
-
-10. **Update State File**
-    - Add component to patterns_built in .state.yaml
-    - Record atomic level, variants, test coverage
-    - Increment component count
-    - Check: .state.yaml contains component name in patterns_built array AND component_count incremented
-
-## Output
-
-- **{Component}.tsx**: React TypeScript component
-- **{Component}.module.css**: Styles using tokens
-- **{Component}.test.tsx**: Unit tests
-- **{Component}.stories.tsx**: Storybook stories (optional)
-- **{Component}.md**: Component documentation
-- **Updated index.ts**: Component exported
-- **.state.yaml**: Updated with component metadata
-
-### Output Format
-
-```typescript
-// Button.tsx
-import React from 'react';
-import styles from './Button.module.css';
-
-export interface ButtonProps {
-  /** Visual style variant */
-  variant?: 'primary' | 'secondary' | 'destructive';
-  /** Size variant */
-  size?: 'sm' | 'md' | 'lg';
-  /** Button content */
-  children: React.ReactNode;
-  /** Click handler */
-  onClick?: () => void;
-  /** Disabled state */
-  disabled?: boolean;
-  /** HTML type attribute */
-  type?: 'button' | 'submit' | 'reset';
-}
-
-export const Button: React.FC<ButtonProps> = ({
-  variant = 'primary',
-  size = 'md',
-  children,
-  onClick,
-  disabled = false,
-  type = 'button',
-}) => {
-  const className = `${styles.btn} ${styles[`btn-${variant}`]} ${styles[`btn-${size}`]}`;
-
-  return (
-    <button
-      type={type}
-      className={className}
-      onClick={onClick}
-      disabled={disabled}
-      aria-disabled={disabled}
-    >
-      {children}
-    </button>
-  );
-};
-```
-
-```css
-/* Button.module.css */
-.btn {
-  font-family: var(--font-base);
-  font-size: var(--font-size-base);
-  font-weight: var(--font-weight-semibold);
-  border-radius: var(--radius-base);
-  padding: var(--space-md) var(--space-lg);
-  border: none;
-  cursor: pointer;
-  transition: all 0.2s ease;
-}
-
-.btn:disabled {
-  opacity: 0.5;
-  cursor: not-allowed;
-}
-
-.btn-primary {
-  background: var(--color-primary);
-  color: white;
-}
-
-.btn-primary:hover:not(:disabled) {
-  background: var(--color-primary-dark);
-}
-
-.btn-secondary {
-  background: var(--color-secondary);
-  color: white;
-}
-
-.btn-destructive {
-  background: var(--color-error);
-  color: white;
-}
-
-.btn-sm {
-  font-size: var(--font-size-sm);
-  padding: var(--space-sm) var(--space-md);
-}
-
-.btn-lg {
-  font-size: var(--font-size-lg);
-  padding: var(--space-lg) var(--space-xl);
-}
-```
-
-## Failure Handling
-
-- **Missing required tokens:** If grep fails to find token name in tokens file, abort with "Required token {name} not found. Available tokens: {list}. Run *setup or add missing tokens before building component."
-- **TypeScript compilation errors:** If `tsc --noEmit {component}.tsx` returns non-zero exit code, abort with "TypeScript errors in {Component}.tsx: {errors}. Fix type errors before proceeding."
-- **Hardcoded design values detected:** If CSS module contains hardcoded colors (#hex) or spacing values (e.g., 16px except 0px), abort with "{N} hardcoded values detected. Replace with tokens: {list}."
-- **Test coverage below threshold:** If `npm test --coverage` shows coverage <80%, abort with "Test coverage {actual}% below required 80%. Add tests for: {uncovered paths}."
-
-## Success Criteria
-
-- [ ] Component compiles without TypeScript errors
-- [ ] All styling uses tokens (zero hardcoded values)
-- [ ] Props fully typed with TSDoc comments
-- [ ] All variants and sizes implemented
-- [ ] Disabled state handled correctly
-- [ ] WCAG AA accessibility standards met
-- [ ] Unit tests pass with >80% coverage
-- [ ] Component documented with examples
-- [ ] Storybook stories work (if enabled)
-
-## Anti-Patterns
-
-- **"Div soup"** — Using `<div>` for everything instead of semantic HTML. A clickable element MUST be `<button>`, a navigation link MUST be `<a>`. Never add `role="button"` to a `<div>` when `<button>` exists
-- **"Hardcoded magic numbers"** — Writing `padding: 16px` instead of `padding: var(--spacing-4)`. Zero hardcoded values means ZERO — including border-radius, font-size, line-height, and box-shadow values
-- **"any-driven development"** — Using TypeScript `any` to make the compiler happy. Every prop must have a specific type. Use discriminated unions for variants: `type ButtonVariant = 'primary' | 'secondary' | 'destructive'`
-- **"Testing the framework, not the component"** — Writing tests like "renders without crashing" that test React, not your component. Test: variants render correct classes, disabled prevents onClick, keyboard events fire handlers
-- **"Accessibility as afterthought"** — Adding ARIA after the component is "done". Build accessible from step 1: semantic HTML first, then ARIA only where HTML semantics are insufficient
-
-## Error Handling
-
-- **Token not found**: Report which token is missing, suggest alternatives
-- **Component exists**: Ask to overwrite or use different name
-- **TypeScript errors**: Display errors, suggest fixes
-- **Test failures**: Show failing tests, don't complete until fixed
-- **Accessibility violations**: Warn and suggest improvements
-
-## Security Considerations
-
-- Sanitize component name (prevent injection)
-- Validate token references
-- Escape user content in examples
-- No eval() or dynamic code execution
-
-## Examples
-
-### Example 1: Build Button Component
-
-```bash
-*build button
-```
-
-Output:
-```
-🏗️ Merovingian: Building Button component...
-
-📋 Configuration:
-  - Type: Atom
-  - Variants: primary, secondary, destructive
-  - Sizes: sm, md, lg
-  - Tests: Yes (>80% coverage)
-  - Storybook: Yes
-
-✓ Generated Button.tsx (142 lines)
-✓ Generated Button.module.css (89 lines, 0 hardcoded values)
-✓ Generated Button.test.tsx (18 tests)
-✓ Generated Button.stories.tsx (6 stories)
-✓ Generated Button.md (documentation)
-
-🧪 Running tests...
-  ✓ renders with default props
-  ✓ renders all variants correctly
-  ✓ renders all sizes correctly
-  ✓ handles disabled state
-  ✓ calls onClick handler
-  ... 13 more tests
-  Coverage: 94.2%
-
-♿ Accessibility check:
-  ✓ ARIA attributes present
-  ✓ Color contrast: 4.8:1 (WCAG AA ✓)
-  ✓ Keyboard navigable
-  ✓ Focus indicators visible
-
-✅ Button component ready!
-
-Import: import { Button } from '@/design-system';
-Usage: <Button variant="primary">Click me</Button>
-
-Merovingian says: "Built right. Built once."
-```
-
-### Example 2: Build Input Component
-
-```bash
-*build input
-```
-
-Output includes additional features:
-- Validation states (error, success)
-- Helper text prop
-- Label integration
-- Icon slots
-
-## Notes
-
-- All components strictly typed with TypeScript
-- Zero hardcoded values enforced (tokens only)
-- Accessibility is non-negotiable (WCAG AA minimum)
-- Test coverage >80% required
-- CSS Modules scope styles automatically
-- Variants and sizes are extensible
-- Components are tree-shakeable
-- Storybook stories enable visual testing
-- Documentation auto-generated from types
-- Components follow Atomic Design principles
-- Merovingian ensures quality at every step
-
-
-## Related Checklists
-
-- `squads/design/checklists/ds-component-quality-checklist.md`
-- `squads/design/checklists/ds-pattern-audit-checklist.md`
-
-## Process Guards
-- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/ds-build-mcp-server.md

@@ -1,84 +0,0 @@
-# Build MCP Server for Design System
-
-> Task ID: brad-ds-build-mcp-server
-> Agent: Brad (Design System Architect)
-> Version: 1.0.0
-
-## Description
-
-Design and implement a Model Context Protocol (MCP) server that exposes design system assets to AI agents.
-
-Core data exposed:
-- component metadata
-- registry entries
-- token catalogs
-- usage guidelines
-
-## Prerequisites
-
-- AI metadata generated (`ds-generate-ai-metadata`)
-- Registry and workspace structure validated
-- Stable token files and schemas
-
-## Workflow
-
-1. **Define MCP Capabilities**
-- Tools to query:
-  - list components
-  - inspect component contract
-  - search by intent/context
-  - resolve required tokens
-
-2. **Implement Server Skeleton**
-- Create:
-  - `workspace/domains/design-system/mcp/server.ts`
-  - `workspace/domains/design-system/mcp/handlers/*`
-- Keep handlers deterministic and stateless.
-
-3. **Connect Data Sources**
-- `metadata/components.json`
-- `workspace/ui/registry.json`
-- token files under `domains/design-system/tokens`
-
-4. **Add Query Guards**
-- Schema validation on load.
-- Safe fallback for missing component entries.
-- No execution of arbitrary user code.
-
-5. **Validate with Real Queries**
-- Query by component name, intent, and accessibility requirement.
-- Verify returned contracts are complete and traceable.
-
-6. **Document Contract**
-- Input/output schema for each MCP tool.
-- Versioning and compatibility policy.
-
-## Deliverables
-
-- MCP server scaffold with handlers
-- Queryable design system knowledge surface
-- Contract documentation for AI consumers
-
-## Success Criteria
-
-- [ ] MCP server lists and resolves all registered components
-- [ ] Responses include props, variants, a11y, and token links
-- [ ] Schema validation blocks invalid metadata
-- [ ] Agent can generate UI using only exposed system contracts
-
-## Notes
-
-- Treat MCP as infrastructure, not integration glue.
-- Keep response payloads concise and fully structured.
-- Favor machine contracts over natural language in API surfaces.
-
-
-## Related Checklists
-
-- `squads/design/checklists/ds-component-quality-checklist.md`
-- `squads/design/checklists/ds-pattern-audit-checklist.md`
-
-## Process Guards
-- **Execution Type:** `Hybrid`
-- **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `design-system`
-- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.