{"slug": "stop-rewriting-your-whole-plan-shard-it-instead", "title": "Stop rewriting your whole plan: shard it instead", "summary": "A developer released plan-shard, a zero-dependency Python CLI that splits monolithic Claude Code Plan Mode documents into numbered shard files with dependency frontmatter, so targeted string-replacement feedback edits only one shard instead of forcing the model to rewrite the whole plan. The tool shards on '##' headings, defaults dependencies to sequential order plus literal PLAN_XXX references, and runs offline with no LLM or API calls; it is MIT-licensed with 24 tests and installs via pip.", "body_md": "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. If you've ever caught yourself manually splitting a plan into `PLAN_1.md`, `PLAN_2.md` files just to keep edits contained, you're not alone. That's the exact workflow I automated with **plan-shard**.\n\nA monolith plan has two failure modes:\n\nIt's a zero-dependency Python CLI with two core moves:\n\n**Shard.** Feed it the monolith:\n\n```\nplan-shard shard plan.md -o shards/\n```\n\nYou get `PLAN_001.md … PLAN_00N.md` plus a `PLAN_INDEX.md`. Every shard carries frontmatter with its dependency order and resume index:\n\n```\n---\nshard: 3\ntotal: 6\ntitle: \"Step 1: Add the Redis client\"\nsource: plan.md\ndepends_on: [2, 4]\nresume_index: 3\nstatus: pending\nrevisions: []\n---\n```\n\n**Targeted feedback.** Fix one shard without touching the rest:\n\n```\nplan-shard feedback shards/PLAN_003.md \\\n  --old \"app/cache.py\" --new \"app/caching.py\" \\\n  --note \"rename module\"\n```\n\nOnly that file changes — every other shard stays byte-identical, and the edit is logged in the shard's `revisions` list. Then track execution with `plan-shard done` / `plan-shard resume`.\n\nThe heuristic is deliberately simple: every `##` heading starts a new shard (configurable with `--level 3`). Text before the first heading becomes shard 1; dependencies default to sequential order plus any literal `PLAN_XXX` references found in a shard's body. No LLM, no API calls, runs offline in milliseconds.\n\n`--feedback` is exact string replacement, not semantic editing. It won't reword surrounding prose or chase cross-shard references for you.`PLAN_XXX` mentions, not a real graph.\n\n```\npip install plan-shard\n```\n\nSource: [https://github.com/hahahahahahahahah6/plan-shard](https://github.com/hahahahahahahahah6/plan-shard) (MIT). 24 tests, stdlib only. If your plans keep getting rewritten wholesale, give your feedback a smaller blast radius.", "url": "https://wpnews.pro/news/stop-rewriting-your-whole-plan-shard-it-instead", "canonical_source": "https://dev.to/haoli/stop-rewriting-your-whole-plan-shard-it-instead-goc", "published_at": "2026-10-02 09:56:02+00:00", "updated_at": "2026-10-02 10:07:49.954573+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents"], "entities": ["plan-shard", "Claude Code", "GitHub"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/stop-rewriting-your-whole-plan-shard-it-instead", "markdown": "https://wpnews.pro/news/stop-rewriting-your-whole-plan-shard-it-instead.md", "text": "https://wpnews.pro/news/stop-rewriting-your-whole-plan-shard-it-instead.txt", "jsonld": "https://wpnews.pro/news/stop-rewriting-your-whole-plan-shard-it-instead.jsonld"}}