Tasks

Tasks are the units of work in HZL. They track what needs to be done, who's working on it, and progress made.

Creating Tasks

hzl task add "Implement user authentication" -P my-project

Tasks require a title and project:

• Title: Clear description of what to do
• Project: Which project this belongs to (-P or --project)

Optional Flags

Flag	Description
-d, --description	Detailed description of the task
-l, --links	Comma-separated URLs or file paths to reference docs
-t, --tags	Comma-separated tags for filtering
-p, --priority	Priority level 0-3 (higher = more important)
-s, --status	Initial status (backlog, ready, in_progress, blocked, done)
--agent	Routing intent: only this agent can claim via --next; omit to let any pool agent claim
--author	Attribution only: who created the task (no routing effect)
--depends-on	Comma-separated task IDs this depends on
--parent	Parent task ID (creates a subtask)

Linking to Context

Keep tasks focused on the work itself. Use --links to reference supporting documents:

hzl task add "Implement auth flow per design" -P myapp \
  --links docs/designs/auth-flow.md,https://example.com/spec

# Long-running work can opt into a wider stale window
hzl task add "Run external security review" -P myapp \
  -s ready \
  --stale-after 2h

Descriptions can be multiline Markdown. Use shell quoting or a heredoc:

hzl task add "Write rollout plan" -P myapp \
  -d "$(cat <<'EOF'
## Goal
- Roll out behind feature flag

## Acceptance Criteria
- [ ] Canary metrics stay within baseline
- [ ] Rollback steps documented
EOF
)"

To track who delegated work, set both agent and author:

hzl task add "Investigate flaky auth test" -P myapp -s ready \
  --agent kenji \
  --author clara

Agent Routing vs Authorship

--agent and --author on task add serve different purposes:

Flag	Where	Meaning
--agent <name> on task add	Routing intent	Only this agent can claim via --next; tasks with no agent are claimable by anyone in the pool
--agent <name> on task claim	Attribution	Who is claiming; routing filter also applies
--author <name> on task add	Attribution only	Who created the task; no routing effect

Omit --agent when any eligible agent in the pool should pick up the task. Set it when the task is specifically for one agent.

# Pool-routed — any researcher can claim
hzl task add "Research competitor pricing" -P research -s ready

# Pre-routed — only kenji can claim via --next
hzl task add "Review Clara's draft" -P research -s ready --agent kenji

--author is optional. Use it when one actor is operating on behalf of another (delegation, handoffs, audits). Skip it for solo/self-tracking flows.

Important behavior:

• hzl task claim has no --author flag; the --agent value is recorded as the event author.
• hzl task steal uses --agent for takeover ownership and optional --author for attribution (--owner remains as a deprecated alias).

Task Statuses

Tasks move through these statuses:

Status	Meaning
backlog	Not ready to be claimed yet
ready	Available to be claimed
in_progress	Someone is working on it
blocked	Stuck on an external issue
done	Work complete
archived	No longer relevant

Note: blocked is different from dependency blocking. A task with unmet dependencies won't appear in --available lists, but its status remains ready. The blocked status is for tasks that are stuck due to external issues (waiting for API access, human decision, etc.).

Claiming Tasks

Before working on a task, claim it:

hzl task claim <id> --agent worker-1

Claiming:

• Changes status to in_progress
• Records who is working on it
• Prevents other agents from claiming

When using claim --next, agent routing applies: tasks assigned to a different agent are skipped. Tasks with no agent assignment are available to everyone.

See Claiming & Leases for atomic claiming, agent IDs, and lease-based recovery.

Recording Progress

Use checkpoints to record progress while working:

hzl task checkpoint <id> "Designed the schema, moving to implementation"

Track completion with a 0-100 progress value:

hzl task progress <id> 50   # 50% complete

See Checkpoints for best practices on preserving context across sessions.

Blocking Tasks

When a task is stuck waiting on external factors:

hzl task block <id> --comment "Blocked: waiting for API credentials from DevOps"

To resume work:

hzl task unblock <id>

See Blocking & Unblocking for the full workflow.

Stale Tasks

A task is stale when it's in_progress but has had no checkpoints for longer than a threshold (default 10 minutes). This is distinct from stuck (lease expired): stuck means the agent's lease ran out, while stale means the agent hasn't posted proof of life.

# List tasks with stale detection (enabled by default at 10 min)
hzl task list -P my-project

# Custom threshold
hzl task list --stale-threshold 15

# Disable stale detection
hzl task list --stale-threshold 0

# Include stale tasks in stuck report
hzl task stuck --stale

# Override stale detection for a single slow task
hzl task update <id> --stale-after 45m

# Clear the task-specific override and fall back to the query default
hzl task update <id> --clear-stale-after

In task list output, stale tasks show a warning indicator and [stale Nm] suffix. In JSON output, each task includes stale (boolean) and stale_minutes (number or null). Task detail and stale-task JSON surfaces also include the stored stale_after_minutes override when present.

Completing Tasks

When done:

hzl task complete <id>

This marks the task as done and unblocks any dependent tasks.

Listing and Finding Tasks

# All tasks
hzl task list

# In a specific project
hzl task list -P my-project

# Assigned to a specific agent/person
hzl task list --agent kenji

# Assigned to a specific agent/person in one project
hzl task list -P my-project --agent kenji

# Only available (ready, not blocked)
hzl task list --available

# Get next available task
hzl task claim --next -P my-project

Task Details

hzl task show <id>
hzl task show <id> --deep   # Full subtask fields + blocked_by
hzl task show <id> --view summary
hzl task show <id> --view standard --json

Shows title, description, status, dependencies, and checkpoints.

The --deep flag expands subtask data from a summary (task_id, title, status) to all Task fields plus a computed blocked_by array. This lets agents get complete context on a parent task and all its children in a single call.

Use --view to control payload size:

• summary for minimal task fields
• standard for minimal task fields plus tags, due_at, and lease_until
• full for all task fields (default)

Updating Tasks

hzl task update <id> --title "New title"
hzl task update <id> --desc "Updated description"
hzl task update <id> --links doc1.md,doc2.md
hzl task update <id> --tags bug,urgent
hzl task update <id> --priority 2
hzl task update <id> --stale-after 30m
hzl task update <id> --clear-stale-after
hzl task update <id> --title "New title" --author clara
hzl task move <id> my-project --author clara
hzl task add-dep <id> <depends-on-id> --author clara
hzl task remove-dep <id> <depends-on-id> --author clara

To clear a field, pass an empty string:

hzl task update <id> --desc ""     # Clear description
hzl task update <id> --links ""    # Remove all links

Archiving Tasks

For tasks no longer needed:

hzl task archive <id>

Archived tasks are hidden from normal lists but preserved in history.

Pruning Old Tasks

Completed tasks accumulate over time. Pruning permanently removes old terminal tasks:

# Preview what would be pruned (safe)
hzl task prune --project my-project --dry-run

# Prune tasks older than 30 days (default)
hzl task prune --project my-project --yes

# Prune tasks older than 90 days
hzl task prune --project my-project --older-than 90d --yes

Warning: Pruning is destructive and cannot be undone. Always use --dry-run first.

Best Practices

1. Keep tasks small - 1-2 hours of focused work
2. Use descriptive titles - Future you will thank you
3. Checkpoint frequently - Preserve context across sessions
4. Track ownership first - Use --agent to set who owns active work
5. Use --author selectively - Add it when attribution differs from ownership
6. Block when stuck - Use hzl task block instead of leaving tasks in limbo
7. Complete or archive - Don't leave tasks hanging