aiox-core 5.0.4 → 5.0.5

package/pro/squads/design/tasks/sb-brownfield-migrate.md

@@ -1,367 +0,0 @@
-# Migrate Brownfield Components
-
-**Task ID:** `sb-brownfield-migrate`
-**Pattern:** HO-TP-001 (Task Anatomy Standard)
-**Version:** 1.0.0
-**Last Updated:** 2026-02-25
-
-## Task Anatomy
-
-| Field | Value |
-|-------|-------|
-| **task_name** | Migrate Brownfield Components |
-| **status** | `pending` |
-| **responsible_executor** | @storybook-expert |
-| **execution_type** | `Agent` |
-| **input** | Component inventory, migration plan, dependency graph, target project |
-| **output** | Story files for all brownfield components, adaptation report |
-| **action_items** | 8 steps |
-| **acceptance_criteria** | 6 criteria |
-
-## Overview
-
-Execute the migration plan produced by `sb-brownfield-scan`. For each component in dependency order: analyze its API, adapt it for Storybook isolation (mock providers, stub data, handle side effects), and generate a `.stories.tsx` file. Handles components ranging from simple atoms to complex organisms with context dependencies.
-
-Supports two migration modes:
-- **Same-project:** Components stay where they are, stories are added co-located
-- **Cross-project:** Components are copied/adapted from source to target project
-
-## Input
-
-- **component_inventory** (JSON)
-  - Description: Full inventory from sb-brownfield-scan
-  - Required: Yes
-  - Source: `outputs/design-system/{project}/brownfield/component-inventory.json`
-- **migration_plan** (Markdown)
-  - Description: Phased migration plan
-  - Required: Yes
-  - Source: `outputs/design-system/{project}/brownfield/migration-plan.md`
-- **dependency_graph** (JSON)
-  - Description: Component dependency tree
-  - Required: Yes
-  - Source: `outputs/design-system/{project}/brownfield/dependency-graph.json`
-- **migration_mode** (enum)
-  - Description: How to handle the migration
-  - Required: No
-  - Default: `same-project`
-  - Options:
-    - `same-project` — Add stories co-located with existing components
-    - `cross-project` — Copy components to target project, then add stories
-- **target_path** (string)
-  - Description: Where to write stories (and components in cross-project mode)
-  - Required: Only for cross-project mode
-  - Default: Same directory as component
-- **phase_filter** (string)
-  - Description: Which phases to execute (e.g., "1", "1-3", "all")
-  - Required: No
-  - Default: `all`
-- **category_filter** (string)
-  - Description: Which category to migrate (e.g., "ui", "agents", "all")
-  - Required: No
-  - Default: `all`
-- **component_filter** (string)
-  - Description: Specific component name to migrate
-  - Required: No
-
-## Output
-
-- **story_files** (list)
-  - Description: Generated `.stories.tsx` files
-  - Destination: Co-located with components or in target_path
-- **adaptation_report** (Markdown)
-  - Description: Report of adaptations made per component
-  - Destination: `outputs/design-system/{project}/brownfield/adaptation-report.md`
-- **mock_files** (list)
-  - Description: Mock/stub files created for context dependencies
-  - Destination: `.storybook/mocks/` or story decorators
-
-## Action Items
-
-### Step 1: Load Migration Context
-
-- [ ] Read `component_inventory.json`
-- [ ] Read `migration_plan.md`
-- [ ] Read `dependency_graph.json`
-- [ ] Apply filters (phase, category, component) to determine scope
-- [ ] Report: "Migrating {N} components in {phases} phases"
-
-### Step 2: Prepare Storybook Environment
-
-If target project doesn't have Storybook yet:
-- [ ] Run `sb-install` task (or delegate to workflow)
-- [ ] Run `sb-configure` task
-
-If Storybook exists:
-- [ ] Verify `.storybook/main.ts` stories glob covers component locations
-- [ ] Update glob if needed to include brownfield component paths
-
-### Step 3: Process Phase by Phase
-
-For each phase in the migration plan (respecting dependency order):
-
-```
-Phase 1 (atoms) → Phase 2 (molecules) → Phase 3 (organisms) → ...
-```
-
-Within each phase, process components in order of "most depended-on first" to maximize unblocking.
-
-### Step 4: Analyze Each Component
-
-For each component, determine story strategy based on complexity:
-
-**4a. Simple Components (atoms, complexity 1-2)**
-Strategy: Args-driven stories, minimal setup
-```
-Read component → extract props → generate meta + Default + Variants + Gallery
-```
-
-**4b. Composite Components (molecules, complexity 3-5)**
-Strategy: Render function stories with composition
-```
-Read component → identify sub-components → compose render → add interaction stories
-```
-
-**4c. Complex Components (organisms, complexity 6-8)**
-Strategy: Render function + decorators for context
-```
-Read component → identify context deps → create mock providers → compose stories
-```
-
-**4d. Context-Dependent Components (complexity 8+)**
-Strategy: Full isolation with mocks and stubs
-
-Identify and handle:
-- **Router dependency:** Wrap with `MemoryRouter` or mock `useRouter`
-- **Auth context:** Provide mock user object
-- **API calls:** Mock with `msw` handlers or `fn()` stubs
-- **Global state:** Provide mock store/context
-- **Feature flags:** Provide default flag values
-
-Create decorator or wrapper:
-```typescript
-// .storybook/decorators/with-providers.tsx
-export const withProviders = (Story) => (
-  <MockAuthProvider user={mockUser}>
-    <MockRouterProvider>
-      <Story />
-    </MockRouterProvider>
-  </MockAuthProvider>
-);
-```
-
-### Step 5: Generate Story Files
-
-For each component, generate story following CSF3 conventions:
-
-```typescript
-import type { Meta, StoryObj } from "{framework_adapter}";
-import { {Component} } from "{import_path}";
-// Additional imports for sub-components, icons, etc.
-
-const meta = {
-  title: "{Category}/{ComponentName}",
-  component: {Component},
-  tags: ["autodocs"],
-  // parameters: { layout: "padded" } for layout components
-  // decorators: [withProviders] for context-dependent components
-} satisfies Meta<typeof {Component}>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = { /* ... */ };
-// Variant stories, gallery, interaction tests as needed
-```
-
-**Title hierarchy for brownfield:**
-
-| Atomic Level | Title Pattern | Example |
-|-------------|---------------|---------|
-| Atom | `Base Components/{Name}` | `Base Components/GlassButton` |
-| Molecule | `Components/{Name}` | `Components/SearchBar` |
-| Organism | `Features/{Category}/{Name}` | `Features/Agents/AgentCard` |
-| Template | `Templates/{Name}` | `Templates/DashboardLayout` |
-| Page | `Pages/{Name}` | `Pages/AgentExplorer` |
-
-### Step 6: Handle Cross-Project Migration (if applicable)
-
-When `migration_mode=cross-project`:
-
-**6a. Copy component file to target:**
-```bash
-cp {source_path}/{component}.tsx {target_path}/components/{category}/{component}.tsx
-```
-
-**6b. Adapt imports:**
-- Rewrite relative imports to match new location
-- Replace project-specific aliases (`@/` → new project alias)
-- Verify all dependencies exist in target project
-- Install missing npm packages
-
-**6c. Resolve missing dependencies:**
-- If component imports another component not yet in target → flag as blocked
-- If component imports a util/hook → copy that too
-- Track all copied files in adaptation_report
-
-### Step 7: Verify Each Phase
-
-After completing each phase:
-
-- [ ] `npm run typecheck` — zero errors from new story files
-- [ ] `npm run lint` — zero errors from new story files
-- [ ] Storybook renders new stories without crashes
-
-If errors found:
-- Fix in the current phase before proceeding to next
-- Document fixes in adaptation_report
-
-### Step 8: Generate Adaptation Report
-
-```markdown
-# Brownfield Migration Report
-
-## Summary
-- **Total components scanned:** 95
-- **Components migrated:** 95
-- **Stories generated:** 95
-- **Phases completed:** 10/10
-- **Adaptations required:** 23
-
-## Phase Results
-
-### Phase 1: Atoms (18 components)
-| Component | Story | Adaptations | Status |
-|-----------|-------|-------------|--------|
-| GlassButton | glass-button.stories.tsx | None | OK |
-| Badge | badge.stories.tsx | None | OK |
-...
-
-### Phase 3: Organisms (30 components)
-| Component | Story | Adaptations | Status |
-|-----------|-------|-------------|--------|
-| AgentCard | agent-card.stories.tsx | Mock: useAgentData hook | OK |
-| ChatContainer | chat-container.stories.tsx | Mock: WebSocket, AuthContext | OK |
-...
-
-## Adaptations Applied
-1. **AgentCard** — Mocked `useAgentData` hook with static fixture data
-2. **ChatContainer** — Created `withChatProviders` decorator for WebSocket + Auth
-3. **KanbanBoard** — Mocked drag-and-drop context (dnd-kit)
-...
-
-## Mock Files Created
-- `.storybook/mocks/auth-provider.tsx`
-- `.storybook/mocks/router-provider.tsx`
-- `.storybook/mocks/agent-data.ts`
-```
-
-## Acceptance Criteria
-
-- [ ] **AC-1:** Every component in the migration plan has a `.stories.tsx` file
-- [ ] **AC-2:** Stories follow CSF3 with `satisfies Meta<typeof Component>`
-- [ ] **AC-3:** `npm run typecheck` — zero errors
-- [ ] **AC-4:** `npm run lint` — zero errors
-- [ ] **AC-5:** All context-dependent components have mock decorators
-- [ ] **AC-6:** Adaptation report documents every adaptation made
-
-## Quality Gate
-
-```yaml
-quality_gate:
-  id: "SB-BF-QG-001"
-  name: "Brownfield Migration Gate"
-  placement: "exit"
-  type: "hybrid"
-  severity: "blocking"
-
-  criteria:
-    - check: "coverage_ratio"
-      field: "stories_generated / components_in_plan"
-      value: 1.0
-      operator: ">="
-      weight: 40
-    - check: "typecheck"
-      field: "typecheck_exit_code"
-      value: 0
-      operator: "=="
-      weight: 25
-    - check: "lint"
-      field: "lint_exit_code"
-      value: 0
-      operator: "=="
-      weight: 25
-    - check: "adaptation_documented"
-      field: "all_adaptations_in_report"
-      value: true
-      operator: "=="
-      weight: 10
-
-  thresholds:
-    pass: 100
-    review: 80
-    fail: 79
-```
-
-## Error Handling
-
-### Component Crashes in Storybook
-- **Trigger:** Component throws error without required context/provider
-- **Detection:** Storybook shows error overlay
-- **Recovery:** Identify missing context, create mock decorator, retry
-- **Prevention:** Step 4 context analysis should catch most cases
-
-### Import Resolution Fails (Cross-Project)
-- **Trigger:** Copied component imports module not in target project
-- **Detection:** TypeScript "Cannot find module" error
-- **Recovery:** Copy missing dependency, or install npm package, or create stub
-- **Prevention:** Step 6c dependency resolution
-
-### Component Has Side Effects
-- **Trigger:** Component makes API calls, mutates global state on mount
-- **Detection:** Network errors or state warnings in Storybook console
-- **Recovery:** Mock API calls with `msw` or `fn()`, provide inert context
-- **Prevention:** Step 4 complexity analysis flags side effects
-
-### Drag-and-Drop / Canvas / WebGL Components
-- **Trigger:** Components using canvas, WebGL, or complex DOM APIs
-- **Detection:** Blank render or "not supported" errors
-- **Recovery:** Skip render stories, create visual-only stories with screenshots
-- **Prevention:** Flag in inventory with `migration_notes: ["requires-canvas-mock"]`
-
-## Dependencies
-
-### Depends On (Upstream)
-- `sb-brownfield-scan` - Scan Brownfield Components
-  - Required output: component_inventory, migration_plan, dependency_graph
-
-### Required By (Downstream)
-- `sb-verify` - Verify Storybook Setup
-  - Uses output: story_files
-
-## Handoff
-
-| Attribute | Value |
-|-----------|-------|
-| **Next Task** | `sb-verify` |
-| **Trigger** | All phases completed, adaptation report generated |
-| **Executor** | @storybook-expert |
-
-### Handoff Package
-- **story_files**: List of all generated story file paths
-- **mock_files**: List of mock/decorator files created
-- **adaptation_report**: Full adaptation report
-- **coverage**: Stories generated vs total components
-
-## Veto Conditions
-
-- Migrating organisms before their atom/molecule dependencies have stories
-- Skipping context analysis for components with hooks
-- Not documenting adaptations in the report
-- Cross-project migration without resolving all import dependencies
-
----
-
-_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-brownfield-scan.md

