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

name, description, user_invocable, allowed-tools

name	description	user_invocable	allowed-tools
decompose	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.	true	Read, Write, Edit, Glob, Grep, Bash(date *), Bash(cat *), Bash(hostname *), Bash(jq *), Bash(ls *), Bash(head *)

/decompose Skill

decompose

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:

{
  "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."