aiox-core 5.0.3 → 5.0.5

package/pro/squads/design/tasks/ds-figma-pipeline.md

@@ -1,95 +0,0 @@
-# Configure Figma MCP + Design-to-Code Pipeline
-
-> Task ID: brad-figma-pipeline
-> Agent: Brad (Design System Architect)
-> Version: 1.0.0
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `figma`
-
-## Description
-
-Configure the Figma MCP Server to connect design files with AI coding tools. Establishes component mapping (Figma components → code components), token sync (Figma Variables → W3C DTCG), and design-to-code workflow.
-
-## Prerequisites
-
-- Figma file with component library
-- Figma API access (personal access token)
-- AI coding tool (Claude Code, Cursor, Windsurf)
-
-## Workflow
-
-### Interactive Elicitation
-
-1. **Gather Parameters**
-   - Figma file URL or key
-   - Code component library location
-   - Target AI tool for integration
-   - Token sync direction (Figma → code, code → Figma, bidirectional)
-
-### Steps
-
-1. **Setup Figma MCP Server**
-   - Install Figma MCP Server package
-   - Configure Figma API token
-   - Connect to target Figma file
-   - Verify MCP server responds with file data
-   - Check: MCP server query returns component list with count > 0 — abort with "MCP server not responding or returned empty component list"
-
-2. **Create Component Mapping**
-   - Map Figma component names → code component imports
-   - Map Figma variants → code component props
-   - Map Figma auto-layout → CSS flex/grid patterns
-   - Document unmapped components (gaps between design and code)
-   - Check: (mapped components / total Figma components) * 100 >= 80 — log "Mapping coverage: {pct}% ({mapped}/{total}), unmapped: {list}"
-
-3. **Configure Token Sync**
-   - Export Figma Variables as W3C DTCG tokens
-   - Compare with existing code tokens (identify drift)
-   - Define sync direction and conflict resolution rules
-   - Setup automated sync (CI/CD or manual trigger)
-   - Check: token drift count == 0 (Figma values match code values) — if drift > 0, log "Token drift detected: {N} mismatches" and list them
-
-4. **Define Design-to-Code Workflow**
-   - Developer selects Figma frame/component
-   - AI tool queries MCP for design context
-   - AI generates code using mapped components and tokens
-   - Developer reviews and refines
-   - Document the workflow for team adoption
-   - Check: sample Figma frame generates code using mapped components AND correct tokens — abort with "Pipeline failed: AI output uses {N} unmapped components"
-
-5. **Validate Round-Trip Fidelity**
-   - Generate code from sample Figma designs
-   - Compare output with expected component usage
-   - Measure fidelity (correct components, correct tokens, correct layout)
-   - Document common mismatches and fixes
-   - Update .state.yaml
-
-## Output
-
-- Figma MCP Server configured and connected
-- `figma-component-mapping.json` — Figma → code component map
-- `figma-token-sync-config.yaml` — Token sync configuration
-- `figma-pipeline-guide.md` — Team workflow documentation
-- `.state.yaml` updated
-
-## Failure Handling
-
-- **MCP Server connection timeout:** If Figma MCP Server does not respond within 10s or returns empty data, verify Figma API token validity and network connectivity, then exit with "MCP connection failed — check token at mcp-servers/figma/config and retry"
-- **Component mapping below 50%:** If less than half of Figma components have code equivalents, generate unmapped component report and suggest creating placeholder components or adjusting component naming conventions before proceeding
-- **Critical token drift detected:** If >20% of color or spacing tokens differ between Figma and code by >10%, halt sync and prompt user to choose canonical source (Figma or code), then document chosen direction in figma-token-sync-config.yaml
-- **AI-generated code uses wrong components:** If sample Figma frame generates code with 3+ unmapped components or incorrect token references, flag as fidelity failure, include comparison screenshot in validation report, and suggest improving component mapping or AI prompt context
-
-## Success Criteria
-
-- MCP Server returns accurate Figma component data
-- >80% of Figma components mapped to code equivalents
-- Token values synchronized (zero drift)
-- AI-generated code uses correct DS components
-
-
-## Related Checklists
-
-- `squads/design/checklists/ds-component-quality-checklist.md`
-
-## Process Guards
-- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

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