@@ -1,318 +0,0 @@
-# Scan Brownfield Components
-
-**Task ID:** `sb-brownfield-scan`
-**Pattern:** HO-TP-001 (Task Anatomy Standard)
-**Version:** 1.0.0
-**Last Updated:** 2026-02-25
-
-## Task Anatomy
-
-| Field | Value |
-|-------|-------|
-| **task_name** | Scan Brownfield Components |
-| **status** | `pending` |
-| **responsible_executor** | @storybook-expert |
-| **execution_type** | `Agent` |
-| **input** | Source codebase path, file extensions, exclusion patterns |
-| **output** | Component inventory JSON with classification and dependency map |
-| **action_items** | 7 steps |
-| **acceptance_criteria** | 5 criteria |
-
-## Overview
-
-Walk an existing (brownfield) codebase and produce a complete component inventory. For each component: identify name, location, exported API (props), dependencies, atomic classification (atom/molecule/organism/template/page), and complexity score. This inventory feeds the migration pipeline that generates Storybook stories for every component.
-
-Works on ANY React/Next.js codebase — source and target can be the same project or different projects.
-
-## Input
-
-- **source_path** (string)
-  - Description: Root path to scan for components (e.g., `./aios-platform/src/components`)
-  - Required: Yes
-- **file_extensions** (list)
-  - Description: File extensions to include
-  - Required: No
-  - Default: `["tsx", "jsx"]`
-- **exclude_patterns** (list)
-  - Description: Glob patterns to exclude from scan
-  - Required: No
-  - Default: `["*.stories.*", "*.test.*", "*.spec.*", "**/__tests__/**", "**/node_modules/**"]`
-- **target_storybook** (string)
-  - Description: Path to the target Storybook project (can be same project or different)
-  - Required: No
-  - Default: Same project as source
-- **scan_mode** (enum)
-  - Description: How deep to scan
-  - Required: No
-  - Default: `full`
-  - Options: `full` (all files), `components-only` (only files in `components/` dirs), `exports-only` (only files with React component exports)
-
-## Output
-
-- **component_inventory** (JSON)
-  - Description: Complete inventory of all components found
-  - Destination: `outputs/design-system/{project}/brownfield/component-inventory.json`
-  - Format: See schema below
-- **migration_plan** (Markdown)
-  - Description: Prioritized migration plan with phases
-  - Destination: `outputs/design-system/{project}/brownfield/migration-plan.md`
-- **dependency_graph** (JSON)
-  - Description: Component dependency tree
-  - Destination: `outputs/design-system/{project}/brownfield/dependency-graph.json`
-
-### Output Schema: component_inventory
-
-```json
-{
-  "scan_metadata": {
-    "source_path": "string",
-    "scan_date": "ISO-8601",
-    "total_files_scanned": "number",
-    "total_components_found": "number",
-    "scan_duration_ms": "number"
-  },
-  "components": [
-    {
-      "name": "GlassCard",
-      "file_path": "src/components/ui/glass-card.tsx",
-      "exports": ["GlassCard", "GlassCardHeader", "GlassCardContent"],
-      "props": {
-        "GlassCard": {
-          "variant": { "type": "union", "values": ["default", "elevated", "flat"] },
-          "className": { "type": "string", "optional": true }
-        }
-      },
-      "atomic_level": "molecule",
-      "category": "ui",
-      "dependencies": {
-        "internal": ["Button", "Badge"],
-        "external": ["@radix-ui/react-slot", "class-variance-authority"]
-      },
-      "has_variants": true,
-      "variant_count": 3,
-      "has_story": false,
-      "complexity_score": 3,
-      "lines_of_code": 85,
-      "migration_notes": []
-    }
-  ],
-  "categories": {
-    "ui": { "count": 18, "components": ["GlassCard", "GlassButton", "..."] },
-    "layout": { "count": 6, "components": ["Sidebar", "Header", "..."] },
-    "agents": { "count": 8, "components": ["AgentCard", "..."] }
-  },
-  "atomic_distribution": {
-    "atom": 12,
-    "molecule": 25,
-    "organism": 30,
-    "template": 8,
-    "page": 5
-  },
-  "migration_phases": [
-    {
-      "phase": 1,
-      "name": "Atoms & Primitives",
-      "components": ["Button", "Badge", "Avatar", "Input", "Label"],
-      "priority": "critical",
-      "rationale": "Foundation — other components depend on these"
-    }
-  ]
-}
-```
-
-## Action Items
-
-### Step 1: Validate Source Path
-
-- [ ] Verify `source_path` exists and is readable
-- [ ] Count total files matching `file_extensions`
-- [ ] Report: "Found {N} files to scan in {path}"
-- [ ] If 0 files found, abort with guidance on correct path
-
-### Step 2: Scan for Component Files
-
-Walk the directory tree and identify files that export React components:
-
-```bash
-# Find all TSX/JSX files (excluding test/story files)
-find {source_path} -type f \( -name "*.tsx" -o -name "*.jsx" \) \
-  ! -name "*.stories.*" ! -name "*.test.*" ! -name "*.spec.*" \
-  ! -path "*/__tests__/*" ! -path "*/node_modules/*"
-```
-
-For each file, determine if it exports a React component by checking for:
-- `export function {Name}` or `export const {Name}` with JSX return
-- `export default function` with JSX return
-- `React.forwardRef` usage
-- `React.FC` or `React.ComponentType` type annotations
-
-### Step 3: Extract Component Metadata
-
-For each component file, extract:
-
-**3a. Exports:**
-- Named exports: `export { Button, ButtonProps }`
-- Default exports: `export default Button`
-- Sub-component exports: `DialogTrigger`, `DialogContent`, etc.
-
-**3b. Props Interface:**
-- TypeScript interfaces/types for props
-- CVA variants (if using class-variance-authority)
-- Default prop values
-
-**3c. Dependencies:**
-- Internal imports: other components from the same project
-- External imports: npm packages (Radix, etc.)
-- Context dependencies: providers, hooks that need wrapping
-
-**3d. Complexity Indicators:**
-- Lines of code
-- Number of hooks used
-- Number of internal dependencies
-- Uses context/providers
-- Has side effects (API calls, subscriptions)
-- Requires global state
-
-### Step 4: Classify by Atomic Level
-
-Apply atomic design classification heuristics:
-
-| Level | Heuristics | Examples |
-|-------|-----------|----------|
-| **Atom** | No internal component deps, single responsibility, <80 LOC, 0-2 props | Button, Badge, Avatar, Input, Label, Separator, Skeleton |
-| **Molecule** | Uses 2-3 atoms, single purpose, <150 LOC | InputWithLabel, CardHeader, NavItem, SearchBar |
-| **Organism** | Uses multiple molecules/atoms, section-level, distinct business function | AgentCard, KanbanColumn, ChatContainer, Sidebar |
-| **Template** | Layout skeleton, defines content areas, no business logic | AppLayout, DashboardLayout, AuthLayout |
-| **Page** | Full page, connects to data, has routing context | AgentExplorer, KanbanBoard, DashboardPage |
-
-**Classification Algorithm:**
-```
-IF internal_deps == 0 AND loc < 80 → atom
-ELIF internal_deps <= 3 AND loc < 150 → molecule
-ELIF internal_deps <= 8 AND has_business_logic → organism
-ELIF is_layout AND defines_content_areas → template
-ELIF connects_to_data OR has_routing → page
-ELSE → organism (default)
-```
-
-### Step 5: Detect Existing Stories
-
-Check if each component already has a `.stories.tsx` file:
-- Co-located: `{component}.stories.tsx` next to component
-- Separate dir: `stories/{component}.stories.tsx`
-- Legacy: `__stories__/{component}.stories.tsx`
-
-Mark `has_story: true/false` in inventory.
-
-### Step 6: Build Dependency Graph
-
-Map which components depend on which:
-
-```json
-{
-  "AgentCard": {
-    "depends_on": ["Badge", "Avatar", "Button"],
-    "depended_by": ["AgentList", "AgentExplorer"]
-  }
-}
-```
-
-This determines migration order: atoms first (no deps), then molecules (depend on atoms), then organisms, etc.
-
-### Step 7: Generate Migration Plan
-
-Based on inventory + dependency graph, produce phased migration plan:
-
-**Phase ordering rules:**
-1. Components with 0 internal deps first (atoms)
-2. Components whose ALL deps are already migrated (molecules)
-3. Continue up the dependency tree (organisms → templates → pages)
-4. Within each phase, sort by: most depended-on first (maximize unblocking)
-
-**Categories:** Group components by domain (ui, layout, agents, chat, kanban, etc.) based on directory structure or naming patterns.
-
-**Output format:**
-
-```markdown
-# Brownfield Migration Plan
-
-## Phase 1: Atoms & Primitives (18 components)
-Priority: CRITICAL — foundation for all other components
-
-| Component | File | Deps | Depended By | Complexity |
-|-----------|------|------|-------------|------------|
-| Button | src/ui/button.tsx | 0 | 42 | 2 |
-| Badge | src/ui/badge.tsx | 0 | 15 | 1 |
-...
-
-## Phase 2: Molecules (25 components)
-Priority: HIGH — compose atoms into reusable patterns
-...
-```
-
-## Acceptance Criteria
-
-- [ ] **AC-1:** `component-inventory.json` contains ALL component files in scan path
-- [ ] **AC-2:** Each component has atomic_level classification
-- [ ] **AC-3:** Each component has dependency map (internal + external)
-- [ ] **AC-4:** `migration-plan.md` has phased plan ordered by dependency tree
-- [ ] **AC-5:** `dependency-graph.json` is complete and acyclic
-
-## Error Handling
-
-### Circular Dependencies
-- **Trigger:** Component A imports B, B imports A
-- **Detection:** Graph cycle detection during Step 6
-- **Recovery:** Flag circular pair, classify both at same phase level, note in migration_notes
-- **Prevention:** Common in brownfield — expected, not a blocker
-
-### Non-Component Files in Scan
-- **Trigger:** File exports hooks, utils, types but no React component
-- **Detection:** Step 2 JSX/component detection
-- **Recovery:** Skip file, do not include in component inventory
-- **Prevention:** Filter by component export patterns
-
-### Very Large Codebases (500+ files)
-- **Trigger:** Scan takes too long or produces unwieldy output
-- **Detection:** File count > 500 in Step 1
-- **Recovery:** Use `scan_mode=components-only` to focus on component directories
-- **Prevention:** Ask user to narrow `source_path` to component directories
-
-## Dependencies
-
-### Depends On (Upstream)
-- None (entry point task)
-
-### Required By (Downstream)
-- `sb-brownfield-migrate` - Migrate Brownfield Components
-  - Uses output: component_inventory, migration_plan, dependency_graph
-
-## Handoff
-
-| Attribute | Value |
-|-----------|-------|
-| **Next Task** | `sb-brownfield-migrate` |
-| **Trigger** | Inventory and migration plan generated |
-| **Executor** | @storybook-expert |
-
-### Handoff Package
-- **component_inventory**: Full JSON inventory
-- **migration_plan**: Phased markdown plan
-- **dependency_graph**: Component dependency tree
-- **total_components**: Count of components found
-- **total_with_stories**: Count that already have stories
-- **migration_gap**: Components needing stories
-
-## Veto Conditions
-
-- Classifying ALL components as "organism" without heuristic analysis
-- Ignoring dependency order in migration plan (atoms MUST come first)
-- Skipping components because they "look complex"
-- Generating migration plan without dependency graph
-
----
-
-_Task Version: 1.0.0_
-_Pattern: HO-TP-001 (Task Anatomy Standard)_
-_Last Updated: 2026-02-25_
-_Compliant: Yes_