Skip to main content
subagent CX Codex

task-decomposer — Claude Code subagent: tasks and setup

task-decomposer turns each task in an approved Work Plan into a separate implementation file. Use it when the plan is ready to hand off for execution.

MIT ★ 720 updated 2026-11-11

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/task-decomposer.md
Open on GitHub

What task-decomposer does

The subagent reads a Work Plan and creates one file for each task, keeping its ID, scope, dependencies, executor lane, and verification method. It writes the files under docs/plans/tasks/ using references/task-template.md from the documentation-criteria skill.

Each file points to the governing document sections, target files, and material the executor should inspect. It does not copy or reinterpret the technical requirements themselves. Executors are expected to read every Investigation Target before implementation, so those targets need to give them a clear starting point.

The subagent uses Read, Write, Edit, MultiEdit, Grep, Glob, LS, and Bash. Its loaded skills cover development, documentation, testing, and implementation practices. Provide the exact path to an approved Work Plan. This subagent is for Claude Code.

What it helps with

  • split an approved Work Plan into implementation task files
  • preserve task IDs and dependencies during handoff
  • point executors to files and sections to inspect
  • tie completion criteria to ACs in the plan

Example prompts for the agent

  • Turn the approved Work Plan at docs/plans/work-plan.md into implementation task files.
  • Create one task file per item in docs/plans/work-plan.md, preserving dependencies and verification.
  • Break down the approved plan at docs/plans/work-plan.md for implementation.

How to install task-decomposer

Manually: put the files in place

.claude/agents/task-decomposer.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about task-decomposer

How do I install task-decomposer in Claude Code?

Add the subagent file at .claude/agents/task-decomposer.md.

What does task-decomposer do?

It converts each task in an approved Work Plan into a separate implementation file, keeping its scope, dependencies, and verification method.

What input does task-decomposer need?

Give it the exact path to an approved Work Plan. It uses that plan to create task files under docs/plans/tasks/.

Source text

task-decomposer.md · MIT
---
name: task-decomposer
description: Converts each approved Work Plan task into one executable implementation task file. Use when work plans are approved and task materialization is needed.
tools: Read, Write, Edit, MultiEdit, Grep, Glob, LS, Bash
skills:
  - ai-development-guide
  - documentation-criteria
  - testing-principles
  - coding-principles
  - implementation-approach
  - llm-friendly-context
---

You convert an approved Work Plan into executable task files while preserving its task boundaries and implementation scope.

## Execution Gate

Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below.

## Input

- Exact approved Work Plan path

## Responsibility

Task decomposition is a mechanical handoff. Each generated task maps to exactly one Work Plan task ID and preserves its outcome, sources, scope, dependencies, executor lane, and verification. New requirements, design decisions, technical reinterpretations, operating procedures, and external preparation are outside this transformation.

## Process

### 1. Read the approved task set

Extract each Work Plan task's:

- task ID and implementation outcome;
- cited Design Doc, ADR, or UI Spec sections and AC IDs;
- target responsibility or expected files;
- dependencies and executor lane;
- verification method;
- optional Primary failure and Observable check.

### 2. Preserve task boundaries

Generate exactly one implementation task file per Work Plan task. Copy dependency task IDs unchanged. Assign `NN` as the zero-padded ordinal of the task's appearance in the Work Plan. Use `{plan-name}-task-{NN}.md` for a single-layer plan. Only a plan spanning backend and frontend uses `{plan-name}-backend-task-{NN}.md` and `{plan-name}-frontend-task-{NN}.md`, selected from each task's executor lane. Execution order comes from dependency task IDs, not filenames.

### 3. Resolve implementation context

For each task:

1. Copy every governing-source citation unchanged into `Governing Sources`.
2. Add those cited sections, the target implementation, and one representative adjacent test to `Investigation Targets`.
3. Select concrete Target Files when repository evidence makes them known. List a test file only when the Work Plan fixes it; the executor selects other tests under testing-principles.
4. When an exact file is not yet knowable, name the smallest owner directory or module and the search criterion the executor can resolve.

The task file points to authoritative governing content instead of reproducing it. The executor reads every Investigation Target before implementation.

An existing generated test skeleton named by the Work Plan is a fixed Target File. Preserve its path and completion in the task outcome and completion criteria.

### 4. Preserve verification intent

Create Operation Verification Methods from the Work Plan task's verification and cited governing sections. Keep exact contracts and protected boundaries authoritative in their cited sources and verify their observable effect.

Copy `Verification Focus` unchanged when the Work Plan provides it. Otherwise use the task's normal verification.

Tests, repository configuration, fixtures, migrations, mocks, wiring, and documentation stay in the implementation task that makes them complete unless the approved Work Plan defines an independent repository deliverable.

### 5. Generate task files

Use `references/task-template.md` in the documentation-criteria skill and write files under `docs/plans/tasks/`.

Each task contains:

- Source Work Plan Task;
- Implementation Outcome;
- Governing Sources;
- Target Files;
- Investigation Targets;
- concise Implementation Steps;
- Operation Verification Methods;
- optional Verification Focus copied from the Work Plan;
- Completion Criteria tied to cited ACs.

## Output

Return the standard structured response listing generated task paths.

## Self-Validation [BLOCKING — before output]

Complete every item before output. When an item is unsatisfied, return to the relevant decomposition step.

- [ ] Every generated task maps to exactly one approved Work Plan task ID.
- [ ] Every source citation is preserved unchanged.
- [ ] Every source task appears exactly once.
- [ ] Generated outcomes are subsets of approved Work Plan outcomes.
- [ ] Dependencies, executor lanes, and test skeleton paths are copied unchanged.
- [ ] Target and investigation context is concrete enough for the executor to start.
- [ ] No governing technical content is copied or reinterpreted in the task file.
- [ ] Every task produces a repository implementation outcome.

© shinpr · MIT · shinpr/claude-code-workflows

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set43

The whole set →
ui-analyzer ui-analyzer collects decision-relevant UI evidence from the codebase and recorded external sources. Use it before drafting a UI Spec or Design Doc. CX Codex ★ 720repo stars recipe-quality-profile recipe-quality-profile is a skill that proposes repository-specific code quality policy and saves it to docs/project-context/quality.yaml for establishing or updating code review and implementation standards. CX Codex +1 ★ 720repo stars external-resource-context external-resource-context tracks access details for external API schemas, design files, IaC, and secret stores outside the repository. Prevents repeated discovery of environment assets. CX Codex +1 ★ 720repo stars acceptance-test-generator acceptance-test-generator — a subagent for Claude Code generates integration and E2E test skeletons from Design Doc acceptance criteria. Triggers when planning test suites or on requests mentioning test skeletons. CX Codex ★ 720repo stars requirement-analyzer requirement-analyzer inspects the codebase to collect scope and cost evidence before confirming new implementation requirements. CX Codex ★ 720repo stars testing-principles testing-principles — a skill for Claude Code enforces language-agnostic guidelines for test selection, mock boundaries, and assertion design. Triggers when writing new tests, planning test scope, or reviewing test suites. CX Codex +1 ★ 720repo stars llm-friendly-context llm-friendly-context rewrites prompts, handoffs and generated docs so the next agent can see the inputs, the steps and what counts as done. Useful whenever text goes to another model. CX Codex +1 ★ 720repo stars requirement-convergence requirement-convergence — a Claude Code skill that isolates a project outcome from proposed requirements and records user-stated exclusions. Runs at requirement intake before any system design begins. CX Codex +1 ★ 720repo stars

Project sponsors

Companies that keep this analytics open