aiox-core 5.0.3 → 5.0.4

package/pro/squads/design/tasks/ds-mcp-status.md

@@ -1,65 +1,65 @@
-# MCP Server Status Check
-
-> Task ID: brad-ds-mcp-status
-> Agent: Brad Frost (Design System Architect)
-> Version: 1.0.0
-
-## Description
-
-Report the current status of the Design System MCP server: tools available, data sources loaded, and health.
-
-## Prerequisites
-
-- MCP server exists at `workspace/domains/design-system/mcp/`
-
-## Workflow
-
-1. **Read Config**
-   - Load `mcp/config.json` for declared tools and data sources
-
-2. **Verify Data Sources**
-   - Check each data source file exists and is valid JSON
-   - Report: file path, exists (Y/N), record count
-
-3. **Verify Handlers**
-   - Check each handler file exists: components.ts, registry.ts, tokens.ts, guidelines.ts
-
-4. **List Tools**
-   - Report all tool names with descriptions from server.ts TOOL_DEFINITIONS
-
-5. **Run Validation Scripts**
-   - `node squads/design/scripts/design-system/validate_mcp_skeleton.cjs`
-   - `node squads/design/scripts/design-system/test_mcp_tools.cjs`
-
-6. **Generate Status Report**
-   ```
-   MCP Server: design-system-mcp v1.0.0
-   Status: HEALTHY | DEGRADED | DOWN
-
-   Tools: 8/8 operational
-   Data Sources: 4/4 loaded
-   Handlers: 4/4 present
-
-   Last validation: PASS/FAIL
-   ```
-
-## Deliverables
-
-- Status report with tool list and data source health
-
-## Success Criteria
-
-- [ ] All tools listed with status
-- [ ] All data sources verified
-- [ ] Validation scripts pass
-
-
-## 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.
+# MCP Server Status Check
+
+> Task ID: brad-ds-mcp-status
+> Agent: Brad Frost (Design System Architect)
+> Version: 1.0.0
+
+## Description
+
+Report the current status of the Design System MCP server: tools available, data sources loaded, and health.
+
+## Prerequisites
+
+- MCP server exists at `workspace/domains/design-system/mcp/`
+
+## Workflow
+
+1. **Read Config**
+   - Load `mcp/config.json` for declared tools and data sources
+
+2. **Verify Data Sources**
+   - Check each data source file exists and is valid JSON
+   - Report: file path, exists (Y/N), record count
+
+3. **Verify Handlers**
+   - Check each handler file exists: components.ts, registry.ts, tokens.ts, guidelines.ts
+
+4. **List Tools**
+   - Report all tool names with descriptions from server.ts TOOL_DEFINITIONS
+
+5. **Run Validation Scripts**
+   - `node squads/design/scripts/design-system/validate_mcp_skeleton.cjs`
+   - `node squads/design/scripts/design-system/test_mcp_tools.cjs`
+
+6. **Generate Status Report**
+   ```
+   MCP Server: design-system-mcp v1.0.0
+   Status: HEALTHY | DEGRADED | DOWN
+
+   Tools: 8/8 operational
+   Data Sources: 4/4 loaded
+   Handlers: 4/4 present
+
+   Last validation: PASS/FAIL
+   ```
+
+## Deliverables
+
+- Status report with tool list and data source health
+
+## Success Criteria
+
+- [ ] All tools listed with status
+- [ ] All data sources verified
+- [ ] Validation scripts pass
+
+
+## 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-motion-audit.md

