aiox-core 5.0.2 → 5.0.4

package/pro/squads/design/tasks/ds-integrate-workspace.md

@@ -0,0 +1,100 @@
+# Integrate Design System with Workspace Structure
+
+> Task ID: brad-ds-integrate-workspace
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+
+## Description
+
+Align the design system with the workspace topology:
+
+- `workspace/domains/design-system`
+- `workspace/system`
+- `workspace/ui`
+
+This task creates clear boundaries for tokens, primitives, patterns, and product-ready components.
+
+## Prerequisites
+
+- Existing design squad setup (`squads/design`)
+- Workspace directory available
+- Tailwind v4 strategy defined (`@theme`)
+- Decision on registry-first distribution (Shadcn model)
+
+## Workflow
+
+1. **Map Current State**
+- Inventory token files, component files, and style utilities.
+- Classify by role: token source, primitive, product UI.
+
+2. **Create Target Workspace Structure**
+- `workspace/domains/design-system/tokens/primitives`
+- `workspace/domains/design-system/tokens/semantic`
+- `workspace/domains/design-system/tokens/component`
+- `workspace/domains/design-system/themes`
+- `workspace/domains/design-system/metadata`
+- `workspace/system/primitives`
+- `workspace/system/patterns`
+- `workspace/ui/components`
+- `workspace/ui/blocks`
+
+3. **Define Ownership Boundaries**
+- `domains/design-system`: token truth and themes.
+- `system`: reusable Radix/Shadcn primitives and patterns.
+- `ui`: app-facing composed components and blocks.
+
+4. **Wire Configuration**
+- Add mapping files under `config/mappings/`:
+  - `colors.json`
+  - `spacing.json`
+  - `components.json`
+- Ensure mappings are generated from tokens, not hardcoded.
+
+5. **Integrate with Registry Flow**
+- Place `registry.json` in `workspace/ui/`.
+- Ensure component metadata references source paths and dependencies.
+
+6. **Validation**
+- Verify no circular dependencies between `domains`, `system`, and `ui`.
+- Verify component imports only flow upward:
+  - `domains` -> `system` -> `ui`
+- Validate with lint, typecheck, and tests.
+
+7. **Documentation**
+- Generate migration notes:
+  - old path -> new path
+  - rollback plan
+  - unresolved gaps
+
+## Deliverables
+
+- Workspace-aligned folder topology
+- Token ownership boundaries documented
+- Mapping config files added/updated
+- `workspace/ui/registry.json` strategy in place
+- Migration report with file move matrix
+
+## Success Criteria
+
+- [ ] Workspace layers are explicit and stable
+- [ ] Token hierarchy is split (primitives/semantic/component)
+- [ ] Registry flow resolves components from `workspace/ui`
+- [ ] Import direction is deterministic (`domains` -> `system` -> `ui`)
+- [ ] Migration steps documented and reproducible
+
+## Notes
+
+- Prefer configuration over hardcoded mappings.
+- Keep token names stable to avoid migration churn.
+- Treat workspace topology as architecture, not temporary structure.
+
+
+## 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-legacy-modernization.md

