Run 3: Organism Port
Move callil organisms and their supporting molecules into the main clone with import rewrites only (no behavioral changes). Validates that the foundation from Runs 1-2 supports the organisms correctly.
Working directory: /Users/jmp/code/arda/ux-prototype/ (main clone, branch jmpicnic/component-consolidation)
Reference directory: /Users/jmp/code/arda/callil-consolidation-worktree/ (read-only, branch jmpicnic/callil-consolidation)
Entry Criteria
Section titled “Entry Criteria”| # | Criterion | Verification Command | Expected Output |
|---|---|---|---|
| 1 | Run 2 exit gate passed | bash validate-exit.sh (Run 2) | ALL CHECKS PASSED |
| 2 | Branch jmpicnic/component-consolidation is checked out | git -C /Users/jmp/code/arda/ux-prototype branch --show-current | jmpicnic/component-consolidation |
| 3 | Working tree is clean | git -C /Users/jmp/code/arda/ux-prototype status --porcelain | (empty) |
| 4 | DataGrid molecule uses themeQuartz (Run 2 deliverable) | grep -l 'themeQuartz' /Users/jmp/code/arda/ux-prototype/src/components/canary/molecules/data-grid/data-grid.tsx | File listed |
| 5 | Primitives directory exists (Run 1 deliverable) | test -d /Users/jmp/code/arda/ux-prototype/src/components/canary/primitives && echo EXISTS | EXISTS |
| 6 | Worktree is available and readable | test -f /Users/jmp/code/arda/callil-consolidation-worktree/src/components/canary/organisms/sidebar/sidebar.tsx && echo EXISTS | EXISTS |
Artifact Specifications
Section titled “Artifact Specifications”| Artifact | Path (relative to ux-prototype/src/) | Format | Description |
|---|---|---|---|
| Sidebar molecules | components/canary/molecules/sidebar/ | TSX + stories + tests | 5 sub-components: sidebar-header, sidebar-nav, sidebar-nav-item, sidebar-nav-group, sidebar-user-menu |
| Item-grid molecules | components/canary/molecules/item-grid/ | TSX + stories | Columns, fixtures, typeahead-cell-editor, select-cell-editor, drag-header |
| Item-details molecules | components/canary/molecules/item-details/ | TSX + stories + tests | item-details-header, item-details-card-preview |
| Action-toolbar molecule | components/canary/molecules/action-toolbar/ | TSX + stories + tests | Action toolbar with overflow dropdown |
| Field-list molecule | components/canary/molecules/field-list/ | TSX + stories + tests | Field list display component |
| Overflow-toolbar molecule | components/canary/molecules/overflow-toolbar/ | TSX + stories | Responsive toolbar with overflow menu |
| Sidebar organism | components/canary/organisms/sidebar/ | TSX + stories + tests + MDX | ArdaSidebar with context, provider, rail |
| App-header organism | components/canary/organisms/app-header/ | TSX + stories + tests + MDX | ArdaAppHeader with search and actions |
| Item-details organism | components/canary/organisms/item-details/ | TSX + stories + tests | ArdaItemDetails drawer with tabs |
| Item-grid organism | components/canary/organisms/item-grid/ | TSX + stories + tests + MDX | ItemGrid with editing, search, pagination |
| Assets | ../public/canary/images/, ../public/canary/ilustrationsColors/ | SVG, JPG, PNG | Brand logos, avatars, illustrations referenced by organisms |
Import Rewrite Rules
Section titled “Import Rewrite Rules”All files copied from the worktree must have their imports rewritten per these rules:
| Original import | Target import | Affected files |
|---|---|---|
@/components/ui/sidebar | @/components/canary/primitives/sidebar | organism/sidebar, mol/sidebar-header, mol/sidebar-nav, mol/sidebar-nav-item, mol/sidebar-nav-group, mol/sidebar-user-menu |
@/components/ui/dropdown-menu | @/components/canary/primitives/dropdown-menu | mol/sidebar-user-menu, mol/sidebar-header, mol/item-details-header, mol/action-toolbar, mol/overflow-toolbar |
@/components/ui/button | @/components/canary/atoms/button | organism/app-header, mol/action-toolbar, mol/overflow-toolbar |
@/components/ui/separator | @/components/canary/primitives/separator | organism/app-header |
@/components/ui/input | @/components/canary/primitives/input | organism/item-grid |
@/components/ui/tabs | @/components/canary/primitives/tabs | mol/item-details-header |
@/components/ui/collapsible | @/components/canary/primitives/collapsible | mol/sidebar-nav-group |
@/components/ui/avatar | @/components/canary/atoms/avatar | mol/sidebar-user-menu |
@/utils (cn import) | @/types/canary/utils | Any file importing cn from @/utils |
@/hooks/use-mobile | @/types/canary/hooks/use-mobile | Any file importing the use-mobile hook |
Task List
Section titled “Task List”| # | Task | Persona | Depends On | Status | Acceptance Criteria |
|---|---|---|---|---|---|
| 3.1 | Copy sidebar molecules with import rewrites | front-end-engineer | — | Pending | 5 sidebar molecule files + stories + tests + index.ts in molecules/sidebar/; all @/components/ui/* imports rewritten; npx tsc --noEmit passes |
| 3.2 | Copy item-grid molecules with import rewrites | front-end-engineer | — | Pending | item-grid-columns, item-grid-fixtures, typeahead-cell-editor, select-cell-editor, drag-header, stories in molecules/item-grid/; all imports rewritten; npx tsc --noEmit passes |
| 3.3 | Copy item-details molecules with import rewrites | front-end-engineer | — | Pending | item-details-header, item-details-card-preview + stories + tests + index.ts in molecules/item-details/; all imports rewritten; npx tsc --noEmit passes |
| 3.4 | Copy action-toolbar and field-list molecules with import rewrites | front-end-engineer | — | Pending | action-toolbar/ and field-list/ directories with all files + index.ts; all imports rewritten; npx tsc --noEmit passes |
| 3.5 | Copy overflow-toolbar molecule with import rewrites | front-end-engineer | — | Pending | overflow-toolbar.tsx + overflow-toolbar.stories.tsx in molecules/overflow-toolbar/; all imports rewritten; npx tsc --noEmit passes |
| 3.6 | Copy sidebar organism with import rewrites | front-end-engineer | 3.1 | Pending | sidebar.tsx, sidebar-context.tsx, stories, tests, MDX, index.ts in organisms/sidebar/; all imports rewritten; npx tsc --noEmit passes |
| 3.7 | Copy app-header organism with import rewrites | front-end-engineer | — | Pending | app-header.tsx, stories, tests, MDX, index.ts in organisms/app-header/; all imports rewritten; npx tsc --noEmit passes |
| 3.8 | Copy item-details organism with import rewrites | front-end-engineer | 3.3, 3.4 | Pending | item-details.tsx, stories, tests, index.ts in organisms/item-details/; all imports rewritten; npx tsc --noEmit passes |
| 3.9 | Copy item-grid organism with import rewrites | front-end-engineer | 3.2 | Pending | item-grid.tsx, use-item-grid-editing.ts, stories, tests, MDX, index.ts in organisms/item-grid/; all imports rewritten; npx tsc --noEmit passes |
| 3.10 | Copy assets from worktree public/canary/ to main clone | front-end-engineer | — | Pending | All missing assets copied; diff shows only new files added (arda-logo-*.svg, avatar-placeholder.jpg, etc.); no existing assets overwritten |
| 3.11 | Full verification gate | front-end-engineer | 3.1-3.10 | Pending | npm run lint + npx tsc --noEmit + npm run test + npm run build-storybook all pass; zero @/components/ui/* references in canary code |
| 3.12 | Playwright MCP visual verification of all organism stories | front-end-engineer | 3.11 | Pending | Navigate to each organism story in Storybook and verify rendering: sidebar (nav items, dark theme, collapse/expand), app-header (action buttons, search input), item-grid (grid renders with data, search filters), item-details (drawer opens, fields display, tabs work) |
Task Details
Section titled “Task Details”Task 3.1: Copy Sidebar Molecules
Section titled “Task 3.1: Copy Sidebar Molecules”Source: callil-consolidation-worktree/src/components/canary/molecules/sidebar/
Target: ux-prototype/src/components/canary/molecules/sidebar/
Copy all 16 files (5 components x {.tsx, .stories.tsx, .test.tsx} + index.ts):
sidebar-header.tsx,sidebar-header.stories.tsx,sidebar-header.test.tsxsidebar-nav.tsx,sidebar-nav.stories.tsx,sidebar-nav.test.tsxsidebar-nav-item.tsx,sidebar-nav-item.stories.tsx,sidebar-nav-item.test.tsxsidebar-nav-group.tsx,sidebar-nav-group.stories.tsx,sidebar-nav-group.test.tsxsidebar-user-menu.tsx,sidebar-user-menu.stories.tsx,sidebar-user-menu.test.tsxindex.ts
Import rewrites per the mapping table:
@/components/ui/sidebar->@/components/canary/primitives/sidebar@/components/ui/collapsible->@/components/canary/primitives/collapsible@/components/ui/dropdown-menu->@/components/canary/primitives/dropdown-menu@/components/ui/avatar->@/components/canary/atoms/avatar@/utils->@/types/canary/utils
Intermediate gate: npx tsc --noEmit after all sidebar molecules are in place.
Task 3.2: Copy Item-Grid Molecules
Section titled “Task 3.2: Copy Item-Grid Molecules”Source: callil-consolidation-worktree/src/components/canary/molecules/item-grid/
Target: ux-prototype/src/components/canary/molecules/item-grid/
Copy all 6 files:
item-grid-columns.tsxitem-grid-fixtures.tstypeahead-cell-editor.tsxselect-cell-editor.tsxdrag-header.tsxitem-grid-molecules.stories.tsx
Import rewrites:
@/utils->@/types/canary/utils- Any
@/components/ui/*imports per the mapping table
Intermediate gate: npx tsc --noEmit.
Task 3.3: Copy Item-Details Molecules
Section titled “Task 3.3: Copy Item-Details Molecules”Source: callil-consolidation-worktree/src/components/canary/molecules/item-details/
Target: ux-prototype/src/components/canary/molecules/item-details/
Copy all 7 files:
item-details-header.tsx,item-details-header.stories.tsx,item-details-header.test.tsxitem-details-card-preview.tsx,item-details-card-preview.stories.tsx,item-details-card-preview.test.tsxindex.ts
Import rewrites:
@/components/ui/tabs->@/components/canary/primitives/tabs@/components/ui/dropdown-menu->@/components/canary/primitives/dropdown-menu@/utils->@/types/canary/utils
Intermediate gate: npx tsc --noEmit.
Task 3.4: Copy Action-Toolbar and Field-List Molecules
Section titled “Task 3.4: Copy Action-Toolbar and Field-List Molecules”Source: callil-consolidation-worktree/src/components/canary/molecules/action-toolbar/ and field-list/
Target: ux-prototype/src/components/canary/molecules/action-toolbar/ and field-list/
Action-toolbar files (4):
action-toolbar.tsx,action-toolbar.stories.tsx,action-toolbar.test.tsx,index.ts
Field-list files (4):
field-list.tsx,field-list.stories.tsx,field-list.test.tsx,index.ts
Import rewrites:
@/components/ui/button->@/components/canary/atoms/button@/components/ui/dropdown-menu->@/components/canary/primitives/dropdown-menu@/utils->@/types/canary/utils
Intermediate gate: npx tsc --noEmit.
Task 3.5: Copy Overflow-Toolbar Molecule
Section titled “Task 3.5: Copy Overflow-Toolbar Molecule”Source: callil-consolidation-worktree/src/components/canary/molecules/overflow-toolbar/
Target: ux-prototype/src/components/canary/molecules/overflow-toolbar/
Copy 2 files:
overflow-toolbar.tsxoverflow-toolbar.stories.tsx
Import rewrites:
@/components/ui/button->@/components/canary/atoms/button@/components/ui/dropdown-menu->@/components/canary/primitives/dropdown-menu@/utils->@/types/canary/utils
Intermediate gate: npx tsc --noEmit.
Task 3.6: Copy Sidebar Organism
Section titled “Task 3.6: Copy Sidebar Organism”Source: callil-consolidation-worktree/src/components/canary/organisms/sidebar/
Target: ux-prototype/src/components/canary/organisms/sidebar/
Copy 6 files:
sidebar.tsx,sidebar-context.tsx,sidebar.stories.tsx,sidebar.test.tsx,sidebar.mdx,index.ts
Import rewrites:
@/components/ui/sidebar->@/components/canary/primitives/sidebar@/utils->@/types/canary/utils
Depends on Task 3.1 because the sidebar organism composes sidebar molecules.
Intermediate gate: npx tsc --noEmit + npm run test -- --run organisms/sidebar.
Task 3.7: Copy App-Header Organism
Section titled “Task 3.7: Copy App-Header Organism”Source: callil-consolidation-worktree/src/components/canary/organisms/app-header/
Target: ux-prototype/src/components/canary/organisms/app-header/
Copy 5 files:
app-header.tsx,app-header.stories.tsx,app-header.test.tsx,app-header.mdx,index.ts
Import rewrites:
@/components/ui/button->@/components/canary/atoms/button@/components/ui/separator->@/components/canary/primitives/separator@/utils->@/types/canary/utils
Intermediate gate: npx tsc --noEmit + npm run test -- --run organisms/app-header.
Task 3.8: Copy Item-Details Organism
Section titled “Task 3.8: Copy Item-Details Organism”Source: callil-consolidation-worktree/src/components/canary/organisms/item-details/
Target: ux-prototype/src/components/canary/organisms/item-details/
Copy 4 files:
item-details.tsx,item-details.stories.tsx,item-details.test.tsx,index.ts
Import rewrites:
- Any
@/components/ui/*imports per mapping (item-details.tsx has no direct ui imports per the analysis, but verify) @/utils->@/types/canary/utils
Depends on Tasks 3.3 and 3.4 because item-details organism composes item-details molecules, field-list, and action-toolbar.
Intermediate gate: npx tsc --noEmit + npm run test -- --run organisms/item-details.
Task 3.9: Copy Item-Grid Organism
Section titled “Task 3.9: Copy Item-Grid Organism”Source: callil-consolidation-worktree/src/components/canary/organisms/item-grid/
Target: ux-prototype/src/components/canary/organisms/item-grid/
Copy 6 files:
item-grid.tsx,use-item-grid-editing.ts,item-grid.stories.tsx,item-grid.test.tsx,item-grid.mdx,index.ts
Import rewrites:
@/components/ui/input->@/components/canary/primitives/input@/utils->@/types/canary/utils
Depends on Task 3.2 because item-grid organism composes item-grid molecules.
Intermediate gate: npx tsc --noEmit + npm run test -- --run organisms/item-grid.
Task 3.10: Copy Assets
Section titled “Task 3.10: Copy Assets”Source: callil-consolidation-worktree/public/canary/
Target: ux-prototype/public/canary/
Assets in the worktree not yet in the main clone (delta):
images/arda-logo-default.svgimages/arda-logo-inverted.svgimages/arda-logo-mono-inverted.svgimages/arda-logo-mono.svgimages/arda-logo-small-default.svgimages/arda-logo-small-inverted.svgimages/arda-logo-small-mono-inverted.svgimages/arda-logo-small-mono.svgimages/avatar-placeholder.jpg
These are referenced by the brand-logo atom and sidebar-header molecule. Copy only files that do not already exist in the main clone (do not overwrite existing assets).
Task 3.11: Full Verification Gate
Section titled “Task 3.11: Full Verification Gate”Run all checks in sequence:
npm run lint— passnpx tsc --noEmit— passnpm run test— pass (existing + new tests)npm run build-storybook— pass- Verify no
@/components/ui/*references remain in canary code:Expected: zero matches.Terminal window grep -r '@/components/ui/' src/components/canary/ --include='*.ts' --include='*.tsx' | grep -v node_modules
Task 3.12: Playwright MCP Visual Verification
Section titled “Task 3.12: Playwright MCP Visual Verification”Start Storybook (npm run dev in ux-prototype/) and use Playwright MCP to navigate to each organism’s stories:
- Sidebar: Default, WithBadges, Composition — check nav items render, dark theme applies, collapse/expand works
- AppHeader: Default, WithSearch — check action buttons visible, search input functional
- ItemGrid: Default, WithSearch, Editable — check grid renders with data, search filters rows, editable cells respond
- ItemDetails: Default — check drawer opens, fields display correctly, tabs work
Screenshot each story for visual record.
Internal Dependency Graph
Section titled “Internal Dependency Graph”3.1 (sidebar molecules) ──────────────────┐3.2 (item-grid molecules) ────────────────┤3.3 (item-details molecules) ─────────────┤3.4 (action-toolbar + field-list) ─────────┤3.5 (overflow-toolbar) ───────────────────┤3.7 (app-header organism) ────────────────┤3.10 (assets) ────────────────────────────┤ │3.1 ──→ 3.6 (sidebar organism) ──────────┤3.3, 3.4 ──→ 3.8 (item-details organism) ┤3.2 ──→ 3.9 (item-grid organism) ────────┤ │ └──→ 3.11 (verification gate) └──→ 3.12 (Playwright MCP)Tasks 3.1-3.5, 3.7, and 3.10 can run in parallel (no interdependencies). Tasks 3.6, 3.8, 3.9 depend on their respective molecule tasks. Task 3.11 waits for all copy tasks. Task 3.12 waits for the verification gate.
Exit Criteria
Section titled “Exit Criteria”| # | Criterion | Verification Command | Expected Output |
|---|---|---|---|
| 1 | Lint passes | npm run lint (in ux-prototype/) | Exit 0 |
| 2 | TypeScript compiles | npx tsc --noEmit (in ux-prototype/) | Exit 0 |
| 3 | All tests pass | npm run test (in ux-prototype/) | Exit 0, all tests pass |
| 4 | Storybook builds | npm run build-storybook (in ux-prototype/) | Exit 0 |
| 5 | No @/components/ui/* in canary code | grep -r '@/components/ui/' src/components/canary/ --include='*.ts' --include='*.tsx' | Zero matches |
| 6 | Sidebar molecules exist | test -f src/components/canary/molecules/sidebar/sidebar-header.tsx && echo EXISTS | EXISTS |
| 7 | Item-grid molecules exist | test -f src/components/canary/molecules/item-grid/item-grid-columns.tsx && echo EXISTS | EXISTS |
| 8 | Item-details molecules exist | test -f src/components/canary/molecules/item-details/item-details-header.tsx && echo EXISTS | EXISTS |
| 9 | Action-toolbar molecule exists | test -f src/components/canary/molecules/action-toolbar/action-toolbar.tsx && echo EXISTS | EXISTS |
| 10 | Field-list molecule exists | test -f src/components/canary/molecules/field-list/field-list.tsx && echo EXISTS | EXISTS |
| 11 | Overflow-toolbar molecule exists | test -f src/components/canary/molecules/overflow-toolbar/overflow-toolbar.tsx && echo EXISTS | EXISTS |
| 12 | All 4 organisms exist | ls src/components/canary/organisms/{sidebar,app-header,item-details,item-grid}/index.ts | wc -l | 4 |
| 13 | Brand logo assets copied | test -f public/canary/images/arda-logo-default.svg && echo EXISTS | EXISTS |
Agent Prompt Templates
Section titled “Agent Prompt Templates”front-end-engineer (Tasks 3.1-3.12)
Section titled “front-end-engineer (Tasks 3.1-3.12)”You are porting callil organisms and molecules from a read-only worktree into the main clone. Your job is mechanical copy + import rewrite. Do NOT change component behavior, APIs, or styling.
Copy direction: ALWAYS from worktree (/Users/jmp/code/arda/callil-consolidation-worktree/) to main clone (/Users/jmp/code/arda/ux-prototype/). The worktree is read-only — never modify it.
Import rewrite rules (apply to EVERY copied file):
@/components/ui/sidebar->@/components/canary/primitives/sidebar@/components/ui/dropdown-menu->@/components/canary/primitives/dropdown-menu@/components/ui/button->@/components/canary/atoms/button@/components/ui/separator->@/components/canary/primitives/separator@/components/ui/input->@/components/canary/primitives/input@/components/ui/tabs->@/components/canary/primitives/tabs@/components/ui/collapsible->@/components/canary/primitives/collapsible@/components/ui/avatar->@/components/canary/atoms/avatar@/utils(cn import) ->@/types/canary/utils@/hooks/use-mobile->@/types/canary/hooks/use-mobile
After copying each group, run npx tsc --noEmit as an intermediate gate. Stop and fix any import errors before proceeding.
After all copies are complete, run the full verification gate: npm run lint, npx tsc --noEmit, npm run test, npm run build-storybook.
Verify zero @/components/ui/* references remain in canary code with: grep -r '@/components/ui/' src/components/canary/ --include='*.ts' --include='*.tsx'
Implementation Output
Section titled “Implementation Output”At run completion, write the following to implementation/run-3-organism-port/:
| Artifact | File | Description |
|---|---|---|
| Run summary | summary.md | What was done, decisions made during implementation, deviations from plan |
| Byproducts log | byproducts.md | Discovered issues, TODOs, observations for later runs |
| Validation output | validation-output.txt | Stdout from validate-exit.sh execution |
| Session log | session-log.md | Agent session IDs, timestamps, notable events |
Path: documentation/src/content/docs/roadmap/backlog/requested/callil-consolidation/implementation/run-3-organism-port/
Handoff
Section titled “Handoff”Artifacts Consumed (from previous runs)
Section titled “Artifacts Consumed (from previous runs)”| Artifact | Source Run | Path/Location |
|---|---|---|
canary/primitives/ directory (13 shadcn files) | Run 1 | src/components/canary/primitives/ |
| Custom atoms (avatar, badge, button, card, dialog, etc.) | Run 1 | src/components/canary/atoms/ |
cn utility at canonical path | Run 1 | src/types/canary/utils.ts |
use-mobile hook at canonical path | Run 1 | src/types/canary/hooks/use-mobile.ts |
Updated tokens.css and globals.css | Run 1 | src/styles/ |
| DataGrid molecule with themeQuartz | Run 2 | src/components/canary/molecules/data-grid/ |
Artifacts Produced (for subsequent runs)
Section titled “Artifacts Produced (for subsequent runs)”| Artifact | Consumer Run | Path/Location |
|---|---|---|
| Sidebar molecules (5 sub-components) | Run 4+, Run 8 | src/components/canary/molecules/sidebar/ |
| Item-grid molecules (columns, fixtures, editors) | Run 4, Run 5, Run 6 | src/components/canary/molecules/item-grid/ |
| Item-details molecules (header, card-preview) | Run 8 | src/components/canary/molecules/item-details/ |
| Action-toolbar molecule | Run 8 | src/components/canary/molecules/action-toolbar/ |
| Field-list molecule | Run 8 | src/components/canary/molecules/field-list/ |
| Overflow-toolbar molecule | Run 8 | src/components/canary/molecules/overflow-toolbar/ |
| Sidebar organism | Run 8 | src/components/canary/organisms/sidebar/ |
| App-header organism | Run 8 | src/components/canary/organisms/app-header/ |
| Item-details organism | Run 8 | src/components/canary/organisms/item-details/ |
| Item-grid organism | Run 4, Run 6 | src/components/canary/organisms/item-grid/ |
select-cell-editor.tsx molecule | Run 4 (promoted to atom) | src/components/canary/molecules/item-grid/select-cell-editor.tsx |
| Brand logo assets | Run 8 | public/canary/images/arda-logo-*.svg |
Copyright: © Arda Systems 2025-2026, All rights reserved