custom-claude-skills/skills/decompose/SKILL.md

---
name: decompose
description: >
  Decompose a task into subtasks with dependencies. Writes .agent-tasks.json for orchestration
  by container agents. Use /decompose followed by a task description or invoke mid-conversation.
user_invocable: true
allowed-tools: Read, Write, Edit, Glob, Grep, Bash(date *), Bash(cat *), Bash(hostname *), Bash(jq *), Bash(ls *), Bash(head *)
---

# /decompose Skill

<command-name>decompose</command-name>

You are decomposing a task into subtasks that can be executed by container agents in parallel.

## Pre-gathered context

### Current date
!`date +%Y-%m-%dT%H:%M:%S`

### Hostname
!`hostname`

### Existing task state
!`cat .agent-tasks.json 2>/dev/null || echo "No task state file yet"`

### Project context
!`cat CLAUDE.md 2>/dev/null | head -100 || echo "No CLAUDE.md"`
!`cat SPEC.md 2>/dev/null | head -50 || echo "No SPEC.md"`
!`ls spec/ 2>/dev/null || echo "No spec directory"`

## Instructions

### Step 1: Understand the task

Read `$ARGUMENTS` for the task description. If empty, ask the user what task to decompose.

Also read the current conversation context — the user may have been discussing the task before invoking this skill.

Read any relevant project files (PLAN.md, SPEC.md, spec/, CLAUDE.md) to understand the project structure and what work is needed.

### Step 2: Decompose into subtasks

Break the task into **independently executable subtasks**. Each subtask must be:

- **Self-contained**: A container agent with access to the project can complete it without human input
- **Scoped**: One clear deliverable (a spec file, a test file, an implementation file)
- **Testable**: Success can be verified (file exists, tests pass, etc.)

For each subtask, determine:
- A short unique ID (e.g., `spec-harness`, `test-composition`, `impl-resolver`)
- A human-readable name
- Which other subtasks it depends on (by ID)
- The full prompt that a container agent would receive
- Which project files it needs to read
- Which files it will create or modify

**Guidelines:**
- Prefer many small tasks over few large tasks
- Tasks that can run in parallel SHOULD NOT depend on each other
- Include "read these files first" in each task's prompt
- Be explicit about what output is expected (file paths, test names)
- **End every prompt with:** "Run `pytest tests/ -v --tb=short` and fix any failures before finishing. Write a session log to memory/log/ when done."
- **State import conventions explicitly** in prompts — e.g., "Use `from module import X`, not `from .module import X`" when source dirs aren't packages
- **Before writing .agent-tasks.json, warn the user to commit WIP** if there are untracked/uncommitted files that agents will need. Worktrees only see committed content.
- **Set the `model` field** for each task. Use `claude-opus-4-20250514` for research, architecture, and complex reasoning tasks. Use `claude-sonnet-4-20250514` (or omit for default) for code generation, testing, and mechanical tasks. Ask the user if unsure.
- **Do NOT include "use web search" in prompts.** Container agents cannot web search. If a task requires current data verification, note this in the task description so the user can validate from their main session after the agent completes.

### Step 3: Present the task graph

Show the user the decomposition as a dependency graph:

```
task-a (no deps) ─┐
task-b (no deps) ─┼─► task-d (depends: a, b)
task-c (no deps) ─┘         │
                             ▼
                      task-e (depends: d)
```

Also show a table:

| ID | Name | Depends On | Writes | Est. Complexity |
|----|------|-----------|--------|-----------------|
| ... | ... | ... | ... | low/medium/high |

### Step 4: Get user approval

Ask the user:
1. Does the decomposition look right? They may want to merge, split, or reorder tasks.
2. **How many concurrent agents should run?** Suggest a number based on the task graph width (max parallel tasks at any level). Note that each agent uses subscription tokens — more agents = faster but uses allocation quicker.

### Step 5: Write the task state file

Once approved, write `.agent-tasks.json` in the project root:

```json
{
  "created_at": "<ISO timestamp>",
  "project": "<project name from directory>",
  "description": "<original task description>",
  "max_concurrent": <user-approved number>,
  "tasks": {
    "<task-id>": {
      "name": "<human readable name>",
      "prompt": "<full prompt for container agent>",
      "model": "<optional model override, e.g. claude-opus-4-20250514>",
      "depends_on": ["<task-id>", ...],
      "reads": ["<file paths the agent should read>"],
      "writes": ["<file paths the agent will create/modify>"],
      "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`

**Worktree fields:**
- `branch`: The git branch name for this task (e.g., `agent/<task-id>`)
- `worktree`: The worktree path (e.g., `.worktrees/<task-id>`)

Tell the user: "Task state written to `.agent-tasks.json`. Run `/orchestrate` to start executing tasks, or `/loop 2m /orchestrate` to auto-poll."