agentleFS
formal-youformal-you/agent-skills-suite/.agents/skills/task-decomposition/SKILL.md

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

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
  1. Distinctive:

    No initialization event is fabricated.

    line 61
  2. Very specific:

    Dependency graph: must be acyclic (DAG); duplicate task_id values are forbidden.

    line 85
  3. Distinctive:

    Intake: Read the three upstream inputs and build a traceability matrix: every requirement and invariant must map to at least one planned …

    line 90
  4. Very specific:

    Validate (optional but recommended): If the plan-linter skill is installed, run its helper from the repository root (project-relative path, …

    line 127
  5. Distinctive:

    Manual fallback: if the linter is unavailable.

    line 137
  6. Distinctive:

    Missing input: stop and report which upstream document is missing.

    line 182
  7. Very specific:

    Scope conflict: if a necessary edit falls outside touch_files, split the task or escalate to the Planner/owner.

    line 184
  8. Distinctive:

    Tooling unavailable: use the manual fallback above.

    line 185

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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-generator first.
  • 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-linter skill (Gate 1 + Gate 2).

Inputs

  • PRD: .specs/01-prd.md and/or .specs/01-prd/.
  • ADRs: .specs/adr/*.md.
  • Tech spec: .specs/02-tech-spec.md and/or .specs/02-tech-spec/.
  • Repository conventions: test layout, commands, lint/type-check setup.

Outputs

For each slice, one directory with four documents:

FileOwnerPurpose
tasks/<task-id>/01-contract.mdPlannerAuthoritative YAML frontmatter + extractable Gherkin acceptance contract
tasks/<task-id>/02-dev-workspace.mdDevImplementation notes, changes, self-verification, handoff
tasks/<task-id>/03-qa-verification.mdQAIndependent test matrix, evidence, verdict
tasks/<task-id>/04-process.mdToolingInitialized 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.md with structured Given-When-Then BDD edge cases, and writes Section 4 as a fenced gherkin block (Feature: + at least two Scenario: blocks) extractable into dod.feature_file, with optional dod.step_definitions glue. 02 and 03 stay blank token-free role forms. 04 starts at macro_status: TODO, micro_phase: UNASSIGNED, current_lock_holder: None, retry_count: 0 with an empty event table. No initialization event is fabricated.
  • Dev implements only paths in touch_files, reads dod.feature_file for acceptance semantics, records design/changes/self-verification in 02, runs the three DoD checks plus BDD edge cases, and checks - [x] WAITING_FOR_QA only when all pass. Dev never edits 01, 03, 04, or tests/acceptance/ (including *.feature and step definitions).
  • QA authors dod.feature_file and its step glue under tests/acceptance/ from the contract BDD scenarios, executes a real BDD runner, records the matrix, evidence, blast-radius audit and exactly one verdict in 03 (QA_PASSED or REWORK_REQUIRED). QA never edits source, 01, 02 or 04.

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_files and 50–250 estimated_lines. The numbers are defaults; a repository may change them in the linter config.
  • Traceability: origin_spec_anchor must match #sec-[a-z0-9-]+ and adherence_adrs must name at least one inherited ADR.
  • BDD acceptance criteria: dod.feature_file names the .feature file under tests/acceptance/; Section 4 is a fenced gherkin block with a Feature: line and at least two Scenario: blocks (Given/When/Then each); dod.edge_cases still requires >=2 structured Given-When-Then entries.
  • Forbidden touch prefix by default: tests/acceptance/ (QA-owned).
  • Dependency graph must be acyclic (DAG); duplicate task_id values are forbidden.
  • No unresolved placeholders in 01/02/03 after instantiation.

Workflow

  1. 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.
  2. 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.
  3. 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 ./tasks

    Useful flags: --dry-run lists the files it would create; --force overwrites an existing task directory; --help shows 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 from assets/templates/ by hand into tasks/<task-id>/ and rename the file suffix .template away.

    Brownfield change mode: the change skill 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.

  4. 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 (see references/decomposition-rules.md). Section 4 must be a fenced gherkin block with one Feature: line and at least two Scenario: blocks; dod.feature_file must point at the matching .feature file under tests/acceptance/, and dod.step_definitions may 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. 02 and 03 are blank role forms with no template tokens: leave them untouched so a freshly planned bundle can pass Gate 1 before Dev/QA start. Leave 04 initialized (TODO/UNASSIGNED/None/retry 0) with an empty event table.
  5. Validate (optional but recommended). If the plan-linter skill 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 --json

    Exit codes: 0 pass, 1 violations, 2 usage/config error, 3 unexpected 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.md frontmatter has all required keys and no placeholder values;
    • task_id equals the directory name; IDs are unique;
    • touch_files has 1–3 entries and does not touch tests/acceptance/;
    • estimated_lines is inside the configured range;
    • origin_spec_anchor matches #sec-[a-z0-9-]+; adherence_adrs has at least one entry;
    • dod has type-check, lint, test-file, feature-file, at least two Given-When-Then edge cases and a valid fenced gherkin Section 4 block;
    • 02/03/04 exist; the dependency graph has no cycles and no missing task IDs.
  6. Optional semantic review. Gate 2 is a prompt-only, read-only review by a reviewer agent. It is never automated. Use the plan-linter skill'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):

KeyTypeRule
task_idstringRequired; equals the task directory name.
titlestringRequired; short human title.
modulestringOwning module or area.
dependencieslist of stringsDefaults to []; every referenced task must exist.
estimated_linesintegerInside the configured Goldilocks range.
touch_fileslist of {action, path}1–3 entries; action is create or modify.
origin_spec_anchorstringRequired; #sec-[a-z0-9-]+.
adherence_adrslist of stringsRequired; at least one ADR.
dodobjecttype_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, 04 initial state, event/status mapping and field ownership.
  • scripts/scaffold_task.py — optional stdlib scaffold helper (exit codes 0/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.md Notes; 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.md is 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.