@@ -1,118 +1,118 @@
-# Audit Animations, Transitions & Motion Tokens
-
-> Task ID: brad-motion-audit
-> Agent: Brad (Design System Architect)
-> Version: 1.1.0
-> v4.0-compatible: true
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `motion`
-
-## Description
-
-Extract all CSS transition/animation values and JS animation calls from the codebase. Extract motion values into token candidates, check prefers-reduced-motion compliance, and validate against motion token best practices. **v4.1: Enriched with Val Head's 5-purpose framework — every animation evaluated for purpose (orient, direct, causality, feedback, brand). Custom easing curve audit included.**
-
-## Prerequisites
-
-- Codebase with UI components
-- Read data/motion-tokens-guide.md for token standards
-- Val Head DNA: Apply 5-purpose test to every animation found
-
-## Workflow
-
-### Interactive Elicitation
-
-1. **Gather Parameters**
-   - Scan path
-   - Animation libraries in use (framer-motion, GSAP, CSS only, etc.)
-   - Output directory
-
-### Steps
-
-1. **Grep CSS transition, animation, and @keyframes Declarations**
-   - Find all `transition` properties with values
-   - Find all `animation` / `@keyframes` declarations
-   - Find all `transform` usage in transitions
-   - Extract duration and easing values with file:line references
-   - Check: extracted CSS animation count >= 0 AND each has file:line reference — log "Found {N} CSS animation values across {F} files"
-
-2. **Grep framer-motion, GSAP, and Web Animations API Calls**
-   - Find framer-motion usage (animate, variants, transition props)
-   - Find GSAP usage (gsap.to, gsap.from, timeline)
-   - Find Web Animations API usage
-   - Find requestAnimationFrame patterns
-   - Extract duration/easing values
-   - Check: extracted JS animation count >= 0 AND each has file:line reference — log "Found {N} JS animation values across {F} files"
-
-3. **Check prefers-reduced-motion**
-   - Search for @media (prefers-reduced-motion) queries
-   - Check coverage: every animated element should have reduced-motion handling
-   - Flag animations without reduced-motion fallback
-   - Categorize: which animations are reduced vs. removed
-   - Check: coverage = (elements with reduced-motion / total animated elements) * 100 — log "prefers-reduced-motion coverage: {pct}% ({covered}/{total})"
-
-4. **Extract Motion Token Candidates**
-   - Cluster similar duration values (e.g., 180ms, 200ms, 220ms → normalize to 200ms)
-   - Cluster similar easing curves
-   - Map to standard motion token scale (instant/fast/normal/moderate/slow/deliberate)
-   - Identify semantic motion patterns (enter, exit, expand, collapse)
-   - Check: token candidate count > 0 AND each has usage count and semantic name — log "{N} motion token candidates extracted from {total} raw values"
-
-5. **Generate Motion Audit Report**
-   - Total animations found
-   - Duration/easing value inventory with redundancy metrics
-   - prefers-reduced-motion coverage (% and gaps)
-   - Token recommendations
-   - Seizure risk check (>3 flashes/second)
-   - Update .state.yaml
-
-## Output
-
-- `motion-audit-report.md` — Full audit with findings
-- `motion-token-candidates.json` — Proposed token values
-- `reduced-motion-gaps.md` — Components missing prefers-reduced-motion
-- `.state.yaml` updated
-
-## Val Head 5-Purpose Evaluation (v4.1)
-
-For every animation found, evaluate against:
-1. **Orient** — Does it help users understand spatial relationships?
-2. **Direct Attention** — Does it guide focus to important changes?
-3. **Show Causality** — Does it show cause-and-effect?
-4. **Provide Feedback** — Does it confirm user actions?
-5. **Express Brand** — Does it communicate brand personality?
-
-Animations failing ALL 5 purposes should be flagged for removal.
-
-### Easing Audit
-- Flag use of CSS defaults (ease, ease-in-out, linear) — recommend custom curves
-- Check if custom easing curves reflect brand personality
-- Evaluate if easing matches interaction type (ease-out for enters, ease-in for exits)
-
-### UI Choreography Check
-- Do animations feel like "siblings" (coherent family)?
-- Or like "strangers" (disconnected, random)?
-- Flag inconsistent motion character across components
-
-## Failure Handling
-
-- **No CSS animations found in codebase:** Verify scan path includes style files (.css, .scss, .tsx). If truly zero, report "No CSS animations detected — motion token extraction skipped"
-- **Animation library not detected (framer-motion, GSAP):** Skip JS animation scan, note "JS animations: N/A — no animation library detected"
-- **prefers-reduced-motion scan returns zero queries:** Flag as critical gap "Zero prefers-reduced-motion coverage — all animated elements at risk"
-- **Motion token clustering produces zero candidates:** Lower clustering threshold and retry. If still zero, report raw values without token recommendations
-
-## Success Criteria
-
-- All animation values catalogued with source references
-- prefers-reduced-motion coverage assessed (Val Head: "reduced motion, not no motion")
-- Token candidates reduce value redundancy by >60%
-- Zero seizure risk issues
-- Every animation has at least one of 5 purposes identified
-- CSS default easings flagged for replacement with custom curves
-
-
-## Related Checklists
-
-- `squads/design/checklists/ds-component-quality-checklist.md`
-
-## Process Guards
-- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.
+# Audit Animations, Transitions & Motion Tokens
+
+> Task ID: brad-motion-audit
+> Agent: Brad (Design System Architect)
+> Version: 1.1.0
+> v4.0-compatible: true
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `motion`
+
+## Description
+
+Extract all CSS transition/animation values and JS animation calls from the codebase. Extract motion values into token candidates, check prefers-reduced-motion compliance, and validate against motion token best practices. **v4.1: Enriched with Val Head's 5-purpose framework — every animation evaluated for purpose (orient, direct, causality, feedback, brand). Custom easing curve audit included.**
+
+## Prerequisites
+
+- Codebase with UI components
+- Read data/motion-tokens-guide.md for token standards
+- Val Head DNA: Apply 5-purpose test to every animation found
+
+## Workflow
+
+### Interactive Elicitation
+
+1. **Gather Parameters**
+   - Scan path
+   - Animation libraries in use (framer-motion, GSAP, CSS only, etc.)
+   - Output directory
+
+### Steps
+
+1. **Grep CSS transition, animation, and @keyframes Declarations**
+   - Find all `transition` properties with values
+   - Find all `animation` / `@keyframes` declarations
+   - Find all `transform` usage in transitions
+   - Extract duration and easing values with file:line references
+   - Check: extracted CSS animation count >= 0 AND each has file:line reference — log "Found {N} CSS animation values across {F} files"
+
+2. **Grep framer-motion, GSAP, and Web Animations API Calls**
+   - Find framer-motion usage (animate, variants, transition props)
+   - Find GSAP usage (gsap.to, gsap.from, timeline)
+   - Find Web Animations API usage
+   - Find requestAnimationFrame patterns
+   - Extract duration/easing values
+   - Check: extracted JS animation count >= 0 AND each has file:line reference — log "Found {N} JS animation values across {F} files"
+
+3. **Check prefers-reduced-motion**
+   - Search for @media (prefers-reduced-motion) queries
+   - Check coverage: every animated element should have reduced-motion handling
+   - Flag animations without reduced-motion fallback
+   - Categorize: which animations are reduced vs. removed
+   - Check: coverage = (elements with reduced-motion / total animated elements) * 100 — log "prefers-reduced-motion coverage: {pct}% ({covered}/{total})"
+
+4. **Extract Motion Token Candidates**
+   - Cluster similar duration values (e.g., 180ms, 200ms, 220ms → normalize to 200ms)
+   - Cluster similar easing curves
+   - Map to standard motion token scale (instant/fast/normal/moderate/slow/deliberate)
+   - Identify semantic motion patterns (enter, exit, expand, collapse)
+   - Check: token candidate count > 0 AND each has usage count and semantic name — log "{N} motion token candidates extracted from {total} raw values"
+
+5. **Generate Motion Audit Report**
+   - Total animations found
+   - Duration/easing value inventory with redundancy metrics
+   - prefers-reduced-motion coverage (% and gaps)
+   - Token recommendations
+   - Seizure risk check (>3 flashes/second)
+   - Update .state.yaml
+
+## Output
+
+- `motion-audit-report.md` — Full audit with findings
+- `motion-token-candidates.json` — Proposed token values
+- `reduced-motion-gaps.md` — Components missing prefers-reduced-motion
+- `.state.yaml` updated
+
+## Val Head 5-Purpose Evaluation (v4.1)
+
+For every animation found, evaluate against:
+1. **Orient** — Does it help users understand spatial relationships?
+2. **Direct Attention** — Does it guide focus to important changes?
+3. **Show Causality** — Does it show cause-and-effect?
+4. **Provide Feedback** — Does it confirm user actions?
+5. **Express Brand** — Does it communicate brand personality?
+
+Animations failing ALL 5 purposes should be flagged for removal.
+
+### Easing Audit
+- Flag use of CSS defaults (ease, ease-in-out, linear) — recommend custom curves
+- Check if custom easing curves reflect brand personality
+- Evaluate if easing matches interaction type (ease-out for enters, ease-in for exits)
+
+### UI Choreography Check
+- Do animations feel like "siblings" (coherent family)?
+- Or like "strangers" (disconnected, random)?
+- Flag inconsistent motion character across components
+
+## Failure Handling
+
+- **No CSS animations found in codebase:** Verify scan path includes style files (.css, .scss, .tsx). If truly zero, report "No CSS animations detected — motion token extraction skipped"
+- **Animation library not detected (framer-motion, GSAP):** Skip JS animation scan, note "JS animations: N/A — no animation library detected"
+- **prefers-reduced-motion scan returns zero queries:** Flag as critical gap "Zero prefers-reduced-motion coverage — all animated elements at risk"
+- **Motion token clustering produces zero candidates:** Lower clustering threshold and retry. If still zero, report raw values without token recommendations
+
+## Success Criteria
+
+- All animation values catalogued with source references
+- prefers-reduced-motion coverage assessed (Val Head: "reduced motion, not no motion")
+- Token candidates reduce value redundancy by >60%
+- Zero seizure risk issues
+- Every animation has at least one of 5 purposes identified
+- CSS default easings flagged for replacement with custom curves
+
+
+## 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-multi-framework.md

