aiox-core 5.0.4 → 5.0.5

package/pro/squads/design/tasks/ds-parallelization-gate.md

@@ -1,246 +0,0 @@
-# Parallelization Analysis Gate
-
-> Task ID: ds-parallelization-gate
-> Agent: Design Chief
-> Version: 1.0.0
-> Heuristic: #11 - Paralelização só após análise de dependência
-
-## Description
-
-Gate obrigatório antes de distribuir trabalho em paralelo. Analisa dependências e identifica conflitos.
-
-**Princípio:** Paralelizar sem análise = merge conflicts + retrabalho.
-
----
-
-## When to Use
-
-Execute ANTES de:
-- Distribuir componentes para múltiplos agents
-- Executar múltiplas tasks de design simultaneamente
-- Modificar tokens que afetam múltiplos componentes
-- Refatorar patterns compartilhados
-
----
-
-## Input
-
-```yaml
-input:
-  tasks_to_parallelize:
-    - task_id: string
-      scope:
-        files: array
-        tokens: array
-        components: array
-
-  execution_mode: enum  # "parallel" | "sequential" | "hybrid"
-```
-
----
-
-## Analysis Algorithm
-
-```python
-def analyze_parallelization(tasks):
-    """
-    Retorna quais tasks podem rodar em paralelo
-    e quais devem ser sequenciais.
-    """
-
-    # 1. Extrair recursos de cada task
-    resources = {}
-    for task in tasks:
-        resources[task.id] = {
-            'reads': extract_reads(task),
-            'writes': extract_writes(task)
-        }
-
-    # 2. Detectar conflitos
-    conflicts = []
-    for i, task_a in enumerate(tasks):
-        for task_b in tasks[i+1:]:
-            # Write-Write conflict
-            if overlap(resources[task_a.id]['writes'],
-                       resources[task_b.id]['writes']):
-                conflicts.append({
-                    'type': 'write-write',
-                    'tasks': [task_a.id, task_b.id],
-                    'resource': get_overlap(...)
-                })
-
-            # Read-Write conflict
-            if overlap(resources[task_a.id]['reads'],
-                       resources[task_b.id]['writes']):
-                conflicts.append({
-                    'type': 'read-write',
-                    'tasks': [task_a.id, task_b.id],
-                    'resource': get_overlap(...)
-                })
-
-    # 3. Separar parallelizable vs sequential
-    if conflicts:
-        return {
-            'can_parallelize': False,
-            'conflicts': conflicts,
-            'recommendation': build_sequence(tasks, conflicts)
-        }
-
-    return {
-        'can_parallelize': True,
-        'parallel_groups': group_by_independence(tasks)
-    }
-```
-
----
-
-## Execution Steps
-
-1. Coletar escopo (`reads`/`writes`) de cada task candidata.
-2. Rodar análise de conflito (`write-write`, `read-write`, dependências de token/composição).
-3. Marcar tasks bloqueadas para execução paralela.
-4. Gerar plano final: grupos paralelos seguros ou sequência ordenada.
-5. Publicar evidências de conflito e decisão final de execução.
-
----
-
-## Conflict Types
-
-| Type | Description | Resolution |
-|------|-------------|------------|
-| **Write-Write** | Duas tasks escrevem no mesmo arquivo | Sequenciar |
-| **Read-Write** | Uma task lê o que outra escreve | Ordenar (write primeiro) |
-| **Token Dependency** | Componente depende de token sendo modificado | Sequenciar |
-| **Component Composition** | Componente A usa componente B | B antes de A |
-
----
-
-## Output
-
-```yaml
-output:
-  analysis_result:
-    can_parallelize: boolean
-    conflicts: array
-
-  execution_plan:
-    # Se pode paralelizar
-    parallel_groups:
-      - group_id: 1
-        tasks: ["task-a", "task-b"]
-      - group_id: 2
-        tasks: ["task-c"]
-        depends_on: [1]
-
-    # Se não pode
-    sequence:
-      - task_id: "task-a"
-        reason: "Modifies shared tokens"
-      - task_id: "task-b"
-        depends_on: "task-a"
-        reason: "Uses tokens from task-a"
-```
-
----
-
-## Example
-
-### Input
-```yaml
-tasks_to_parallelize:
-  - task_id: "update-button-tokens"
-    scope:
-      files: ["design-tokens-spec.yaml"]
-      tokens: ["color.brand.primary"]
-      components: []
-
-  - task_id: "refactor-button-component"
-    scope:
-      files: ["button.tsx", "button.variants.ts"]
-      tokens: ["color.brand.primary"]  # READS this token
-      components: ["button"]
-
-  - task_id: "create-card-component"
-    scope:
-      files: ["card.tsx"]
-      tokens: ["color.surface.default"]
-      components: ["card"]
-```
-
-### Output
-```yaml
-analysis_result:
-  can_parallelize: false
-  conflicts:
-    - type: "read-write"
-      tasks: ["update-button-tokens", "refactor-button-component"]
-      resource: "color.brand.primary"
-      reason: "refactor-button reads token that update-button writes"
-
-execution_plan:
-  sequence:
-    - task_id: "update-button-tokens"
-      order: 1
-    - task_id: "refactor-button-component"
-      order: 2
-      depends_on: "update-button-tokens"
-
-  parallel_safe:
-    - task_id: "create-card-component"
-      can_run_with: ["update-button-tokens", "refactor-button-component"]
-```
-
----
-
-## Veto Conditions
-
-- [ ] Conflito write-write detectado sem resolução clara
-- [ ] Dependência circular detectada
-- [ ] Mais de 3 níveis de dependência (complexidade alta)
-
----
-
-## Integration
-
-### Com Task Runner
-```javascript
-// Antes de executar tasks em paralelo
-const analysis = await runParallelizationGate(tasks);
-
-if (!analysis.can_parallelize) {
-  console.log('Conflicts detected:', analysis.conflicts);
-  console.log('Running sequentially:', analysis.execution_plan.sequence);
-  await runSequential(analysis.execution_plan.sequence);
-} else {
-  await runParallel(analysis.execution_plan.parallel_groups);
-}
-```
-
----
-
-## Quality Gates
-
-- [ ] Análise executada antes de qualquer paralelização
-- [ ] Conflitos documentados com razão clara
-- [ ] Plano de execução gerado automaticamente
-- [ ] Zero merge conflicts após execução
-
----
-
-*Task criada: 2026-02-16*
-*Squad: Design*
-
-
-## Related Checklists
-
-- `squads/design/checklists/ds-component-quality-checklist.md`
-- `squads/design/checklists/ds-pattern-audit-checklist.md`
-
-## Process Guards
-- **Execution Type:** `Hybrid`
-- **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-query.md

