aiox-core 5.0.2 → 5.0.3

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

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

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

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