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: ```bash 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>`. ```bash # 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.