aiox-core 5.0.4 → 5.0.5

package/pro/squads/design/tasks/sb-generate-all-stories.md

@@ -1,288 +0,0 @@
-# Generate All Stories
-
-**Task ID:** `sb-generate-all-stories`
-**Pattern:** HO-TP-001 (Task Anatomy Standard)
-**Version:** 1.0.0
-**Last Updated:** 2026-02-25
-
-## Task Anatomy
-
-| Field | Value |
-|-------|-------|
-| **task_name** | Generate All Stories |
-| **status** | `pending` |
-| **responsible_executor** | @storybook-expert |
-| **execution_type** | `Agent` |
-| **input** | Component directory, component list, story conventions |
-| **output** | `.stories.tsx` file for every component |
-| **action_items** | 7 steps |
-| **acceptance_criteria** | 6 criteria |
-
-## Overview
-
-Generate a `.stories.tsx` file for EVERY component in the project's UI directory. Follows CSF3 conventions with TypeScript strict mode, `satisfies Meta<typeof Component>` pattern, Portuguese content, and co-located file placement. Handles both shadcn standard components and project-specific custom components.
-
-## Input
-
-- **components_dir** (string)
-  - Description: Directory containing UI components
-  - Required: Yes
-  - Default: `src/components/ui/`
-- **installed_components** (list)
-  - Description: List of component files from sb-expand-shadcn output
-  - Required: Yes
-  - Source: Previous task handoff
-- **custom_components** (list)
-  - Description: Project-specific components not from shadcn
-  - Required: No
-  - Source: Previous task handoff
-- **story_conventions** (object)
-  - Description: Project-specific story writing conventions
-  - Required: No
-  - Source: storybook-expert agent configuration
-
-## Output
-
-- **story_files** (list)
-  - Description: Generated `.stories.tsx` files
-  - Destination: Co-located with components (`src/components/ui/{name}.stories.tsx`)
-- **coverage_report** (object)
-  - Description: Components covered vs total
-
-## Action Items
-
-### Step 1: Inventory All Components
-
-- [ ] Scan `{components_dir}` for all `.tsx` files (exclude `.stories.tsx`, `.test.tsx`)
-- [ ] For each file, extract: exported component names, props interface, variants (CVA)
-- [ ] Separate into: shadcn standard components vs custom components
-- [ ] Check which already have `.stories.tsx` files (skip if exists and valid)
-
-### Step 2: Classify Components
-
-Classify each component to determine story strategy:
-
-| Category | Examples | Story Strategy |
-|----------|----------|---------------|
-| **Simple (args-only)** | Badge, Separator, Avatar, Progress, Skeleton | Default + variant stories, AllVariants gallery |
-| **Form Controls** | Input, Textarea, Select, Checkbox, Switch, Slider, RadioGroup, Toggle | Default + WithLabel + states (disabled, error) |
-| **Compound (render required)** | Dialog, Sheet, Drawer, Popover, Tooltip, DropdownMenu, ContextMenu, Command, AlertDialog, HoverCard | Render function stories showing trigger + content |
-| **Layout** | Card, Table, Tabs, Accordion, Collapsible, Resizable, ScrollArea | Render function with realistic content |
-| **Navigation** | Breadcrumb, Pagination, NavigationMenu, Menubar, Sidebar | Render function with navigation structure |
-| **Notification** | Alert, Sonner/Toast | Default + variants (success, error, warning) |
-| **Utility** | AspectRatio, Calendar, Carousel, Chart, InputOTP | Specialized render per component |
-| **Custom** | Project-specific | Analyze props/variants and generate accordingly |
-
-### Step 3: Generate Story Files
-
-For EACH component without an existing valid story:
-
-**3a. Read the component file:**
-```
-Read(src/components/ui/{name}.tsx)
-```
-
-**3b. Extract metadata:**
-- Component name and exports
-- Props interface (variants, sizes, states)
-- CVA variants (if using class-variance-authority)
-- Required children/content patterns
-- Event handlers (onClick, onChange, etc.)
-
-**3c. Apply story template:**
-
-```typescript
-import type { Meta, StoryObj } from "{framework_adapter}";
-import { {ComponentName} } from "./{component-file}";
-
-const meta = {
-  title: "{Category}/{ComponentName}",
-  component: {ComponentName},
-  tags: ["autodocs"],
-  // argTypes based on extracted props
-  // args with sensible defaults
-} satisfies Meta<typeof {ComponentName}>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-// Default story (always first)
-export const Default: Story = {
-  args: { /* default props */ },
-};
-
-// Variant stories (one per variant)
-// Gallery story (AllVariants)
-// Composition stories (With{Feature})
-```
-
-**3d. Content rules:**
-- ALL text content in Portuguese (pt-BR): "Abrir", "Salvar", "Cancelar", "Digite aqui..."
-- Use `fn()` from `storybook/test` for event handlers
-- Use `parameters: { layout: "padded" }` for layout components
-- Use `parameters: { layout: "fullscreen" }` for navigation/sidebar
-- Default layout is `centered` (from preview.ts global config)
-
-### Step 4: Handle Compound Components
-
-Components with multiple sub-exports (Dialog, DropdownMenu, etc.) need special handling:
-
-```typescript
-// Import all sub-components
-import {
-  {Parent},
-  {ParentTrigger},
-  {ParentContent},
-  // ... other sub-components
-} from "./{component-file}";
-```
-
-The render function composes sub-components with realistic content:
-- Triggers use Button or text elements
-- Content shows representative UI
-- Include enough sub-components to demonstrate the API
-
-### Step 5: Batch Write Files
-
-Write all story files to disk. For large batches (40+ files), process in groups of 5-10 to maintain quality:
-
-- [ ] Group 1: Simple components (args-only) — fastest to generate
-- [ ] Group 2: Form controls — moderate complexity
-- [ ] Group 3: Compound components — highest complexity, need careful composition
-- [ ] Group 4: Layout/navigation components — need realistic content
-- [ ] Group 5: Custom components — need individual analysis
-
-### Step 6: Type Check and Fix
-
-After writing all story files:
-
-```bash
-npm run typecheck
-```
-
-**Common TypeScript errors and fixes:**
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `Type '...' not assignable to parameter of 'never'` | Story with render but no args, component has required props | Add required props to `args` even when render handles them |
-| `Cannot find module` | Wrong import path | Verify component exports match imports |
-| `Property '...' does not exist` | Wrong prop name | Check component props interface |
-| Unused imports | Imported component not used in render | Remove unused imports |
-
-Fix ALL type errors before proceeding.
-
-### Step 7: Lint Check and Fix
-
-```bash
-npm run lint
-```
-
-Fix any lint errors in generated story files.
-
-## Acceptance Criteria
-
-- [ ] **AC-1:** Every component in `{components_dir}` has a corresponding `.stories.tsx` file
-- [ ] **AC-2:** All stories use `satisfies Meta<typeof Component>` pattern
-- [ ] **AC-3:** All stories have `tags: ["autodocs"]`
-- [ ] **AC-4:** `npm run typecheck` — zero errors
-- [ ] **AC-5:** `npm run lint` — zero errors
-- [ ] **AC-6:** All text content in Portuguese (pt-BR)
-
-## Quality Gate
-
-```yaml
-quality_gate:
-  id: "SB-QG-001"
-  name: "Story Coverage Gate"
-  placement: "exit"
-  type: "automated"
-  severity: "blocking"
-
-  criteria:
-    - check: "coverage_ratio"
-      type: "threshold"
-      field: "stories_count / components_count"
-      value: 1.0
-      operator: ">="
-      weight: 40
-    - check: "typecheck_pass"
-      type: "boolean"
-      field: "typecheck_exit_code"
-      value: 0
-      operator: "=="
-      weight: 30
-    - check: "lint_pass"
-      type: "boolean"
-      field: "lint_exit_code"
-      value: 0
-      operator: "=="
-      weight: 30
-
-  thresholds:
-    pass: 100
-    review: 80
-    fail: 79
-
-  pass_action:
-    - "Proceed to sb-verify"
-  fail_action:
-    - "Fix type/lint errors"
-    - "Generate missing stories"
-    - "Re-run quality gate"
-```
-
-## Error Handling
-
-### Component Has No Exported Component
-- **Trigger:** File exports only utilities, types, or hooks (not a React component)
-- **Detection:** No JSX.Element or React.FC export found
-- **Recovery:** Skip this file — it doesnt need a story
-- **Prevention:** Step 1 filters by exported component presence
-
-### Generated Story Has Type Errors
-- **Trigger:** Props interface doesnt match args
-- **Detection:** Step 6 typecheck
-- **Recovery:** Read component source again, fix args to match actual props
-- **Prevention:** Careful prop extraction in Step 3b
-
-### Component Requires External Context
-- **Trigger:** Component crashes without Provider, Router, or Context
-- **Detection:** Runtime error in Storybook
-- **Recovery:** Add decorator with required Provider in story meta
-- **Prevention:** Detect context dependencies during component analysis
-
-## Dependencies
-
-### Depends On (Upstream)
-
-- `sb-expand-shadcn` - Expand Shadcn Library
-  - Required output: installed_components, custom_components
-- `sb-configure` - Configure Storybook
-  - Required output: framework_adapter, stories_glob
-
-### Required By (Downstream)
-
-- `sb-verify` - Verify Storybook Setup
-  - Uses output: All story files written
-
-## Handoff
-
-| Attribute | Value |
-|-----------|-------|
-| **Next Task** | `sb-verify` |
-| **Trigger** | All acceptance criteria met |
-| **Executor** | @storybook-expert |
-
-### Handoff Package
-
-- **story_files**: List of generated story files with paths
-- **coverage_report**: Components total vs stories generated
-- **type_errors_fixed**: List of type errors encountered and fixed
-- **skipped_components**: Files skipped (no exportable component)
-
----
-
-_Task Version: 1.0.0_
-_Pattern: HO-TP-001 (Task Anatomy Standard)_
-_Last Updated: 2026-02-25_
-_Compliant: Yes_

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

