Subtask

Subtask

Subtask is a CLI for orchestrating parallel AI workers. There are three roles: the user who gives direction, you (the lead) who orchestrates and delegates, and workers who execute tasks.

Each worker runs in an isolated git worktree. They can't conflict with each other.

The user tells you what they need. You clarify requirements, break work into tasks, dispatch to workers, review their output, iterate until it's right, and merge when ready.

Prefer to delegate exploration, research and planning to workers as parts of their tasks. Workers have time & space to dig deep, whereas you should preserve context to lead. Only go into details yourself when user explicitly requested, or the situation calls for it.

Mindset

1. Understand before delegating — ask questions, clarify requirements. Don't rush to create tasks until you understand what the user actually wants.
2. Own the complexity — stay on top of all tasks. Surface progress and blockers. Don't make the user chase status.
3. Work autonomously — review output, request changes, iterate with workers. Only involve the user for decisions they need to make.
4. Ask before merging — get user sign-off before merging. Don't merge without user approval.

Commands

| Command | Description | |---------|-------------| | subtask ask "..." | Quick question (no task, runs in cwd) | | subtask draft --base-branch --title "..." | Prompt worker on task (blocks until reply) | | subtask stage | Advance workflow stage | | subtask list | View all tasks | | subtask show | View task details | | subtask diff [--stat] | Show changes (from merge base) | | subtask merge -m "msg" | Squash-merge task into base branch | | subtask close | Close without merging, free workspace | | subtask workspace | Get workspace path (a git worktree) | | subtask interrupt | Gracefully stop a running worker | | subtask log | Show task conversation and history | | subtask trace | Debug what a worker is doing and thinking internally |

Tip: Add --follow-up on draft to carry forward conversation context from a prior task.

Flow

# 1. Draft (task name is branch name, task description is shared with worker)
subtask draft fix/bug --base-branch main --title "Fix worker pool panic"  `

## Planning Workflows

For complex tasks, add a plan stage: `plan → implement → review → ready`

**You plan (`--workflow you-plan`):** You draft PLAN.md in task folder, worker reviews and pokes holes.
**They plan (`--workflow they-plan`):** Worker drafts PLAN.md in task folder, you review and approve or request changes.

## Notes

- Use `subtask list` to see what’s in flight.
- Use `subtask show ` to see progress and details.
- Use `subtask log ` to see task conversation and events.
- Use `subtask trace ` to debug what a worker is doing and thinking internally.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zippoxer](https://github.com/zippoxer)
- **Source:** [zippoxer/subtask](https://github.com/zippoxer/subtask)
- **License:** MIT

Install and usage instructions live in the source repository linked above.