@@ -1,90 +0,0 @@
-# Interactive Design System Query
-
-> Task ID: brad-ds-query
-> Agent: Brad Frost (Design System Architect)
-> Version: 1.0.0
-
-## Description
-
-Interactive query interface for the design system via MCP tools. Answers questions about components, tokens, guidelines, and suggests components for use cases.
-
-## Prerequisites
-
-- MCP server functional (8 tools)
-- All data sources loaded
-
-## Workflow
-
-1. **Parse User Query**
-   - Identify intent: component lookup, token search, guideline check, or suggestion
-   - Extract key entities: component name, category, use case description
-
-2. **Route to MCP Tool**
-
-   | Intent | MCP Tool |
-   |--------|----------|
-   | "What components exist?" | `design_system.list_components` |
-   | "Show me the button" | `design_system.get_component` |
-   | "Find components for forms" | `design_system.search_components` |
-   | "What are the a11y requirements for X?" | `design_system.get_a11y_requirements` |
-   | "Show color tokens" | `design_system.get_tokens` |
-   | "How should I use the input?" | `design_system.get_guidelines` |
-   | "I need a status indicator" | `design_system.suggest_component` |
-   | "Show registry entry for X" | `design_system.get_registry_entry` |
-
-3. **Format Response**
-   - Present results in structured format (tables, code blocks)
-   - Include related information (e.g., related components from guidelines)
-   - Suggest follow-up queries
-
-4. **Chain Queries (Advanced)**
-   - "Show me everything about button" →
-     1. get_component (metadata)
-     2. get_guidelines (usage)
-     3. get_tokens (component tier, button-*)
-     4. get_registry_entry (files, deps)
-
-## Examples
-
-```
-User: *ds-query what component for a submit button?
-Brad: Running suggest_component("submit")...
-
-  Suggestions:
-  1. button (score: 6) — when_to_use: "Primary actions (submit, save, create)", "Form submissions"
-  2. form-field (score: 3) — when_to_use: "Any form input that needs a label"
-
-  Recommendation: Use `button` with variant="primary" inside a `form-field`.
-
-User: *ds-query color tokens
-Brad: Running get_tokens(category: "color")...
-
-  27 color tokens found:
-  | Tier | Count | Examples |
-  |------|-------|---------|
-  | primitive | 18 | --primitive-color-gold, --primitive-color-bg-base |
-  | semantic | 6 | --color-bg-default, --color-interactive-default |
-  | component | 3 | --button-bg-primary, --card-bg |
-```
-
-## Deliverables
-
-- Real-time answers from design system data
-- Structured output with actionable recommendations
-
-## Success Criteria
-
-- [ ] All 8 MCP tools accessible via natural language queries
-- [ ] Responses include concrete values, not just descriptions
-- [ ] Follow-up suggestions provided for deeper exploration
-
-
-## 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-rebuild-artifact.md

