/task

name: task
description: AI DevKit · Track dev-lifecycle / structured-debug progress on a durable task with the ai-devkit task CLI. Use to record phase, progress, next step, blockers, and validation evidence.

Task Progress Tracking

Record development progress on a durable task: phase, progress, next step, blockers, and validation evidence.

Requires the optional task command. Use `npx ai-devkit@latest` for task and agent commands. Before recording task events, run a real read probe:

npx ai-devkit@latest task list --json
# or, when a task name is known:
npx ai-devkit@latest task list --name <task-name> --json

Only treat task tracing as available when the read probe exits 0. If it fails, continue without task logging and include the failed command plus stderr/stdout summary in the final report. Do not block the user's work just because optional task tracing is unavailable or unusable.

Core idea

• **One task per work item.** Create it once; advance its `phase` field as work

moves through the lifecycle or debug workflow.

• **`<id>` can be a task name.** Every command below accepts the task name in

place of a task id, resolving to the latest non-terminal task. Prefer `<task-name>` so agents do not track task ids.

• **Choose stable names.** For lifecycle work, use the feature key as the task

name. For debugging or review work, choose a short kebab-case task name.

• **Emit at checkpoints, not streaming.** Phase transitions, task toggles,

immediate next-step changes, fresh evidence, blockers discovered/resolved. A handful of calls per session.

• **Sequence mutations.** Never run task mutation commands in parallel for the

same task. Each mutation reads the current task snapshot and writes it back; parallel writes can clobber snapshot fields even though events append. Run create/assign/phase/next/progress/evidence/blocker/artifact/close commands one at a time, then read back with `show --events --json` when the final state matters.

• **Attribution is explicit.** Identify self once, then pass actor flags on

mutation commands.

Identify self

Use `agent-management` when attribution is needed:

1. Run the `agent-management` self-identification workflow with `npx ai-devkit@latest agent list --json`. 2. Match the current agent entry from that list. Prefer an exact session match when available; otherwise use the unambiguous entry for the current project/worktree. 3. Build actor flags from the matched entry: `--agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId>`. Map JSON fields directly: `name` -> `--agent`, `type` -> `--agent-type`, `pid` -> `--pid`, and `sessionId` -> `--session`. 4. If identity is ambiguous, do not guess. Continue task logging without actor flags rather than fabricating attribution. 5. Add `--agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId>` to every mutation command once known. If a task already exists, run `npx ai-devkit@latest task assign <task-name> --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json` once so the task snapshot has current ownership. 6. If actor identity is unknown, run the same mutation commands without the four actor flags.

Canonical commands

When self identity is known, add all four actor flags to every mutation command: `--agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId>`.

# Create the task once (capture taskId from --json if needed)
npx ai-devkit@latest task create --title "<title>" --name <task-name> --phase requirements --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# If the task already exists, assign current ownership once when known
npx ai-devkit@latest task assign <task-name> --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Mark real work as active after create/resume
npx ai-devkit@latest task status <task-name> active --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Advance phase as the lifecycle moves on
npx ai-devkit@latest task phase <task-name> implementation --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Progress (use --text; positional text is ignored)
npx ai-devkit@latest task progress <task-name> --text "Implementing task CLI" --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Next step
npx ai-devkit@latest task next <task-name> "Run validation" --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Blockers
npx ai-devkit@latest task status <task-name> blocked --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json
npx ai-devkit@latest task blocker <task-name> add "Waiting for review" --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json
npx ai-devkit@latest task blocker <task-name> resolve <blocker-id> --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json
npx ai-devkit@latest task status <task-name> active --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Validation evidence - record after a fresh verify/tdd/test run
npx ai-devkit@latest task evidence <task-name> --passed --command "npm test" --exit-code 0 --summary "tests passed" --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Reference an artifact (never copies the file)
npx ai-devkit@latest task artifact <task-name> docs/ai/testing/foo.md --kind test-report --description "Testing notes" --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

# Read current status / list
npx ai-devkit@latest task show <task-name> --json
npx ai-devkit@latest task list --name <task-name> --json

# Close at lifecycle end
npx ai-devkit@latest tas