aiox-core 5.0.3 → 5.0.5

package/pro/squads/design/tasks/sb-verify.md

@@ -1,203 +0,0 @@
-# Verify Storybook Setup
-
-**Task ID:** `sb-verify`
-**Pattern:** HO-TP-001 (Task Anatomy Standard)
-**Version:** 1.0.0
-**Last Updated:** 2026-02-25
-
-## Task Anatomy
-
-| Field | Value |
-|-------|-------|
-| **task_name** | Verify Storybook Setup |
-| **status** | `pending` |
-| **responsible_executor** | @storybook-expert |
-| **execution_type** | `Agent` |
-| **input** | Project with Storybook configured, all stories written |
-| **output** | Verification report (PASS/FAIL per check) |
-| **action_items** | 6 steps |
-| **acceptance_criteria** | 6 criteria |
-
-## Overview
-
-Final verification gate for the complete Storybook setup pipeline. Runs typecheck, lint, build, and functional checks to ensure everything works end-to-end. This is the terminal task in the `storybook-full-setup` workflow.
-
-## Input
-
-- **project_root** (string)
-  - Description: Absolute path to the project root
-  - Required: Yes
-- **story_files** (list)
-  - Description: All story files from sb-generate-all-stories output
-  - Required: Yes
-  - Source: Previous task handoff
-
-## Output
-
-- **verification_report** (object)
-  - Description: PASS/FAIL status for each verification check
-  - Format: Table with check name, status, details
-
-## Action Items
-
-### Step 1: TypeScript Verification
-
-```bash
-npm run typecheck
-```
-
-- [ ] Exit code 0 (zero errors)
-- [ ] No errors in `.storybook/` config files
-- [ ] No errors in `src/components/ui/*.stories.tsx` files
-- [ ] No errors in `src/components/ui/*.tsx` component files
-
-If errors found:
-- Fix all errors
-- Re-run typecheck
-- Document fixes applied
-
-### Step 2: Lint Verification
-
-```bash
-npm run lint
-```
-
-- [ ] Exit code 0 (zero errors)
-- [ ] No warnings in story files (warnings acceptable in other files)
-
-If errors found:
-- Fix all lint errors in story and config files
-- Re-run lint
-- Document fixes applied
-
-### Step 3: Storybook Build Verification
-
-```bash
-npm run build-storybook
-```
-
-- [ ] Exit code 0 (build succeeds)
-- [ ] No compilation errors
-- [ ] Output directory `storybook-static/` created
-- [ ] Build size is reasonable (log total size)
-
-If build fails:
-- Check error output for specific file/component
-- Fix the issue (usually import errors or missing dependencies)
-- Re-run build
-- Delete `storybook-static/` after verification (or leave if user wants to deploy)
-
-### Step 4: Story Count Verification
-
-Count stories visible in Storybook:
-
-- [ ] Scan all `.stories.tsx` files in project
-- [ ] Count exported stories (named exports that are StoryObj)
-- [ ] Compare with total component count
-- [ ] Report coverage ratio
-
-Expected: Every component file in `src/components/ui/` has a corresponding `.stories.tsx` file.
-
-### Step 5: Functional Smoke Test
-
-Start Storybook dev server and verify:
-
-```bash
-npm run storybook -- --no-open &
-# Wait for server ready
-curl -s -o /dev/null -w "%{http_code}" http://localhost:6006
-```
-
-- [ ] Server starts on port 6006
-- [ ] HTTP 200 response
-- [ ] Kill dev server after verification
-
-**If browser testing available (Playwright MCP):**
-- [ ] Navigate to localhost:6006
-- [ ] Verify sidebar shows all component categories
-- [ ] Click on 3-5 random stories to verify they render
-- [ ] Toggle dark/light theme to verify theme switch works
-- [ ] Check Accessibility panel for critical violations
-
-### Step 6: Generate Verification Report
-
-Produce final report:
-
-```markdown
-## Storybook Verification Report
-
-| Check | Status | Details |
-|-------|--------|---------|
-| TypeScript | {PASS/FAIL} | {error count} errors |
-| Lint | {PASS/FAIL} | {error count} errors |
-| Build | {PASS/FAIL} | {build size} |
-| Story Coverage | {PASS/FAIL} | {stories}/{components} ({ratio}%) |
-| Dev Server | {PASS/FAIL} | HTTP {status_code} |
-| Theme Toggle | {PASS/FAIL/SKIPPED} | {details} |
-
-### Summary
-- **Overall Status:** {PASS/FAIL}
-- **Components:** {total_components}
-- **Stories:** {total_stories}
-- **Coverage:** {ratio}%
-- **Fixes Applied:** {fix_count}
-```
-
-## Acceptance Criteria
-
-- [ ] **AC-1:** `npm run typecheck` — zero errors
-- [ ] **AC-2:** `npm run lint` — zero errors
-- [ ] **AC-3:** `npm run build-storybook` — builds successfully
-- [ ] **AC-4:** Story coverage >= 100% (every component has stories)
-- [ ] **AC-5:** Dev server responds with HTTP 200
-- [ ] **AC-6:** Verification report generated
-
-## Error Handling
-
-### TypeCheck Fails After Stories Written
-- **Trigger:** Type errors in story files
-- **Detection:** Step 1 typecheck exit code != 0
-- **Recovery:** Parse error output, fix each story file, re-run
-- **Prevention:** sb-generate-all-stories should catch these
-
-### Build Fails
-- **Trigger:** Storybook build compilation error
-- **Detection:** Step 3 build exit code != 0
-- **Recovery:** Parse build error, fix specific file, re-run
-- **Prevention:** If typecheck passes, build usually succeeds
-
-### Dev Server Wont Start
-- **Trigger:** Port 6006 already in use, or config error
-- **Detection:** Step 5 server doesnt respond
-- **Recovery:** Kill process on 6006 (`lsof -ti:6006 | xargs kill`), retry
-- **Prevention:** Check port availability before starting
-
-## Dependencies
-
-### Depends On (Upstream)
-
-- `sb-generate-all-stories` - Generate All Stories
-  - Required output: All story files written
-- `sb-configure` - Configure Storybook
-  - Required output: Valid .storybook/ configuration
-
-## Handoff
-
-| Attribute | Value |
-|-----------|-------|
-| **Next Task** | None (terminal task) |
-| **Trigger** | All acceptance criteria met |
-| **Executor** | Returns to user |
-
-### Handoff Package
-
-- **verification_report**: Full verification results
-- **coverage_ratio**: Story-to-component coverage percentage
-- **storybook_url**: `http://localhost:6006` (if dev server left running)
-
----
-
-_Task Version: 1.0.0_
-_Pattern: HO-TP-001 (Task Anatomy Standard)_
-_Last Updated: 2026-02-25_
-_Compliant: Yes_