@@ -1,369 +0,0 @@
-# Rebuild Artifact with Design Tokens
-
-> Task ID: ds-rebuild-artifact
-> Agent: design-system
-> Version: 1.0.0
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[ds-scan-artifact]` · enables: `[]` · workflow: `artifact-analysis`
-
-## Description
-
-Rebuilds HTML artifact using design tokens to produce clean, token-based version with identical visual output. This is a pragmatic alternative to manual migration - takes messy HTML (inline styles, hardcoded values) and outputs clean HTML using tokens.css.
-
-**Goal**: Same design, better code, in minutes not hours.
-
-## Input Schema
-- **requires:** Output from `ds-scan-artifact`
-- **format:** JSON data
-- **location:** `outputs/design-system/{project}/artifacts/artifact-scan-{id}.json`
-
-## Prerequisites
-
-- Tokenization completed (*tokenize command run successfully)
-- tokens.css exists in outputs/design-system/{project}/
-- Artifact to rebuild available (file path or HTML content)
-- .state.yaml contains token data
-
-## Workflow
-
-### Interactive Elicitation
-
-This task uses interactive elicitation to configure rebuild.
-
-1. **Select Source Artifact**
-   - Ask for artifact source (file path, artifact ID from scan, or paste HTML)
-   - Validate artifact exists and is readable
-   - Show preview of current state (inline styles count, hardcoded values)
-
-2. **Confirm Rebuild Approach**
-   - Show what will be changed (inline → classes, hardcoded → var())
-   - Ask if user wants component extraction (optional)
-   - Confirm output location
-
-3. **Validate Tokens Available**
-   - Check tokens.css exists
-   - Show token coverage for this artifact
-   - Warn if artifact uses patterns not in token system
-
-### Steps
-
-1. **Load Source Artifact**
-   - Read artifact HTML (from file, scan ID, or direct paste)
-   - Parse HTML structure
-   - Identify current styling approach (inline, hardcoded, mixed)
-   - Check: HTML parses without errors AND contains at least one element — abort with "Invalid HTML: {parse error}"
-
-2. **Load Token System**
-   - Read tokens.css from project directory
-   - Parse available tokens (colors, spacing, typography, etc)
-   - Build token lookup table
-   - Check: `test -f tokens.css` AND file parses as valid CSS AND token count > 0 — abort with "tokens.css invalid or missing: run *tokenize first"
-
-3. **Analyze Current Patterns**
-   - Extract all color declarations (inline, hardcoded)
-   - Extract all spacing values
-   - Extract all typography styles
-   - Map to nearest token matches
-   - Check: unmapped pattern count == 0 OR unmapped patterns documented — log "{mapped}/{total} patterns mapped to tokens, {unmapped} gaps identified"
-
-4. **Generate Clean HTML Structure**
-   - Preserve semantic HTML structure
-   - Remove inline styles
-   - Apply semantic class names
-   - Use token-based utility classes
-   - Maintain visual hierarchy
-   - Check: rebuilt HTML element count matches original AND semantic tags preserved — abort with "HTML structure lost: {original_count} elements -> {rebuilt_count}"
-
-5. **Apply Token-Based Styling**
-   - Replace inline colors with token classes (`.text-success`, `.bg-secondary`)
-   - Replace hardcoded values with `var()` references
-   - Replace spacing with token utilities
-   - Replace typography with token classes
-   - Check: hardcoded color/spacing value count == 0 AND all style values use `var(--` or token classes — abort with "{N} hardcoded values remain"
-
-6. **Generate Companion CSS**
-   - Create artifact-specific CSS file (if needed)
-   - Use tokens.css as base
-   - Add only custom styles not covered by tokens
-   - Document any deviations
-   - Check: custom CSS declarations count < 20 AND all reference tokens.css variables — log "Companion CSS: {N} custom rules extending tokens.css"
-
-7. **Visual Validation**
-   - Compare visual output (automated if possible)
-   - Check color accuracy (HSL distance < 5%)
-   - Check spacing consistency
-   - Check typography rendering
-   - Check: color HSL distance < 5% for all mapped colors AND spacing values match within 2px — log "Visual validation: {pass_count}/{total} checks passed"
-
-8. **Generate Output Files**
-   - Write rebuilt HTML to output directory
-   - Copy/link tokens.css
-   - Write companion CSS if needed
-   - Generate comparison report
-   - Check: `test -f {name}-rebuilt.html` AND `test -f tokens.css` AND all file sizes > 0 — abort with "Output generation failed: {missing file}"
-
-9. **Create Rebuild Report**
-   - Document changes made (inline removed, tokens applied)
-   - Show before/after metrics
-   - List any patterns that couldn't be tokenized
-   - Include visual comparison screenshots/descriptions
-   - Check: `test -f rebuild-report-{id}.md` AND report contains before/after metrics + changes list — abort with "Rebuild report generation failed"
-
-10. **Update State File**
-    - Add rebuild to agent history
-    - Record artifact ID, output location
-    - Update component metrics
-    - Set phase flag if applicable
-    - Check: .state.yaml contains rebuild entry with artifact ID + output location — abort with "State update failed"
-
-## Output
-
-- **{artifact-name}-rebuilt.html**: Clean HTML with token-based styling
-- **{artifact-name}.css**: Companion CSS (minimal, extends tokens.css)
-- **rebuild-report-{artifact-id}.md**: Before/after comparison report
-- **.state.yaml**: Updated with rebuild history
-
-### Output Format
-
-```html
-<!-- {artifact-name}-rebuilt.html -->
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>{Original Title}</title>
-
-  <!-- Design System Tokens -->
-  <link rel="stylesheet" href="tokens.css">
-
-  <!-- Artifact-specific styles (if needed) -->
-  <link rel="stylesheet" href="{artifact-name}.css">
-</head>
-<body>
-  <!-- Clean semantic HTML with token classes -->
-  <div class="bg-secondary text-primary p-xl rounded-lg">
-    <h1 class="text-hero font-bold">Example</h1>
-    <span class="text-success">✓</span>
-  </div>
-</body>
-</html>
-```
-
-### Rebuild Report Format
-
-```markdown
-# Rebuild Report: {artifact-name}
-
-**Artifact ID**: {id}
-**Rebuilt**: 2025-10-28
-**Agent**: Brad (Design System Architect)
-
----
-
-## Summary
-
-✅ **Rebuild Complete**
-- Visual output: 100% match
-- Code quality: Improved 85%
-- Token usage: 100%
-
-## Metrics
-
-| Metric | Before | After | Change |
-|--------|--------|-------|--------|
-| Inline styles | 110 | 0 | -100% |
-| Hardcoded colors | 15 | 0 | -100% |
-| Token usage | 0% | 100% | +100% |
-| File size | 2.4 KB | 1.8 KB | -25% |
-| Maintainability | 15/100 | 95/100 | +533% |
-
-## Changes Made
-
-### Colors
-- `style="color: rgb(72, 187, 120)"` → `class="text-success"`
-- `#262625` → `var(--bg-secondary)`
-
-### Spacing
-- `padding: 16px` → `class="p-lg"`
-- `margin: 24px` → `class="m-xl"`
-
-### Typography
-- `font-size: 24px` → `class="text-section"`
-- `font-weight: 600` → `class="font-semibold"`
-
-## Patterns Not Tokenized
-
-None - 100% token coverage achieved.
-
-## Visual Validation
-
-✅ Colors match (HSL distance < 1%)
-✅ Spacing preserved
-✅ Typography identical
-✅ Layout unchanged
-
-## Next Steps
-
-- Deploy rebuilt version
-- Archive old version
-- Update references
-```
-
-## Failure Handling
-
-- **Token coverage below 70%:** If less than 70% of artifact patterns map to tokens, halt rebuild and suggest running *tokenize with additional pattern extraction before proceeding
-- **Critical structural changes detected:** If rebuilt HTML loses semantic tags or element hierarchy (parent-child relationships broken), abort with "Structure preservation failed — manual review required for {component}"
-- **Visual validation fails by >10%:** If color HSL distance exceeds 10% or spacing differs by >4px on 20%+ of comparisons, generate diff report and exit with "Visual fidelity threshold not met — review diff report before accepting rebuild"
-- **Circular token references detected:** If token mapping creates circular dependencies (token A → token B → token A), break the cycle by inlining one value and document as tech debt in rebuild report
-
-## Success Criteria
-
-- [ ] Original HTML parsed successfully
-- [ ] All patterns mapped to tokens
-- [ ] Clean HTML generated (zero inline styles)
-- [ ] Visual output matches original (automated or manual check)
-- [ ] Rebuild report documents all changes
-- [ ] State file updated with rebuild metadata
-
-## Error Handling
-
-- **Source artifact not found**: Exit with helpful message, suggest *scan to find artifact IDs
-- **tokens.css missing**: Exit with message to run *tokenize first
-- **Pattern not in tokens**: Warn user, offer to add to custom CSS or skip
-- **HTML parsing error**: Report error location, suggest manual cleanup
-- **Visual mismatch**: Generate comparison report, let user decide to accept or reject
-
-## Security Considerations
-
-- Validate HTML input (prevent XSS)
-- Sanitize artifact names for file system
-- No code execution from artifact content
-- Backup original before rebuild
-- Rollback option if rebuild fails
-
-## Examples
-
-### Example 1: Rebuild Scanned Artifact
-
-```bash
-*rebuild 005
-```
-
-**Output:**
-```
-🔍 Brad: Rebuilding artifact-005 (tabela-comparativa)...
-
-📊 Current State:
-  - 110 inline color declarations
-  - 45 hardcoded spacing values
-  - 15 unique colors (all in token system ✅)
-
-🔨 Rebuilding...
-  ✅ HTML structure preserved
-  ✅ 110 inline styles → token classes
-  ✅ 45 spacing values → token utilities
-  ✅ Visual output validated (100% match)
-
-📁 Output:
-  - tabela-comparativa-rebuilt.html (1.8 KB, was 2.4 KB)
-  - tokens.css (linked)
-  - rebuild-report-005.md
-
-⏱️ Rebuild time: 8 minutes
-
-✅ Ready to deploy! Old version backed up.
-```
-
-### Example 2: Rebuild from File Path
-
-```bash
-*rebuild outputs/courses/claude-code/resources/guia-reducao-tokens-claude.html
-```
-
-**Output:**
-```
-🔍 Brad: Rebuilding from file path...
-
-📊 Current State:
-  - Already 95% token-based (artifact-001) ✅
-  - Only typography needs tokenization
-
-🔨 Adding typography tokens...
-  ✅ Font sizes → token classes
-  ✅ Line heights → token utilities
-  ✅ 100% token coverage achieved
-
-📁 Output:
-  - guia-reducao-tokens-claude-rebuilt.html
-  - rebuild-report-001.md
-
-✅ Polish complete! Now 100% token-based.
-```
-
-### Example 3: Rebuild with Component Extraction
-
-```bash
-*rebuild 005 --extract-components
-```
-
-**Output:**
-```
-🔍 Brad: Rebuilding with component extraction...
-
-🧩 Components Identified:
-  - StatusIcon (✓, ◐, ✕) - 45 instances
-  - ComparisonCell - 30 instances
-  - TableHeader - 5 instances
-
-🔨 Extracting components...
-  ✅ StatusIcon.html (reusable component)
-  ✅ ComparisonCell.html (reusable component)
-  ✅ tabela-comparativa-rebuilt.html (uses components)
-
-📁 Output:
-  - tabela-comparativa-rebuilt.html
-  - components/StatusIcon.html
-  - components/ComparisonCell.html
-  - rebuild-report-005.md
-
-✅ Ready for component library integration!
-```
-
-## Notes
-
-- Rebuild is **non-destructive** - original artifact preserved
-- Visual validation is critical - always review output
-- Rebuild time: ~10 minutes per artifact (vs hours of manual migration)
-- Components can be extracted optionally for reuse
-- Rebuilt artifacts are standalone (include tokens.css)
-- Brad recommends: Rebuild artifacts 004-005 first (highest inline style count)
-- After rebuild, use rebuilt version as new source of truth
-- Original artifacts can be archived or deleted
-
-## Comparison: Rebuild vs Migrate
-
-| Aspect | *rebuild | *migrate |
-|--------|----------|----------|
-| **Speed** | 10 min/artifact | 12+ hours total |
-| **Approach** | Automated rebuild | Manual step-by-step |
-| **Output** | New clean files | Modified existing |
-| **Risk** | Low (original preserved) | Medium (changes in place) |
-| **Best for** | Small # of artifacts | Large codebase |
-| **Learning** | Fast results | Educational process |
-
-**Use *rebuild when**: You have 5-10 artifacts and want fast results
-**Use *migrate when**: You have large codebase and need phased rollout
-
----
-
-*Brad's recommendation: "Rebuild is faster. Migration is safer at scale. Pick based on your context."*
-
-
-## 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.