planning-and-task-breakdown
Skill8 starsChanged 4 days agoMITView on GitHub
Use after a spec is approved and before multi-file implementation begins, to break work into verifiable batches with checkpoints.
81 other projects use a version of this.
Adopted by
Most recently taken up by
- Cody-Sims/agent-skillstheir own version, first seen Nov 16, 2026
- zademy/lu-querytheir own version, first seen Nov 16, 2026
- sirius-cc-wu/sirius-skillstheir own version, first seen Nov 16, 2026
- tkbk-online/skillstheir own version, first seen Nov 15, 2026
- addyosmani/agent-skillstheir own version, first seen Nov 14, 2026
- ishandutta2007/Awesome-Agent-Skillstheir own version, first seen Nov 8, 2026
Used with
Projects with it also use constraint-driven-development, deprecation-and-migration and 8 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
MrCipherSmithSkillconstraint-driven-development
Use when a project needs a persistent, measurable quality bar — starting a project without documented standards, 'set up constraints', or when coverage/perf/a11y thresholds get re-debated per-PR. Produces CONSTRAINTS.md with enforceable numbers, ratchets, and a guard against silent weakening. NOT for throwaway prototypes or a one-off CI setup.
Also in 14 projects that use this
HK-hubSkilldeprecation-and-migration
Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when deciding whether to maintain or sunset existing code.
Also in 34 projects that use this
HK-hubSkillobservability-and-instrumentation
Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting. Use when shipping any feature that runs in production and you need evidence it works. Use when production issues are reported but you can't tell what happened from the available data.
Also in 26 projects that use this
seikaikyoSkilldoubt-driven-development
對非平凡決策啟動新鮮 context 對抗審查(找碴不背書),在修正還便宜的時候抓出錯誤方向。適用:高風險改動(production、資安敏感邏輯、不可逆操作)、不熟的程式碼、要宣稱「這樣是安全的 / 可行的」之前。機械性操作與一行修改不適用。
Also in 30 projects that use this
seikaikyoSkillinterview-me
需求不明時的意圖萃取訪談:一次一題、每題附上自己的猜測、聽出「真正想要 vs 覺得應該要」,直到能預測使用者反應(約 95% 信心)才動工。適用:需求缺少對象 / 動機 / 成功標準 / 約束,或使用者點名「訪談我」「先確認一下」「我們確定嗎」。明確自足的指示、純資訊查詢、機械性操作不適用。
Also in 31 projects that use this
GSA-TTSSkillarchitecture-decision-records
Load when a user wants architecture decision records (ADRs) drafted from requirements or a design discussion, asks which decisions need an ADR, or wants an ADR draft reviewed for one-sided trade-offs, weak alternatives or missing requirement links. Not for setting up a project's whole documentation system (project-documentation-system).
Also in 3 projects that use this
- +1 more from HK-hub
Other versions81 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 81
- addyosmani/agent-skills★ 118ksame name
- ollaya-dev/ollaya★ 1.4ksame name
- shashankswe2020-ux/whoop-mcp★ 181same name
- tranhieutt/software_development_department★ 71same name
- larchanka/skills★ 50same name
- vinvcn/addyosmani-agent-skills-zh★ 46same name
- jmxt3/gitscape.ai★ 33same name
- sampleXbro/agentsmesh★ 27same name
- jaskirat1616/grok-skills★ 22same name
- ishandutta2007/Awesome-Agent-Skills★ 21same name
71 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository34 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- batch-fixSkill
- brainstormingSkill
- code-review-and-qualitySkill
- code-simplificationSkill
- context-engineeringSkill
- fixSkill
- handoffSkill
- implementSkill
- incremental-implementationSkill
- instructionsSkill
- lessonsSkill
- mtk-doctorSkill
- mtk-setupSkill
- mtkSkill
- pre-commit-reviewSkill
- prior-work-checkSkill
- promote-lessonSkill
- repo-healthSkill
- research-contextSkill
- security-and-hardeningSkill
- setup-auditSkill
- setup-bootstrapSkill
- setup-refreshSkill
- spec-drift-detectionSkill
- spec-driven-developmentSkill
- subagent-implementationSkill
- tech-stack-dotnetSkill
- tech-stack-pythonSkill
- tech-stack-typescriptSkill
- verification-before-completionSkill
- workflow-artifactsSkill
- writing-skillsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. 0 are common, 9 are distinctive, and 8 are very specific to this project.
0
Common
Most of the 74 edited versions we read keep these.
9
Distinctive
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 25
Before any multi-file implementation
- Distinctive: line 26
When implementation needs explicit checkpoints or re-planning boundaries
- Distinctive: line 35
Start from the approved change manifest and test manifest.
- Distinctive: line 49
Boundary — state the invariant, not the file: Write what must remain true, not which file must stay shut.
- Distinctive: line 67
Prefer vertical slices where possible so each batch leaves the system in a working state.
- Very specific: line 69
Run the stack's registry-verification command (from .claude/references/dependency-intake-checklist.md criterion 0, also listed in the …
- Very specific: line 78
If a spec file exists in docs/specs/, persist the plan alongside it:
- Very specific: line 85
Use the full filename stem of the active spec, including any version suffix (e.g., -v2, -v3).
- Very specific: line 86
If no spec path is available (standalone planning run), use YYYY-MM-DD-<feature-slug>.md with no suffix.
- Very specific: line 87
Create docs/plans/ if it does not exist.
- Very specific: line 88
Add docs/plans/ to .gitignore if not already present.
- Very specific: line 107
Every files entry must already exist in the top-level change_manifest.
- Very specific: line 108
If it does not, re-plan first — don't quietly widen scope here.
- Distinctive: line 112
Keep the task list synchronized with reality.
- Distinctive: line 120
Every batch must be buildable.
- Distinctive: line 121
Every behavior change must have an associated test task.
- Distinctive: line 122
No task should require changing more than a small handful of files without justification.
“Common” is measured: kept by at least 6 in 10 of the 74 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Planning And Task Breakdown
Overview
Convert the approved plan into small, executable tasks that can be verified one at a time. Good task breakdown reduces hidden coupling, scope drift, and fake progress.
Model tier: runs on
sonnet(bounded decomposition against a written spec) per.claude/references/model-routing.md. Tool discipline (phase-locked): planning is a read + plan-artifact phase. Write only the plan/todo artifacts (docs/plans/,tasks/todo.md) — never source or test code. Implementation belongs to Phase 3; a source edit here is a scope violation thescope-guardhook will flag.
When To Use
- After spec approval
- Before any multi-file implementation
- When implementation needs explicit checkpoints or re-planning boundaries
When NOT To Use
- Tiny single-file work already small enough to execute safely
- Exploratory debugging before the root cause is known
Workflow
- Start from the approved change manifest and test manifest.
- Break work into batches of 2-4 related files, dependency-ordered. Two batches that list the same file in
filesmust carry a dependency edge between them (later depends on earlier) — this is what lets the scheduler run edge-free batches concurrently without two implementers editing one file. Files that many batches touch by nature — DI registration (Program.cs,*Startup*,DependencyInjection*,ServiceRegistration*), project/solution files (*.csproj,*.sln*,package.json,pyproject.toml), and migration snapshots — are serialize-if-touched: every batch that touches one of them depends on the previous batch that did. - For each task, write:
- task description
- acceptance criteria
- verification step — quoted, not composed. Copy the build/test/format
command verbatim from the active tech-stack skill's
## Build & Test Commandsor the reference section it points at, and cite that source in the batch (per dotnet/data-layer.md §5.5). A command written from memory is[UNVERIFIED]and must be marked so, because the implementer will run it: a freehanddotnet ef … --startup-project AIProxycost a batch a failed run when the correct invocation was already written down in the stack reference (2026-09 field run). - files in scope
- Boundary — state the invariant, not the file. Write what must remain true,
not which file must stay shut. A bare file prohibition is a bug generator: a
brief saying "don't touch
SkillsDataRepository" meant "don't add filtering there", but the implementer read it literally and loaded every bundled file on every request to route around it — and the correct fix was two lines in the file the brief had forbidden (2026-09 field run). Write "filtering stays out of the repository layer — it remains a plain data accessor", not "no changes toFoo.cs". Name a file only when the file itself is the constraint (a frozen migration, a vendored artifact), and then say why it is frozen. - Depends (mandatory): the batch ids this batch assumes are complete (e.g., "B1 — needs the entity to exist"). An empty list is a claim of independence and must say why (
depends_rationale: "independent: no shared files, reads no type another batch creates"). The scheduler runs edge-free batches in the same wave, so a missing edge is a concurrency bug, not a style nit. - Governing constraints: the Critical Rule / principle ids that constrain
this batch — from the spec's Constitution Check in extended mode, otherwise
from
bash scripts/constitution-digest.sh. Each batch states which rules it must satisfy, not just what it builds — recorded in the plan so the implementer and human reviewers see, per batch, exactly which rules constrain it. An empty list is allowed only with an explicit "no rule constrains this batch" note.
- Prefer vertical slices where possible so each batch leaves the system in a working state.
4b. Package-legitimacy gate for new dependencies. If any batch introduces a third-party package not already present in the repo's dependency manifests — especially one an AI assistant, blog post, or the spec's research brief recommended — do not plan a bare install step. Instead:
- Run the stack's registry-verification command (from
.claude/references/dependency-intake-checklist.mdcriterion 0, also listed in the active tech-stack skill) to confirm the package exists and is the real one (not a typosquat / hallucination). - Tag the package
[ASSUMED]in the plan until verified, and insert an explicitcheckpoint:human-verifystep before the install task. This checkpoint is one of the conditions that blocksMTK_AUTO_PROCEEDat theimplementPhase 2.5 gate, so an unverified package can never be installed autonomously. - A criterion-0 Poor (not found / dead repo / typosquat signal) blocks the dependency outright — re-plan without it.
- Run the stack's registry-verification command (from
- State the resulting wave schedule in the plan (
W0: B1 · W1: B2 B3 B4 · W2: B5) — derived fromdependsas topological levels, wave width capped atMTK_BATCH_WAVE_MAX(default 3). The schedule is a readback of the edges, not a second source of truth: if it looks wrong, fixdepends. - Read
tasks/todo.mdbefore writing it. Unfinished items for different work (not batches of this plan, the same comparisonbatch-fixmakes against its stub's findings) stay in the file under a short heading below the new plan, or you ask the engineer; never overwrite them silently. Then writetasks/todo.mdwith:- task title
- scope and branch
- batches with checkboxes
- post-implementation review items
- If a spec file exists in
docs/specs/, persist the plan alongside it:- If the plan was supplied by the engineer as input (adopted by
implementPhase 0.7 — the file already exists at the plan path): do not author a new plan or version-bump the engineer's file. Adopt the supplied path as-is and validate itsplan.batchesagainst the JSON sidecar schema; Phase 0.7 has already reconciled it against current code (prior-work-checkruns once per run). Skip the authoring sub-steps below. - Use the full filename stem of the active spec, including any version suffix (e.g.,
-v2,-v3). If the spec was written asdocs/specs/2026-04-23-foo-v2.md, the plan isdocs/plans/2026-04-23-foo-v2.md. - If no spec path is available (standalone planning run), use
YYYY-MM-DD-<feature-slug>.mdwith no suffix. - Create
docs/plans/if it does not exist. - Add
docs/plans/to.gitignoreif not already present. - This enables session recovery and plan reuse across sessions.
- If the plan was supplied by the engineer as input (adopted by
- Append the
plansection to the existing JSON handoff artifact atdocs/specs/<date>-<slug>.json(created by spec-driven-development). Schema:.claude/schemas/handoff.schema.json. Required keys:
Every"plan": { "batches": [ { "id": "B1", "files": ["src/X.cs"], "acceptance": "...", "verification": "...", "boundary": "...", "depends": [], "depends_rationale": "independent: first batch, creates the entity", "governing_constraints": ["C0.2", "S1.15"] }, { "id": "B2", "files": ["src/XHandler.cs"], "acceptance": "...", "verification": "...", "boundary": "...", "depends": ["B1"], "governing_constraints": ["C0.2"] } ] }filesentry must already exist in the top-levelchange_manifest. If it does not, re-plan first — don't quietly widen scope here.dependsis required on every batch;depends_rationaleis required when it is empty. Any two batches sharing afilesentry without an edge between them fail the sidecar check and theplan-gap-reviewermarks itBLOCKING. - Keep the task list synchronized with reality. If a new file is needed, re-plan before continuing.
- Record the plan/todo paths on the workflow artifact and leave
plan_trust_gateatpending— only the engineer's Phase 2.5 approval flips it topass. See.claude/references/orchestration-gates.md. 10.5. Update the workflow artifact (additive, capability-gated). Withplan_path/todo_pathrecorded, follow.claude/references/artifact-publishing.mdto add the Plan section to the workflow's Claude Artifact. Because the artifact is keyed to the workflow uuid, this updates the existing URL in place (passing the recordedresults.artifact_url) — it does not mint a new link. Silent no-op when the tool is unavailable orMTK_ARTIFACT_PUBLISH=0. - Anti-anchored gap check. Before surfacing the plan to the engineer, dispatch the
plan-gap-revieweragent with the original user request and the saved plan path — plus, when they exist, the spec markdown path, the spec JSON sidecar path, andtasks/todo.md. Passing the sidecar and todo activates the agent's cross-artifact consistency check: spec ↔ plan ↔ todo are mapped against each other in both directions (manifest entries ↔ batches, success criteria ↔ tests, out-of-scope ↔ batch contents) so disagreement between the artifacts is caught before the approval gate, not after implementation. The agent runs in a forked context and is forbidden from reading lessons, prior reviewer output, or the workflow artifact — its job is to challenge the plan against the repo with no anchors. Surface everyBLOCKINGfinding back to the planner and revise before the approval gate. SurfaceADVISORYfindings unchanged at the approval gate so the engineer decides. A plan-gapPASSdoes not replace engineer approval: the gate still runs.
Rules
- Every hand-written file touched must already exist in the change manifest. Derived artifacts are the exception — lockfiles, snapshots, generated sources, and files whose own header says they are generated stay out of it. Name the regenerator in the batch's verification step instead (
then run scripts/build-references-index.sh);validate-handoff.shclassifies the output as collateral, so an unlisted one is never drift. - Every batch must be buildable.
- Every behavior change must have an associated test task.
- No task should require changing more than a small handful of files without justification.
- Re-planning is mandatory if the task grows beyond the approved manifest.
Verification
tasks/todo.mdexists and is actionable- Batches are dependency-ordered; every batch has
depends, every emptydependshas a rationale, and no two edge-free batches share a file - Each task has acceptance and verification
- Each batch ends with a concrete checkpoint
- Each task has Boundary and Depends annotations, and every Boundary states an invariant (a file name appears only when the file itself is frozen, with the reason)
- Every verification command is quoted from the tech-stack skill or a reference it cites, with the source named — or explicitly marked
[UNVERIFIED] - No circular dependencies exist between tasks
- Workflow artifact updated in place (same URL) or gate correctly closed, per
.claude/references/artifact-publishing.md(step 10.5)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

