task
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.
Install
npx skills add https://github.com/codeaholicguy/ai-devkit/tree/main/skills/task
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install codeaholicguy-ai-devkit@llmmart
git clone https://github.com/codeaholicguy/ai-devkit.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole codeaholicguy/ai-devkit collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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
phasefield 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 (backward too), task toggles, immediate next-step changes, fresh evidence, blockers discovered/resolved, feedback, commits/PRs. 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 --jsonwhen 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-managementself-identification workflow withnpx 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, andsessionId->--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, runnpx ai-devkit@latest task assign <task-name> --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --jsononce 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); also every commit and PR
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
npx ai-devkit@latest task artifact <task-name> <commit-sha> --kind commit --description "<commit subject>" --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json
npx ai-devkit@latest task artifact <task-name> <pr-url> --kind pr --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json
# Feedback (--source user|review|ci); --reopen moves the phase back in the same call
npx ai-devkit@latest task feedback <task-name> "Cut settle window to 200ms" --source user --reopen implementation --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;
createat start when no non-terminal task exists for the feature;assignonce when actor is known; setstatus activewhen real work starts or resumes;phaseon every phase transition;nextafter phase planning;progressafter planning/implementation task toggles;showat resume;close completedonly after final verification/review is done. - verify / tdd / dev-testing -
evidenceafter fresh proof (this is what makes "last validation" trustworthy). Use--failedwhen it fails. - dev-debug - reuse the same commands:
evidencefor repro results,nextfor the next hypothesis,blocker add/resolve,progress. - Any phase -
blocker addwhen blocked,resolvewhen clear;nextto state the immediate next step. Setstatus blockedwhen an open blocker stops progress, and setstatus activeagain after the blocker is resolved. - Any time -
artifact --kind commitfor every commit andartifact --kind prfor every PR;evidence --failedfor every failed validation, including flaky failures that pass on retry. - Rework - see below.
Rework
Whenever user feedback or a review finding changes code or docs after a phase is done, record the loop instead of just the fix:
feedback <task-name> "<what was asked>" --source user|review|ci --reopen implementation(or the earlier phase the change needs). Records the feedback and moves the phase back in one call.progress --textwith what changed.evidence --passedor--failedfrom fresh validation.phaseforward again (e.g.testing,review), plusartifactfor new commits/PRs.
Small follow-ups count too: a docs fix requested after review is still rework.
If the CLI has no feedback command, use note <task-name> "Feedback (user): <text>"
then phase <task-name> implementation instead.
Tips
- Add
--jsonwhen 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, including feedback and rework loops. Do not log every command; do log those checkpoints.
Files (ai-devkit)
-
agents
-
openai.yaml 289 B
Loading…
-
-
SKILL.md 9 KB
--- name: task description: AI DevKit · Track dev-lifecycle / dev-debug progress on a durable task with the ai-devkit task CLI. Use to record phase, progress, next step, blockers, validation evidence, commits/PRs, and feedback/rework loops. --- # 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 (backward too), task toggles, immediate next-step changes, fresh evidence, blockers discovered/resolved, feedback, commits/PRs. 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); also every commit and PR 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 npx ai-devkit@latest task artifact <task-name> <commit-sha> --kind commit --description "<commit subject>" --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json npx ai-devkit@latest task artifact <task-name> <pr-url> --kind pr --agent <agent-name> --agent-type <agent-type> --pid <pid> --session <sessionId> --json # Feedback (--source user|review|ci); --reopen moves the phase back in the same call npx ai-devkit@latest task feedback <task-name> "Cut settle window to 200ms" --source user --reopen implementation --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. - **dev-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. - **Any time** - `artifact --kind commit` for every commit and `artifact --kind pr` for every PR; `evidence --failed` for every failed validation, including flaky failures that pass on retry. - **Rework** - see below. ## Rework Whenever user feedback or a review finding changes code or docs after a phase is done, record the loop instead of just the fix: 1. `feedback <task-name> "<what was asked>" --source user|review|ci --reopen implementation` (or the earlier phase the change needs). Records the feedback and moves the phase back in one call. 2. `progress --text` with what changed. 3. `evidence --passed` or `--failed` from fresh validation. 4. `phase` forward again (e.g. `testing`, `review`), plus `artifact` for new commits/PRs. Small follow-ups count too: a docs fix requested after review is still rework. If the CLI has no `feedback` command, use `note <task-name> "Feedback (user): <text>"` then `phase <task-name> implementation` instead. ## 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, including feedback and rework loops. Do not log every command; do log those checkpoints.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.