aiox-core 5.0.2 → 5.0.3

package/pro/squads/design/tasks/ds-reverse-engineer.md

@@ -0,0 +1,194 @@
+# Reverse Engineer Validated System
+
+> Task ID: ds-reverse-engineer
+> Agent: Brad Frost (Design System Architect)
+> Version: 1.0.0
+> Heuristic: #9 - Engenharia reversa do validado > criar do zero
+
+## Description
+
+Extrair padrões de design systems validados (Shopify, Vercel, ClickMax, etc) em vez de criar do zero.
+
+**Princípio:** Sistemas com milhões de usuários já validaram UX. Extrair > inventar.
+
+---
+
+## Input Contract
+
+```yaml
+input:
+  source_url: string          # URL do sistema a analisar
+  source_type: enum           # "public_site" | "figma" | "storybook" | "github"
+  focus_areas:                # Áreas de interesse
+    - tokens
+    - components
+    - patterns
+    - interactions
+  output_format: enum         # "report" | "tokens" | "components" | "full"
+```
+
+## Output Contract
+
+```yaml
+output:
+  analysis_report:
+    source: string
+    extraction_date: date
+    patterns_found: array
+    tokens_extracted: object
+    components_identified: array
+    recommendations: array
+  artifacts:
+    - path: string
+      type: string
+```
+
+---
+
+## Workflow
+
+### Phase 1: Capture
+
+```bash
+# Para sites públicos
+node infrastructure/services/etl/bin/fetch-page.js <url> --format json
+
+# Para Storybook
+# Navegar e capturar via Playwright
+
+# Para Figma
+# Usar Figma API ou MCP
+```
+
+**Deliverable:** Raw data capturado
+
+### Phase 2: Extract
+
+1. **Tokens**
+   - Cores (primitives + semantic)
+   - Spacing scale
+   - Typography scale
+   - Border radius
+   - Shadows
+
+2. **Components**
+   - Lista de componentes identificados
+   - Variantes por componente
+   - Estados (hover, focus, disabled, error)
+
+3. **Patterns**
+   - Layout patterns
+   - Navigation patterns
+   - Form patterns
+   - Feedback patterns
+
+**Deliverable:** Structured extraction
+
+### Phase 3: Analyze
+
+1. Comparar com nosso `design-tokens-spec.yaml`
+2. Identificar gaps
+3. Identificar conflitos
+4. Priorizar adoção
+
+**Deliverable:** Gap analysis report
+
+### Phase 4: Propose
+
+1. Propor tokens para adicionar/modificar
+2. Propor componentes para criar
+3. Propor patterns para adotar
+4. Estimar esforço
+
+**Deliverable:** Adoption proposal
+
+---
+
+## Veto Conditions
+
+- [ ] Source não é acessível
+- [ ] Source requer autenticação não disponível
+- [ ] Extração viola ToS do source
+- [ ] Padrões extraídos conflitam com brand guidelines
+
+---
+
+## Quality Gates
+
+- [ ] Extraction é reproduzível (script documentado)
+- [ ] Tokens extraídos validam contra schema
+- [ ] Gap analysis tem priorização clara
+- [ ] Proposal tem estimativa de esforço
+
+---
+
+## Example Output
+
+```yaml
+# extraction-report-vercel-2026-02-16.yaml
+source: "vercel.com/dashboard"
+extraction_date: "2026-02-16"
+
+tokens_extracted:
+  colors:
+    background: "#000000"
+    foreground: "#FFFFFF"
+    accents:
+      blue: "#0070F3"
+      cyan: "#50E3C2"
+  spacing:
+    base: "4px"
+    scale: [4, 8, 16, 24, 32, 48, 64]
+  radius:
+    sm: "4px"
+    md: "6px"
+    lg: "8px"
+
+components_identified:
+  - name: "Button"
+    variants: ["primary", "secondary", "ghost", "danger"]
+    sizes: ["sm", "md", "lg"]
+  - name: "Card"
+    variants: ["default", "hover", "selected"]
+
+patterns_identified:
+  - name: "Dashboard Layout"
+    description: "Sidebar + main content"
+  - name: "Empty State"
+    description: "Icon + title + description + CTA"
+
+recommendations:
+  - priority: "high"
+    action: "Adopt spacing scale (matches our 4px base)"
+  - priority: "medium"
+    action: "Consider accent color palette"
+```
+
+---
+
+## References
+
+- Meeting Insights: Heuristic #9
+- Design Tokens Spec: `squads/design/data/design-tokens-spec.yaml`
+- ETL Service: `infrastructure/services/etl/`
+
+---
+
+*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`
+- **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-scan-artifact.md

@@ -0,0 +1,131 @@
+# Design System Artifact Scan Task
+
+> Task ID: ds-scan-artifact
+> Agent: design-system
+> Version: 1.1.0
+> v4.0-compatible: true
+> Extends: generic-scan.md
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[ds-rebuild-artifact]` · workflow: `artifact-analysis`
+
+## Output Schema
+- **produces:** `outputs/design-system/{project}/artifacts/artifact-scan-{id}.json`
+- **format:** JSON data
+- **consumed_by:** ds-rebuild-artifact
+
+## Description
+
+Analyzes HTML/React artifacts to extract design patterns, components,
+colors, typography, and other design system elements. Generates comprehensive
+reports with auto-incrementing artifact IDs.
+
+## Specific Workflow
+
+## Execution Steps
+
+1. Inicializar ambiente de scan e validar pré-requisitos.
+2. Definir origem do artefato (arquivo, URL ou conteúdo colado).
+3. Normalizar nome do artefato e reservar ID único.
+4. Executar extração de padrões visuais e estruturais.
+5. Gerar relatório JSON de análise.
+6. Atualizar metadata e registry de scans.
+7. Expor resumo final com próximos passos.
+
+### 1. Initialize Scan
+
+```bash
+# Set agent parameters
+AGENT_NAME="design-system"
+SCAN_TYPE="artifact-analysis"
+
+# Load core library
+source squads/super-agentes/scan-system/lib/scan-core.sh
+
+# Validate environment
+validate_scan_environment "$AGENT_NAME"
+```
+
+### 2. Get Target
+
+Interactive prompt or parameter:
+- File path: `path/to/artifact.html`
+- URL: `https://example.com/artifact`
+- Direct paste: User provides HTML content
+
+### 3. Get Artifact Name
+
+```bash
+# Prompt for descriptive name
+echo "Enter a descriptive name for this artifact (e.g., 'dashboard', 'pricing-table'):"
+read ARTIFACT_NAME
+# Sanitize name (remove spaces, special chars)
+ARTIFACT_NAME=$(echo "$ARTIFACT_NAME" | tr ' ' '-' | tr -cd '[:alnum:]-')
+```
+
+### 4. Get Next ID and Create Metadata
+
+```bash
+ARTIFACT_ID=$(get_next_artifact_id "$AGENT_NAME")
+echo "📋 Assigned Artifact ID: $ARTIFACT_ID"
+
+METADATA_FILE=$(create_metadata "$AGENT_NAME" "$ARTIFACT_ID" "$SCAN_TYPE" "$ARTIFACT_NAME")
+echo "📄 Created metadata: $METADATA_FILE"
+```
+
+### 5. Analyze Artifact
+
+Extract design elements from HTML/React content.
+
+### 6. Generate Report
+
+Create comprehensive analysis report with extracted data.
+
+### 7. Update Metadata with Results
+
+Update metadata file with analysis metrics and extracted data.
+
+### 8. Update Registry and Commit
+
+Update scan registry and optionally commit to git.
+
+### 9. Display Summary
+
+Show completion message with artifact details and next steps.
+
+## Failure Handling
+
+- **Invalid artifact source:** If URL returns 404 or file not found, exit with error "Artifact not accessible at {source}. Verify path/URL and permissions."
+- **HTML parsing fails:** If artifact contains malformed HTML or non-HTML content, attempt recovery with lenient parser, note "HTML parsing recovered with lenient mode — review extracted data for accuracy"
+- **No design patterns found:** If artifact has no colors, spacing, or typography (empty extraction), exit with error "No design patterns detected in {artifact}. Verify content contains CSS or inline styles."
+- **Duplicate artifact name:** If ARTIFACT_NAME already exists in registry with different content, append timestamp suffix and note "Name collision resolved: saved as {name}-{timestamp}"
+
+## Success Criteria
+
+- [ ] Artifact analyzed and data extracted
+- [ ] Report generated with all sections
+- [ ] Metadata includes all metrics
+- [ ] Registry updated correctly
+- [ ] Git commit created (if enabled)
+
+## Example Usage
+
+```bash
+# From Design System agent
+*scan path/to/dashboard.html
+
+# Or with URL
+*scan https://example.com/artifact.html
+
+# Or paste content directly
+*scan
+# [Agent prompts for content]
+```
+
+
+## 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.

