aios-core 2.1.0

package/.aios-core/development/tasks/compose-molecule.md

@@ -0,0 +1,284 @@
+# Compose Molecule from Atoms
+
+> Task ID: atlas-compose-molecule
+> Agent: Atlas (Design System Builder)
+> Version: 1.0.0
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: composeMolecule()
+responsável: Uma (Empathizer)
+responsavel_type: Agente
+atomic_layer: Molecule
+
+**Entrada:**
+- campo: name
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must be non-empty, lowercase, kebab-case
+
+- campo: options
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Valid JSON object with allowed keys
+
+- campo: force
+  tipo: boolean
+  origem: User Input
+  obrigatório: false
+  validação: Default: false
+
+**Saída:**
+- campo: created_file
+  tipo: string
+  destino: File system
+  persistido: true
+
+- campo: validation_report
+  tipo: object
+  destino: Memory
+  persistido: false
+
+- campo: success
+  tipo: boolean
+  destino: Return value
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Target does not already exist; required inputs provided; permissions granted
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check target does not already exist; required inputs provided; permissions granted
+    error_message: "Pre-condition failed: Target does not already exist; required inputs provided; permissions granted"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Resource created successfully; validation passed; no errors logged
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify resource created successfully; validation passed; no errors logged
+    error_message: "Post-condition failed: Resource created successfully; validation passed; no errors logged"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Resource exists and is valid; no duplicate resources created
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert resource exists and is valid; no duplicate resources created
+    error_message: "Acceptance criterion not met: Resource exists and is valid; no duplicate resources created"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** component-generator
+  - **Purpose:** Generate new components from templates
+  - **Source:** .aios-core/scripts/component-generator.js
+
+- **Tool:** file-system
+  - **Purpose:** File creation and validation
+  - **Source:** Node.js fs module
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** create-component.js
+  - **Purpose:** Component creation workflow
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/create-component.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Resource Already Exists
+   - **Cause:** Target file/resource already exists in system
+   - **Resolution:** Use force flag or choose different name
+   - **Recovery:** Prompt user for alternative name or force overwrite
+
+2. **Error:** Invalid Input
+   - **Cause:** Input name contains invalid characters or format
+   - **Resolution:** Validate input against naming rules (kebab-case, lowercase, no special chars)
+   - **Recovery:** Sanitize input or reject with clear error message
+
+3. **Error:** Permission Denied
+   - **Cause:** Insufficient permissions to create resource
+   - **Resolution:** Check file system permissions, run with elevated privileges if needed
+   - **Recovery:** Log error, notify user, suggest permission fix
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 2-5 min (estimated)
+cost_estimated: $0.001-0.003
+token_usage: ~1,000-3,000 tokens
+```
+
+**Optimization Notes:**
+- Parallelize independent operations; reuse atom results; implement early exits
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Description
+
+Build molecule component by composing existing atoms following Atomic Design methodology. Examples: FormField (Label + Input), Card (Heading + Text + Button), SearchBar (Input + Button).
+
+## Prerequisites
+
+- Setup completed
+- Atom components exist (dependencies)
+- Tokens loaded
+
+## Workflow
+
+### Steps
+
+1. **Validate Atom Dependencies** - Check required atoms exist
+2. **Generate Molecule Component** - Compose atoms with molecule logic
+3. **Generate Molecule Styles** - Molecule-specific layout and spacing
+4. **Generate Tests** - Test molecule composition and interactions
+5. **Generate Stories** - Show molecule with different atom combinations
+6. **Generate Documentation** - Document composed structure
+7. **Update Index** - Export molecule
+8. **Update State** - Track molecule built
+
+## Output
+
+- Molecule component (TypeScript)
+- Molecule styles (CSS Modules)
+- Tests (>80% coverage)
+- Stories (optional)
+- Documentation
+
+## Success Criteria
+
+- [ ] All atom dependencies imported correctly
+- [ ] Molecule composes atoms (not reimplements)
+- [ ] Molecule-specific logic isolated
+- [ ] Tests cover atom interactions
+- [ ] Accessible (WCAG AA)
+
+## Example
+
+```typescript
+// FormField.tsx (molecule)
+import { Label } from '../atoms/Label';
+import { Input, InputProps } from '../atoms/Input';
+import { HelperText } from '../atoms/HelperText';
+
+export interface FormFieldProps extends InputProps {
+  label: string;
+  helperText?: string;
+  error?: string;
+}
+
+export const FormField: React.FC<FormFieldProps> = ({
+  label,
+  helperText,
+  error,
+  ...inputProps
+}) => {
+  return (
+    <div className={styles.formField}>
+      <Label htmlFor={inputProps.id}>{label}</Label>
+      <Input {...inputProps} error={!!error} />
+      {error && <HelperText variant="error">{error}</HelperText>}
+      {!error && helperText && <HelperText>{helperText}</HelperText>}
+    </div>
+  );
+};
+```
+
+## Notes
+
+- Molecules compose atoms, don't reimplement
+- Molecule adds composition logic only
+- Atoms remain independent and reusable
+- Test atom interactions in molecule context

package/.aios-core/development/tasks/consolidate-patterns.md

@@ -0,0 +1,414 @@
+# Consolidate Patterns Using Intelligent Clustering
+
+> Task ID: brad-consolidate-patterns
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: consolidatePatterns()
+responsável: Aria (Visionary)
+responsavel_type: Agente
+atomic_layer: Strategy
+
+**Entrada:**
+- campo: task
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must be registered task
+
+- campo: parameters
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Valid task parameters
+
+- campo: mode
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: yolo|interactive|pre-flight
+
+**Saída:**
+- campo: execution_result
+  tipo: object
+  destino: Memory
+  persistido: false
+
+- campo: logs
+  tipo: array
+  destino: File (.ai/logs/*)
+  persistido: true
+
+- campo: state
+  tipo: object
+  destino: State management
+  persistido: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Task is registered; required parameters provided; dependencies met
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check task is registered; required parameters provided; dependencies met
+    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Task completed; exit code 0; expected outputs created
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify task completed; exit code 0; expected outputs created
+    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Task completed as expected; side effects documented
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert task completed as expected; side effects documented
+    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** task-runner
+  - **Purpose:** Task execution and orchestration
+  - **Source:** .aios-core/core/task-runner.js
+
+- **Tool:** logger
+  - **Purpose:** Execution logging and error tracking
+  - **Source:** .aios-core/utils/logger.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** execute-task.js
+  - **Purpose:** Generic task execution wrapper
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/execute-task.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Task Not Found
+   - **Cause:** Specified task not registered in system
+   - **Resolution:** Verify task name and registration
+   - **Recovery:** List available tasks, suggest similar
+
+2. **Error:** Invalid Parameters
+   - **Cause:** Task parameters do not match expected schema
+   - **Resolution:** Validate parameters against task definition
+   - **Recovery:** Provide parameter template, reject execution
+
+3. **Error:** Execution Timeout
+   - **Cause:** Task exceeds maximum execution time
+   - **Resolution:** Optimize task or increase timeout
+   - **Recovery:** Kill task, cleanup resources, log state
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-20 min (estimated)
+cost_estimated: $0.003-0.015
+token_usage: ~2,000-8,000 tokens
+```
+
+**Optimization Notes:**
+- Iterative analysis with depth limits; cache intermediate results; batch similar operations
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Description
+
+Reduce UI pattern redundancy by clustering similar patterns using intelligent algorithms (HSL color clustering at 5% threshold, semantic button grouping). Target: >80% reduction.
+
+## Prerequisites
+
+- Audit completed (*audit command run successfully)
+- .state.yaml exists with inventory results
+- pattern-inventory.json available
+
+## Workflow
+
+### Interactive Elicitation
+
+This task uses interactive elicitation to review consolidation decisions.
+
+1. **Load Audit Results**
+   - Read .state.yaml to get inventory data
+   - Display current redundancy metrics
+   - Confirm user wants to proceed with consolidation
+
+2. **Review Clustering Parameters**
+   - HSL threshold for colors (default: 5%)
+   - Ask if user has manual overrides (patterns that shouldn't merge)
+   - Confirm output directory
+
+3. **Present Consolidation Recommendations**
+   - Show before/after for each pattern type
+   - Ask for approval or adjustments
+   - Allow manual overrides before finalizing
+
+### Steps
+
+1. **Load Audit Data**
+   - Read .state.yaml for inventory results
+   - Validate audit phase completed
+   - Extract pattern counts and scan path
+   - Validation: State file exists and contains inventory data
+
+2. **Cluster Colors by HSL Similarity**
+   - Extract all unique colors from codebase
+   - Convert hex to HSL color space
+   - Group colors within 5% HSL threshold
+   - Select most-used color in each cluster as primary
+   - Identify semantic relationships (primary-dark as hover state)
+   - Validation: Color clusters created with usage counts
+
+3. **Cluster Button Patterns by Semantic Purpose**
+   - Extract button class names and patterns
+   - Analyze naming for semantic meaning (primary, secondary, danger, etc)
+   - Group functionally equivalent buttons
+   - Recommend minimal variant set (primary, secondary, destructive)
+   - Validation: Button consolidation map created
+
+4. **Consolidate Spacing Values**
+   - Extract all padding and margin values
+   - Identify base unit (4px or 8px)
+   - Propose spacing scale (xs, sm, md, lg, xl, 2xl, 3xl)
+   - Map existing values to scale
+   - Validation: Spacing scale generated
+
+5. **Consolidate Typography**
+   - Extract font sizes, weights, families
+   - Propose type scale (modular scale or fixed intervals)
+   - Consolidate similar weights (merge 500 and 600 if both exist)
+   - Recommend minimal font family set
+   - Validation: Typography scale created
+
+6. **Generate Consolidation Report**
+   - Create consolidation-report.md with before/after metrics
+   - Include reduction percentages for each pattern type
+   - Generate detailed cluster files (color-clusters.txt, button-consolidation.txt)
+   - Calculate overall reduction percentage
+   - Validation: Report shows >80% reduction or explain why not
+
+7. **Create Pattern Mapping**
+   - Generate old-to-new mapping for each pattern type
+   - Document which old patterns map to which new tokens
+   - Create migration guide snippets
+   - Validation: Complete mapping for all patterns
+
+8. **Update State File**
+   - Add consolidation section to .state.yaml
+   - Record before/after counts for all pattern types
+   - Update phase to "consolidation_complete"
+   - Log Brad's consolidation decisions
+   - Validation: State updated with consolidation data
+
+## Output
+
+- **consolidation-report.md**: Executive summary with reduction metrics
+- **color-clusters.txt**: Detailed color groupings with usage counts
+- **button-consolidation.txt**: Button semantic analysis and recommendations
+- **spacing-consolidation.txt**: Spacing scale proposal
+- **typography-consolidation.txt**: Typography scale proposal
+- **pattern-mapping.json**: Old pattern → new token mappings
+- **.state.yaml**: Updated with consolidation decisions
+
+### Output Format
+
+```yaml
+# .state.yaml consolidation section
+consolidation:
+  completed_at: "2025-10-27T12:30:00Z"
+  patterns_consolidated:
+    colors:
+      before: 89
+      after: 12
+      reduction: "86.5%"
+      clusters: 8
+    buttons:
+      before: 47
+      after: 3
+      reduction: "93.6%"
+      variants: ["primary", "secondary", "destructive"]
+    spacing:
+      before: 19
+      after: 7
+      reduction: "63.2%"
+      scale: ["xs", "sm", "md", "lg", "xl", "2xl", "3xl"]
+    typography:
+      before: 21
+      after: 10
+      reduction: "52.4%"
+  overall_reduction: "81.8%"
+  target_met: true
+```
+
+## Success Criteria
+
+- [ ] >80% overall pattern reduction achieved
+- [ ] Color clustering uses HSL similarity (not just hex distance)
+- [ ] Button variants identified by semantic purpose
+- [ ] Spacing scale based on consistent base unit
+- [ ] Most-used patterns preserved as primary tokens
+- [ ] All consolidation decisions documented with rationale
+- [ ] User can review and override before finalizing
+
+## Error Handling
+
+- **No audit data found**: Exit with message to run *audit first
+- **Insufficient patterns to consolidate**: Report that codebase is already clean
+- **Cannot achieve 80% reduction**: Explain why and show actual reduction achieved
+- **Invalid state file**: Attempt to recover from backup or prompt re-audit
+
+## Security Considerations
+
+- Read-only analysis of patterns (no code modification)
+- Validate user overrides to prevent injection
+- Handle malformed color values safely
+- Backup state file before overwriting
+
+## Examples
+
+### Example 1: Successful Consolidation
+
+```bash
+*consolidate
+```
+
+Output:
+```
+🎨 CONSOLIDATING COLORS...
+Found 89 unique colors
+Clustering with 5% HSL threshold...
+
+CLUSTER 1 - Primary Blues (4 → 1):
+  #0066CC (234 uses) <- KEEP
+  #0065CB, #0067CD, #0064CA (merge)
+
+CLUSTER 2 - Error Reds (3 → 1):
+  #DC2626 (89 uses) <- KEEP
+  #DB2525, #DD2727 (merge)
+
+📊 CONSOLIDATION SUMMARY:
+| Pattern    | Before | After | Reduction |
+|------------|--------|-------|-----------|
+| Colors     | 89     | 12    | 86.5%     |
+| Buttons    | 47     | 3     | 93.6%     |
+| Spacing    | 19     | 7     | 63.2%     |
+| Typography | 21     | 10    | 52.4%     |
+| TOTAL      | 176    | 32    | 81.8%     |
+
+✅ TARGET MET: >80% reduction achieved
+✅ Report saved: outputs/design-system/my-app/consolidation/consolidation-report.md
+```
+
+### Example 2: User Override
+
+```bash
+*consolidate
+
+Brad: "Merge #0066CC and #0052A3?"
+User: "No, #0052A3 is intentional hover state"
+Brad: "Override recorded. Keeping both."
+```
+
+## Notes
+
+- HSL color space provides perceptual similarity (better than RGB/hex distance)
+- Most-used pattern in each cluster becomes the canonical token
+- Semantic button analysis looks for keywords: primary, main, secondary, default, danger, delete, destructive
+- Spacing scale should use consistent base unit (4px or 8px)
+- Manual overrides are respected and documented
+- Run this after every audit to prevent pattern regression
+- Brad says: "Numbers don't lie. 82% reduction = real savings."