Choreography

Execution Sequence

Order	Run	Directory	Trigger	Stories	MDX
1	Run 1: View and Fallback	run-1-view-and-fallback/	Manual (branch jmpicnic/item-image-upload-components)	10	5
2	Run 2: Input and Validation	run-2-input-and-validation/	After Run 1 exit gate passes	16	3
3	Run 3: Preview and Confirm	run-3-preview-and-confirm/	After Run 2 exit gate passes	10	3
4	Run 4: Integration	run-4-integration/	After Run 3 exit gate passes	16	6
5	Run 5: Sidebar Clean-Up	run-5-cleanup/	After Run 4 exit gate passes	0	0
	Total			52 stories	17 MDX

Stories: 47 *.stories.tsx files. MDX: 1 section + 3 use case + 13 scenario description.mdx files. Run 5 modifies preview.ts only — no new files.

Artifact Dependency Map

Artifact	Produced By	Consumed By	Path	Format
Use-case mock data	Run 1	Runs 2, 3, 4	entity-media/_shared/mock-data.ts	TypeScript
Directory structure	Run 1	Runs 2, 3, 4	entity-media/ tree	Directories
VRT baselines	Each run	Next run	VRT snapshot directory	PNG
entity-media.mdx (stub)	Run 1	Run 4 (finalized)	entity-media/entity-media.mdx	MDX
View stories	Run 1	Runs 2–4 (pattern reference)	view-entity-image/*.stories.tsx	TypeScript
Input/validation stories	Run 2	Runs 3–4 (pattern reference)	set-entity-image/input-*, formats-*, url-*	TypeScript
Preview/confirm stories	Run 3	Run 4 (pattern reference)	set-entity-image/preview-*, confirm-*	TypeScript
Set Entity Image MDX	Run 3	Run 4 (referenced by entity-media.mdx)	set-entity-image/set-entity-image.mdx	MDX

Hand-Off Protocol

All hand-offs are filesystem-only — no in-memory state is shared between runs. Each run reads its inputs from files produced by prior runs and writes its outputs to files for subsequent runs.

All runs operate in the same repository (ux-prototype) on the same branch. No worktree isolation is needed between runs (they are sequential). Within a run, story tasks can use worktree isolation for parallelism.

Between Run 1 and Run 2

1. Run 1 completes and validate-exit.sh passes.
2. Verify: 10 view stories render in Storybook, existing Item stories pass.
3. Run 2 begins — consumes _shared/mock-data.ts and directory structure.

Between Run 2 and Run 3

1. Run 2 completes and validate-exit.sh passes.
2. Verify: 16 input/validation stories render, no regressions in Run 1 stories.
3. Run 3 begins — uses Run 2 patterns for consistency.

Between Run 3 and Run 4

1. Run 3 completes and validate-exit.sh passes.
2. Verify: 10 preview/confirm stories render, Set Entity Image MDX complete.
3. Run 4 begins — all prior stories available as pattern references for end-to-end composition.

Between Run 4 and Run 5

1. Run 4 completes and validate-exit.sh passes.
2. Verify: all 47 stories + 5 MDX exist, full test runner passes.
3. Run 5 begins — reorganizes sidebar titles and preview.ts sort order. No new files; only modifications to existing story titles and configuration.

Recovery Procedures

Run N fails mid-execution

1. Check which tasks completed by reviewing git log for committed stories.
2. Identify the failing task from the wave gate output.
3. Fix the issue in the failing story file.
4. Re-run the wave gate to verify all checks pass.
5. Continue with remaining tasks.

Run N exit gate fails

1. Review the validate-exit.sh output to identify which criteria failed.
2. Common failures:
   • File count mismatch — a story was skipped or misnamed.
   • Lint failure — fix import ordering, unused variables.
   • TypeScript error — fix type mismatches against component props.
   • Storybook build failure — fix MDX formatting (bare braces, named entities, markdown tables).
   • VRT failure — evaluate diffs; retake baselines if intentional.
3. Fix and re-run the exit gate.

Run N+1 entry criteria fail

1. Return to Run N and verify its exit gate still passes.
2. If the exit gate passes but entry criteria fail, there may be a dependency gap — check the artifact paths.

Branching and Worktree Strategy

Two repositories, two branches

This project spans two repositories. Each uses a single shared branch for all 5 runs. Each run ends with checkpoint commits on both branches.

Repository	Branch	Based On	Purpose
ux-prototype	jmpicnic/uc-stories	jmpicnic/item-image-upload-components	Story files, MDX, mock data
documentation	jmpicnic/item-image-uploads	(existing branch)	Specification, plans, decision log, session logs, byproducts

ux-prototype:
  jmpicnic/item-image-upload-components  (base — all 19 image components)
    └─► jmpicnic/uc-stories  (single branch for all runs)
          ├── <Run 1 commits> ── checkpoint: "Run 1 complete — view/fallback stories"
          ├── <Run 2 commits> ── checkpoint: "Run 2 complete — input/validation stories"
          ├── <Run 3 commits> ── checkpoint: "Run 3 complete — preview/confirm stories"
          ├── <Run 4 commits> ── checkpoint: "Run 4 complete — integration stories"
          └── <Run 5 commits> ── checkpoint: "Run 5 complete — sidebar reorder"

documentation:
  jmpicnic/item-image-uploads  (existing branch — spec, plans, decisions)
          ├── <Run 1 docs> ── checkpoint: "Run 1 docs — session log, decisions"
          ├── <Run 2 docs> ── checkpoint: "Run 2 docs — session log, decisions"
          ├── ...
          └── <Run 5 docs> ── checkpoint: "Run 5 docs — session log, decisions"

At project end: two PRs referencing each other.

• ux-prototype: PR jmpicnic/uc-stories → main
• documentation: PR jmpicnic/item-image-uploads → main

Worktree layout

arda/
├── ux-prototype/                             # Main checkout (untouched)
├── documentation/                            # Main checkout (untouched)
│
├── uc-stories-worktrees/                     # ux-prototype worktrees
│   ├── main/                                 # Primary worktree on jmpicnic/uc-stories
│   │                                         #   — coordinator works here
│   │                                         #   — exit gate runs here
│   │                                         #   — checkpoint commits happen here
│   ├── fe-1/                                 # Ephemeral agent worktree (parallel tasks)
│   ├── fe-2/                                 # Created per run, cleaned up after
│   └── fe-N/                                 # As many as needed
│
└── uc-stories-docs-worktree/                 # documentation worktree (single)
    └── main/                                 # On branch jmpicnic/item-image-uploads
                                              #   — session logs, decisions, spec updates
                                              #   — checkpoint commits after each run

Implementation output directory

All run outputs in the documentation repo go under:

documentation/src/content/docs/roadmap/completed/item-image-upload/
├── decision-log.md                           # Accumulates UD-* decisions across runs
└── ux-design/use-cases/
    ├── specification.md                      # Updated if scope changes during implementation
    ├── plan/                                 # Run plans (read-only during execution)
    └── implementation/                       # Run outputs and byproducts
        ├── run-1-view-and-fallback/
        │   ├── session-log.md
        │   └── byproducts/
        ├── run-2-input-and-validation/
        │   ├── session-log.md
        │   └── byproducts/
        ├── run-3-preview-and-confirm/
        │   ├── session-log.md
        │   └── byproducts/
        ├── run-4-integration/
        │   ├── session-log.md
        │   └── byproducts/
        └── run-5-cleanup/
            ├── session-log.md
            └── byproducts/

Lifecycle per run

1. Entry check: Coordinator verifies branch is up-to-date with base (origin/jmpicnic/item-image-upload-components is an ancestor of HEAD).
2. Coordinator starts on uc-stories-worktrees/main/ (branch jmpicnic/uc-stories).
3. For parallel story tasks, creates ephemeral worktrees (fe-1, fe-2, …) branching from jmpicnic/uc-stories.
4. As each agent completes, its branch merges back into jmpicnic/uc-stories on main/ — one at a time with checks between merges.
5. Pre-gate artifact checks run on main/.
6. Rebase onto base branch: git fetch origin jmpicnic/item-image-upload-components && git rebase origin/jmpicnic/item-image-upload-components. This picks up any changes from parallel sessions (including the ImageCellEditor fix). Resolve conflicts if any.
7. Post-rebase checks: Re-run lint, tsc, build, test, VRT after rebase.
8. ux-prototype checkpoint commit: Run N complete — <summary>.
9. Ephemeral worktrees cleaned up.
10. Coordinator switches to uc-stories-docs-worktree/main/ (branch jmpicnic/item-image-uploads).
11. Writes implementation/run-N-*/session-log.md, updates decision-log.md with any new decisions, updates specification.md if scope changed.
12. documentation checkpoint commit: Run N docs — session log, decisions.
13. Next run starts back on uc-stories-worktrees/main/ (step 1).

Recovery

To revert an entire run: git reset --hard <previous checkpoint commit> on both branches. The checkpoint commits provide clean rollback points in each repo independently.

Launch Commands

Run	Command
1	/launch-team documentation/src/content/docs/roadmap/completed/item-image-upload/ux-design/use-cases/plan/run-1-view-and-fallback
2	/launch-team documentation/src/content/docs/roadmap/completed/item-image-upload/ux-design/use-cases/plan/run-2-input-and-validation
3	/launch-team documentation/src/content/docs/roadmap/completed/item-image-upload/ux-design/use-cases/plan/run-3-preview-and-confirm
4	/launch-team documentation/src/content/docs/roadmap/completed/item-image-upload/ux-design/use-cases/plan/run-4-integration
5	/launch-team documentation/src/content/docs/roadmap/completed/item-image-upload/ux-design/use-cases/plan/run-5-cleanup