Run 1: Foundation

Entry Criteria

#	Criterion	Verification Command	Expected Output
1	Branch jmpicnic/component-consolidation exists and is current	git -C /Users/jmp/code/arda/ux-prototype branch --show-current	jmpicnic/component-consolidation
2	Working tree is clean	git -C /Users/jmp/code/arda/ux-prototype status --porcelain | wc -l | tr -d ' '	0
3	Baseline tests pass	npm run test --prefix /Users/jmp/code/arda/ux-prototype > /dev/null 2>&1 && echo PASS	PASS
4	Worktree available for reference	test -d /Users/jmp/code/arda/callil-consolidation-worktree/src/components/ui && echo EXISTS	EXISTS
5	Run 0 exit gate passed	bash run-0-branch-setup/validate-exit.sh	ALL CHECKS PASSED

Artifact Specifications

Artifact	Path	Format	Description
Updated tokens.css	ux-prototype/src/styles/tokens.css	CSS	Arda orange palette, new tokens (control heights, state ramp, font vars, destructive-foreground, dark mode)
Refactored globals.css	ux-prototype/src/styles/globals.css	CSS	@import './tokens.css', worktree version (Arda orange, Geist Mono, touch media queries), no legacy sidebar CSS, no duplicate :root
Primitives directory	ux-prototype/src/components/canary/primitives/	TSX	13 stock shadcn files with cn imports rewritten to @/types/canary/utils
Custom atoms	ux-prototype/src/components/canary/atoms/	TSX	6 custom components + existing callil atoms (brand-logo, drawer, icon-button, icon-label, read-only-field, search-input) with stories and tests
Hook migration	ux-prototype/src/types/canary/hooks/use-mobile.ts	TS	use-mobile hook from worktree
Canonical cn imports	38+ files across ux-prototype/src/	TS imports	All @/utils imports rewritten to @/types/canary/utils
Primitives import check story	ux-prototype/src/components/canary/primitives/primitives.stories.tsx	TSX	Integration story importing from several primitives

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
1.1	Styles and Tokens	front-end-engineer	—	Pending	tokens.css has Arda orange palette + new tokens; globals.css imports tokens.css via @import; no legacy sidebar CSS; no duplicate :root; intermediate gate passes (npx tsc --noEmit + npm run test)
1.2	Primitives Directory	front-end-engineer	1.1	Pending	canary/primitives/ contains 13 stock shadcn files; all cn imports use @/types/canary/utils; NO sonner.tsx; intermediate gate passes (npx tsc --noEmit)
1.3	Custom Atoms	front-end-engineer	1.2	Pending	6 custom components + callil atoms in canary/atoms/; all cn imports canonical; all @/components/ui/* imports rewritten to @/components/canary/primitives/*; intermediate gate passes (npx tsc --noEmit + npm run test)
1.4	Hook Migration	front-end-engineer	1.3	Pending	use-mobile.ts at src/types/canary/hooks/use-mobile.ts; old import path @/hooks/use-mobile updated; intermediate gate passes (npx tsc --noEmit)
1.5	cn Import Rewrite	front-end-engineer	1.4	Pending	38+ files rewritten from @/utils to @/types/canary/utils; src/utils.ts not needed if no other exports; full gate passes (npx tsc --noEmit + npm run lint + npm run test)
1.6	Primitives Import Check Story	front-end-engineer	1.5	Pending	primitives.stories.tsx renders composed example from several primitives; npm run build-storybook passes; Playwright MCP verification of story rendering

Task Details

Task 1.1: Styles and Tokens

Working directory: /Users/jmp/code/arda/ux-prototype Reference directory: /Users/jmp/code/arda/callil-consolidation-worktree Governs: analysis/styles.md

Steps:

1. Read worktree src/styles/tokens.css and main clone src/styles/tokens.css. Merge: take all Arda orange values from worktree, add new tokens (control heights, state ramp, font vars, --destructive-foreground, dark mode overrides).
2. Refactor main clone src/styles/globals.css: add @import './tokens.css' at top, remove all CSS custom property declarations that duplicate tokens.css values.
3. Replace remaining globals.css content with worktree version: Arda orange palette references, Geist Mono font, touch media queries, sidebar-inset dark override.
4. Drop legacy sidebar CSS: .sidebar-menu-button-hover, [data-active='true'], .add-company-button.
5. Drop duplicate :root block.

Intermediate gate (1.1): npx tsc --noEmit + npm run test

Task 1.2: Primitives Directory

Working directory: /Users/jmp/code/arda/ux-prototype Reference directory: /Users/jmp/code/arda/callil-consolidation-worktree

Steps:

1. Create directory src/components/canary/primitives/.
2. Copy 13 stock shadcn files from worktree src/components/ui/: collapsible, dropdown-menu, input, label, separator, sheet, sidebar, skeleton, table, tabs, textarea, toggle, tooltip.
3. Rewrite cn imports in all copied primitives from @/utils to @/types/canary/utils.
4. Do NOT copy sonner.tsx (dropped per styles.md decision).
5. Create index.ts barrel if needed for internal re-exports.

Intermediate gate (1.2): npx tsc --noEmit

Task 1.3: Custom Atoms

Working directory: /Users/jmp/code/arda/ux-prototype Reference directory: /Users/jmp/code/arda/callil-consolidation-worktree

Steps:

1. Copy custom components from worktree src/components/ui/ to src/components/canary/atoms/:
   • avatar.tsx -> atoms/avatar/
   • badge.tsx -> atoms/badge/ (merge with existing callil ArdaBadge wrapper)
   • button.tsx -> atoms/button/ (merge with existing callil ArdaButton wrapper)
   • card.tsx -> atoms/card/
   • dialog.tsx -> atoms/dialog/
   • input-group.tsx -> atoms/input-group/
2. Copy existing callil canary atoms from worktree: brand-logo, drawer, icon-button, icon-label, read-only-field, search-input (with their stories and tests).
3. Rewrite cn imports from @/utils to @/types/canary/utils.
4. Rewrite @/components/ui/* imports to @/components/canary/primitives/*.

Intermediate gate (1.3): npx tsc --noEmit + npm run test

Task 1.4: Hook Migration

Working directory: /Users/jmp/code/arda/ux-prototype Reference directory: /Users/jmp/code/arda/callil-consolidation-worktree

Steps:

1. Copy src/hooks/use-mobile.ts from worktree to src/types/canary/hooks/use-mobile.ts.
2. Create src/types/canary/hooks/ directory if it does not exist.
3. Update any imports referencing @/hooks/use-mobile to @/types/canary/hooks/use-mobile.

Intermediate gate (1.4): npx tsc --noEmit

Task 1.5: cn Import Rewrite

Working directory: /Users/jmp/code/arda/ux-prototype

This is the highest-risk task in Run 1 due to the broadest file change set (38+ files).

Steps:

1. Find all files importing cn from @/utils: grep -r "from '@/utils'" src/ --include='*.ts' --include='*.tsx' -l.
2. Rewrite each import to from '@/types/canary/utils'.
3. Verify src/utils.ts has no other exports besides cn. If it only exports cn, it is no longer needed (but do not delete yet — Run 7 handles cleanup).
4. Run the full gate: npx tsc --noEmit + npm run lint + npm run test.

Intermediate gate (1.5): Full gate — npx tsc --noEmit + npm run lint + npm run test. Run this gate before 1.6 so cn issues are debugged in isolation.

Task 1.6: Primitives Import Check Story

Working directory: /Users/jmp/code/arda/ux-prototype

Steps:

1. Create src/components/canary/primitives/primitives.stories.tsx.
2. Import from several primitives (e.g., Input, Label, Tabs, Separator, Tooltip) and render a composed example.
3. Run npm run build-storybook to verify Storybook can index and build with the new structure.
4. [Playwright MCP] Navigate to the primitives import check story and verify components render.

Intermediate gate (1.6): npm run build-storybook

Internal Dependency Graph

1.1 (styles/tokens) --> 1.2 (primitives) --> 1.3 (custom atoms) --> 1.4 (hooks) --> 1.5 (cn rewrite) --> 1.6 (import check story)

Strictly sequential. Each task has an intermediate blocking gate. If a gate fails, stop and fix before proceeding.

Rationale for sequencing:

• 1.1 first: tokens/globals changes could break any component referencing CSS vars.
• 1.2 after 1.1: primitives need the updated cn utility path pattern established in 1.1’s verification.
• 1.3 after 1.2: atoms import from primitives, so primitives must exist first.
• 1.4 after 1.3: small task, sequenced here to keep the dependency chain clean.
• 1.5 after 1.4: the broadest change (38+ files). Isolated after all directory moves so the grep/rewrite targets are stable.
• 1.6 after 1.5: integration verification story; must come after all imports are canonical.

Exit Criteria

#	Criterion	Verification Command	Expected Output
1	Lint passes	npm run lint --prefix /Users/jmp/code/arda/ux-prototype	Exit 0
2	TypeScript compiles	npx tsc --noEmit --prefix /Users/jmp/code/arda/ux-prototype	Exit 0
3	Tests pass	npm run test --prefix /Users/jmp/code/arda/ux-prototype	Exit 0
4	Storybook builds	npm run build-storybook --prefix /Users/jmp/code/arda/ux-prototype	Exit 0
5	No @/components/ui/ imports remain in canary code	grep -r "from '@/components/ui/" /Users/jmp/code/arda/ux-prototype/src/components/canary/ | wc -l | tr -d ' '	0
6	No @/utils imports remain (except vendored)	grep -r "from '@/utils'" /Users/jmp/code/arda/ux-prototype/src/ --include='*.ts' --include='*.tsx' | grep -v '/vendored/' | grep -v '/extras/' | wc -l | tr -d ' '	0
7	Primitives directory exists with 13+ files	ls /Users/jmp/code/arda/ux-prototype/src/components/canary/primitives/*.tsx | wc -l | tr -d ' '	13 or more
8	use-mobile.ts exists at canonical path	test -f /Users/jmp/code/arda/ux-prototype/src/types/canary/hooks/use-mobile.ts && echo EXISTS	EXISTS
9	Primitives import check story exists	test -f /Users/jmp/code/arda/ux-prototype/src/components/canary/primitives/primitives.stories.tsx && echo EXISTS	EXISTS

Agent Prompt Templates

Front End Engineer — fe-foundation

You are executing Run 1 (Foundation) of the Callil Consolidation project. Your working directory is /Users/jmp/code/arda/ux-prototype on branch jmpicnic/component-consolidation. The worktree at /Users/jmp/code/arda/callil-consolidation-worktree is your read-only reference for file contents to copy and adapt.

Tasks (strictly sequential with intermediate blocking gates):

1. Task 1.1 — Styles and Tokens: Update tokens.css to Arda orange palette, refactor globals.css to import tokens.css, drop legacy sidebar CSS, drop duplicate :root. Gate: npx tsc --noEmit + npm run test.
2. Task 1.2 — Primitives Directory: Create canary/primitives/, copy 13 stock shadcn files from worktree, rewrite cn imports. Do NOT copy sonner.tsx. Gate: npx tsc --noEmit.
3. Task 1.3 — Custom Atoms: Copy 6 custom components + callil atoms to canary/atoms/, rewrite imports. Gate: npx tsc --noEmit + npm run test.
4. Task 1.4 — Hook Migration: Copy use-mobile.ts to types/canary/hooks/, update imports. Gate: npx tsc --noEmit.
5. Task 1.5 — cn Import Rewrite: Rewrite 38+ files from @/utils to @/types/canary/utils. Full gate: npx tsc --noEmit + npm run lint + npm run test.
6. Task 1.6 — Primitives Import Check Story: Add integration story, verify build-storybook passes, Playwright MCP verification.

Critical rules:

• If an intermediate gate fails, STOP and fix before proceeding to the next task.
• Use absolute paths for all tool calls.
• Read analysis documents for decisions: analysis/styles.md (task 1.1), analysis/primitives.md (tasks 1.2-1.3).
• The cn canonical import path is @/types/canary/utils (NOT @/utils).
• Commit after each task with a descriptive message.

Reference paths:

• Analysis docs: /Users/jmp/code/arda/documentation/src/content/docs/roadmap/backlog/requested/callil-consolidation/analysis/
• Worktree source: /Users/jmp/code/arda/callil-consolidation-worktree/src/
• Main clone target: /Users/jmp/code/arda/ux-prototype/src/

Personas Required

Persona	Tasks Assigned	Working Directory	Spawn Order	Agent Name
front-end-engineer	1.1, 1.2, 1.3, 1.4, 1.5, 1.6	/Users/jmp/code/arda/ux-prototype	1	fe-foundation

All agents use mode: "bypassPermissions".

Worktree Strategy

Worktrees are NOT needed for Run 1. Single agent working sequentially on the same branch. The pre-existing worktree at /Users/jmp/code/arda/callil-consolidation-worktree/ is a read-only reference for copying files — it is not created, modified, or managed by this run.

Implementation Output

At run completion, write the following to implementation/run-1-foundation/:

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-1-foundation/

Handoff

Artifacts Consumed (from previous runs)

Artifact	Source Run	Path
Branch jmpicnic/component-consolidation	Run 0	ux-prototype repo, local branch
Baseline green verification	Run 0	validate-exit.sh pass

Artifacts Produced (for subsequent runs)

Artifact	Consumer Run	Path
Updated tokens.css with Arda orange palette	Run 2 (theme migration)	ux-prototype/src/styles/tokens.css
Refactored globals.css	Run 2, Run 3	ux-prototype/src/styles/globals.css
canary/primitives/ directory (13 files)	Run 3 (organism import rewrites)	ux-prototype/src/components/canary/primitives/
Expanded canary/atoms/ directory	Run 3 (organism imports), Run 4 (editor promotion)	ux-prototype/src/components/canary/atoms/
use-mobile.ts at canonical path	Run 3 (sidebar organism)	ux-prototype/src/types/canary/hooks/use-mobile.ts
Canonical cn imports (38+ files)	All subsequent runs	@/types/canary/utils across codebase
Primitives import check story	Run 2 (Storybook verification)	ux-prototype/src/components/canary/primitives/primitives.stories.tsx