Storyboard developer experience: discover, recommend, run step-by-step

[bokelley]

Summary

Storyboards should be the primary developer interface for building an AdCP agent — prescriptive before you code, evaluative as you build, and a reference for what passing looks like.

Based on analysis of 9 real production conversations with Addie where developers tried to build/test/connect agents, plus two expert reviews.

Key findings from real conversations

1. The Welcome to adcp Discussions! #1 interaction is "test this URL" — developers paste a URL and want instant feedback
2. Platform type creates confusion — Addie asks "What platform type?" which developers can't answer correctly
3. v2->v3 is the real blocker — every agent test fails on v3. Step-by-step execution would surface this at step 1
4. Developers want to understand what is being tested before running it
5. Buyer vs seller confusion — developers say "buyer agent" when they mean seller MCP server
6. No seller quickstart exists in any language

The flow: discover, recommend, run

1. Discover — paste URL, connect, discover tools (fast, non-destructive)
2. Recommend — "Your agent exposes X tools. These storyboards apply. Start with media_buy_seller?"
3. Confirm — developer picks or accepts recommendation
4. Run step-by-step — one step at a time, pass/fail with reference comparison

Implementation phases

Phase	What	Where
1	Seller quickstart in JS, Python, Go	adcp-client, adcp-client-python, adcp-go
2	Step-by-step runner endpoint + UI	this repo
3	Tool-based storyboard resolution API	this repo
4	Storyboard map UI (replace flat picker)	this repo
5	Error humanizer for validation failures	this repo
6	Addie storyboard tools (recommend, detail, run, progress)	this repo
7	Result persistence + regression notifications	this repo
8	Remove org gate for storyboard testing	this repo

[bokelley]

Progress update (April 9, 2026)

Completed

• Phase 3: Tool-based storyboard resolution — GET /registry/agents/:url/applicable-storyboards with SSRF protection and auth (feat: storyboard-first testing and creative agent schema fix #2015)
• Phase 6: Addie storyboard tools — recommend_storyboards, get_storyboard_detail, run_storyboard, run_storyboard_step (feat: storyboard-first testing and creative agent schema fix #2015)
• Deprecate platform_type as testing gate — storyboards self-select based on agent tools (feat: storyboard-first testing and creative agent schema fix #2015)
• Fix creative agent adcp_major_version rejection — replaced McpServer Zod with canonical JSON Schema (feat: storyboard-first testing and creative agent schema fix #2015)
• Delegate comply() to @adcp/client — server compliance module reduced from ~500 to ~90 lines (refactor: delegate comply() to @adcp/client #2011)
• Inline agent connect form — no more chat bounce for auth setup (feat: storyboard UX, inline agent connect, OAuth auth #1998)
• OAuth fallback in resolveOwnerAuth() — uses OAuth tokens when no static bearer exists (feat: storyboard UX, inline agent connect, OAuth auth #1998)
• Storyboard picker filtering by agent tracks — recommended vs other grouping (feat: storyboard UX, inline agent connect, OAuth auth #1998)
• Generative creative storyboard — creative_generative.yaml (feat: storyboard UX, inline agent connect, OAuth auth #1998)

Remaining

• Phase 1: Seller quickstart — issues filed: adcp-client#452 (JS), adcp-client-python#167 (Python), adcp-go#25 (Go)
• Phase 2: Step-by-step runner REST endpoint + dashboard UI — Addie tool exists but no dashboard integration
• Phase 4: Storyboard map UI — replace flat picker with grouped, progress-aware view using the new applicable-storyboards API
• Phase 5: Error humanizer — structured error output instead of raw validation dumps
• Phase 7: Result persistence + regression notifications — per-agent per-storyboard history
• Phase 8: Remove org gate for testing — let any authenticated user test without membership