Task

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:

• Run the agent-management self-identification workflow with npx ai-devkit@latest agent list --json.
• 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.
• 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.

• If identity is ambiguous, do not guess. Continue task logging without actor

flags rather than fabricating attribution.

• 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.

• 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 task close <task-name> completed --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json

When to emit (by workflow)

• dev-lifecycle - real read probe first; create at start when no

non-terminal task exists for the feature; assign once when actor is known; set

status active when real work starts or resumes; phase on every phase

transition; next after phase planning; progress after

planning/implementation task toggles; show at resume; close completed

only after final verification/review is done.

• verify / tdd / dev-testing - evidence after fresh proof (this is what

makes "last validation" trustworthy). Use --failed when it fails.

• structured-debug - reuse the same commands: evidence for repro results,

next for the next hypothesis, blocker add/resolve, progress.

• Any phase - blocker add when blocked, resolve when clear; next to

state the immediate next step. Set status blocked when an open blocker stops

progress, and set status active again after the blocker is resolved.

Tips

• Add --json when an agent must parse output (create/show/list). Omit for

human-readable checks.

• Don't restate obvious nearby files or transient state; keep summaries short.
• Good task records let a later reader answer: who worked on it, which phase it

reached, what changed, what is next, what verified the claim, and what blocked

or changed scope. Do not log every command; do log those checkpoints.