Choreography: Image Upload Components

Worktree Setup

Setup before Run 1:

# Ensure main is up-to-date
git -C /Users/jmp/code/arda/ux-prototype fetch origin
git -C /Users/jmp/code/arda/ux-prototype checkout main
git -C /Users/jmp/code/arda/ux-prototype pull origin main

# Create base branch off main
git -C /Users/jmp/code/arda/ux-prototype branch jmpicnic/item-image-upload-components

# Create worktree for Run 1
git -C /Users/jmp/code/arda/ux-prototype worktree add \
  /Users/jmp/code/arda/image-components-worktrees/run-1 \
  jmpicnic/item-image-upload-components

For runs with parallel agents (e.g., Run 2), create one worktree per task branch:

# Create task branches off the base branch
git -C /Users/jmp/code/arda/ux-prototype branch \
  jmpicnic/item-image-upload-components/image-display \
  jmpicnic/item-image-upload-components

# Create worktree for parallel agent
git -C /Users/jmp/code/arda/ux-prototype worktree add \
  /Users/jmp/code/arda/image-components-worktrees/run-2-display \
  jmpicnic/item-image-upload-components/image-display

At the end of each wave, merge task branches back into the base branch and validate the gate.

Execution Sequence

Order	Run	Directory	Trigger	Wave
1	Run 1: Infrastructure	`run-1-infrastructure/`	Manual (after worktree setup)	0a + 0b
2	Run 2: Foundation	`run-2-foundation/`	After Run 1 exit gate passes	1
3	Run 3: Composition	`run-3-composition/`	After Run 2 exit gate passes	2
4	Run 4: Grid + Organism	`run-4-grid-organism/`	After Run 3 exit gate passes	3 + 4

Artifact Dependency Map

Artifact	Produced By	Consumed By	Path	Format
Utilities directory + barrel	Run 1	Runs 2-4	`src/types/canary/utilities/`	TypeScript
ImageFieldConfig types	Run 1	Runs 2-4	`src/types/canary/utilities/image-field-config.ts`	TypeScript
getInitials utility	Run 1	Run 2 (ImageDisplay, Avatar)	`src/types/canary/utilities/get-initials.ts`	TypeScript
getCroppedImage utility	Run 1	Run 4 (ImageUploadDialog)	`src/types/canary/utilities/get-cropped-image.ts`	TypeScript
ShadCN primitives (6)	Run 1	Runs 2-4	`src/components/canary/primitives/`	TSX
Badge error-overlay variant	Run 1	Run 2 (ImageDisplay)	`src/components/canary/atoms/badge/badge-base.tsx`	TSX
Mock data module	Run 1	Runs 2-4	`src/components/canary/__mocks__/image-story-data.ts`	TypeScript
ImageDisplay molecule	Run 2	Run 3 (HoverPreview, Comparison, FormField), Run 4 (CellDisplay)	`src/components/canary/molecules/image-display/`	TSX
ImageDropZone molecule	Run 2	Run 4 (ImageUploadDialog)	`src/components/canary/molecules/image-drop-zone/`	TSX
ImagePreviewEditor molecule	Run 2	Run 4 (ImageUploadDialog)	`src/components/canary/molecules/image-preview-editor/`	TSX
CopyrightAcknowledgment atom	Run 2	Run 4 (ImageUploadDialog)	`src/components/canary/atoms/copyright-acknowledgment/`	TSX
ImageHoverPreview molecule	Run 3	Run 4 (ImageCellDisplay)	`src/components/canary/molecules/image-hover-preview/`	TSX
ImageComparisonLayout molecule	Run 3	Run 4 (ImageUploadDialog)	`src/components/canary/molecules/image-comparison-layout/`	TSX
ImageFormField molecule	Run 3	Run 4 (barrel exports)	`src/components/canary/molecules/form/image/`	TSX
ImageInspectorOverlay molecule	Run 3	Run 4 (barrel exports)	`src/components/canary/molecules/image-inspector-overlay/`	TSX

Hand-Off Protocol

All hand-offs are filesystem-only — no in-memory state is shared between runs. Each run reads committed code from prior runs.

Between Any Two Consecutive Runs

Current run completes all tasks and commits locally.
validate-exit.sh for the current run passes.
Next run’s entry criteria are checked (reference prior run outputs).
Next run is launched.

Between Run 4 and PR

Run 4 exit gate passes.
Final review of all stories in Storybook (manual).
Push branch to origin: git push -u origin jmpicnic/item-image-upload-components
Create PR against main.

Recovery Procedures

Run N fails mid-execution

Check which tasks completed (review git log in worktree).
Fix the failing task.
Re-run the remaining tasks.
Run validate-exit.sh to confirm.

Run N exit gate fails

Read the validation output to identify which criteria failed.
Fix the issues in the worktree.
Commit the fixes.
Re-run validate-exit.sh.

Run N+1 entry criteria fail

This means Run N produced incomplete outputs.
Return to Run N, fix the missing artifacts.
Re-validate Run N exit, then retry Run N+1 entry.

Worktree Cleanup

After each wave gate: remove that wave’s worktrees and task branches.

After the final PR is merged:

# Remove any remaining worktrees
git -C /Users/jmp/code/arda/ux-prototype worktree prune

# Remove parent directory
rm -rf /Users/jmp/code/arda/image-components-worktrees

Launch Commands

Run	Worktree(s)	Notes
1	`image-components-worktrees/run-1`	Single worktree, sequential tasks
2	`image-components-worktrees/run-2-*` (up to 3)	Parallel agents per component; merge to base branch at end
3	`image-components-worktrees/run-3-*` (up to 3)	3 parallel + 1 sequential (FormField after HoverPreview)
4	`image-components-worktrees/run-4`	Single worktree; critical path on ImageUploadDialog