task-decomposition
Skill0 starsChanged 28 days agoMITView on GitHub
Slice a PRD, ADRs and tech spec into small, independently verifiable task bundles with BDD executable specifications that follow the repository's 4-document convention. Use when a reviewed spec must become executable tasks with clear blast radius, Given-When-Then acceptance criteria, traceability anchors and inherited ADRs. Do not use when the spec is still being designed, when the request is a single-file change that fits one task, or when the task only needs review (use plan-linter instead).
19 other projects use a version of this.
Adopted by
Most recently taken up by
- madeincartel/claude-code-frameworktheir own version, first seen Nov 15, 2026
- baekenough/oh-my-customcodetheir own version, first seen Nov 14, 2026
- MMACABRE/SKILLStheir own version, first seen Nov 8, 2026
- michaelalber/ai-toolkittheir own version, first seen Nov 1, 2026
- mabzhang/opc-toolkittheir own version, first seen Nov 1, 2026
- DevelopersGlobal/ai-agent-skillstheir own version, first seen Oct 25, 2026
Other versions19 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 19
- DevelopersGlobal/ai-agent-skills★ 216same name
- adamentwistle/fable-skills★ 98same name
- charliehzm/medharness★ 85same name
- baekenough/oh-my-customcode★ 42same name
- d-oit/rust-2026-template★ 15same name
- aws-solutions/konductor★ 12same name
- hieutrtr/ai1-skills★ 8same name
- AgentShekel/agentic-workflow★ 4same name
- karthikrshet/aiskills★ 4same name
- Lukasbrujula/claude-code-framework★ 4same name
9 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 repository24 other files it gives its agents.
- AGENTS.mdAGENTS.md
- changeSkill
- convergeSkill
- devSkill
- diagnose-windows-sandbox-aclSkill
- plan-linterSkill
- prd-generatorSkill
- qaSkill
- quality-engineeringSkill
- reviewSkill
- spec-generatorSkill
- task-decompositionSkill
- test-engineeringSkill
- diagnose-windows-sandbox-aclSkill
- changeSkill
- convergeSkill
- devSkill
- plan-linterSkill
- prd-generatorSkill
- qaSkill
- quality-engineeringSkill
- reviewSkill
- spec-generatorSkill
- test-engineeringSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 5 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 15 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 61
No initialization event is fabricated.
- Very specific: line 85
Dependency graph: must be acyclic (DAG); duplicate task_id values are forbidden.
- Distinctive: line 90
Intake: Read the three upstream inputs and build a traceability matrix: every requirement and invariant must map to at least one planned …
- Very specific: line 127
Validate (optional but recommended): If the plan-linter skill is installed, run its helper from the repository root (project-relative path, …
- Distinctive: line 137
Manual fallback: if the linter is unavailable.
- Distinctive: line 182
Missing input: stop and report which upstream document is missing.
- Very specific: line 184
Scope conflict: if a necessary edit falls outside touch_files, split the task or escalate to the Planner/owner.
- Distinctive: line 185
Tooling unavailable: use the manual fallback above.
“Common” is measured: kept by at least 6 in 10 of the 15 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
Task Decomposition
Turn reviewed upstream documents into atomic task bundles with BDD executable specifications that a Dev agent can implement and a QA agent can verify without re-reading the whole spec. This skill is prompt-first: every step works with no tooling, and the bundled scripts are optional helpers.
Pipeline position: prd-generator → spec-generator → task-decomposition → plan-linter → implementation.
Use when
- A PRD, ADR set and tech spec are approved and need to become executable tasks.
- A large change must be split into vertical slices with an explicit dependency graph.
- Each task needs a contract with blast radius, traceability, inherited ADRs and BDD Given-When-Then acceptance criteria.
Do not use when
- The spec is incomplete or contested — finish
spec-generatorfirst. - The work is smaller than the Goldilocks minimum (one small file): keep it as a single task instead.
- You only need to audit existing task bundles: use the
plan-linterskill (Gate 1 + Gate 2).
Inputs
- PRD:
.specs/01-prd.mdand/or.specs/01-prd/. - ADRs:
.specs/adr/*.md. - Tech spec:
.specs/02-tech-spec.mdand/or.specs/02-tech-spec/. - Repository conventions: test layout, commands, lint/type-check setup.
Outputs
For each slice, one directory with four documents:
| File | Owner | Purpose |
tasks/<task-id>/01-contract.md | Planner | Authoritative YAML frontmatter + extractable Gherkin acceptance contract |
tasks/<task-id>/02-dev-workspace.md | Dev | Implementation notes, changes, self-verification, handoff |
tasks/<task-id>/03-qa-verification.md | QA | Independent test matrix, evidence, verdict |
tasks/<task-id>/04-process.md | Tooling | Initialized status card + append-only event log (derived) |
task_id in the frontmatter must equal the directory name. Paths in the contract are repo-relative
and use forward slashes.
Role workflow (Planner → Dev → QA)
The bundle format is shared; the work is not. A short contract for the three roles:
- Planner fills
01-contract.mdwith structured Given-When-Then BDD edge cases, and writes Section 4 as a fencedgherkinblock (Feature:+ at least twoScenario:blocks) extractable intodod.feature_file, with optionaldod.step_definitionsglue.02and03stay blank token-free role forms.04starts atmacro_status: TODO,micro_phase: UNASSIGNED,current_lock_holder: None,retry_count: 0with an empty event table. No initialization event is fabricated. - Dev implements only paths in
touch_files, readsdod.feature_filefor acceptance semantics, records design/changes/self-verification in02, runs the three DoD checks plus BDD edge cases, and checks- [x] WAITING_FOR_QAonly when all pass. Dev never edits01,03,04, ortests/acceptance/(including*.featureand step definitions). - QA authors
dod.feature_fileand its step glue undertests/acceptance/from the contract BDD scenarios, executes a real BDD runner, records the matrix, evidence, blast-radius audit and exactly one verdict in03(QA_PASSEDorREWORK_REQUIRED). QA never edits source,01,02or04.
04 event/status mapping (marker → event code → status/lock/retry) and the full rework loop are in
references/role-lifecycle.md. When no tooling is available, leave
04 as initialized and rely on git/CI; never hand-write events.
Repository conventions (configurable)
- 4-document bundles under
tasks/<task-id>/; all four files must exist. - Goldilocks defaults: 1–3
touch_filesand 50–250estimated_lines. The numbers are defaults; a repository may change them in the linter config. - Traceability:
origin_spec_anchormust match#sec-[a-z0-9-]+andadherence_adrsmust name at least one inherited ADR. - BDD acceptance criteria:
dod.feature_filenames the.featurefile undertests/acceptance/; Section 4 is a fencedgherkinblock with aFeature:line and at least twoScenario:blocks (Given/When/Then each);dod.edge_casesstill requires >=2 structured Given-When-Then entries. - Forbidden touch prefix by default:
tests/acceptance/(QA-owned). - Dependency graph must be acyclic (DAG); duplicate
task_idvalues are forbidden. - No unresolved placeholders in
01/02/03after instantiation.
Workflow
- Intake. Read the three upstream inputs and build a traceability matrix: every requirement and invariant must map to at least one planned task, and every planned task must point back to a spec anchor and at least one ADR. If a requirement has no owner yet, plan a task for it; if a task has no upstream requirement, delete it.
- Slice vertically. Each slice must deliver an end-to-end, independently verifiable behavior — never "only data structures" or "only an empty endpoint". Estimate net diff lines and touched files as you slice. Order slices into a DAG; prefer fewer edges and no cycles.
Scaffold. From the workspace root, or with the absolute path of an installed copy:
python .agents/skills/task-decomposition/scripts/scaffold_task.py \ --task-id task-001-auth \ --title "User authentication" \ --tasks-dir ./tasksUseful flags:
--dry-runlists the files it would create;--forceoverwrites an existing task directory;--helpshows all flags. The scaffold replaces{{TASK_ID}}and{{TASK_TITLE}}in the contract and leaves the other contract/process placeholders for their owners. If Python is unavailable, copy the four templates fromassets/templates/by hand intotasks/<task-id>/and rename the file suffix.templateaway.Brownfield change mode: the
changeskill scaffolds one bundle per change. Pass--change-id <change-id> --size-class standard|micro; the scaffolder adds those two keys to the contract frontmatter (without the flags the output is unchanged) and the Planner then validates the proposal and contract against the existing spec anchor.- Write the contract. Fill every placeholder in
01-contract.md. Derive executable BDD scenarios and Given-When-Then edge cases directly from PRD requirements and Tech Spec invariants (seereferences/decomposition-rules.md). Section 4 must be a fencedgherkinblock with oneFeature:line and at least twoScenario:blocks;dod.feature_filemust point at the matching.featurefile undertests/acceptance/, anddod.step_definitionsmay name its glue code. The YAML frontmatter is authoritative; human sections below explain decisions for readers. Do not invent entities or fields absent from the spec. If the spec is silent, record an open question instead of guessing.02and03are blank role forms with no template tokens: leave them untouched so a freshly planned bundle can pass Gate 1 before Dev/QA start. Leave04initialized (TODO/UNASSIGNED/None/retry 0) with an empty event table. Validate (optional but recommended). If the
plan-linterskill is installed, run its helper from the repository root (project-relative path, not the skill directory):python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --jsonExit codes:
0pass,1violations,2usage/config error,3unexpected error. Read the JSON errors, fix the contracts and rerun.Manual fallback if the linter is unavailable. Check every item and fix failures by hand:
- each
01-contract.mdfrontmatter has all required keys and no placeholder values; task_idequals the directory name; IDs are unique;touch_fileshas 1–3 entries and does not touchtests/acceptance/;estimated_linesis inside the configured range;origin_spec_anchormatches#sec-[a-z0-9-]+;adherence_adrshas at least one entry;dodhas type-check, lint, test-file, feature-file, at least two Given-When-Then edge cases and a valid fencedgherkinSection 4 block;02/03/04exist; the dependency graph has no cycles and no missing task IDs.
- each
- Optional semantic review. Gate 2 is a prompt-only, read-only review by a reviewer agent. It is
never automated. Use the
plan-linterskill's Gate 2 reference when that skill is available; otherwise perform the equivalent manual pass: re-read each contract against the PRD and tech spec and reject anything that the upstream documents do not support.
Contract frontmatter
01-contract.md starts with YAML frontmatter (see assets/templates/01-contract.template.md):
| Key | Type | Rule |
task_id | string | Required; equals the task directory name. |
title | string | Required; short human title. |
module | string | Owning module or area. |
dependencies | list of strings | Defaults to []; every referenced task must exist. |
estimated_lines | integer | Inside the configured Goldilocks range. |
touch_files | list of {action, path} | 1–3 entries; action is create or modify. |
origin_spec_anchor | string | Required; #sec-[a-z0-9-]+. |
adherence_adrs | list of strings | Required; at least one ADR. |
dod | object | type_check, lint, test_file (BDD runner target, never a .feature file), feature_file (required .feature under tests/acceptance/), optional step_definitions, and edge_cases with at least two Given-When-Then strings. |
The human sections below the frontmatter are for readers; they must not contradict it. An
instantiated 01-contract.md must contain no unresolved placeholder tokens.
Templates, references and helper script
assets/templates/README.md— placeholder variables, ownership and edit rules.assets/templates/01-contract.template.md— contract skeleton (frontmatter first).assets/templates/02-dev-workspace.template.md,03-qa-verification.template.md,04-process.template.md— role scaffolds.references/decomposition-rules.md— detailed slicing, traceability, BDD derivation, and anti-hallucination rules.references/role-lifecycle.md— Dev/QA workflow, handoff markers,04initial state, event/status mapping and field ownership.scripts/scaffold_task.py— optional stdlib scaffold helper (exit codes0/1/2/3).
Failure handling
- Missing input: stop and report which upstream document is missing; do not reconstruct it.
- Ambiguous requirement: turn it into an explicit open question in
01-contract.mdNotes; do not invent behavior. - Scope conflict: if a necessary edit falls outside
touch_files, split the task or escalate to the Planner/owner. - Tooling unavailable: use the manual fallback above; the workflow must not depend on Python or optional tooling.
- Wrapper/tooling failure: report the command and exit code; do not silently hand-edit
04-process.md.
Honest limits
04-process.mdis derived output. The authoritative audit trail is git history plus the repository CI audit; no local hook adapter is shipped, and any adopter-provided hook is best-effort and bypassable, never a security guarantee.- The Goldilocks thresholds, forbidden prefixes and required documents are repository conventions; they are configurable in the linter config and must not be presented as universal law.
- Gate 2 is a prompt, not a script.
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.