@@ -0,0 +1,302 @@
+# Legacy System Modernization Playbook
+
+> Task ID: ds-legacy-modernization
+> Agent: Brad Frost + Design Chief
+> Version: 1.0.0
+> Heuristic: #15 - Legado é oportunidade massiva
+
+## Description
+
+Playbook para modernizar sistemas legados (CodeIgniter, Laravel, Rails, jQuery) para stacks modernas com design system.
+
+**Princípio:** Migrar sistemas legados = produto de múltiplos 6 dígitos.
+
+---
+
+## Value Proposition
+
+| Legacy Stack | Migration Target | Market Value |
+|--------------|------------------|--------------|
+| CodeIgniter + Bootstrap 3 | Next.js + Tailwind + Shadcn | $50K-150K |
+| Laravel Blade + jQuery | React + Design System | $80K-200K |
+| Rails ERB + Sprockets | Next.js + Modern CSS | $100K-300K |
+| WordPress + Custom Theme | Headless + Component Library | $30K-100K |
+
+---
+
+## Assessment Phase
+
+### 1. Inventory
+
+```yaml
+assessment:
+  codebase:
+    total_files: number
+    ui_files: number
+    css_files: number
+    js_files: number
+
+  patterns:
+    inline_styles: count
+    hardcoded_colors: count
+    duplicated_components: count
+    accessibility_issues: count
+
+  dependencies:
+    framework: string
+    css_framework: string
+    js_libraries: array
+    build_tool: string
+```
+
+### 2. Complexity Score
+
+```
+Score = (UI files × 0.3) + (Inline styles × 0.2) + (Duplications × 0.3) + (A11y issues × 0.2)
+
+Low:    0-100   → 2-4 weeks
+Medium: 100-500 → 1-3 months
+High:   500+    → 3-6 months
+```
+
+### 3. Risk Matrix
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Breaking existing flows | HIGH | Feature flags + gradual rollout |
+| Data loss | CRITICAL | Backup + rollback plan |
+| Performance regression | MEDIUM | Benchmark before/after |
+| Team unfamiliarity | MEDIUM | Training + documentation |
+
+---
+
+## Migration Strategies
+
+### Strategy A: Big Bang (Greenfield Rebuild)
+
+```
+✅ When to use:
+- Codebase is small (<50 UI files)
+- Team has capacity for full rebuild
+- Business can tolerate downtime
+
+❌ When to avoid:
+- Large codebase
+- Critical system with SLAs
+- Limited team bandwidth
+```
+
+### Strategy B: Strangler Fig (Gradual)
+
+```
+✅ When to use:
+- Large codebase
+- Can't afford downtime
+- Need to maintain features during migration
+
+Approach:
+1. New features in new stack
+2. Wrap legacy in adapter
+3. Migrate page by page
+4. Sunset legacy when empty
+```
+
+### Strategy C: Component Islands
+
+```
+✅ When to use:
+- Mixed team (legacy + modern skills)
+- Partial modernization acceptable
+- Budget constraints
+
+Approach:
+1. Identify high-value components
+2. Rebuild only those in modern stack
+3. Embed via Web Components or iframes
+4. Leave low-value areas in legacy
+```
+
+---
+
+## Execution Phases
+
+### Phase 1: Foundation (Week 1-2)
+
+```yaml
+deliverables:
+  - Assessment report
+  - Migration strategy selection
+  - Token extraction from legacy CSS
+  - Design system setup
+
+tasks:
+  - ds-audit-codebase
+  - ds-extract-tokens
+  - ds-setup-design-system
+```
+
+### Phase 2: Primitives (Week 3-4)
+
+```yaml
+deliverables:
+  - Button, Input, Card in new system
+  - Typography system
+  - Color system
+  - Spacing system
+
+tasks:
+  - ds-build-component (×N)
+  - ds-sync-registry
+```
+
+### Phase 3: Patterns (Week 5-8)
+
+```yaml
+deliverables:
+  - Form patterns
+  - Layout patterns
+  - Navigation patterns
+  - Feedback patterns
+
+tasks:
+  - ds-compose-molecule (×N)
+  - ds-consolidate-patterns
+```
+
+### Phase 4: Pages (Week 9-12)
+
+```yaml
+deliverables:
+  - High-traffic pages migrated
+  - Feature parity verified
+  - A11y audit passed
+
+tasks:
+  - Page migration (per page)
+  - a11y-audit
+  - ds-govern-a11y-compliance
+```
+
+### Phase 5: Cleanup (Week 13+)
+
+```yaml
+deliverables:
+  - Legacy code removed
+  - Documentation updated
+  - Team trained
+
+tasks:
+  - Legacy sunset
+  - Documentation
+  - Training sessions
+```
+
+---
+
+## VPAT Generation (Bonus Value)
+
+VPAT (Voluntary Product Accessibility Template) = documento que prova compliance de acessibilidade.
+
+**Market Value:** $50K-200K por documento
+
+### VPAT Automation Workflow
+
+1. Run `ds-govern-a11y-compliance` on all components
+2. Map results to WCAG criteria
+3. Generate VPAT document
+4. Human review for edge cases
+
+```yaml
+vpat_output:
+  criteria_covered: 86
+  criteria_passed: 82
+  criteria_partial: 4
+  criteria_failed: 0
+  overall_conformance: "AA"
+```
+
+---
+
+## Pricing Model
+
+```yaml
+pricing_tiers:
+  assessment_only:
+    deliverables: ["Assessment report", "Migration recommendation"]
+    price_range: "$5K-15K"
+    timeline: "1-2 weeks"
+
+  foundation_package:
+    deliverables: ["Assessment", "Design system setup", "Token extraction", "5 core components"]
+    price_range: "$25K-50K"
+    timeline: "4-6 weeks"
+
+  full_migration:
+    deliverables: ["Everything above", "Full page migration", "A11y compliance", "Documentation"]
+    price_range: "$80K-300K"
+    timeline: "3-6 months"
+
+  vpat_addon:
+    deliverables: ["VPAT document", "Remediation report"]
+    price_range: "$15K-50K"
+    timeline: "2-4 weeks"
+```
+
+---
+
+## Veto Conditions
+
+- [ ] No budget approved
+- [ ] No executive sponsor
+- [ ] Legacy system has no documentation AND no original developers
+- [ ] Migration timeline is unrealistic (<50% of estimated)
+
+---
+
+## Quality Gates
+
+- [ ] Assessment score calculated
+- [ ] Strategy selected with justification
+- [ ] Phase deliverables defined
+
+## Output
+
+- `outputs/design-system/{project}/legacy/assessment-report.md`
+- `outputs/design-system/{project}/legacy/migration-strategy.md`
+- `outputs/design-system/{project}/legacy/migration-roadmap.md`
+- `outputs/design-system/{project}/legacy/risk-matrix.md`
+
+## Related Checklists
+
+- `squads/design/checklists/ds-migration-readiness-checklist.md`
+- `squads/design/checklists/ds-accessibility-wcag-checklist.md`
+- [ ] Rollback plan documented
+- [ ] Success metrics defined
+
+---
+
+## Success Metrics
+
+| Metric | Target |
+|--------|--------|
+| Page load time | -50% |
+| Bundle size | -40% |
+| A11y score | 95+ |
+| Component reuse | 80%+ |
+| Developer velocity | +100% |
+
+---
+
+*Task criada: 2026-02-16*
+*Squad: Design*
+
+
+## Process Guards
+- **Execution Type:** `Hybrid`
+- **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `design-system`
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.
+
+## Success Criteria
+- [ ] Output artifact(s) generated and referenced.
+- [ ] Validation checks executed with evidence.
+- [ ] Next-step dependencies documented.

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

@@ -0,0 +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.

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

@@ -0,0 +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.

package/pro/squads/design/tasks/ds-multi-framework.md

@@ -0,0 +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.