Stop rewriting your whole plan: shard it instead

Description and use

Splitting monolithic AI plans into shards lets you edit only the needed parts, avoiding full rewrites and providing a resume point for execution.

Problem

Monolithic AI-generated plans rewrite the entire document when a single bullet changes, causing all-or-nothing feedback and no resume point.

Outcome

Sharding reduces rewrite scope, preserves unchanged shards, logs revisions, and enables resume points, improving edit efficiency and plan execution tracking.

Workflow

• 1. Run plan-shard shard plan.md -o shards/ to split the monolith into numbered markdown files and an index.
• 2. Edit a specific shard file (e.g., PLAN_003.md).
• 3. Apply targeted feedback with plan-shard feedback shards/PLAN_003.md --old "app/cache.py" --new "app/caching.py" --note "rename module" to replace only the specified text.
• 4. Mark a shard as done with plan-shard done and resume execution with plan-shard resume.
• 5. Re‑shard if the original plan changes significantly.

Evidence

Claude Code's Plan Mode is great at producing thorough plans. It's also great at producing monolithic ones — thirty pages of markdown where changing one bullet means the model rewrites the entire document.

Source

It's a zero-dependency Python CLI with two core moves: Shard. Feed it the monolith: plan-shard shard plan.md -o shards/

Source

Targeted feedback. Fix one shard without touching the rest: plan-shard feedback shards/PLAN_003.md --old "app/cache.py" --new "app/caching.py" --note "rename module"

Source

The heuristic is deliberately simple: every ## heading starts a new shard (configurable with --level 3).

Source

Slicing is heuristic. Plans without consistent headings slice badly; a heading‑free plan becomes one shard.

Source