Shep Workstreams

Workstream Breakdown & Parallel Execution with Shep

Turn a large, vague body of work into a small set of parallel workstreams, then execute each one as an isolated shep feature. One workstream = one feature = one worktree = one agent.

The rule this skill exists to enforce

Never tell an agent "work on all of it." That produces context loss, jumping between unrelated tasks, dozens of touched files, giant commits, and merge conflicts.

Act like a tech lead: partition first, then run one focused agent per partition.

Two phases, hard separated

PHASE 1 — PLAN            PHASE 2 — EXECUTE
(read-only, no shep       (shep feat new / start,
 mutations, produces      wave by wave, monitored)
 WORKSTREAMS.md)

Do not create a single feature until Phase 1 is written down and the user has approved it. The plan is cheap. Rework across six half-merged branches is not.

Phase 1 — Produce the workstream plan

Step 1: Read every source doc, in full

Read all the input material (PRDs, design docs, roadmap, existing specs, issue lists) before writing anything. Then inventory the deliverables — not the docs, the actual things that must exist when this is done.

Step 2: Answer the five tech-lead questions

Answer these explicitly in the plan. They are the whole point of the exercise:

1. What is on the critical path? Which deliverables block everything else, and which are genuinely independent?
2. What does the dependency graph look like? Which files and components are shared between deliverables? Which subtrees are touched by exactly one deliverable?
3. What is the right worktree split? Group deliverables into the smallest set of parallel branches that minimises merge conflicts. Estimate merge risk for each.
4. What are the integration milestones? Replace "finish V6" with contract-level checkpoints ("backend contract frozen", "design system frozen", "CRUD complete", "QA").
5. Which decisions are irreversible? What should be decided now because changing it later is expensive — and what should be deliberately delayed behind a flag?

Step 3: Partition on file ownership, not on feature semantics

This is the single highest-leverage rule, and the one most often gotten wrong:

Two deliverables that both edit the same file belong in the same workstream, no matter how unrelated they sound. Two deliverables that touch disjoint subtrees belong in different workstreams, no matter how related they sound.

For the full partitioning rubric — the foundation-first rule, ship-the-small-thing-first rule, merge-risk scoring, concurrency caps, and the common failure modes — read references/partitioning.md.

Step 4: Write WORKSTREAMS.md

Use templates/workstream-plan.md. Every workstream gets, without exception:

Then add, at the plan level: the merge order, the integration milestones, the irreversible decisions, and any work that should be pulled earlier into the current release (small, high-impact, zero-dependency items usually should be).

Step 5: Stop and get approval

Present the plan. Ask specifically about: the workstream count, the merge order, and anything recommended for pull-forward. Do not proceed to Phase 2 unapproved.

Phase 2 — Execute with the shep CLI

The mechanics that matter

Shep already does worktree-per-workstream. Do not hand-roll git worktree add.

• shep feat new "<description>" creates a branch and an isolated worktree off the repo's default branch, then spawns an agent in it.
• --pending creates the feature without spawning. shep feat start <id> spawns it later. This is how you stage waves.
• --parent <feature-id> records a real dependency. The child starts Blocked. When the parent completes — Maintain, i.e. its branch actually merged — shep automatically rebases the child's branch onto the parent's work and spawns its agent. Implementation and Review do not release the child: that code is still being rewritten, and a PR under review may never land. Only direct children unblock — a chain A → B → C cascades one link at a time, which is what you want.
• --attach <path> is repeatable. Attach the source PRDs/design docs to every feature so each agent has the context without you pasting it.

Full flag reference, monitoring commands, and the PM/work-item commands are in references/cli-reference.md. Read it before composing commands.