@@ -1,152 +0,0 @@
-# Install Storybook
-
-**Task ID:** `sb-install`
-**Pattern:** HO-TP-001 (Task Anatomy Standard)
-**Version:** 1.0.0
-**Last Updated:** 2026-02-25
-
-## Task Anatomy
-
-| Field | Value |
-|-------|-------|
-| **task_name** | Install Storybook |
-| **status** | `pending` |
-| **responsible_executor** | @storybook-expert |
-| **execution_type** | `Agent` |
-| **input** | Project root path, package manager (npm/pnpm/bun) |
-| **output** | Storybook packages installed as devDependencies |
-| **action_items** | 5 steps |
-| **acceptance_criteria** | 4 criteria |
-
-## Overview
-
-Install Storybook with the `nextjs-vite` framework and all required addons as devDependencies. This task handles package installation only — configuration is handled by `sb-configure`.
-
-## Input
-
-- **project_root** (string)
-  - Description: Absolute path to the project root (where package.json lives)
-  - Required: Yes
-- **package_manager** (string)
-  - Description: Package manager to use (`npm`, `pnpm`, or `bun`)
-  - Required: Yes
-  - Default: Detected from lockfile
-- **storybook_version** (string)
-  - Description: Storybook major version to install
-  - Required: No
-  - Default: `latest` (currently v10)
-
-## Output
-
-- **installed_packages** (list)
-  - Description: List of installed devDependencies
-  - Destination: `package.json` devDependencies
-
-## Action Items
-
-### Step 1: Detect Project Environment
-
-Read `package.json` to identify:
-- [ ] Framework (Next.js, Vite, React)
-- [ ] Existing Storybook packages (if any — abort if already installed)
-- [ ] Package manager (from lockfile: package-lock.json → npm, pnpm-lock.yaml → pnpm, bun.lockb → bun)
-- [ ] TypeScript version
-
-### Step 2: Determine Package Set
-
-Based on framework detection, select packages:
-
-**Core (always required):**
-```
-storybook
-```
-
-**Framework adapter (select ONE):**
-
-| Framework | Adapter Package |
-|-----------|----------------|
-| Next.js + Vite | `@storybook/nextjs-vite` |
-| Next.js + Webpack | `@storybook/nextjs` |
-| Vite (standalone) | `@storybook/react-vite` |
-| Webpack (standalone) | `@storybook/react-webpack5` |
-
-**Addons (recommended set):**
-```
-@storybook/addon-docs
-@storybook/addon-a11y
-@storybook/addon-themes
-@storybook/addon-vitest
-@chromatic-com/storybook
-```
-
-**Notes:**
-- In Storybook v10+, `@storybook/test` is bundled as `storybook/test` — do NOT install separately
-- Types (`Meta`, `StoryObj`, `Preview`) import from the framework adapter, NOT from `storybook`
-
-### Step 3: Install Packages
-
-```bash
-{package_manager} install -D storybook {framework_adapter} @storybook/addon-docs @storybook/addon-a11y @storybook/addon-themes @storybook/addon-vitest @chromatic-com/storybook
-```
-
-If peer dependency conflicts occur:
-- Try `--legacy-peer-deps` (npm) or `--no-strict-peer-deps` (pnpm)
-- Document which flag was needed
-
-### Step 4: Verify Installation
-
-- [ ] All packages appear in `devDependencies`
-- [ ] No duplicate Storybook packages at different major versions
-- [ ] `npx storybook --version` returns installed version
-
-### Step 5: Add Scripts to package.json
-
-Add to `scripts`:
-```json
-{
-  "storybook": "storybook dev -p 6006",
-  "build-storybook": "storybook build"
-}
-```
-
-## Acceptance Criteria
-
-- [ ] **AC-1:** All required packages installed as devDependencies
-- [ ] **AC-2:** No peer dependency errors in install output
-- [ ] **AC-3:** `storybook` and `build-storybook` scripts present in package.json
-- [ ] **AC-4:** `npx storybook --version` returns correct version
-
-## Error Handling
-
-### Peer Dependency Conflict
-- **Trigger:** npm/pnpm rejects install due to peer dep mismatch
-- **Detection:** Exit code != 0 with "ERESOLVE" or "peer dep" in output
-- **Recovery:** Retry with `--legacy-peer-deps`. If still fails, check for `@storybook/test` as separate package (remove it — bundled in v10)
-- **Prevention:** Always check for existing Storybook packages before installing
-
-### Framework Adapter Wrong Choice
-- **Trigger:** Project uses Vite but nextjs adapter selected (or vice versa)
-- **Detection:** Build fails with "Cannot find module" for framework-specific APIs
-- **Recovery:** Uninstall wrong adapter, install correct one based on framework detection
-- **Prevention:** Step 1 framework detection is mandatory
-
-## Handoff
-
-| Attribute | Value |
-|-----------|-------|
-| **Next Task** | `sb-configure` |
-| **Trigger** | All acceptance criteria met |
-| **Executor** | @storybook-expert |
-
-### Handoff Package
-
-- **installed_packages**: List of package names and versions installed
-- **framework_adapter**: Which adapter was selected
-- **package_manager**: Which PM was used
-
----
-
-_Task Version: 1.0.0_
-_Pattern: HO-TP-001 (Task Anatomy Standard)_
-_Last Updated: 2026-02-25_
-_Compliant: Yes_

