aiox-core 5.0.3 → 5.0.5

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

@@ -1,194 +0,0 @@
-# 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

@@ -1,131 +0,0 @@
-# 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

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