taskgraph-implement-next-task

name	taskgraph-implement-next-task
description	Claim, implement, test, and report the next ready coding item from Taskgraph through the Taskgraph tools. Use when the user asks an agent to implement, take, work on, or continue with the next task, issue, item, or queued code change and expects one complete repository change.

Taskgraph Implement Next Task

Use Taskgraph as the work queue and the repository as the work site. Complete exactly one ready action unless the user asks for more. Each action should be granular — one concrete deliverable with verifiable acceptance criteria — so the change is small and checkable.

Select and claim the task

1. Derive the smallest useful Taskgraph scope from the user's request. Keep an explicit project, milestone, item, or path boundary.
2. Call tg_peek_next with that scope. Request only a few alternatives and blocked examples.
3. If no item is ready, inspect the returned blockers and report them. Do not change dependencies, status, priority, or scope just to create ready work.
4. Call tg_claim_next with the same scope, the selected item ID as expected_candidate_id, a suitable lease, and a new idempotency_key. Use about 30 minutes unless the task suggests another safe length.
5. Reuse the key only when retrying that same claim call. If the candidate changed or another agent won the claim, peek again; never switch tasks without checking the new result.
6. Keep the claim ID and token private. Call tg_context_bundle for the claimed item and retain the returned renew_after time.

Do not claim until ready to inspect and edit the repository. If the Taskgraph tools are unavailable, stop and state that the skill needs the Taskgraph extension loaded; do not infer queue state from repository files or edit the workspace file.

Prepare the change

1. Read the item, its acceptance criteria, context bundle, ancestors, and direct dependencies needed to understand its bounds.
2. Read all applicable repository instructions, including AGENTS.md files and any skill named or triggered by the task.
3. Inspect the worktree, relevant code, tests, build commands, and recent local patterns before editing.
4. Preserve user changes. Do not overwrite, revert, or fold unrelated work into the task.
5. State a short implementation plan when the change has several parts. Record a decision entry before a major choice that future agents will need to know.

If the selected item cannot be implemented in the allowed repository or needs a user choice that would change its scope, do not make speculative edits. Follow the unable path below. An item that is really a phase — one task covering several unrelated deliverables or acceptance criteria that span a whole area — also belongs on the unable path: record a finding recommending decomposition instead of folding a broad change into one claim.

Implement the task

• Make the smallest complete change that meets the item and its acceptance criteria.
• Follow existing design, naming, error handling, and test patterns unless the task calls for a change.
• Add or update tests for changed behavior. Update docs or examples only when the behavior or acceptance criteria require them.
• Keep edits within the claimed item. Do not fix nearby issues unless they block the task; record them as findings instead.
• Check the lease during long tool calls or between work phases. Before renew_after, call tg_manage_claim with action: "renew" and a suitable lease_seconds value.
• Do not commit, push, deploy, publish, or send messages unless the user has authorized that action.

Verify the result

1. Run the narrowest relevant tests first.
2. Run the repository's required format, lint, type, build, or wider test gates in proportion to the change and the stated acceptance criteria.
3. Inspect the final diff and status for stray files, debug code, secrets, generated output, and unrelated edits.
4. Match each acceptance criterion to code, tests, or another concrete check. Do not treat review alone as proof when a runnable check exists.

Record the exact checks and their results. If a check fails, find whether the change caused it. Fix in-scope failures. Report any known unrelated failure without hiding it, and do not mark the item complete if the required evidence is missing.

Report the outcome

Fetch the item again before writing status so that version and acceptance data are current.

For success:

1. Use tg_patch_item with the current version to mark acceptance criteria met only when the checks support them.
2. Add a completion_summary with the behavior changed, main files touched, and checks run. Never include a claim token.
3. Call tg_report_work with status: "completed" and a concise reason. This must mark the item done and end the claim.
4. Fetch the item once more to confirm its final state and note any newly ready work. Stop after this one item; do not claim the next item unless the user asked for a work loop.

For a blocker or incomplete result:

1. Add a finding or comment that states what is done, the exact blocker, and the next action.
2. Call tg_report_work with status: "unable" and a clear reason so the item stays open and the claim ends. Use failed only when the item itself has failed and that state is justified.
3. If reporting is unavailable, call tg_manage_claim with action: "release". Do not leave a live claim when work has stopped.

Handle common errors

• NO_READY_ITEM: report the useful blocked examples and explain a likely candidate with tg_explain_blocked.
• CANDIDATE_CHANGED: peek again and assess the new candidate before claiming.
• CLAIM_CONFLICT: inspect the queue; do not retry the same item blindly.
• AGENT_CLAIM_LIMIT: finish or release the agent's existing claim before taking another.
• VERSION_CONFLICT: fetch the item, review the new state, and retry only still-valid updates.
• ACCEPTANCE_INCOMPLETE: leave the item open until each criterion is met or the user authorizes a reasoned waiver.

Use the Taskgraph tools for queue and item changes. Never bypass them with direct file or HTTP writes.