Choreography: Agentation-Hypothesis Bridge

Execution Sequence

Order	Run	Directory	Trigger	Estimated Duration
1	Run 1: hypothesis-mcp Extension	run-1-hypothesis-mcp/	Manual	0.5 day
2	Run 2: ux-prototype Bridge & Highlights	run-2-ux-prototype/	Manual (can start in parallel with Run 1)	4.5 days

Key insight: Run 1 and Run 2 can execute concurrently. They operate on different repositories with no shared state. Run 2 calls the Hypothesis REST API directly (not the MCP), so it does not require Run 1’s output. The CssSelector in the target field is a progressive enhancement that Run 2 includes unconditionally (the Hypothesis API accepts arbitrary selectors regardless of whether the MCP supports them).

Artifact Dependency Map

Artifact	Produced By	Consumed By	Path	Format
Extended createAnnotation with target param	Run 1	Future MCP callers (not Run 2 directly)	/hypothesis-mcp/src/client.ts	TypeScript
Merged hypothesis-mcp PR	Run 1	None (standalone)	Arda-cards/hypothesis-mcp repo	Git PR
Bridge module (proxy, transform, client)	Run 2	Run 2 highlight layer	.storybook/addons/hypothesis-bridge/	TypeScript
Highlight decorator	Run 2	Storybook preview	.storybook/preview.ts	TypeScript
Hypothesis sidebar embed	Run 2	Storybook preview iframe	.storybook/preview-body.html	HTML

Hand-Off Protocol

Since the two runs are independent and can execute in parallel, the hand-off is minimal:

Between Run 1 and Run 2

No blocking dependency. Run 2 can start immediately without waiting for Run 1.

If Run 1 completes first and its PR is merged, Run 2’s transform module can optionally be enhanced to verify the MCP tool also supports the target parameter. This is a nice-to-have, not a requirement.

Post-Completion

After both runs complete:

1. Run 1: PR is created, reviewed, and merged into hypothesis-mcp/main. CHANGELOG is updated with v1.3.0.

2. Run 2: All code is on the working branch in the worktree. The user decides next steps (PR creation, merge into base branch, etc.).

3. Worktree cleanup: After user approval, remove the ux-prototype worktree:

   git -C /Users/jmp/code/arda/ux-prototype worktree remove \
     /Users/jmp/code/arda/integrate-hypothesis-worktrees/ux-prototype

Recovery Procedures

Run 1 fails mid-execution

The hypothesis-mcp changes are small (3 files). If the agent fails:

1. Check the working branch state: git -C /Users/jmp/code/arda/hypothesis-mcp log --oneline -5
2. If partially committed, continue from where it stopped.
3. If uncommitted, review the diff and manually complete the remaining tasks.

Run 1 PR has review comments

Per user guidance:

1. Wait 10 minutes after PR creation.
2. Check for failures and reviewer comments.
3. Present the user with a numbered table summarizing each comment and the agent’s recommendation.
4. Fix comments the user approves.
5. Reply to all comments and resolve threads.

Run 2 fails mid-execution

1. The worktree preserves all state. Check: git -C /Users/jmp/code/arda/integrate-hypothesis-worktrees/ux-prototype status
2. Run validation: bash plan/run-2-ux-prototype/validate-exit.sh
3. Identify which exit criteria fail and resume from the corresponding task.

Run 2 Storybook build fails

Most likely cause: TypeScript errors in new files or import path issues.

1. Run npx tsc --noEmit for detailed error output.
2. Fix type errors.
3. Re-run npx storybook build.

Storybook middleware.ts not supported in Storybook 10

Fallback approach:

1. Move proxy logic into a Vite plugin in .storybook/main.ts viteFinal.
2. Use Vite’s configureServer hook to add the proxy routes.

Launch Commands

Run	Command
1	Launch back-end-engineer agent with Run 1 prompt template
2	Launch front-end-engineer agent with Run 2 prompt template

Both can be launched simultaneously in a single message with parallel Agent tool calls.