---
name: skill-decompose
description: /decompose skill — breaks tasks into subtasks with dependency graph, writes .agent-tasks.json for container agent orchestration
type: reference
---

# /decompose Skill

## Purpose

Decompose a complex task into independently-executable subtasks with a dependency graph. Each subtask gets a full prompt for a container agent. Writes `.agent-tasks.json` in the project root for `/orchestrate` to consume.

## Usage

```
/decompose <task description>
/decompose                     # uses conversation context
```

## How It Works

1. Reads project context (CLAUDE.md, SPEC.md, PLAN.md, spec/) to understand the project
2. Breaks the task into subtasks — each self-contained, scoped to one deliverable, testable
3. Presents a dependency graph and table for user approval
4. Asks user to set `max_concurrent` (number of simultaneous container agents)
5. Writes `.agent-tasks.json` with task IDs, prompts, dependencies, reads/writes, and status fields

### Task State Format

```json
{
  "created_at": "ISO timestamp",
  "project": "project-name",
  "max_concurrent": 3,
  "tasks": {
    "task-id": {
      "name": "...", "prompt": "...", "depends_on": [],
      "reads": [], "writes": [],
      "status": "pending", "branch": null, "worktree": null,
      "host": null, "container_id": null,
      "started_at": null, "completed_at": null,
      "exit_code": null, "error": null
    }
  }
}
```

Status values: `pending`, `running`, `completed`, `failed`, `blocked`.

## Gotchas

- Task prompts need to be fully self-contained — container agents have no conversation history
- Include explicit "read these files first" instructions in each task's prompt
- Over-decomposing creates merge overhead; under-decomposing wastes parallelism potential

## Used By

- `agent-runtimes` — M3 harness implementation decomposition
- Any project needing parallel container agent work