Skill: Task Management
Use this skill when your role involves planning, delegating, and tracking work across agents. The agency workspace is at $AGENCY_DIR.
Priority levels
| Value | Label | When to use |
|---|---|---|
| 0 | critical | Blocking production / blocking other agents |
| 1 | high | Should be picked up in the current cycle |
| 2 | normal | Default — regular backlog work |
| 3 | low | Nice-to-have, do when free |
Create a task for an agent
bash# Minimal agencycli --dir $AGENCY_DIR task add \ --project <project> --agent <agent> \ --title "Short title" \ --prompt "Detailed instructions for the agent..." # With priority and type agencycli --dir $AGENCY_DIR task add \ --project <project> --agent <agent> \ --title "Fix auth bug" \ --prompt "Reproduce with: curl -X POST /login with empty password. Root cause is in auth/validator.go." \ --priority 1 \ --type bug # With dependencies (task will not start until listed IDs are done) agencycli --dir $AGENCY_DIR task add \ --project <project> --agent <agent> \ --title "Deploy to staging" \ --prompt "Run: make deploy-staging" \ --depends-on <task-id-1> --depends-on <task-id-2> # With scheduling / nesting metadata agencycli --dir $AGENCY_DIR task add \ --project <project> --agent <agent> \ --title "Implement sub-feature" \ --prompt "..." \ --parent <parent-task-id> \ --due-date 2026-07-15 \ --estimate-duration 2h
Task metadata fields
| Field | CLI flag | Notes |
|---|---|---|
| Due date | --due-date YYYY-MM-DD | Deadline |
| Estimate | --estimate-duration 30m | Go duration (30m, 2h) |
| Parent | --parent <task-id> | Sub-task nesting |
| Labels | --label (repeatable) | Tags |
| Started / finished | (auto) | Set when status → in_progress / terminal |
Task types
feature · bug · chore · review · deploy · research · wakeup · (custom string)
Inspect task queues
bash# All active tasks for one agent (sorted by priority) agencycli --dir $AGENCY_DIR task list --project <project> --agent <agent> # Filter by status agencycli --dir $AGENCY_DIR task list --project <project> --agent <agent> --status pending agencycli --dir $AGENCY_DIR task list --project <project> --agent <agent> --status in_progress # Include archived (completed / cancelled) tasks agencycli --dir $AGENCY_DIR task list --project <project> --agent <agent> --archived # Show full detail of a specific task (project + agent known) agencycli --dir $AGENCY_DIR task show <task-id> --project <project> --agent <agent> # Find a task anywhere by ID (no project/agent needed) agencycli --dir $AGENCY_DIR task find --id <task-id>
Update task fields
bash# Only flags you pass are changed; project/agent auto-detected if omitted agencycli --dir $AGENCY_DIR task set <task-id> --priority 1 agencycli --dir $AGENCY_DIR task set <task-id> --status in_progress agencycli --dir $AGENCY_DIR task set <task-id> \ --due-date 2026-07-15 --estimate-duration 2h --parent <parent-task-id> agencycli --dir $AGENCY_DIR task set <task-id> --label bug --label urgent agencycli --dir $AGENCY_DIR task set <task-id> --due-date "" # clear due date agencycli --dir $AGENCY_DIR task set <task-id> --format json # print updated task
Updatable: title, description, status, priority, type, summary, label,
parent, due-date, estimate-duration, assignee, prompt / prompt-file, position.
Status changes auto-maintain started_at / finished_at.
Monitor progress across agents
To get an overview of all agents and their queue depths:
bashagencycli --dir $AGENCY_DIR overview
To iterate agents and check queues programmatically:
bash# List all agents in a project agencycli --dir $AGENCY_DIR list agents --project <project> # Then per agent agencycli --dir $AGENCY_DIR task list --project <project> --agent <agent> --status pending agencycli --dir $AGENCY_DIR task list --project <project> --agent <agent> --status in_progress
Task stats (throughput & efficiency)
bash# Today by executor queue (default: all agents, grouped) agencycli --dir $AGENCY_DIR task stats --since today # One agent's queue agencycli --dir $AGENCY_DIR task stats --since today --project <project> --agent <agent> # By assignee field agencycli --dir $AGENCY_DIR task stats --since today --assignee <project>/<agent> agencycli --dir $AGENCY_DIR task stats --since 7d --by assignee # By label (evening summary: value / category buckets) agencycli --dir $AGENCY_DIR task stats --since today --by label:value agencycli --dir $AGENCY_DIR task stats --since today --by label:category agencycli --dir $AGENCY_DIR task stats --since today --label value:owner # List each finished task agencycli --dir $AGENCY_DIR task stats --since today --detail # JSON export (includes elapsedHuman, estimateHuman, etc.) agencycli --dir $AGENCY_DIR task stats --since today --format json
Metrics: success/failed/cancelled counts, sum of actual elapsed time (started_at→finished_at),
sum of estimate_duration, coverage (tasks with estimates), and actual/estimate ratio.
JSON uses human-readable durations (elapsedHuman: 14m32s) instead of nanosecond integers.
bash# Success agencycli --dir $AGENCY_DIR task done \ --id <task-id> --status success --summary "What was accomplished" # Failure agencycli --dir $AGENCY_DIR task done \ --id <task-id> --status failed --error "reason"
Request human confirmation (non-blocking)
When an agent needs a human decision before continuing, it calls:
bashagencycli --dir $AGENCY_DIR task confirm-request \ --id $TASK_ID \ --summary "One-line description of what needs approval" \ --action-item "Option A: reply 'approve'" \ --action-item "Option B: reply 'reject <reason>'"
The task is archived. The human responds via:
bashagencycli --dir $AGENCY_DIR inbox list agencycli --dir $AGENCY_DIR inbox messages # view messages agencycli --dir $AGENCY_DIR inbox reply <msg-id> --body "approve" agencycli --dir $AGENCY_DIR inbox reject <task-id> --reason "out of scope"
The human's reply is sent as a message. The agent sees it on the next wakeup and continues via session memory.
Escalate or delegate a task
If a task is better suited for a different agent, cancel it and re-create for the target agent:
bash# 1. Cancel the original agencycli --dir $AGENCY_DIR task cancel <task-id> --project <project> --agent <from-agent> # 2. Create for the new agent with transferred context agencycli --dir $AGENCY_DIR task add \ --project <project> --agent <to-agent> \ --title "<same title>" \ --prompt "<original prompt + re-delegation note>"
To notify the new agent with async context before the task runs:
bashagencycli --dir $AGENCY_DIR inbox send \ --from <project>/pm \ --to <project>/<to-agent> \ --subject "Incoming task: <title>" \ --body "Extra context: ..."
Retry a failed task
bashagencycli --dir $AGENCY_DIR task retry <task-id> \ --project <project> --agent <agent>
Optionally update the prompt before retrying:
bashagencycli --dir $AGENCY_DIR task retry <task-id> \ --project <project> --agent <agent> \ --prompt "Updated instructions based on failure: ..."
Cancel tasks
bash# Cancel a specific task agencycli --dir $AGENCY_DIR task cancel <task-id> \ --project <project> --agent <agent> # Emergency halt — cancel all pending tasks for all agents in a project agencycli --dir $AGENCY_DIR task stop-all \ --project <project> --all-agents # Cancel pending + in-progress for a single agent agencycli --dir $AGENCY_DIR task stop-all \ --project <project> --agent <agent> --include-running
Recurring tasks with cron
Schedule a task to be automatically enqueued on a fixed schedule:
bashagencycli --dir $AGENCY_DIR cron add \ --project <project> --agent <agent> \ --id weekly-review \ --title "Weekly backlog review" \ --schedule "0 9 * * 1" \ --prompt "Review all open issues. Prioritise for the week. Update task queue accordingly." agencycli --dir $AGENCY_DIR cron list --project <project> --agent <agent> agencycli --dir $AGENCY_DIR cron disable weekly-review --project <project> --agent <agent> agencycli --dir $AGENCY_DIR cron enable weekly-review --project <project> --agent <agent>
Cron syntax: minute hour day month weekday (standard 5-field)
Token usage and cost
bash# One agent agencycli --dir $AGENCY_DIR task tokens --project <project> --agent <agent> # All agents in a project agencycli --dir $AGENCY_DIR task tokens --project <project> --all-agents # Specific task agencycli --dir $AGENCY_DIR task tokens \ --project <project> --agent <agent> --task <task-id>
Task assignment decision guide
| Situation | Action |
|---|---|
| Clear scope, right agent | task add directly |
| Scope unclear, need human input first | inbox send --to human to clarify, then task add |
| Depends on another task being done first | task add --depends-on <id> |
| Task failed once | task retry with updated prompt |
| Wrong agent received the task | Cancel + re-create for correct agent |
| Repeated recurring work | cron add with a schedule |
| Human must approve before agent proceeds | Agent calls task confirm-request |
| Need to change title/priority/due date/parent mid-flight | task set <id> --<field> ... |
| Review throughput / efficiency for a person or agent | task stats --since today [--assignee A] |
| Evening summary by value/category labels | task stats --since today --by label:value or --by label:category |
| Need to know which agent owns a task ID | task find --id <id> |
