Set up task-based multi-agent systems with shared task files. Use when setting up parallel agent execution, designing worktree isolation patterns, or implementing task file coordination.
Limited to specific tools
Additional assets for this skill
This skill is limited to using the following tools:
Guide creation of task-based multi-agent systems using shared task files and worktree isolation.
Agents share a task file that acts as a coordination mechanism:
## To Do
- [ ] Task A
- [ ] Task B
## In Progress
- [π‘ abc123] Task C - being worked on
## Done
- [β
def456] Task D - completed
```markdown
## Task File Format
`tasks.md`:
```markdown
# Tasks
## Git Worktree {worktree-name}
## To Do
[] Pending task description # Available
[β°] Blocked task (waits for above) # Blocked
[] Task with #opus tag # Model override
[] Task with #adw_plan_implement tag # Workflow override
## In Progress
[π‘, adw_12345] Task being processed # Claimed by agent
## Done
[β
abc123, adw_12345] Completed task # Commit hash saved
[β, adw_12345] Failed task // Error reason # Error captured
```markdown
## Status Markers
| Marker | Meaning | State |
| -------- | --------- | ------- |
| `[]` | Pending | Available for pickup |
| `[β°]` | Blocked | Waiting for previous |
| `[π‘, {id}]` | In Progress | Being processed |
| `[β
{hash}, {id}]` | Complete | Finished successfully |
| `[β, {id}]` | Failed | Error occurred |
## Tag System
Tags modify agent behavior:
| Tag | Effect |
| ----- | -------- |
| `#opus` | Use Opus model |
| `#sonnet` | Use Sonnet model |
| `#adw_plan_implement` | Complex workflow |
| `#adw_build` | Simple build workflow |
## Implementation Architecture
```text
βββββββββββββββββββββββββββββββββββββββββββ
β CRON TRIGGER β
β (polls tasks.md every N seconds) β
βββββββββββββββββββ¬ββββββββββββββββββββββββ
β
βββββββββββΌββββββββββ
β β β
v v v
ββββββββββ ββββββββββ ββββββββββ
β Task A β β Task B β β Task C β
βWorktreeβ βWorktreeβ βWorktreeβ
β 1 β β 2 β β 3 β
ββββββββββ ββββββββββ ββββββββββ
```markdown
## Setup Workflow
### Step 1: Create Task File
```markdown
# tasks.md
## To Do
[] First task to complete
[] Second task to complete
[β°] Blocked until first completes
## In Progress
## Done
```markdown
### Step 2: Create Data Models
```python
from pydantic import BaseModel
from typing import Literal, Optional, List
class Task(BaseModel):
description: str
status: Literal["[]", "[β°]", "[π‘]", "[β
]", "[β]"]
adw_id: Optional[str] = None
commit_hash: Optional[str] = None
tags: List[str] = []
worktree_name: Optional[str] = None
```markdown
### Step 3: Create Trigger Script
```python
# adw_trigger_cron_tasks.py
def main():
while True:
tasks = parse_tasks_file("tasks.md")
pending = [t for t in tasks if t.status == "[]"]
for task in pending:
if not is_blocked(task):
# Mark as in progress
claim_task(task)
# Spawn subprocess
spawn_task_workflow(task)
time.sleep(5) # Poll interval
```markdown
### Step 4: Create Task Workflows
```python
# adw_build_update_task.py (simple)
def main(task_id: str):
# Mark in progress
update_task_status(task_id, "[π‘]")
# Execute /build
response = execute_template("/build", task_description)
# Mark complete
if response.success:
update_task_status(task_id, "[β
]", commit_hash)
else:
update_task_status(task_id, "[β]", error_reason)
```markdown
### Step 5: Add Worktree Isolation
Each task gets its own worktree:
```bash
git worktree add trees/{task_id} -b task-{task_id} origin/main
```markdown
## Coordination Rules
1. **Claim before processing**: Update status to `[π‘]` immediately
2. **Respect blocking**: Don't process `[β°]` tasks until dependencies complete
3. **Update on completion**: Always update status, even on failure
4. **Include context**: Save commit hash, error reason, ADW ID
## Key Memory References
- @git-worktree-patterns.md - Worktree isolation
- @composable-primitives.md - Workflow composition
- @zte-progression.md - Scaling to ZTE
## Output Format
```markdown
## Multi-Agent System Setup
**Task File:** tasks.md
**Trigger Interval:** 5 seconds
**Max Concurrent:** 5 agents
### Components
1. Task file format with status markers
2. Data models (Task, Status, Tags)
3. Cron trigger script
4. Task workflow scripts
5. Worktree isolation
### Workflow Routing
- Default: adw_build_update_task.py
- #adw_plan_implement: adw_plan_implement_update_task.py
- #opus: Use Opus model
### Status Flow
[] -> [π‘, id] -> [β
hash, id]
-> [β, id] // error
```markdown
## Anti-Patterns
- Polling too frequently (< 1 second)
- Not claiming before processing (race conditions)
- Ignoring blocked tasks
- Not capturing failure reasons
- Running in same directory (no isolation)