aiox-core 5.0.2 → 5.0.3

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

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

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