@@ -1,105 +0,0 @@
-# Evaluate Fluent 2 Design Alignment
-
-> Task ID: brad-fluent-audit
-> Agent: Brad (Design System Architect)
-> Version: 1.0.0
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[]` · enables: `[ds-fluent-build]` · workflow: `fluent`
-
-## Description
-
-Calculate a Fluent 2 alignment score (0-100) by comparing your design system's component patterns, token naming, and accessibility approach against Fluent 2 specifications. Checks compound component patterns, token naming conventions, accessibility approach, and cross-platform readiness. Outputs alignment score with gap analysis.
-
-## Output Schema
-- **produces:** `outputs/design-system/{project}/fluent/fluent-alignment-report.json`
-- **format:** JSON data
-- **consumed_by:** ds-fluent-build
-
-## Prerequisites
-
-- Existing design system with components
-- Read data/fluent2-design-principles.md for reference
-
-## Workflow
-
-### Interactive Elicitation
-
-1. **Gather Parameters**
-   - DS root path
-   - Target Fluent aspects (all, or specific: components, tokens, a11y)
-   - Current framework (React, Vue, other)
-
-### Steps
-
-1. **Compare Component Patterns Against Fluent 2 Compound Model**
-   - Check for compound component pattern usage
-   - Check for slot-based customization
-   - Check for controlled/uncontrolled pattern support
-   - Check for forwardRef usage
-   - Score: compound + slots = 20pts, monolithic props = 5pts
-   - Check: every component has architecture score (0-20) based on compound/slot/ref patterns — log "{N} components scored, avg: {avg}/20"
-
-2. **Match Token Names Against Fluent Convention Regex**
-   - Compare token names against Fluent convention (color + category + variant + state)
-   - Check for 3-layer architecture (global → alias → component)
-   - Validate semantic token coverage
-   - Score: Fluent naming = 20pts, partial match = 10pts, custom = 5pts
-   - Check: token naming comparison generated with Fluent match percentage — log "Token naming: {pct}% Fluent-aligned ({matched}/{total})"
-
-3. **Check Built-in ARIA Attributes and Focus Management**
-   - Check for built-in ARIA attributes (not consumer-applied)
-   - Check for focus management (FocusZone, Tabster, or equivalent)
-   - Check for keyboard navigation implementation
-   - Check for high-contrast mode support via tokens
-   - Score: Built-in a11y = 20pts, partial = 10pts, consumer-applied = 5pts
-   - Check: each component categorized as built-in / partial / consumer-applied a11y — log "A11y: {builtin} built-in, {partial} partial, {consumer} consumer-applied"
-
-4. **Classify Platform Dependencies as Cross-Platform or Web-Only**
-   - Check for platform-agnostic token values
-   - Check for platform-specific implementations (not web-only wrappers)
-   - Check for responsive design patterns
-   - Score: Cross-platform ready = 20pts, web-only = 10pts
-   - Check: platform assessment completed with cross-platform / web-only classification — log "Platform readiness: {classification} ({score}/20)"
-
-5. **Score Clarity, System, and Productive Principles (0-20 each)**
-   - Clarity: Is ambiguity minimized? Information hierarchy clear?
-   - System: Do components work coherently together?
-   - Productive: Are components optimized for task completion?
-   - Score: Strong adherence = 20pts, partial = 10pts
-   - Check: clarity + system + productive principles each scored (0-20) — log "Principles: clarity={c}, system={s}, productive={p}, total={t}/20"
-
-6. **Generate Alignment Report**
-   - Total Fluent alignment score (0-100)
-   - Gap analysis by category
-   - Migration recommendations (what to change to align with Fluent 2)
-   - Effort estimates per gap
-   - Update .state.yaml
-
-## Output
-
-- `fluent-alignment-report.md` — Score + gap analysis
-- Category-by-category breakdown
-- Prioritized migration recommendations
-- `.state.yaml` updated
-
-## Failure Handling
-
-- **Fluent 2 reference file not found:** Fetch fluent2-design-principles.md from data/ directory. If missing, abort with "Reference file data/fluent2-design-principles.md required for audit"
-- **No components found at DS root path:** Exit with error "No component files in {path}. Cannot perform Fluent alignment audit."
-- **Token naming extraction returns empty:** Check alternate token file formats (.json, .yaml, .ts). Report "Token naming: 0% aligned — no tokens found"
-- **Component architecture scoring fails for a component:** Log warning, skip that component, continue with remaining. Note skipped components in report
-
-## Success Criteria
-
-- Accurate scoring based on actual component analysis
-- Gaps have specific, actionable recommendations
-- Report distinguishes must-have vs. nice-to-have alignments
-
-
-## 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-fluent-build.md

@@ -1,110 +0,0 @@
-# Generate Component Following Fluent 2 Patterns
-
-> Task ID: brad-fluent-build
-> Agent: Brad (Design System Architect)
-> Version: 1.0.0
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[ds-fluent-audit]` · enables: `[]` · workflow: `fluent`
-
-## Description
-
-Generate a production-ready component following Microsoft Fluent 2 design patterns: compound component architecture, slot-based customization, built-in accessibility, and token-based styling.
-
-## Input Schema
-- **requires:** Output from `ds-fluent-audit`
-- **format:** JSON data
-- **location:** `outputs/design-system/{project}/fluent/fluent-alignment-report.json`
-
-## Prerequisites
-
-- Design tokens available (preferably W3C DTCG format)
-- React + TypeScript environment
-- Read data/fluent2-design-principles.md for principles
-
-## Workflow
-
-### Interactive Elicitation
-
-1. **Gather Parameters**
-   - Component name and purpose
-   - Variants needed (size, appearance, shape)
-   - Slots/sub-components required
-   - Target output directory
-
-### Steps
-
-1. **Design Component API**
-   - Define root component and sub-components (compound pattern)
-   - Define slot props for customizable sub-parts
-   - Define variants as union types (not open strings)
-   - Define controlled/uncontrolled props
-   - Check: all props have TypeScript types AND variant props use union types (not open strings) — abort with "API design incomplete: {N} untyped or open-string props"
-
-2. **Implement Component Structure**
-   - Root component: orchestrates state, provides context
-   - Sub-components: render individual parts, accept slot overrides
-   - Use forwardRef on all components
-   - Implement controlled + uncontrolled patterns via hooks
-   - Check: root component provides context AND sub-components consume it AND forwardRef used — abort with "Compound pattern incomplete: {missing aspect}"
-
-3. **Apply Token-Based Styling**
-   - All colors from semantic tokens (no hardcoded values)
-   - All spacing from spacing tokens
-   - All typography from typography tokens
-   - Support mode switching (light/dark/high-contrast)
-   - Check: hardcoded color/spacing/typography value count == 0 in component files — abort with "{N} hardcoded design values found"
-
-4. **Implement Accessibility**
-   - Add appropriate ARIA roles and attributes
-   - Implement keyboard navigation (Tab, Arrow keys, Enter, Escape)
-   - Handle focus management (focus trap for modals, focus restore)
-   - Add aria-label, aria-describedby where needed
-   - Check: component has ARIA roles + keyboard navigation + focus management — abort with "A11y incomplete: missing {list}"
-
-5. **Generate Tests**
-   - Unit tests for component rendering and state
-   - Interaction tests for keyboard navigation
-   - Accessibility tests (role, label assertions)
-   - Check: test coverage >= 80% AND all tests pass with exit code 0 — abort with "Tests: {pass}/{total} passing, coverage {pct}%"
-
-6. **Generate Storybook Story**
-   - Default story with all variants
-   - Interactive controls for all props
-   - Compound usage examples
-   - Accessibility annotations
-   - Check: story file exports default + variant stories AND argTypes defined for all props — abort with "Story incomplete: {missing aspect}"
-
-## Output
-
-- `{Component}/` directory with:
-  - `types.ts` — TypeScript interfaces
-  - `{Component}.tsx` — Root component
-  - `{SubComponent}.tsx` — Sub-components
-  - `use{Component}.ts` — State hook
-  - `{Component}.test.tsx` — Tests
-  - `{Component}.stories.tsx` — Storybook story
-  - `index.ts` — Barrel export
-
-## Failure Handling
-
-- **Compound pattern incomplete:** If root component does not provide context OR sub-components do not consume context OR forwardRef missing on components, abort with "Compound pattern incomplete: {missing aspect}. Ensure root provides context, sub-components consume it, and all use forwardRef."
-- **Hardcoded design values detected:** If component files contain hardcoded colors (#hex), spacing (px values), or typography values instead of tokens, abort with "{N} hardcoded design values found: {list}. All styling must use semantic design tokens."
-- **Accessibility implementation incomplete:** If component missing ARIA roles, keyboard navigation handlers, or focus management, abort with "A11y incomplete: missing {list}. Add ARIA attributes, keyboard event handlers, and focus trap/restore logic."
-- **Variant props use open strings:** If component prop types use `string` instead of union types for variants (e.g., `appearance: string` not `appearance: 'primary' | 'secondary'`), abort with "API design incomplete: {N} props use open strings instead of union types. Define explicit variant enums."
-
-## Success Criteria
-
-- Compound component pattern correctly implemented
-- All styling via tokens, zero hardcoded values
-- Keyboard navigation works completely
-- Tests pass with >80% coverage
-- Storybook story renders all variants
-
-
-## 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-generate-ai-metadata.md

@@ -1,81 +0,0 @@
-# Generate AI-Readable Component Metadata
-
-> Task ID: brad-ds-generate-ai-metadata
-> Agent: Brad (Design System Architect)
-> Version: 1.0.0
-
-## Description
-
-Create machine-readable metadata for design system components so AI agents can discover, reason about, and assemble UI with real components (not hallucinated variants).
-
-## Prerequisites
-
-- Components organized in workspace/system and workspace/ui
-- Token hierarchy available (primitives/semantic/component)
-- Registry strategy defined (`registry.json`)
-- Governance protocol available: `squads/design/protocols/ai-first-governance.md`
-
-## Workflow
-
-1. **Collect Component Inventory**
-- Enumerate each component with canonical path and export name.
-- Resolve variants, slots, and composition relations.
-
-2. **Attach Design Semantics**
-- For each component, define:
-  - intent (e.g. `form-submit`, `navigation`, `feedback`)
-  - allowed contexts (marketing, dashboard, onboarding)
-  - interaction model (controlled/uncontrolled)
-
-3. **Attach Technical Contracts**
-- Props schema with type, required, default.
-- Variant schema (`cva` variants, compound variants).
-- Accessibility contract (`role`, keyboard behavior, aria requirements).
-
-4. **Link Tokens and Dependencies**
-- Map semantic tokens used by each variant.
-- Capture dependencies (primitives, icons, hooks, utilities).
-
-5. **Write Metadata Artifacts**
-- Per-component metadata JSON files.
-- Consolidated index:
-  - `workspace/domains/design-system/metadata/components.json`
-
-6. **Quality Validation**
-- Validate metadata against JSON schema.
-- Reject components with missing a11y contract or token mapping.
-
-7. **AI-First Governance Check (Required)**
-- Confirm canonical references are used (no alternate policy paths).
-- Mark status of each dependency: `Implemented`, `Partially implemented`, `Concept only`.
-- Flag unresolved dependencies explicitly.
-
-## Deliverables
-
-- Component metadata files (JSON)
-- Central metadata index in domains/design-system/metadata
-- Validation output (pass/fail by component)
-
-## Success Criteria
-
-- [ ] 100% of exported components represented in metadata index
-- [ ] Every component includes a11y contract and token mapping
-- [ ] Metadata schema validation passes with zero errors
-- [ ] Metadata can be consumed by MCP handlers and RAG pipelines
-
-## Notes
-
-- Prefer explicit schemas over prose.
-- Keep metadata deterministic and versioned.
-- Machine-readable documentation is part of the product, not optional docs.
-
-
-## 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.

package/pro/squads/design/tasks/ds-generate-cursor-rules.md

@@ -1,74 +0,0 @@
-# Generate IDE Rules from Design System
-
-> Task ID: brad-ds-generate-cursor-rules
-> Agent: Brad Frost (Design System Architect)
-> Version: 1.0.0
-
-## Description
-
-Generate `.cursorrules` and `.claude-rules.md` files from the design system metadata, tokens, and guidelines. Rules enforce correct token usage, component selection, and accessibility.
-
-## Prerequisites
-
-- Token registry at `metadata/tokens/index.json`
-- Component metadata at `metadata/components.json`
-- Guidelines at `metadata/guidelines/usage.json`
-
-## Workflow
-
-1. **Extract Token Rules**
-   - List all CSS variables from token registry
-   - Generate rules: "Use var(--X) instead of hardcoded value Y"
-   - Group by category (color, spacing, typography, radius, shadow, motion)
-
-2. **Extract Component Rules**
-   - List all components with their intended use cases (from guidelines)
-   - Generate rules: "For X use case, use Y component"
-   - Include anti-patterns from when_not_to_use
-
-3. **Extract Accessibility Rules**
-   - From component a11y contracts, generate:
-   - Required ARIA attributes per component
-   - Keyboard interaction requirements
-   - WCAG criteria that must be met
-
-4. **Generate .cursorrules**
-   - Markdown format optimized for Cursor IDE
-   - Sections: Token Usage, Component Selection, Accessibility, Anti-Patterns
-
-5. **Generate .claude-rules.md**
-   - Markdown format optimized for Claude Code
-   - Include MCP tool references for runtime queries
-
-6. **Validate**
-   - Rules don't conflict with existing project rules
-   - Token references resolve to actual tokens
-   - Component references resolve to actual components
-
-## Output Path
-
-- `workspace/domains/design-system/rules/.cursorrules`
-- `workspace/domains/design-system/rules/.claude-rules.md`
-
-## Deliverables
-
-- IDE rules files generated from live metadata
-- Zero hardcoded rules — all derived from data sources
-
-## Success Criteria
-
-- [ ] Rules reference only existing tokens and components
-- [ ] Anti-patterns derived from guidelines when_not_to_use
-- [ ] Accessibility rules cover all component a11y contracts
-- [ ] No conflicts with existing .claude/ rules
-
-
-## 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.

package/pro/squads/design/tasks/ds-generate-documentation.md

@@ -1,101 +0,0 @@
-# Generate Pattern Library Documentation
-
-> Task ID: atlas-generate-documentation
-> Agent: Merovingian (Design System Builder)
-> Version: 1.1.0
-> v4.0-compatible: true
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `documentation`
-
-## Description
-
-Generate comprehensive pattern library documentation from built components. Creates searchable, navigable docs with usage examples, prop tables, accessibility notes, and live previews.
-
-## Prerequisites
-
-- At least 1 component built
-- Design system setup complete
-- Component .md files exist
-
-## Workflow
-
-### Steps
-
-1. **Scan Built Components** - Find all atoms, molecules, organisms
-2. **Parse Component Metadata** - Extract props, types, variants
-3. **Generate Pattern Library Index** - Main navigation page
-4. **Generate Component Pages** - Detailed pages per component
-5. **Generate Usage Examples** - Code snippets and live previews
-6. **Generate Accessibility Guide** - WCAG compliance notes
-7. **Generate Token Reference** - Token usage documentation
-8. **Create Search Index** - Searchable component library
-
-## Output
-
-- **index.md**: Pattern library homepage
-- **components/{Component}.md**: Per-component pages
-- **tokens.md**: Token reference guide
-- **accessibility.md**: Accessibility guidelines
-- **getting-started.md**: Setup and usage guide
-
-## Failure Handling
-
-- **No components found:** If scan finds zero component files in design-system directory, abort with "No components found. Run *build to create components before generating documentation."
-- **Component metadata extraction failed:** If TypeScript parser fails to extract prop types from component file, abort with "Cannot parse {ComponentName}.tsx: {error}. Ensure valid TypeScript and exported interfaces."
-- **Missing component documentation files:** If component exists but {ComponentName}.md does not exist or is empty, warn user "{N} components missing .md files. Generate basic docs or skip incomplete components?"
-- **Broken usage examples:** If code snippets in generated documentation contain syntax errors or reference non-existent props, abort with "{N} documentation examples have errors: {list}. Fix component APIs or example code before publishing docs."
-
-## Success Criteria
-
-- [ ] All components documented
-- [ ] Props documented with types
-- [ ] Usage examples for each variant
-- [ ] Accessibility notes included
-- [ ] Searchable and navigable
-- [ ] Up-to-date with latest components
-
-## Example
-
-```bash
-*document
-```
-
-Output:
-```
-📚 Merovingian: Generating pattern library documentation...
-
-Scanning components:
-  ✓ 8 atoms found
-  ✓ 5 molecules found
-  ✓ 2 organisms found
-
-Generating documentation:
-  ✓ index.md (pattern library home)
-  ✓ components/Button.md
-  ✓ components/Input.md
-  ✓ components/FormField.md
-  ...
-  ✓ tokens.md (token reference)
-  ✓ accessibility.md (WCAG guide)
-  ✓ getting-started.md
-
-✅ Pattern library: design-system/docs/
-
-Merovingian says: "Documentation is code. Keep it fresh."
-```
-
-## Notes
-
-- Auto-generates from TypeScript types
-- Updates when components change
-- Includes live Storybook links (if enabled)
-- Searchable by component name, prop, or token
-
-
-## 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.