aiox-core 5.0.3 → 5.0.4

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

@@ -1,246 +1,246 @@
-# 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.
+# 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 +1,90 @@
-# 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.
+# 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.