Task Skill

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