aiox-core 5.0.2 → 5.0.4

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

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

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

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

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