Add decompose + orchestrate skills with operational improvements
New skills for container agent task orchestration: - /decompose: break tasks into subtasks with dependency graph, write .agent-tasks.json - /orchestrate: check task state, launch container agents in git worktrees, poll for completion Updated with learnings from first real run (agent-runtimes M3, 9 tasks): - Prompts must end with "run pytest and fix failures" - State import conventions explicitly in prompts - Warn about uncommitted files before decomposing (worktrees need committed content) - Copy dependency outputs into downstream worktrees before launching Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Paul O'Reilly
128
skills/decompose/SKILL.md
Normal file
128
skills/decompose/SKILL.md
Normal file
@@ -0,0 +1,128 @@
|
||||
---
|
||||
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.
|
||||
|
||||
### 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>",
|
||||
"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."
|
||||
Reference in New Issue
Block a user