package/pro/squads/design/tasks/ds-setup-design-system.md

@@ -0,0 +1,297 @@
+# Setup Design System Structure
+
+> Task ID: atlas-setup-design-system
+> Agent: Brad (Design System Architect)
+> Version: 1.1.0
+> v4.0-compatible: true
+> **Execution Type:** `Hybrid`
+> **Human Checkpoint:** Review and approve the directory structure, token configuration, and framework setup before component generation begins
+> **Dependencies:** depends_on: `[]` · enables: `[ds-build-component]` · workflow: `greenfield`
+
+## Description
+
+Initialize design system structure for greenfield or brownfield projects. Loads tokens from Brad's .state.yaml or prompts for manual setup. Creates directory structure, validates tokens, prepares for component generation. **v4.0: Supports agentic-ready setup (machine-readable infrastructure for AI consumption) and W3C DTCG v1.0 token format by default.**
+
+## Output Schema
+- **produces:** `outputs/design-system/{project}/setup/`
+- **format:** Directory structure with token config, framework scaffolding, and .state.yaml
+- **consumed_by:** ds-build-component
+
+## Prerequisites
+
+- Node.js and npm installed (for React/TypeScript components)
+- Either: Brad's .state.yaml with tokens OR manual token files
+- Project has package.json (or Merovingian will create one)
+- Reference: Read data/agentic-ds-principles.md for agentic-ready setup options
+- Reference: Read data/w3c-dtcg-spec-reference.md for default token format
+- Reference: Read data/fluent2-design-principles.md if targeting Microsoft Fluent 2 patterns
+
+## Workflow
+
+### Interactive Elicitation
+
+This task uses interactive elicitation to configure setup.
+
+1. **Detect Starting Point**
+   - Check for Brad's .state.yaml (brownfield from audit)
+   - If not found, ask for greenfield setup
+   - Confirm which approach to use
+
+2. **Load or Create Tokens**
+   - Brownfield: Load tokens from Brad's state
+   - Greenfield: Ask for tokens.yaml location or create template
+   - Validate token schema
+
+3. **Configure Project Structure**
+   - Ask for component output directory (default: src/design-system)
+   - CSS approach (CSS Modules, styled-components, Tailwind)
+   - Test framework (Jest default)
+   - Storybook (yes/no)
+
+### Steps
+
+1. **Detect Brad's State**
+   - Search for .state.yaml in outputs/design-system/
+   - If found, validate tokenization phase completed
+   - If not found, prepare greenfield setup
+   - Check: starting_point is "brownfield" (state file found) or "greenfield" (no state) — log "Starting point: {type}"
+
+2. **Load Token Data**
+   - Brownfield: Read token locations from .state.yaml
+   - Greenfield: Prompt for tokens.yaml location
+   - Parse and validate token schema
+   - Check for required token categories (color, spacing, typography)
+   - Check: token file parses without errors AND contains color + spacing + typography categories — abort with "Invalid tokens: {parse error or missing category}"
+
+3. **Create Directory Structure**
+   - Create design-system/ root directory
+   - Create subdirectories: atoms/, molecules/, organisms/, templates/
+   - Create tokens/ directory for token files
+   - Create docs/ for pattern library documentation
+   - Create __tests__/ for test files
+   - Check: `test -d atoms/` AND `test -d molecules/` AND `test -d organisms/` AND `test -d tokens/` — abort with "Directory creation failed: {missing dir}"
+
+4. **Copy Token Files**
+   - Copy tokens.yaml to design-system/tokens/
+   - Copy token exports (JSON, CSS, Tailwind, SCSS)
+   - Generate index files for easy imports
+   - Check: `test -f design-system/tokens/tokens.yaml` AND index files exist — abort with "Token copy failed: {missing file}"
+
+5. **Initialize Package Dependencies**
+   - Check for React and TypeScript in package.json
+   - Add missing dependencies (if needed)
+   - Add testing library dependencies
+   - Add Storybook dependencies (if requested)
+   - Check: `npm ls` exits with 0 for required packages (react, typescript, testing-library) — abort with "Missing dependencies: {list}"
+
+6. **Create Configuration Files**
+   - Generate tsconfig.json for design system (if needed)
+   - Create jest.config.js for tests
+   - Create .storybook/ config (if Storybook enabled)
+   - Create design-system.config.yaml for Merovingian settings
+   - Check: config files parse without errors (tsconfig.json, jest.config.js, design-system.config.yaml) — abort with "Invalid config: {file}: {error}"
+
+7. **Generate Token Index**
+   - Create tokens/index.ts for centralized token imports
+   - Export all token categories
+   - Add TypeScript types for tokens
+   - Check: `test -f tokens/index.ts` AND TypeScript compiles index without errors — abort with "Token index generation failed"
+
+8. **Create Base Styles**
+   - Generate global.css with token CSS variables
+   - Create reset/normalize styles
+   - Add base typography styles using tokens
+   - Check: global.css contains `var(--` references AND zero hardcoded color/spacing values — log "Base styles: {N} token references, 0 hardcoded values"
+
+9. **Initialize State Tracking**
+   - Create or update .state.yaml for Merovingian
+   - Record setup configuration
+   - Set phase to "setup_complete"
+   - Check: `test -f .state.yaml` AND contains `phase: "setup_complete"` — abort with "State file creation failed"
+
+10. **Generate Setup Report**
+    - Create setup-summary.md
+    - List all created files and directories
+    - Document next steps (build components)
+    - Check: `test -f setup-summary.md` AND file size > 0 — abort with "Setup documentation generation failed"
+
+## Output
+
+- **design-system/** directory structure
+- **tokens/** with all token files and index
+- **docs/** for documentation
+- **global.css** with base styles
+- **setup-summary.md** with configuration details
+- **.state.yaml** updated with Merovingian setup data
+
+### Output Format
+
+```yaml
+# .state.yaml Merovingian setup section
+atlas_setup:
+  completed_at: "2025-10-27T15:00:00Z"
+  starting_point: "brownfield"  # or "greenfield"
+
+  configuration:
+    component_directory: "src/design-system"
+    css_approach: "css_modules"
+    test_framework: "jest"
+    storybook_enabled: true
+
+  tokens_loaded:
+    source: "Brad tokenization"
+    categories:
+      - color (12 tokens)
+      - spacing (7 tokens)
+      - typography (10 tokens)
+      - radius (4 tokens)
+      - shadow (3 tokens)
+    total_tokens: 36
+    validation: "passed"
+
+  directory_structure:
+    - design-system/atoms/
+    - design-system/molecules/
+    - design-system/organisms/
+    - design-system/templates/
+    - design-system/tokens/
+    - design-system/docs/
+    - design-system/__tests__/
+
+  dependencies_added:
+    - "@testing-library/react"
+    - "@testing-library/jest-dom"
+    - "@storybook/react"
+
+  phase: "setup_complete"
+  ready_for: "component_building"
+```
+
+## Failure Handling
+
+- **Token validation fails due to missing required categories:** Create placeholder tokens for missing categories (color/spacing/typography), flag for manual completion, proceed with partial setup
+- **npm install fails due to version conflicts:** Document conflicting dependencies, provide lockfile diff, suggest resolution strategies (peer dependency overrides, version bumps), allow manual resolution before proceeding
+- **Target directory already exists with conflicting structure:** Prompt user to archive existing directory, merge intelligently (preserve custom files, replace standard scaffolding), or abort with comparison report
+- **TypeScript compilation errors in generated token index:** Fall back to JavaScript token exports, generate .d.ts manually from schema, log type generation failure for follow-up fix
+
+## Success Criteria
+
+- [ ] Directory structure follows Atomic Design principles
+- [ ] Tokens loaded and validated successfully
+- [ ] All token exports accessible (JSON, CSS, etc)
+- [ ] Package dependencies installed
+- [ ] Configuration files valid and working
+- [ ] Base styles generated using tokens
+- [ ] State tracking initialized
+- [ ] Setup documented clearly
+
+## Error Handling
+
+- **No tokens found**: Offer to create token template or prompt for manual input
+- **Invalid token schema**: Report specific errors, suggest fixes
+- **Missing dependencies**: Auto-install with npm or prompt user
+- **Directory exists**: Ask to overwrite or use different location
+- **Invalid project structure**: Warn user, continue with compatible setup
+
+## Security Considerations
+
+- Validate token file paths (no directory traversal)
+- Sanitize directory names
+- Don't execute code during setup
+- Validate package.json before modifying
+
+## Examples
+
+### Example 1: Brownfield Setup (From Brad)
+
+```bash
+*setup
+```
+
+Output:
+```
+🏗️ Merovingian: Setting up design system structure...
+
+✓ Detected Brad's state: outputs/design-system/my-app/.state.yaml
+✓ Loading tokens from Brad's tokenization...
+  - 12 color tokens
+  - 7 spacing tokens
+  - 10 typography tokens
+  - Total: 36 tokens validated
+
+📁 Creating directory structure...
+  ✓ src/design-system/
+  ✓ src/design-system/atoms/
+  ✓ src/design-system/molecules/
+  ✓ src/design-system/organisms/
+  ✓ src/design-system/tokens/
+
+📦 Installing dependencies...
+  ✓ @testing-library/react
+  ✓ @testing-library/jest-dom
+  ✓ @storybook/react (optional)
+
+⚙️ Generating configuration...
+  ✓ tokens/index.ts (centralized exports)
+  ✓ global.css (base styles)
+  ✓ jest.config.js
+  ✓ .storybook/main.js
+
+✅ Setup complete!
+
+Next steps:
+  1. Build components: *build button
+  2. Generate docs: *document
+  3. See component list: *help
+
+Merovingian says: "Foundation is solid. Ready to build."
+```
+
+### Example 2: Greenfield Setup
+
+```bash
+*setup
+```
+
+Output:
+```
+🏗️ Merovingian: No Brad state found. Starting greenfield setup...
+
+? Token source:
+  1. I have tokens.yaml
+  2. Create token template
+  3. Manual input
+
+User selects 1
+
+? Path to tokens.yaml: ./tokens/tokens.yaml
+
+✓ Tokens loaded and validated (24 tokens)
+
+? Component directory: src/design-system
+? CSS approach: CSS Modules
+? Enable Storybook? Yes
+
+[...setup continues...]
+```
+
+## Notes
+
+- Brownfield setup is faster (tokens from Brad)
+- Greenfield requires manual token creation or import
+- Atomic Design structure (atoms → molecules → organisms → templates)
+- All styling must use tokens (enforced in component generation)
+- Storybook is optional but recommended for component showcase
+- Merovingian automatically creates TypeScript types for tokens
+- Base styles include CSS reset and token variables
+- Setup can be re-run safely (asks before overwriting)
+- Next step after setup: *build {pattern} to generate components
+
+
+## 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.