package/pro/squads/design/tasks/sb-sync-workspace.md

@@ -1,239 +0,0 @@
-# Sync Storybook with Workspace
-
-**Task ID:** `sb-sync-workspace`
-**Pattern:** HO-TP-001 (Task Anatomy Standard)
-**Version:** 1.0.0
-**Last Updated:** 2026-02-25
-
-## Task Anatomy
-
-| Field | Value |
-|-------|-------|
-| **task_name** | Sync Storybook with Workspace |
-| **status** | `pending` |
-| **responsible_executor** | @storybook-expert |
-| **execution_type** | `Agent` |
-| **input** | Story files, workspace metadata, component files |
-| **output** | Synchronized inventory, drift report |
-| **action_items** | 6 steps |
-| **acceptance_criteria** | 5 criteria |
-
-## Overview
-
-Bidirectional sync between Storybook (source of truth for visualization, states, and testing)
-and Workspace (source of truth for governance, metadata, and cross-squad integration).
-
-**Hybrid Source-of-Truth Model:**
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    SOURCE OF TRUTH MAP                       │
-├──────────────────────┬──────────────────────────────────────┤
-│     STORYBOOK        │         WORKSPACE                    │
-│   (visualization)    │       (governance)                   │
-├──────────────────────┼──────────────────────────────────────┤
-│ Component states     │ Component metadata (owner, squad)    │
-│ Variant rendering    │ Token definitions (DTCG source)      │
-│ Interaction tests    │ Cross-squad contracts                │
-│ A11y compliance      │ Deprecation policies                 │
-│ Visual regression    │ Versioning & changelog               │
-│ Atomic hierarchy     │ Domain assignments                   │
-│ (story titles)       │ Design decisions (ADRs)              │
-│ Props/API docs       │ Governance rules                     │
-│ (autodocs)           │                                      │
-└──────────────────────┴──────────────────────────────────────┘
-
-        ↕  sb-sync-workspace  ↕
-        (bidirectional sync)
-```
-
-**Sync direction:**
-- Storybook → Workspace: component inventory, atomic hierarchy, variant list, coverage status
-- Workspace → Storybook: metadata enrichment (owner, domain, deprecation status)
-
-## Input
-
-- **stories_dir** (string)
-  - Description: Directory containing story files
-  - Required: Yes
-  - Default: `src/components/ui/`
-- **workspace_metadata_path** (string)
-  - Description: Path to workspace component metadata
-  - Required: Yes
-  - Default: `workspace/domains/design-system/metadata/components.json`
-- **sync_direction** (enum)
-  - Description: Which direction to sync
-  - Required: No
-  - Default: `bidirectional`
-  - Options: `storybook-to-workspace`, `workspace-to-storybook`, `bidirectional`, `drift-report-only`
-
-## Output
-
-- **synced_metadata** (JSON)
-  - Description: Updated component metadata reflecting both sources
-  - Destination: `workspace/domains/design-system/metadata/components.json`
-- **drift_report** (Markdown)
-  - Description: Report of discrepancies between Storybook and Workspace
-  - Destination: `outputs/design-system/{project}/sync/drift-report.md`
-
-## Action Items
-
-### Step 1: Extract Storybook Inventory
-
-Scan all `.stories.tsx` files and extract:
-
-```json
-{
-  "storybook_inventory": {
-    "Button": {
-      "story_file": "src/components/ui/button.stories.tsx",
-      "title": "Base Components/Button",
-      "atomic_level": "atom",
-      "variants": ["Default", "Destructive", "Outline", "Secondary", "Ghost", "Link"],
-      "has_gallery": true,
-      "has_play_function": true,
-      "has_a11y": true,
-      "tags": ["autodocs"],
-      "story_count": 12
-    }
-  }
-}
-```
-
-For each story file:
-- [ ] Parse `title` field to determine atomic hierarchy
-- [ ] Count named exports (story count)
-- [ ] Check for `play` functions (interaction coverage)
-- [ ] Check for gallery stories (AllVariants, AllSizes)
-- [ ] Extract `tags` from meta
-
-### Step 2: Read Workspace Metadata
-
-Read existing workspace component metadata:
-- [ ] `workspace/domains/design-system/metadata/components.json`
-- [ ] Any domain-specific component registries
-- [ ] Governance rules (deprecation, ownership)
-
-### Step 3: Detect Drift
-
-Compare Storybook inventory against Workspace metadata:
-
-| Drift Type | Meaning | Resolution |
-|------------|---------|------------|
-| **In Storybook, not in Workspace** | New component not registered | Add to workspace metadata |
-| **In Workspace, not in Storybook** | Component exists in metadata but has no story | Flag as undocumented |
-| **Hierarchy mismatch** | Story title says "atom" but workspace says "molecule" | Storybook wins (it renders the truth) |
-| **Variant mismatch** | Workspace lists 3 variants, Storybook shows 6 | Storybook wins (it renders them) |
-| **Missing coverage** | Component has story but no interaction test | Flag for test improvement |
-
-### Step 4: Sync Storybook → Workspace
-
-Update workspace metadata with Storybook-derived data:
-
-- [ ] Add new components discovered in stories
-- [ ] Update atomic_level from story title hierarchy
-- [ ] Update variant list from story exports
-- [ ] Update coverage status (has_story, has_play, has_a11y)
-- [ ] Preserve workspace-only fields (owner, domain, deprecation, governance)
-
-### Step 5: Sync Workspace → Storybook (metadata enrichment)
-
-Enrich story files with workspace metadata (where applicable):
-
-- [ ] Add `parameters.docs.description` from workspace component descriptions
-- [ ] Add deprecation badges to deprecated components via `tags: ['deprecated']`
-- [ ] Update title hierarchy if workspace governance dictates reclassification
-
-**Note:** This direction is lighter — Storybook is the primary source for visual truth,
-workspace only contributes governance context.
-
-### Step 6: Generate Drift Report
-
-```markdown
-# Storybook ↔ Workspace Drift Report
-
-**Scan Date:** {date}
-**Total Components (Storybook):** {N}
-**Total Components (Workspace):** {M}
-**In Sync:** {sync_count}
-**Drifted:** {drift_count}
-
-## New in Storybook (not in Workspace)
-| Component | Story Title | Action |
-|-----------|-------------|--------|
-| InputOTP | Base Components/InputOTP | Added to workspace |
-
-## In Workspace Only (no Story)
-| Component | Workspace Status | Action |
-|-----------|-----------------|--------|
-| LegacyTable | active | NEEDS STORY |
-
-## Hierarchy Mismatches (Storybook wins)
-| Component | Storybook | Workspace | Resolved |
-|-----------|-----------|-----------|----------|
-| SearchBar | molecule | atom | → molecule |
-
-## Coverage Gaps
-| Component | Story | Play | A11y | Gallery |
-|-----------|-------|------|------|---------|
-| Dialog | Yes | No | Yes | No |
-| AgentCard | Yes | No | No | No |
-```
-
-## Acceptance Criteria
-
-- [ ] **AC-1:** All Storybook components reflected in workspace metadata
-- [ ] **AC-2:** All workspace components flagged if missing stories
-- [ ] **AC-3:** Hierarchy mismatches resolved (Storybook wins for visual truth)
-- [ ] **AC-4:** Drift report generated with actionable items
-- [ ] **AC-5:** Workspace-only fields (owner, governance) preserved during sync
-
-## Error Handling
-
-### Workspace Metadata File Missing
-- **Trigger:** `components.json` doesnt exist
-- **Detection:** File read fails
-- **Recovery:** Create initial metadata from Storybook inventory (storybook-to-workspace only)
-- **Prevention:** Check file exists in Step 2
-
-### Story Title Doesnt Map to Atomic Level
-- **Trigger:** Custom title that doesnt follow Base Components/Components/Features pattern
-- **Detection:** Title parsing fails
-- **Recovery:** Classify as "unclassified", flag in drift report
-- **Prevention:** Document title conventions in storybook-expert
-
-### Circular Ownership Conflict
-- **Trigger:** Workspace says component belongs to Squad A, but story is in Squad B directory
-- **Detection:** Owner mismatch
-- **Recovery:** Flag in drift report, dont auto-resolve (governance decision)
-- **Prevention:** Ownership is workspace-only field, never overwritten by sync
-
-## Dependencies
-
-### Depends On (Upstream)
-- `sb-generate-all-stories` or `sb-brownfield-migrate` — Stories must exist first
-
-### Required By (Downstream)
-- None (utility task, run on-demand or on schedule)
-
-## Handoff
-
-| Attribute | Value |
-|-----------|-------|
-| **Next Task** | None (utility task) |
-| **Trigger** | After story generation or on-demand |
-| **Executor** | @storybook-expert |
-
-## Veto Conditions
-
-- Overwriting workspace governance fields (owner, deprecation) with Storybook data
-- Deleting workspace entries just because no story exists yet
-- Auto-reclassifying atomic level without Storybook rendering evidence
-- Running sync before any stories exist (empty Storybook = meaningless sync)
-
----
-
-_Task Version: 1.0.0_
-_Pattern: HO-TP-001 (Task Anatomy Standard)_
-_Last Updated: 2026-02-25_
-_Compliant: Yes_