Parcel Plan

Parcel Plan

Bundled with rookery and works against any rookery project — the parcel format and worktree layout are documented in rookery's README, and this skill pairs naturally with rookery-daemon (the orchestrator daemon) and the rest of the parcel-* family. It was originally extracted from the Axiom build but is no longer Axiom-specific.

The upstream companion to parcel-generate. Where parcel-generate takes a ready-made parcel breakdown and writes the prompt files, this skill takes a raw spec and produces the breakdown.

Output is a ranked list of candidate parcels, each with enough structure that parcel-generate can take it directly.

When to use

• A new wave is being planned and the spec (PROJECT.md, WAVE3_PLAN.md, ROADMAP.md, etc.) needs to be turned into parcelable units
• An existing wave needs rebalancing (e.g. a parcel is too big and must be split, or two parcels share files and must be merged)
• Mid-build, a gap surfaces and you need to scope a follow-up G-parcel (gap-fill) or I-parcel (integration)
• Cross-checking an existing parcel list against the spec to find missing coverage

When NOT to use

• The spec is too fluid to plan against — stabilise it first
• You have a clear parcel list already and just need the prompt files — use parcel-generate directly
• You want merge-order for in-flight parcels — use wave-triage
• The work is inherently sequential (serial parcels like P0 bootstrap, P12 integration) — document as an interactive step, not a parcel

Workflow

Step 1 — Read the source spec

Identify the canonical source. Common spec inputs in priority order (illustrative — adapt to the project's actual doc layout):

• docs/WAVE<N>_PLAN.md — if it exists, its §2 parcel table is often 80% of the answer and only needs gap-filling
• docs/BUILD_PLAN.md — phase-level structure; parcels live within phases
• docs/PARCELS.md — any previous wave's parcels (reference patterns, ownership tables)
• docs/ROLES.md, docs/ARCHITECTURE.md — if no wave plan exists, the architecture doc implies decomposition via its module boundaries

Read the spec in full. Do not skim — parcel boundaries live in sentences like "owns X", "depends on Y", "must not touch Z".

Step 2 — Extract candidate parcel units

A candidate parcel is a unit of work that:

1. Has an owner directory or module — concrete scope boundary (e.g. src/<pkg>/bus/, docs/admin/)
2. Has a measurable done criterion — tests green, a CLI command works, a file exists
3. Fits in 2–4 hours of wall-clock — larger → split; smaller → merge
4. Has at most 2 upstream dependencies — more than that is a sign the decomposition is wrong

For each candidate, capture:

Step 3 — Detect and fix scope collisions

Two parcels must not write to the same file. For every pair (A, B) in the candidate list, cross-reference their scope columns. If overlap exists:

• Same file, different concerns → one parcel becomes a dep of the other; sequence them
• Same directory, non-overlapping files → split the directory into sub-scopes (e.g. "A owns foo/api.py, B owns foo/models.py")
• Same file, same concern → merge A and B into one parcel

Flag unresolvable collisions and stop — a plan with overlap guarantees merge hell.

Step 4 — Compute the dependency DAG

Construct the DAG from the deps columns. Detect and report:

• Cycles — unrecoverable; a parcel cannot depend on its transitive output. Fix the decomposition.
• Orphans — parcels no downstream parcel consumes; verify intentional (often the demo / submission / polish parcels sit here)
• Bottlenecks — parcels with ≥3 downstream dependents; these are critical-path and deserve extra budget

Step 5 — Assign to waves

Greedy algorithm:

1. Wave 1 = all parcels with no deps
2. Wave N+1 = all parcels whose deps are fully satisfied by waves ≤ N
3. Repeat until all parcels are assigned

If a wave exceeds ~8 parcels, consider splitting along scope lines (e.g. infra parcels first, role parcels second) to keep the launch operator's mental model manageable.

Step 6 — Emit the plan

Produce a structured report:

## Plan summary

GOAL: <one-line restatement of the wave's goal>
SPEC: <resolved path>
WAVES: <N>
PARCELS: <M>
CRITICAL-PATH: <ordered list of parcel IDs>
EST-WALL-CLOCK: <hours>, assuming <K>-parallel
DETECTED-COLLISIONS: <list or "none">
ORPHANS: <list or "none">

## Parcels

### Wave 1

| ID | Name | Scope | Deps | Est | Parallel-safe |
|---|---|---|---|---|---|
| ... | ... | ... | — | 2h | all wave-1 |

### Wave 2
...

## Open questions (for Planning lane to resolve before parcel-generate runs)

- <any ambiguity in the spec that prevents unambiguous parcel authoring>

Step 7 — Hand-off

The output of this skill is the direct input to parcel-generate Step 1–2. Downstream operator runs parcel-generate to turn each row into a committed parcels/<id>.md prompt file.

Do not author the prompt files yourself — that is parcel-generate's remit. Do not launch sessions — that is dsp-launch or rookery (the queue-based dispatcher).

Hard rules

Anti-patterns

See also

• parcel-generate — consumes this skill's output; writes the prompt files
• wave-triage — evaluates gate status and merge order for in-flight waves this skill produced
• parcel-roster — inventories what was actually built vs what this skill planned
• The project repo root's spec docs (e.g. docs/BUILD_PLAN.md, docs/WAVE<N>_PLAN.md) — primary spec inputs