package/pro/squads/design/tasks/tailwind-upgrade.md

@@ -1,117 +0,0 @@
-# Tailwind CSS v4 Upgrade Playbook
-
-> Task ID: brad-tailwind-upgrade  
-> Agent: Brad (Design System Architect)  
-> Version: 1.1.0
-> v4.0-compatible: true
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[]` · enables: `[audit-tailwind-config]` · workflow: `modernization`
-
-## Description
-
-Plan and execute migration from Tailwind CSS v3 (or earlier) to v4 (Oxide engine). Covers risk assessment, @theme conversion, Oxide benchmarks, dependency alignment, and human-in-the-loop verification.
-
-## Output Schema
-- **produces:** `outputs/design-system/{project}/modernization/tailwind-upgrade-report.md`
-- **format:** Markdown report
-- **consumed_by:** audit-tailwind-config
-
-## Prerequisites
-
-- Existing Tailwind configuration and usage inventoried (*audit command recommended)
-- Node.js ≥ 18.17 (prefer 20+)
-- Access to CI pipelines and performance metrics
-- Visual regression tooling (Chromatic, Lost Pixel, or equivalent)
-
-## Workflow
-
-### 1. Discovery & Planning
-- Capture current Tailwind version, build times, CSS bundle size
-- Identify PostCSS/Sass/Less/Stylus usage (must be removed/replaced)
-- List third-party libraries dependent on `tailwind.config.js` (e.g. daisyUI)
-
-### 2. Dry Run Upgrade
-- Create feature branch `chore/tailwind-v4-upgrade`
-- Run official upgrade CLI
-  ```bash
-  npx @tailwindcss/upgrade
-  ```
-- Convert config to CSS-first structure (`app.css` with `@import "tailwindcss";`)
-- Replace `tailwind.config.js` customizations with `@theme`, `@layer`, `@plugin` CSS equivalents
-
-### 3. Token & Utility Validation
-- Ensure design tokens re-exported via `@theme` (core, semantic, component layers)
-- Regenerate CSS utilities relying on previous `theme.extend`
-- Validate arbitrary values still required; prefer tokenized utilities
-- Confirm `@container`, `@starting-style`, 3D transforms working
-
-### 4. Benchmark Oxide Engine
-- Measure cold build, incremental build (with and without new CSS)
-- Target benchmarks (Catalyst reference):
-  - Cold build ≤ 120ms (target <100ms)
-  - Incremental (new CSS) ≤ 8ms
-  - Incremental (no CSS) ≤ 300µs
-- Record metrics in README/Changelog
-
-### 5. Regression Testing
-- Run full unit + integration suite
-- Execute visual regression (Chromatic/Lost Pixel) to detect class/utility drift
-- Verify dark mode, theming, and Tailwind plugins still functional
-
-### 6. Documentation & Rollout
-- Update contributing docs with new `@theme` usage
-- Refresh `.cursorrules` / coding guidelines (Tailwind v4 best practices)
-- Communicate rollout checklist to team, include fallback steps
-
-### 7. Update State
-- Log upgrade metadata in `.state.yaml` (tailwind_version, benchmarks, validation status)
-- Flag `tailwind_theme_validated: true` when `@theme` layers verified
-
-## Deliverables
-
-- Updated `app.css` (or dedicated entry) with `@theme` definitions
-- Removed/archived legacy `tailwind.config.js` (if not required)
-- Benchmarks documented (`docs/logs/tailwind-upgrade.md` or similar)
-- Regression test results (links/screenshots)
-- `.state.yaml` updated with upgrade details
-
-## Related Checklists
-
-- `squads/design/checklists/ds-migration-readiness-checklist.md`
-- `squads/design/checklists/ds-component-quality-checklist.md`
-- `squads/design/checklists/ds-a11y-release-gate-checklist.md`
-
-## Failure Handling
-
-- **@theme conversion produces invalid CSS or missing utilities:** Maintain parallel v3 config as fallback, incrementally migrate theme sections one category at a time, validate each migration with visual regression before proceeding
-- **Third-party plugin (daisyUI, Flowbite) incompatible with v4:** Check for v4-compatible fork or alternative, vendor plugin code locally with manual adaptation, document plugin as blocking dependency requiring upstream fix
-- **Oxide build times exceed v3 benchmarks or targets:** Profile build with --debug flag, identify slow transformers or large input files, split CSS entry points, consider partial adoption (keep v3 for specific modules)
-- **Visual regression tests fail with >5% diff across multiple components:** Isolate breaking changes to specific utility classes, create compatibility layer with v3-style class aliases, phase rollout component-by-component rather than all-at-once
-
-## Success Criteria
-
-- [ ] Tailwind upgraded to v4, builds pass locally and in CI
-- [ ] `@theme` defines all design tokens (colors, spacing, typography, etc.)
-- [ ] Oxide benchmarks recorded and meet targets (<30s cold build, <1ms incremental)
-- [ ] CSS bundle size ≤ previous production size (ideally <50KB gzipped)
-- [ ] No visual regressions (diff <1% or consciously accepted)
-- [ ] Documentation (.cursorrules, README) reflects v4 workflow
-- [ ] `.state.yaml` updated (`tailwind_theme_validated`, benchmarks, timestamp)
-
-## Rollback Plan
-
-1. `git revert` upgrade commits (config + package lock)
-2. Restore previous `tailwind.config.js`
-3. Reinstall previous Tailwind version
-4. Re-run build/tests to ensure stability
-
-## Notes
-
-- Remove or replace Sass/Less/Stylus pipelines (v4 does not support preprocessors)
-- Tailwind plugins may require v4-compatible versions (@tailwindcss/forms/typography/container-queries)
-- Validate IDE tooling (Tailwind IntelliSense, Prettier plugin) upgraded to v4-aware releases
-- Encourage incremental adoption: keep feature flags until confidence is high
-
-
-## Process Guards
-- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/token-usage-analytics.md

@@ -1,262 +0,0 @@
-# Task: Token Usage Analytics
-
-> Command: `*token-usage [path]`
-> Purpose: Analyze which design tokens are used, unused, and misused
-> **Execution Type:** `Worker`
-> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `metrics`
-
-## Overview
-
-This task provides analytics on design token adoption:
-- Which tokens are most/least used
-- Token coverage by category (colors, spacing, typography)
-- Misuse detection (wrong token for context)
-- Recommendations for token consolidation
-
-## Prerequisites
-
-- Design tokens spec: `squads/super-agentes/data/design-tokens-spec.yaml`
-- Target path (default: `app/components/`)
-
-## Execution Steps
-
-### Step 1: Token Inventory
-
-Load all defined tokens from spec:
-
-```yaml
-# From design-tokens-spec.yaml
-colors:
-  primary: [gold, gold_dark, gold_light]
-  background: [base, elevated, surface, overlay]
-  text: [primary, secondary, muted, inverse]
-  semantic: [success, warning, error, info]
-  border: [default, subtle, emphasis]
-
-spacing: [0, px, 0.5, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24]
-
-typography:
-  families: [sans, serif, display, mono]
-  sizes: [xs, sm, base, lg, xl, 2xl, 3xl, 4xl, 5xl]
-  weights: [normal, medium, semibold, bold]
-```
-
-### Step 2: Token Usage Scan
-
-```bash
-# Color tokens
-echo "=== Color Token Usage ==="
-for token in studio-primary studio-primary-dark studio-bg studio-card-bg \
-             text-foreground text-muted-foreground bg-background bg-card; do
-  count=$(grep -rn --include="*.tsx" "$token" {path}/ | wc -l)
-  echo "$count - $token"
-done | sort -rn
-
-# Spacing tokens
-echo "=== Spacing Token Usage ==="
-for size in p-1 p-2 p-3 p-4 p-5 p-6 p-8 p-10 p-12 \
-            m-1 m-2 m-3 m-4 m-5 m-6 m-8 \
-            gap-1 gap-2 gap-3 gap-4 gap-6 gap-8; do
-  count=$(grep -rn --include="*.tsx" "\b$size\b" {path}/ | wc -l)
-  echo "$count - $size"
-done | sort -rn
-
-# Typography tokens
-echo "=== Typography Token Usage ==="
-for token in text-xs text-sm text-base text-lg text-xl text-2xl \
-             font-normal font-medium font-semibold font-bold \
-             font-sans font-serif font-display font-mono; do
-  count=$(grep -rn --include="*.tsx" "\b$token\b" {path}/ | wc -l)
-  echo "$count - $token"
-done | sort -rn
-```
-
-### Step 3: Unused Token Detection
-
-Compare defined tokens vs actual usage:
-
-```bash
-# Find defined but never used tokens
-defined_tokens=$(cat design-tokens-spec.yaml | grep "value:" | wc -l)
-used_tokens=0
-
-for token in $(cat design-tokens-spec.yaml | grep -oP "^\s+\w+:" | tr -d ' :'); do
-  if grep -rq "$token" {path}/; then
-    ((used_tokens++))
-  else
-    echo "UNUSED: $token"
-  fi
-done
-
-echo "Token adoption: $used_tokens / $defined_tokens"
-```
-
-### Step 4: Misuse Detection
-
-Check tokens used in wrong context:
-
-```bash
-# Background tokens on text elements
-grep -rn --include="*.tsx" "text-.*bg-\|text-studio-bg\|text-background" {path}/
-
-# Text tokens on background elements
-grep -rn --include="*.tsx" "bg-.*text-\|bg-foreground\|bg-muted-foreground" {path}/
-
-# Spacing misuse (very large padding on small elements)
-grep -rn --include="*.tsx" "Button.*p-8\|Badge.*p-6\|Icon.*p-4" {path}/
-
-# Wrong semantic color usage
-# Error color for success states
-grep -rn --include="*.tsx" "success.*text-red\|error.*text-green" {path}/
-```
-
-### Step 5: Usage Heatmap Generation
-
-```markdown
-# Token Usage Heatmap
-
-## Colors
-| Token | Usage | Coverage | Status |
-|-------|-------|----------|--------|
-| studio-primary | 47 | 12% | ✅ High |
-| studio-bg | 89 | 23% | ✅ High |
-| studio-card-bg | 34 | 9% | ✅ Medium |
-| text-foreground | 156 | 40% | ✅ Very High |
-| text-muted | 67 | 17% | ✅ High |
-| studio-primary-light | 2 | <1% | ⚠️ Low |
-| studio-accent | 0 | 0% | ❌ Unused |
-
-## Spacing
-| Scale | Usage | Most Common Context |
-|-------|-------|---------------------|
-| p-4 | 234 | Cards, Sections |
-| p-6 | 89 | Modal, Large cards |
-| gap-2 | 156 | Inline elements |
-| gap-4 | 78 | Form fields |
-| p-1 | 12 | Tight badges |
-| p-12 | 3 | Hero sections |
-| p-20 | 0 | ❌ Unused |
-
-## Typography
-| Token | Usage | Context |
-|-------|-------|---------|
-| text-sm | 289 | Body, buttons |
-| text-base | 145 | Paragraphs |
-| text-xs | 67 | Captions, badges |
-| text-5xl | 8 | Hero headings |
-| font-medium | 156 | Buttons, labels |
-| font-serif | 0 | ❌ Unused |
-```
-
-### Step 6: Generate Analytics Report
-
-```markdown
-# Token Usage Analytics Report
-Generated: {timestamp}
-Path: {path}
-
-## Summary
-
-| Category | Defined | Used | Coverage |
-|----------|---------|------|----------|
-| Colors | 18 | 15 | 83% |
-| Spacing | 15 | 12 | 80% |
-| Typography | 17 | 14 | 82% |
-| **Total** | **50** | **41** | **82%** |
-
-## Top 10 Most Used Tokens
-
-| Rank | Token | Usage | Category |
-|------|-------|-------|----------|
-| 1 | text-foreground | 156 | Color |
-| 2 | text-sm | 289 | Typography |
-| 3 | p-4 | 234 | Spacing |
-| 4 | gap-2 | 156 | Spacing |
-| 5 | font-medium | 156 | Typography |
-| ... | ... | ... | ... |
-
-## Unused Tokens (Candidates for Removal)
-
-| Token | Category | Recommendation |
-|-------|----------|----------------|
-| studio-accent | Color | Remove or document use case |
-| p-20 | Spacing | Remove from scale |
-| font-serif | Typography | Remove if not needed |
-| ... | ... | ... |
-
-## Misuse Detected
-
-| File | Line | Issue | Fix |
-|------|------|-------|-----|
-| Card.tsx | 45 | bg-foreground (text token on bg) | Use bg-surface |
-| Alert.tsx | 23 | success with text-red | Use text-green |
-| ... | ... | ... | ... |
-
-## Token Consolidation Opportunities
-
-### Similar Tokens (merge candidates)
-| Tokens | Usage | Recommendation |
-|--------|-------|----------------|
-| p-3, p-4 | 45, 234 | Keep p-4, migrate p-3 |
-| gap-3, gap-4 | 23, 78 | Keep gap-4, migrate gap-3 |
-
-### Underutilized Scale Points
-| Token | Usage | Recommendation |
-|-------|-------|----------------|
-| p-5 | 3 | Consider removing |
-| text-lg | 8 | Document specific use |
-
-## Recommendations
-
-1. **Remove** 9 unused tokens from spec
-2. **Consolidate** p-3 → p-4 (23 occurrences)
-3. **Fix** 5 token misuse instances
-4. **Document** use cases for low-usage tokens
-5. **Consider** adding text-muted-dark (no dark variant)
-
-## Token Health Score: 82/100
-
-Breakdown:
-- Coverage: 82% (41/50 tokens used)
-- No misuse: -3 points (5 misuse instances)
-- Consolidation: -5 points (redundant tokens)
-```
-
-## Output Location
-
-```
-outputs/design-system/{project}/
-├── token-analytics-{date}.md
-├── token-usage.json
-└── token-heatmap.html (visual)
-```
-
-## Failure Handling
-
-- **Design tokens spec file not found:** Exit with error "Token spec required at squads/super-agentes/data/design-tokens-spec.yaml. Cannot analyze without token inventory."
-- **Zero token matches in codebase:** Verify token naming convention matches project (CSS vars vs Tailwind classes vs styled-components). Adjust grep patterns and retry
-- **Misuse detection produces false positives:** Filter results by context (className vs inline style vs variable name). Only report confirmed misuse patterns
-- **Token heatmap generation fails:** Fall back to text-only report with usage counts per token category
-
-## Success Criteria
-
-- [ ] All tokens catalogued (defined vs used)
-- [ ] Usage counts per token
-- [ ] Unused tokens identified
-- [ ] Misuse patterns found
-- [ ] Consolidation recommendations
-
-## Related Commands
-
-- `*ds-health` - Overall health dashboard
-- `*validate-tokens` - Validate token usage in code
-- `*dead-code` - Full dead code detection
-
-
-## 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/ux-rewrite-sixth-grade.md

@@ -1,82 +0,0 @@
-# Rewrite UX Copy for Sixth-Grade Literacy
-
-> Task ID: brad-ux-rewrite-sixth-grade
-> Agent: Brad (Design System Architect)
-> Version: 1.0.0
-
-## Description
-
-Rewrite interface copy so a person with sixth-grade literacy can understand it quickly without losing product intent.
-
-Use this as a simplification gate for:
-- onboarding flows
-- settings screens
-- forms and validation messages
-- dashboards with instructional text
-
-## Prerequisites
-
-- Screen text inventory (titles, descriptions, labels, helper text, empty states, errors)
-- Business-critical terms that cannot be removed
-- Locale defined (pt-BR or en)
-
-## Workflow
-
-1. **Extract Copy**
-- Capture all visible strings from the target screen.
-- Group by element type: heading, action, instruction, error, hint.
-
-2. **Detect Complexity**
-- Flag long sentences (>20 words).
-- Flag jargon, passive voice, and abstract terms.
-- Flag multi-idea paragraphs.
-
-3. **Rewrite to Sixth-Grade Level**
-- Prefer short sentences (8-14 words).
-- Use common words and concrete verbs.
-- Keep one idea per sentence.
-- Convert passive to active voice.
-- Replace vague text with clear user action.
-
-4. **Preserve Critical Precision**
-- Keep legal/compliance terms when required.
-- Keep domain terms only when unavoidable, then explain in plain language.
-
-5. **Run Clarity Checks**
-- "Can I understand this in one read?"
-- "Can I act without asking support?"
-- "Can a new user explain this screen in their own words?"
-
-6. **Deliver Before/After Table**
-- Include rationale per change.
-- Mark high-impact rewrites first (primary CTA, errors, key instructions).
-
-## Output
-
-- `before-after-copy.md` with full rewrite map
-- Prioritized list of copy changes
-- Optional "Do/Don't" style guide snippets for the product
-
-## Success Criteria
-
-- [ ] Primary actions understood in <5 seconds
-- [ ] No sentence above 20 words in critical paths
-- [ ] Jargon removed or explained
-- [ ] Error messages include cause + next step
-- [ ] User can complete core flow without external explanation
-
-## Notes
-
-- Simplify, do not infantilize.
-- Clarity beats cleverness.
-- If copy must stay complex for legal reasons, add a plain-language helper line.
-
-
-## Related Checklists
-
-- `squads/design/checklists/reading-accessibility-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.