Feature Planning Pipeline

Generate quality plans through systematic discovery, synthesis, verification, and decomposition.

Pipeline Overview

USER REQUEST → Worktree Setup → Discovery → Synthesis → Verification → Decomposition → Validation → Track Planning → Ready Plan

Phase 0: Worktree Setup (Mandatory)

Why: Beads are tracked in git. Without worktrees, branch switching causes conflicts when PRs merge.

Always create a worktree before creating beads for a feature:

bash
1# From main repo root
2bd worktree create .worktrees/<feature-name> --branch feature/<feature-name>
3cd .worktrees/<feature-name>

This creates a redirect file so all beads operations share the main repo's .beads/ database. No merge conflicts when PR lands.

After PR merges:

bash
1cd <main-repo>
2git pull
3bd worktree remove .worktrees/<feature-name>

Skip worktree only if: Quick fix on main that won't create new beads.

Phase 1: Discovery (Parallel Exploration)

Launch parallel sub-agents to gather codebase intelligence:

Task() → Agent A: Architecture snapshot (gkg repo_map)
Task() → Agent B: Pattern search (find similar existing code)
Task() → Agent C: Constraints (package.json, tsconfig, deps)
Librarian → External patterns ("how do similar projects do this?")
exa → Library docs (if external integration needed)

Discovery Report Template

Save to history/<feature>/discovery.md:

markdown
1# Discovery Report: <Feature Name>
2
3## Architecture Snapshot
4
5- Relevant packages: ...
6- Key modules: ...
7- Entry points: ...
8
9## Existing Patterns
10
11- Similar implementation: <file> does X using Y pattern
12- Reusable utilities: ...
13- Naming conventions: ...
14
15## Technical Constraints
16
17- Node version: ...
18- Key dependencies: ...
19- Build requirements: ...
20
21## External References
22
23- Library docs: ...
24- Similar projects: ...

Phase 2: Synthesis (Oracle)

Feed Discovery Report to Oracle for gap analysis:

oracle(
  task: "Analyze gap between current codebase and feature requirements",
  context: "Discovery report attached. User wants: <feature>",
  files: ["history/<feature>/discovery.md"]
)

Oracle produces:

1. Gap Analysis - What exists vs what's needed
2. Approach Options - 1-3 strategies with tradeoffs
3. Risk Assessment - LOW / MEDIUM / HIGH per component

Risk Classification

Risk Indicators

Pattern exists in codebase? ─── YES → LOW base
                            └── NO  → MEDIUM+ base

External dependency? ─── YES → HIGH
                     └── NO  → Check blast radius

Blast radius >5 files? ─── YES → HIGH
                       └── NO  → MEDIUM

Save to history/<feature>/approach.md:

markdown
1# Approach: <Feature Name>
2
3## Gap Analysis
4
5| Component | Have | Need | Gap |
6| --------- | ---- | ---- | --- |
7| ...       | ...  | ...  | ... |
8
9## Recommended Approach
10
11<Description>
12
13### Alternative Approaches
14
151. <Option A> - Tradeoff: ...
162. <Option B> - Tradeoff: ...
17
18## Risk Map
19
20| Component   | Risk | Reason           | Verification |
21| ----------- | ---- | ---------------- | ------------ |
22| Stripe SDK  | HIGH | New external dep | Spike        |
23| User entity | LOW  | Follows existing | Proceed      |

Phase 3: Verification (Risk-Based)

For HIGH Risk Items → Create Spike Beads

Spikes are mini-plans executed via MULTI_AGENT_WORKFLOW:

bash
1bd create "Spike: <question to answer>" -t epic -p 0
2bd create "Spike: Test X" -t task --blocks <spike-epic>
3bd create "Spike: Verify Y" -t task --blocks <spike-epic>

Spike Bead Template

markdown
1# Spike: <specific question>
2
3**Time-box**: 30 minutes
4**Output location**: .spikes/<spike-id>/
5
6## Question
7
8Can we <specific technical question>?
9
10## Success Criteria
11
12- [ ] Working throwaway code exists
13- [ ] Answer documented (yes/no + details)
14- [ ] Learnings captured for main plan
15
16## On Completion
17
18Close with: `bd close <id> --reason "YES: <approach>" or "NO: <blocker>"`

Execute Spikes

Use the MULTI_AGENT_WORKFLOW:

1. bv --robot-plan to parallelize spikes
2. Task() per spike with time-box
3. Workers write to .spikes/<feature>/<spike-id>/
4. Close with learnings: bd close <id> --reason "<result>"

Aggregate Spike Results

oracle(
  task: "Synthesize spike results and update approach",
  context: "Spikes completed. Results: ...",
  files: ["history/<feature>/approach.md"]
)

Update approach.md with validated learnings.

