--- name: parcel-plan description: "Decompose a spec document (architecture, roadmap, wave plan) into a ranked list of candidate parcels ready for parcel-generate. Given a goal and a spec, produce parcel IDs with scope, dependencies, estimated duration, and parallel-safe groupings — the upstream half of the parcel-generate pipeline. Triggers on: plan parcels, decompose spec, parcel breakdown, wave plan, parcel sequencing, what parcels do we need, spec to parcels, parcel decomposition, fleet wave plan." allowed-tools: "Read, Glob, Grep" --- # 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_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//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: | Facet | Extracted from | |---|---| | ID | Convention: letter prefix (P for build, I for integration, G for gap-fill, W for wave-specific) + number | | Name | Short imperative phrase ("merge-to-main", "bench-submission", "rule-hook") | | Scope | Owned dirs/files — enumerate verbatim from the spec | | Deps | Other parcel IDs that must land first | | Duration | Your honest estimate in hours (1–4) | | Parallel-safe | Which other parcels in the same wave it can run concurrently with (disjoint files) | ### 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: SPEC: WAVES: PARCELS: CRITICAL-PATH: EST-WALL-CLOCK: , assuming -parallel DETECTED-COLLISIONS: ORPHANS: ## 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) - ``` ### 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/.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 | Rule | Why | |---|---| | Read the spec in full before decomposing | Parcel boundaries are often in paragraphs, not tables | | Scope collisions are a hard error | Overlap at plan time is merge hell at build time | | Every parcel must have a concrete done criterion | "Implement X" without a test / command / file is not a parcel | | Never invent deps not implied by the spec | Fabricated deps create false sequencing and leave parallelism on the table | | Estimate duration honestly, not optimistically | 4h-est parcels that take 8h break the wave plan; under-promise | ## Anti-patterns | Anti-pattern | Why it hurts | |---|---| | Copying the spec's §2 table verbatim without re-checking scope | Specs drift; overlap creeps in; plan becomes a stale projection | | Assigning every parcel to Wave 1 to "maximise parallelism" | Deps exist for a reason; ignoring them ships broken waves | | Merging too-small parcels without a reason | Parcel size is a crash-recovery and context-budget trade-off; smaller is not always worse | | Splitting a parcel into two that both need the same file | Scope collision; worse than a larger parcel | | Using the skill to *author* parcel prompts | Wrong skill; this is a planning doc, not prompt content. Hand off to `parcel-generate`. | ## 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_PLAN.md`) — primary spec inputs