Tasks & Lifecycle

Tasks are the atomic unit of work in codepakt. Everything agents do — planning, claiming work, reporting completion — flows through the task model.

Task data model

Field	Type	Description
id	string	Auto-assigned. Format: T-001, T-002, etc.
title	string	Short, imperative description of the work
description	string	Full details of what needs to be done
status	enum	Current lifecycle state (see below)
priority	enum	P0, P1, or P2
assignee	string	Agent name currently holding this task
capabilities	string[]	Informational metadata (not enforced on pickup)
depends_on	string[]	Task IDs that must complete before this task can be picked up
deps_met	boolean	Auto-managed. True when all dependencies are in review or done
verify	string	Shell command to run to verify completion
acceptance_criteria	string	Human-readable definition of done
epic	string	Group name for related tasks
notes	string[]	Append-only log of agent notes
blocker_reason	string	Set when status is blocked. Cleared on unblock
context_refs	string[]	References to knowledge base doc IDs

Status lifecycle

Tasks move through these states. Status transitions are fully permissive — you can move a task to any status using cpk task update.

backlog ──► open ──► in-progress ──► review ──► done
                          │
                          ▼
                       blocked ──► open

Status	Meaning	Who sets it
backlog	Dependencies not yet met	Auto-set when depends_on tasks are incomplete
open	Ready for pickup. All dependencies met	Server auto-sets when deps_met becomes true
in-progress	Claimed by an agent via cpk task pickup	Server sets on atomic pickup
review	Agent called cpk task done. Work complete, awaiting human review	Server sets on task done
blocked	Agent called cpk task block. Work cannot proceed	Agent sets via cpk task block
done	Human approved from dashboard	Human moves from review via dashboard or cpk task update

Key behaviors:

• cpk task done moves in-progress → review (not straight to done)
• Dependencies resolve when a task reaches review — the pipeline doesn’t wait for human approval
• cpk task update T-001 --status <any> can move a task to any status
• review → done is the human approval step (from dashboard or CLI)

Priority levels

Priority	Meaning
P0	Critical. Pickup preference. Blocking other work.
P1	Standard. Default for most tasks.
P2	Low. Nice-to-have. Picked up when nothing higher is available.

When an agent calls cpk task pickup, the server returns the highest-priority open task with all dependencies met. P0 tasks are always offered before P1, P1 before P2.

Dependencies

Dependencies are declared at creation time with --depends-on:

cpk task add \
  --title "Build auth API" \
  --depends-on T-001,T-002

The server tracks deps_met automatically. When all tasks in depends_on reach review or done, the server sets deps_met: true on the dependent task and transitions it from backlog to open, making it available for pickup.

You don’t need to manually unblock dependent tasks. The server handles it.

Verification

The --verify flag stores a shell command that defines concrete completion criteria:

cpk task add \
  --title "Add user registration endpoint" \
  --verify "pnpm test src/api/users --coverage && pnpm typecheck"

The verify command is informational — it’s stored with the task and shown to the agent at pickup time. Agents are expected to run it before calling cpk task done. The server does not auto-run it.

Acceptance criteria

--acceptance-criteria is a human-readable description of what done looks like:

cpk task add \
  --title "Build login UI" \
  --acceptance-criteria "Login form with email/password. Error states for invalid credentials. Redirects to dashboard on success. Mobile-responsive."

This is what a human reviewer checks when a task is in review status.

Notes

When an agent marks a task done, it appends notes explaining what was done:

cpk task done T-007 --agent claude --notes "Implemented JWT login with 15-min access token and 7-day refresh token."

Notes are append-only. Multiple done/re-open cycles preserve the full history. This is the primary audit trail for understanding what happened on a task.