Example: Wave Structure (Business Affiliates)

This file excerpts the wave structure and dependency graph from the Business Affiliate UX project. It serves as a concrete reference for how to decompose a medium-complexity entity feature set into parallelizable waves.

See the Implementation Plan template for the full template structure.

Dependency Graph

Wave 0 (done) --- Wave 1 (parallel, 6 stories)
       |
       +---------- Wave 2 (1 story: View Details -> builds drawer)
                        |
                        +-- Wave 3a: Create Happy Path (sequential)
                        |       |
                        +-- Wave 3b: Edit Happy Path (sequential, after 3a)
                        |
                        +-- Wave 4 (parallel, 3 stories, after Wave 3)

Wave 1 and Wave 2 are both unlocked by Wave 0, so they can begin at the same time. However, Waves 3 and 4 have a hard dependency on Wave 2 — specifically on the supplier-drawer.tsx component that Wave 2 builds. No work in Waves 3 or 4 can begin until Wave 2 is merged.

Wave Table

Wave	Stories	Agents	Worktrees	Notes
0	4	—	—	Foundation stories, pre-existing; no agent work required
1	6	5 parallel	Yes	Browse, search, filter, sort, empty state, loading state
2	1	1	No	View Details — the critical unlock; builds `supplier-drawer.tsx`
3	2	1 (sequential)	No	Create Happy Path (3a), then Edit Happy Path (3b); sequential due to shared file conflicts
4	3	3 parallel	Yes	Validation Errors, Panel Delete, and related error states

Why Wave 2 Was the Critical Unlock

Wave 2 implemented the View Details story, which built supplier-drawer.tsx — the shared drawer component that renders a Business Affiliate record in a side panel. This component was not merely one story among many; it was the structural foundation for the remaining feature work:

Wave 3a (Create Happy Path) redirects to the detail drawer after a successful creation. The drawer must exist to test the post-creation state.
Wave 3b (Edit Happy Path) opens the drawer, modifies fields inline, and saves. The drawer is the edit surface.
Wave 4 (Validation Errors, Panel Delete) tests error and delete flows that are initiated from within the drawer.

Because all three downstream waves depended on a single file (supplier-drawer.tsx) that did not exist until Wave 2 completed, Wave 2 was deliberately kept as a single-agent, single-story wave with no worktree. Keeping it small minimized the risk of merge conflicts or rework that would block the downstream waves. The lesson for future projects: identify the shared structural component early, build it as its own wave, and treat its completion as an explicit gate before downstream work begins.

Wave 3 was also kept sequential (no parallel agents) because both the Create and Edit stories write to the same wizard and form files. The risk of simultaneous edits to shared files outweighed the time savings from parallelism for a two-story wave.