/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 "On