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:

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.