aiox-core 5.0.3 → 5.0.4

package/pro/squads/design/tasks/ds-generate-ai-metadata.md

@@ -1,81 +1,81 @@
-# 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.
+# 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 +1,74 @@
-# 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.
+# 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 +1,101 @@
-# 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.
+# 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.