Phase 4: Decomposition (file-beads skill)

Load the file-beads skill and create beads with embedded learnings:

bash
1skill("file-beads")

Bead Requirements

Each bead MUST include:

• Spike learnings embedded in description (if applicable)
• Reference to .spikes/ code for HIGH risk items
• Clear acceptance criteria
• File scope for track assignment

Example Bead with Learnings

markdown
1# Implement Stripe webhook handler
2
3## Context
4
5Spike bd-12 validated: Stripe SDK works with our Node version.
6See `.spikes/billing-spike/webhook-test/` for working example.
7
8## Learnings from Spike
9
10- Must use `stripe.webhooks.constructEvent()` for signature verification
11- Webhook secret stored in `STRIPE_WEBHOOK_SECRET` env var
12- Raw body required (not parsed JSON)
13
14## Acceptance Criteria
15
16- [ ] Webhook endpoint at `/api/webhooks/stripe`
17- [ ] Signature verification implemented
18- [ ] Events: `checkout.session.completed`, `invoice.paid`

Phase 5: Validation

Run bv Analysis

bash
1bv --robot-suggest   # Find missing dependencies
2bv --robot-insights  # Detect cycles, bottlenecks
3bv --robot-priority  # Validate priorities

Fix Issues

bash
1bd dep add <from> <to>      # Add missing deps
2bd dep remove <from> <to>   # Break cycles
3bd update <id> --priority X # Adjust priorities

Oracle Final Review

oracle(
  task: "Review plan completeness and clarity",
  context: "Plan ready. Check for gaps, unclear beads, missing deps.",
  files: [".beads/"]
)

Phase 6: Track Planning

This phase creates an execution-ready plan so the orchestrator can spawn workers immediately without re-analyzing beads.

Step 1: Get Parallel Tracks

bash
1bv --robot-plan 2>/dev/null | jq '.plan.tracks'

Step 2: Assign File Scopes

For each track, determine the file scope based on beads in that track:

bash
1# For each bead, check which files it touches
2bd show <bead-id>  # Look at description for file hints

Rules:

• File scopes must NOT overlap between tracks
• Use glob patterns: packages/sdk/**, apps/server/**
• If overlap unavoidable, merge into single track

Step 3: Generate Agent Names

Assign unique adjective+noun names to each track:

• BlueLake, GreenCastle, RedStone, PurpleBear, etc.
• Names are memorable identifiers, NOT role descriptions

Step 4: Create Execution Plan

Save to history/<feature>/execution-plan.md:

markdown
1# Execution Plan: <Feature Name>
2
3Epic: <epic-id>
4Generated: <date>
5
6## Tracks
7
8| Track | Agent       | Beads (in order)      | File Scope        |
9| ----- | ----------- | --------------------- | ----------------- |
10| 1     | BlueLake    | bd-10 → bd-11 → bd-12 | `packages/sdk/**` |
11| 2     | GreenCastle | bd-20 → bd-21         | `packages/cli/**` |
12| 3     | RedStone    | bd-30 → bd-31 → bd-32 | `apps/server/**`  |
13
14## Track Details
15
16### Track 1: BlueLake - <track-description>
17
18**File scope**: `packages/sdk/**`
19**Beads**:
20
211. `bd-10`: <title> - <brief description>
222. `bd-11`: <title> - <brief description>
233. `bd-12`: <title> - <brief description>
24
25### Track 2: GreenCastle - <track-description>
26
27**File scope**: `packages/cli/**`
28**Beads**:
29
301. `bd-20`: <title> - <brief description>
312. `bd-21`: <title> - <brief description>
32
33### Track 3: RedStone - <track-description>
34
35**File scope**: `apps/server/**`
36**Beads**:
37
381. `bd-30`: <title> - <brief description>
392. `bd-31`: <title> - <brief description>
403. `bd-32`: <title> - <brief description>
41
42## Cross-Track Dependencies
43
44- Track 2 can start after bd-11 (Track 1) completes
45- Track 3 has no cross-track dependencies
46
47## Key Learnings (from Spikes)
48
49Embedded in beads, but summarized here for orchestrator reference:
50
51- <learning 1>
52- <learning 2>

Validation

Before finalizing, verify:

bash
1# No cycles in the graph
2bv --robot-insights 2>/dev/null | jq '.Cycles'
3
4# All beads assigned to tracks
5bv --robot-plan 2>/dev/null | jq '.plan.unassigned'

Output Artifacts

Quick Reference

Tool Selection

Common Mistakes

• Skipping discovery → Plan misses existing patterns
• No risk assessment → Surprises during execution
• No spikes for HIGH risk → Blocked workers
• Missing learnings in beads → Workers re-discover same issues
• No bv validation → Broken dependency graph