task-management

name	task-management
description	Create, assign, monitor, and close tasks across agents. Covers full task lifecycle — add, priority, dependencies, confirm-request, retry, cancel, bulk ops, and cross-agent search.

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

# 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

# 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

# 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:

agencycli --dir $AGENCY_DIR overview

To iterate agents and check queues programmatically:

# 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)

# 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.

---

# 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:

agencycli --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:

agencycli --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:

# 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:

agencycli --dir $AGENCY_DIR inbox send \
  --from <project>/pm \
  --to   <project>/<to-agent> \
  --subject "Incoming task: <title>" \
  --body "Extra context: ..."

---

Retry a failed task

agencycli --dir $AGENCY_DIR task retry <task-id> \
  --project <project> --agent <agent>

Optionally update the prompt before retrying:

agencycli --dir $AGENCY_DIR task retry <task-id> \
  --project <project> --agent <agent> \
  --prompt "Updated instructions based on failure: ..."

---

Cancel tasks

# 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:

agencycli --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

# 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>