@@ -1,96 +1,96 @@
-# Design Web Components Strategy for Multi-Framework DS
-
-> Task ID: brad-multi-framework
-> Agent: Brad (Design System Architect)
-> Version: 1.0.0
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `multi-framework`
-
-## Description
-
-Design a strategy to make your design system work across multiple frameworks (React, Vue, Angular, Svelte) using Web Components as the interop layer. Evaluates current framework coupling, assesses Web Components viability, and creates a migration path.
-
-## Prerequisites
-
-- Existing DS in at least one framework
-- Read data/ds-reference-architectures.md for multi-framework patterns
-
-## Workflow
-
-### Interactive Elicitation
-
-1. **Gather Parameters**
-   - Current framework(s) in use
-   - Target frameworks to support
-   - Component count and complexity
-   - Performance requirements
-
-2. **Strategy Selection**
-   - **Lit** — Google's Web Components library, lightweight, reactive
-   - **StencilJS** — Ionic's compiler, generates framework wrappers automatically
-   - **Vanilla Web Components** — No library, maximum control, more boilerplate
-   - Recommend based on team size and target frameworks
-
-### Steps
-
-1. **Assess Current Framework Coupling**
-   - Identify framework-specific patterns (React hooks, Vue composables, Angular services)
-   - Separate pure logic from framework-specific rendering
-   - Identify components that are framework-agnostic vs. tightly coupled
-   - Check: each component has coupling score (framework-agnostic / tightly-coupled) AND migration difficulty rating — log "{agnostic} agnostic, {coupled} coupled components"
-
-2. **Design Web Components Architecture**
-   - Define component API surface (attributes, properties, events, slots)
-   - Plan styling strategy (CSS custom properties, shadow DOM, light DOM)
-   - Define custom element naming convention ({prefix}-{component})
-   - Plan server-side rendering approach (declarative shadow DOM)
-   - Check: architecture defines API surface (attributes, properties, events, slots) AND styling strategy documented — abort with "Architecture missing: {missing section}"
-
-3. **Create Framework Wrappers**
-   - React wrapper: handle synthetic events, ref forwarding, prop mapping
-   - Vue wrapper: v-model support, event mapping, slot forwarding
-   - Angular wrapper: NgModule/standalone, input/output binding
-   - Check: wrapper exists for each target framework AND handles events + refs + props — abort with "Wrapper missing or incomplete for: {framework}"
-
-4. **Build Proof-of-Concept Component**
-   - Select a medium-complexity component (e.g., Select, Dialog, Tabs)
-   - Implement as Web Component with chosen library
-   - Generate wrappers for each target framework
-   - Test in each framework's development environment
-   - Check: PoC component renders AND passes same test suite in each target framework — abort with "PoC failed in: {framework}: {error}"
-
-5. **Create Migration Path**
-   - Phase 1: New components built as Web Components
-   - Phase 2: High-reuse existing components migrated
-   - Phase 3: Framework-specific components gradually replaced
-   - Check: migration plan has 3 phases AND component priority list with migration order — abort with "Migration plan incomplete: {missing section}"
-
-## Output
-
-- `multi-framework-strategy.md` — Architecture and decision documentation
-- `poc/{component}/` — Proof-of-concept Web Component + framework wrappers
-- `migration-plan.md` — Phased migration with component priorities
-- `.state.yaml` updated
-
-## Failure Handling
-
-- **Web Component library incompatible with target framework:** If chosen library (Lit/Stencil/Vanilla) fails to render or causes runtime errors in one of the target frameworks, document the failure, test with alternate library, and recommend library switch if issue persists
-- **Shadow DOM breaks framework styling:** If shadow DOM encapsulation prevents framework's CSS-in-JS or scoped styles from applying, switch strategy to light DOM with CSS custom properties for theming, document trade-offs in multi-framework-strategy.md
-- **SSR/SSG not supported in target framework:** If framework requires server-side rendering (Next.js, Nuxt) but Web Components cause hydration errors or are not SSR-compatible, implement declarative shadow DOM polyfill or defer component initialization to client-side, note limitation in migration-plan.md
-- **Framework wrapper overhead exceeds 5KB:** If wrapper code for React/Vue/Angular is too large (e.g., event mapping complexity, prop transformation), refactor to minimize wrapper logic, move complexity into Web Component itself, and re-measure — if still over threshold, document performance impact and suggest tree-shaking optimization
-
-## Success Criteria
-
-- PoC component works identically in all target frameworks
-- Wrapper overhead < 2KB per framework
-- No functionality loss compared to framework-native implementation
-- Clear migration path with prioritized component list
-
-
-## 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.
+# Design Web Components Strategy for Multi-Framework DS
+
+> Task ID: brad-multi-framework
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `multi-framework`
+
+## Description
+
+Design a strategy to make your design system work across multiple frameworks (React, Vue, Angular, Svelte) using Web Components as the interop layer. Evaluates current framework coupling, assesses Web Components viability, and creates a migration path.
+
+## Prerequisites
+
+- Existing DS in at least one framework
+- Read data/ds-reference-architectures.md for multi-framework patterns
+
+## Workflow
+
+### Interactive Elicitation
+
+1. **Gather Parameters**
+   - Current framework(s) in use
+   - Target frameworks to support
+   - Component count and complexity
+   - Performance requirements
+
+2. **Strategy Selection**
+   - **Lit** — Google's Web Components library, lightweight, reactive
+   - **StencilJS** — Ionic's compiler, generates framework wrappers automatically
+   - **Vanilla Web Components** — No library, maximum control, more boilerplate
+   - Recommend based on team size and target frameworks
+
+### Steps
+
+1. **Assess Current Framework Coupling**
+   - Identify framework-specific patterns (React hooks, Vue composables, Angular services)
+   - Separate pure logic from framework-specific rendering
+   - Identify components that are framework-agnostic vs. tightly coupled
+   - Check: each component has coupling score (framework-agnostic / tightly-coupled) AND migration difficulty rating — log "{agnostic} agnostic, {coupled} coupled components"
+
+2. **Design Web Components Architecture**
+   - Define component API surface (attributes, properties, events, slots)
+   - Plan styling strategy (CSS custom properties, shadow DOM, light DOM)
+   - Define custom element naming convention ({prefix}-{component})
+   - Plan server-side rendering approach (declarative shadow DOM)
+   - Check: architecture defines API surface (attributes, properties, events, slots) AND styling strategy documented — abort with "Architecture missing: {missing section}"
+
+3. **Create Framework Wrappers**
+   - React wrapper: handle synthetic events, ref forwarding, prop mapping
+   - Vue wrapper: v-model support, event mapping, slot forwarding
+   - Angular wrapper: NgModule/standalone, input/output binding
+   - Check: wrapper exists for each target framework AND handles events + refs + props — abort with "Wrapper missing or incomplete for: {framework}"
+
+4. **Build Proof-of-Concept Component**
+   - Select a medium-complexity component (e.g., Select, Dialog, Tabs)
+   - Implement as Web Component with chosen library
+   - Generate wrappers for each target framework
+   - Test in each framework's development environment
+   - Check: PoC component renders AND passes same test suite in each target framework — abort with "PoC failed in: {framework}: {error}"
+
+5. **Create Migration Path**
+   - Phase 1: New components built as Web Components
+   - Phase 2: High-reuse existing components migrated
+   - Phase 3: Framework-specific components gradually replaced
+   - Check: migration plan has 3 phases AND component priority list with migration order — abort with "Migration plan incomplete: {missing section}"
+
+## Output
+
+- `multi-framework-strategy.md` — Architecture and decision documentation
+- `poc/{component}/` — Proof-of-concept Web Component + framework wrappers
+- `migration-plan.md` — Phased migration with component priorities
+- `.state.yaml` updated
+
+## Failure Handling
+
+- **Web Component library incompatible with target framework:** If chosen library (Lit/Stencil/Vanilla) fails to render or causes runtime errors in one of the target frameworks, document the failure, test with alternate library, and recommend library switch if issue persists
+- **Shadow DOM breaks framework styling:** If shadow DOM encapsulation prevents framework's CSS-in-JS or scoped styles from applying, switch strategy to light DOM with CSS custom properties for theming, document trade-offs in multi-framework-strategy.md
+- **SSR/SSG not supported in target framework:** If framework requires server-side rendering (Next.js, Nuxt) but Web Components cause hydration errors or are not SSR-compatible, implement declarative shadow DOM polyfill or defer component initialization to client-side, note limitation in migration-plan.md
+- **Framework wrapper overhead exceeds 5KB:** If wrapper code for React/Vue/Angular is too large (e.g., event mapping complexity, prop transformation), refactor to minimize wrapper logic, move complexity into Web Component itself, and re-measure — if still over threshold, document performance impact and suggest tree-shaking optimization
+
+## Success Criteria
+
+- PoC component works identically in all target frameworks
+- Wrapper overhead < 2KB per framework
+- No functionality loss compared to framework-native implementation
+- Clear migration path with prioritized component list
+
+
+## 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.