aios-core 2.1.0

package/.aios-core/development/tasks/audit-codebase.md

@@ -0,0 +1,429 @@
+# Audit Codebase for UI Pattern Redundancy
+
+> Task ID: brad-audit-codebase
+> 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: auditCodebase()
+responsável: Quinn (Guardian)
+responsavel_type: Agente
+atomic_layer: Strategy
+
+**Entrada:**
+- campo: target
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Valid path or identifier
+
+- campo: options
+  tipo: object
+  origem: config
+  obrigatório: false
+  validação: Analysis configuration
+
+- campo: depth
+  tipo: number
+  origem: User Input
+  obrigatório: false
+  validação: Default: 1 (0-3)
+
+**Saída:**
+- campo: analysis_report
+  tipo: object
+  destino: File (.ai/*.json)
+  persistido: true
+
+- campo: findings
+  tipo: array
+  destino: Memory
+  persistido: false
+
+- campo: metrics
+  tipo: object
+  destino: Memory
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Target exists and is accessible; analysis tools available
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check target exists and is accessible; analysis tools available
+    error_message: "Pre-condition failed: Target exists and is accessible; analysis tools available"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Analysis complete; report generated; no critical issues
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify analysis complete; report generated; no critical issues
+    error_message: "Post-condition failed: Analysis complete; report generated; no critical issues"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Analysis accurate; all targets covered; report complete
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert analysis accurate; all targets covered; report complete
+    error_message: "Acceptance criterion not met: Analysis accurate; all targets covered; report complete"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** code-analyzer
+  - **Purpose:** Static code analysis and metrics
+  - **Source:** .aios-core/utils/code-analyzer.js
+
+- **Tool:** file-system
+  - **Purpose:** Recursive directory traversal
+  - **Source:** Node.js fs module
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** analyze-codebase.js
+  - **Purpose:** Codebase analysis and reporting
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/analyze-codebase.js
+
+---
+
+## Error Handling
+
+**Strategy:** fallback
+
+**Common Errors:**
+
+1. **Error:** Target Not Accessible
+   - **Cause:** Path does not exist or permissions denied
+   - **Resolution:** Verify path and check permissions
+   - **Recovery:** Skip inaccessible paths, continue with accessible ones
+
+2. **Error:** Analysis Timeout
+   - **Cause:** Analysis exceeds time limit for large codebases
+   - **Resolution:** Reduce analysis depth or scope
+   - **Recovery:** Return partial results with timeout warning
+
+3. **Error:** Memory Limit Exceeded
+   - **Cause:** Large codebase exceeds memory allocation
+   - **Resolution:** Process in batches or increase memory limit
+   - **Recovery:** Graceful degradation to summary analysis
+
+---
+
+## 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
+
+Scan codebase to detect UI pattern redundancies (buttons, colors, spacing, typography, forms) and quantify technical debt with hard metrics. Brad's specialty: showing you the horror show you've created.
+
+## Prerequisites
+
+- Codebase with UI code (React, Vue, HTML, or vanilla CSS)
+- Bash shell access
+- grep, find, awk utilities available
+
+## Workflow
+
+### Interactive Elicitation
+
+This task uses interactive elicitation to gather scan parameters.
+
+1. **Gather Scan Parameters**
+   - Ask for scan path (e.g., ./src, ./app, ./components)
+   - Detect frameworks automatically or ask for confirmation
+   - Confirm output directory (default: outputs/design-system/{project}/audit/)
+
+2. **Validate Scan Path**
+   - Check path exists and is readable
+   - Count total files to scan
+   - Estimate scan time (100k LOC ~2 min)
+
+3. **Confirm and Execute**
+   - Show scan plan summary
+   - Ask for confirmation before starting
+   - Begin pattern detection
+
+### Steps
+
+1. **Validate Environment**
+   - Check scan path exists
+   - Verify read permissions
+   - Create output directory structure
+   - Validation: Path exists and is readable
+
+2. **Detect Frameworks**
+   - Count React/JSX files (*.jsx, *.tsx)
+   - Count Vue files (*.vue)
+   - Count HTML files (*.html)
+   - Count CSS files (*.css, *.scss, *.sass)
+   - Validation: At least 1 UI file type found
+
+3. **Scan Button Patterns**
+   - Detect button elements (<button, <Button, className="btn")
+   - Count total button instances across all files
+   - Extract unique button class names and patterns
+   - Calculate redundancy factor (instances / unique patterns)
+   - Validation: Patterns detected or zero if none exist
+
+4. **Scan Color Usage**
+   - Extract hex colors (#RGB, #RRGGBB)
+   - Extract rgb/rgba colors
+   - Count unique color values
+   - Count total color usage instances
+   - Identify top 10 most-used colors
+   - Calculate redundancy factor
+   - Validation: Color list generated
+
+5. **Scan Spacing Patterns**
+   - Extract padding values (padding: Npx)
+   - Extract margin values (margin: Npx)
+   - Count unique spacing values
+   - Identify most common patterns
+   - Validation: Spacing inventory complete
+
+6. **Scan Typography**
+   - Extract font-family declarations
+   - Extract font-size values
+   - Extract font-weight values
+   - Count unique typography patterns
+   - Validation: Typography catalog created
+
+7. **Scan Form Patterns**
+   - Count input elements
+   - Extract unique input class patterns
+   - Count form elements
+   - Extract unique form patterns
+   - Validation: Form patterns documented
+
+8. **Generate Inventory Report**
+   - Create pattern-inventory.json with all metrics
+   - Include scan metadata (timestamp, path, file counts)
+   - Calculate redundancy factors for each pattern type
+   - Validation: Valid JSON output generated
+
+9. **Create State File**
+   - Generate .state.yaml for Atlas handoff
+   - Record all pattern counts and metrics
+   - Log agent history
+   - Set phase to "audit_complete"
+   - Validation: State file created and valid YAML
+
+## Output
+
+- **pattern-inventory.json**: Structured data with all pattern counts, redundancy factors, and usage statistics
+- **.state.yaml**: Brad's state file for handoff to Atlas or next command
+- **Console summary**: Key metrics displayed for immediate review
+
+### Output Format
+
+```json
+{
+  "scan_metadata": {
+    "timestamp": "2025-10-27T12:00:00Z",
+    "scan_path": "./src",
+    "total_files": 487,
+    "frameworks_detected": {
+      "react": true,
+      "vue": false,
+      "html": false
+    }
+  },
+  "patterns": {
+    "buttons": {
+      "unique_patterns": 47,
+      "total_instances": 327,
+      "redundancy_factor": 6.96
+    },
+    "colors": {
+      "unique_hex": 82,
+      "unique_rgb": 7,
+      "total_unique": 89,
+      "total_instances": 1247,
+      "redundancy_factor": 14.01
+    },
+    "spacing": {
+      "unique_padding": 19,
+      "unique_margin": 15
+    },
+    "typography": {
+      "unique_font_families": 4,
+      "unique_font_sizes": 15,
+      "unique_font_weights": 6
+    },
+    "forms": {
+      "input_instances": 189,
+      "unique_input_patterns": 23,
+      "form_instances": 45,
+      "unique_form_patterns": 12
+    }
+  }
+}
+```
+
+## Success Criteria
+
+- [ ] Scan completes in <2 minutes for 100k LOC
+- [ ] All pattern types detected (buttons, colors, spacing, typography, forms)
+- [ ] Redundancy factors calculated for measurable patterns
+- [ ] Valid JSON output generated with complete data
+- [ ] State file created for next command (consolidate/tokenize)
+- [ ] No scan errors or missing permissions
+
+## Error Handling
+
+- **Scan path does not exist**: Exit with clear error message, suggest valid paths
+- **No UI files found**: Warn user, check if path is correct or files exist
+- **Permission denied**: Explain which directory needs read access
+- **Partial scan failure**: Log which files failed, continue with remaining files, report incomplete data
+
+## Security Considerations
+
+- Read-only access to codebase (no writes during scan)
+- No code execution during pattern detection
+- Validate file paths to prevent directory traversal
+- Handle malformed files gracefully (invalid CSS/JSX)
+- Skip binary files and large non-text files
+
+## Examples
+
+### Example 1: React Codebase Scan
+
+```bash
+*audit ./src
+```
+
+Output:
+```
+🔍 Brad: Scanning ./src for UI chaos...
+
+📊 Files found:
+  - React/JSX: 234
+  - CSS/SCSS: 89
+  - TOTAL: 323
+
+🔍 Scanning BUTTONS...
+📊 BUTTONS:
+  - Total instances: 327
+  - Unique patterns: 47
+  - Redundancy factor: 7.0x
+
+🎨 Scanning COLORS...
+📊 COLORS:
+  - Unique hex values: 82
+  - Total usage instances: 1247
+  - Redundancy factor: 15.2x
+
+✅ Inventory saved: outputs/design-system/my-app/audit/pattern-inventory.json
+✅ State saved: outputs/design-system/my-app/.state.yaml
+```
+
+### Example 2: Vue Codebase Scan
+
+```bash
+*audit ./components
+```
+
+Output shows Vue-specific patterns (v-btn, el-button, etc.)
+
+## Notes
+
+- Redundancy factor >3x indicates significant technical debt
+- Colors >50 unique values = major consolidation opportunity
+- Buttons >20 variations = serious pattern explosion
+- Run this audit periodically to prevent pattern regression
+- Brad recommends: If redundancy factors are high, run *consolidate next
+- For cost analysis of this waste, run *calculate-roi after audit

package/.aios-core/development/tasks/audit-tailwind-config.md

@@ -0,0 +1,270 @@
+# Audit Tailwind v4 Configuration & Utility Health
+
+> Task ID: brad-audit-tailwind-config  
+> 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: auditTailwindConfig()
+responsável: Uma (Empathizer)
+responsavel_type: Agente
+atomic_layer: Strategy
+
+**Entrada:**
+- campo: target
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Valid path or identifier
+
+- campo: options
+  tipo: object
+  origem: config
+  obrigatório: false
+  validação: Analysis configuration
+
+- campo: depth
+  tipo: number
+  origem: User Input
+  obrigatório: false
+  validação: Default: 1 (0-3)
+
+**Saída:**
+- campo: analysis_report
+  tipo: object
+  destino: File (.ai/*.json)
+  persistido: true
+
+- campo: findings
+  tipo: array
+  destino: Memory
+  persistido: false
+
+- campo: metrics
+  tipo: object
+  destino: Memory
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Target exists and is accessible; analysis tools available
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check target exists and is accessible; analysis tools available
+    error_message: "Pre-condition failed: Target exists and is accessible; analysis tools available"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Analysis complete; report generated; no critical issues
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify analysis complete; report generated; no critical issues
+    error_message: "Post-condition failed: Analysis complete; report generated; no critical issues"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Analysis accurate; all targets covered; report complete
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert analysis accurate; all targets covered; report complete
+    error_message: "Acceptance criterion not met: Analysis accurate; all targets covered; report complete"
+```
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** analyze-codebase.js
+  - **Purpose:** Codebase analysis and reporting
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/analyze-codebase.js
+
+---
+
+## Error Handling
+
+**Strategy:** fallback
+
+**Common Errors:**
+
+1. **Error:** Target Not Accessible
+   - **Cause:** Path does not exist or permissions denied
+   - **Resolution:** Verify path and check permissions
+   - **Recovery:** Skip inaccessible paths, continue with accessible ones
+
+2. **Error:** Analysis Timeout
+   - **Cause:** Analysis exceeds time limit for large codebases
+   - **Resolution:** Reduce analysis depth or scope
+   - **Recovery:** Return partial results with timeout warning
+
+3. **Error:** Memory Limit Exceeded
+   - **Cause:** Large codebase exceeds memory allocation
+   - **Resolution:** Process in batches or increase memory limit
+   - **Recovery:** Graceful degradation to summary analysis
+
+---
+
+## 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
+
+Review Tailwind CSS v4 setup to guarantee @theme layering, content scanning, utility hygiene, and performance baselines are correct. Produces remediation plan and metrics.
+
+## Prerequisites
+
+- Tailwind v4 installed (or upgrade plan underway)
+- Access to codebase for static analysis
+- Ability to run Tailwind build locally
+
+## Workflow
+
+1. **Collect Context**
+   - Locate primary CSS entry (`app.css`, `src/styles.css`, etc.)
+   - Identify additional `@imports`, custom utilities, plugins
+   - Read `.state.yaml` for current Tailwind metadata (if available)
+
+2. **Validate @theme Layers**
+   - Ensure tokens defined within `@theme` grouped as core → semantic → component
+   - Confirm dark mode overrides (`[data-theme="dark"]`) map to semantic tokens
+   - Check no residual `theme.extend` references exist
+
+3. **Inspect @layer Usage**
+   - `@layer base`: Resets, typography, `focus-visible`
+   - `@layer components`: Reusable abstractions (e.g., `.form-label`)
+   - `@layer utilities`: Custom utility definitions with `@utility`
+   - Verify ordering (base → components → utilities) and duplication avoidance
+
+4. **Content & Purge Coverage**
+   - Review Tailwind CLI entry for `content` globs (JIT purge)
+   - Ensure glob coverage includes `.tsx`, `.jsx`, `.mdx`, Storybook stories, templates
+   - Flag false negatives (classes generated dynamically) and propose safelist
+
+5. **Utility Health Scan**
+   - Run class collision detection (tailwind-merge or eslint-plugin-tailwindcss)
+   - Identify redundant custom utilities replaced by tokens/variants
+   - Detect legacy classes (e.g., `outline-none` instead of `outline-hidden`)
+
+6. **Performance Snapshot**
+   - Record build metrics (cold + incremental)
+   - Capture CSS bundle size, number of utilities generated
+   - Compare with target benchmarks (Oxide reference)
+
+7. **Report & Remediation**
+   - Summarize findings (pass/warn/fail) in `docs/reports/tailwind-audit.md`
+   - Provide prioritized action list (tokens to add, utilities to remove, config fixes)
+   - Update `.state.yaml` with audit timestamp, benchmark data, outstanding actions
+
+## Output
+
+- Audit report (`docs/reports/tailwind-audit.md`)
+- Updated `.state.yaml` under `tooling.tailwind` (validation + metrics)
+- Optional lint/config patches (ESLint Tailwind rules, Prettier plugin settings)
+
+## Success Criteria
+
+- [ ] `@theme` defines full token stack with no missing categories
+- [ ] `@layer` usage consistent and free of duplicate definitions
+- [ ] Content paths cover 100% of templates (no orphaned utilities)
+- [ ] tailwind-merge/eslint scans zero conflicts or all logged issues resolved
+- [ ] Build metrics captured (cold/incremental) and comparable to prior baseline
+- [ ] Recommendations documented with owners + due dates
+- [ ] `.state.yaml` updated (`tailwind_theme_validated: true/false`) and audit timestamp logged
+
+## Tools & Commands
+
+- Tailwind CLI build: `npx tailwindcss -i ./app.css -o ./dist.css --watch`
+- Utility audit: `npx @tailwindcss/oxide --analyze`
+- ESLint Tailwind plugin: `eslint --ext .tsx src`
+- tailwind-merge checker: integrate via ESLint rule `tailwindcss/no-contradicting-classname`
+
+## Notes
+
+- Encourage automated linting (ESLint + prettier-plugin-tailwindcss) post-audit
+- Document class naming conventions (order: layout → size → spacing → typography → color → effect)
+- Track manual overrides (safelist patterns, arbitrary values) for future cleanup