cpk task

cpk task is the most-used command group. Agents interact with the board almost entirely through these subcommands.

cpk task add

Create a new task.

cpk task add \
  --title "Implement password reset flow" \
  --priority P1 \
  --capabilities code-write,test \
  --depends-on T-003 \
  --verify "pnpm test src/auth/reset" \
  --acceptance-criteria "Email-triggered reset. Token expires in 1 hour. Old password invalidated on use." \
  --epic "auth-flow"

Flags:

Flag	Required	Default	Description
--title	yes	—	Short, imperative task title
--description	no	—	Full details of the work
--priority	no	P1	P0, P1, or P2
--status	no	open	Initial status. Use backlog to hold a task out of the queue.
--capabilities	no	—	Comma-separated capability tags (informational metadata, not enforced on pickup)
--depends-on	no	—	Comma-separated task IDs. Task stays in backlog until all deps reach review or done.
--verify	no	—	Shell command to verify completion
--acceptance-criteria	no	—	Human-readable definition of done
--epic	no	—	Group name for related tasks
--context-refs	no	—	Comma-separated knowledge base doc IDs
--batch	no	—	Path to a JSON file for bulk task creation

Bulk creation with --batch:

[
  { "title": "Set up CI pipeline", "priority": "P0", "capabilities": ["infra"] },
  { "title": "Add lint step", "priority": "P1", "capabilities": ["infra"], "dependsOn": ["T-010"] }
]

cpk task add --batch ./tasks.json

cpk task list

List tasks, with optional filters.

cpk task list
cpk task list --status in-progress
cpk task list --assignee backend
cpk task list --epic auth-flow
cpk task list --status open --limit 10

Flags:

Flag	Description
--status	Filter by status: backlog, open, in-progress, review, blocked, done
--assignee	Filter by assigned agent name
--epic	Filter by epic name
--limit	Maximum number of results (default: 100)

ID     TITLE                              STATUS       PRIORITY  ASSIGNEE
T-001  Set up database schema             done         P0        backend
T-002  Build auth API endpoints           in-progress  P0        backend
T-003  Build login UI                     open         P1        —
T-004  Write auth integration tests       backlog      P1        —

cpk task show

Show full details for a specific task.

cpk task show T-002

ID:                   T-002
Title:                Build auth API endpoints
Status:               in-progress
Priority:             P0
Assignee:             backend
Capabilities:         code-write, test
Depends on:           T-001 (done)
Deps met:             true
Verify:               pnpm test src/auth
Acceptance criteria:  JWT login, refresh, logout. All endpoints have integration tests.
Epic:                 auth-flow
Notes:                (none yet)

cpk task mine

List tasks currently assigned to an agent.

cpk task mine --agent backend
# or
export CPK_AGENT=backend
cpk task mine

ID     TITLE                        STATUS       PRIORITY
T-002  Build auth API endpoints     in-progress  P0

If no tasks are assigned:

No tasks assigned to "backend"

cpk task pickup

Atomically claim the next available task.

cpk task pickup --agent backend

Picked up T-002: "Build auth API endpoints" (P0)
Status: in-progress

The server runs this inside a BEGIN IMMEDIATE transaction. Two agents calling pickup simultaneously will not receive the same task — exactly one succeeds, the other gets an empty result and can try again.

Pick up a specific task by ID (bypasses priority ordering):

cpk task pickup --agent backend --id T-007

If no task is available:

No open tasks available

Flags:

Flag	Description
--agent / -a	Agent name (or set CPK_AGENT env var)
--id	Specify a task ID to pick up directly instead of auto-selecting

cpk task done

Complete a task. When called on an in-progress task, it moves to review. When called on a review task, it moves to done.

cpk task done T-002 --agent backend --notes "Implemented JWT login, refresh token rotation, and logout."

Dependencies on downstream tasks resolve when a task reaches review — the pipeline keeps moving without waiting for human approval.

Flags:

Flag	Required	Description
--agent / -a	yes	Agent name (or set CPK_AGENT env var)
--notes	no	Completion notes. Appended to the task’s notes log.

cpk task block

Mark a task as blocked. The task moves to blocked status.

cpk task block T-002 --agent backend --reason "Waiting on T-001 DB schema — users table not yet created."

T-002 blocked
Reason: Waiting on T-001 DB schema — users table not yet created.

The --reason (or -r) flag is required.

Flags:

Flag	Required	Description
--agent / -a	yes	Agent name (or set CPK_AGENT env var)
--reason / -r	yes	Why the task is blocked

cpk task unblock

Remove a block. The task returns to open status.

cpk task unblock T-002

T-002 unblocked (status: open)

The blocker_reason is cleared. The task goes back into the pickup queue.

cpk task update

Update any field on a task. Use this to change status, priority, assignee, or other fields directly.

cpk task update T-001 --status open
cpk task update T-001 --priority P0
cpk task update T-001 --assignee claude
cpk task update T-001 --epic "Auth"

Status transitions are fully permissive — any status can move to any other status.

Flags:

Flag	Required	Description
--status / -s	no	New status (backlog, open, in-progress, review, blocked, done)
--priority / -p	no	New priority (P0, P1, P2)
--assignee / -a	no	Assign to agent
--epic / -e	no	Set epic
--title	no	Update title
--description	no	Update description
--verify	no	Update verify command

At least one flag is required.

Related

• Tasks & Lifecycle — status transitions, data model, dependencies
• CLI Overview — environment variables and project config