taskgraph-execute-work

name	taskgraph-execute-work
description	Select, claim, execute, and report Taskgraph work through the Taskgraph tools. Use when an agent needs the next ready item, a bounded execution context, claim lease handling, progress notes, completion, failure, or a blocker report.

Taskgraph Execute Work

Use Taskgraph as the work queue. Claim one ready action, gather its context, do the work, keep the claim alive when needed, and report the outcome. Actions should be granular — one deliverable per claim — so a work cycle stays small and reportable.

Start a work cycle

1. Call tg_peek_next with the smallest useful scope and a few alternatives and blocked examples.
2. If a suitable item is selected, call tg_claim_next with the same scope, expected_candidate_id set to the selected ID, a lease, and a new idempotency_key.
3. If the candidate changed, peek again. Do not claim a different item silently.
4. Call tg_context_bundle for the claimed item. Taskgraph accepts a direct ref; it also accepts source.item as a fallback.
5. Do the implementation or other work outside the tools, within the user's allowed workspace.

Example claim:

{
  "scope": {"under": "project/compiler-rewrite"},
  "lease_seconds": 1800,
  "expected_candidate_id": "<id from tg_peek_next>",
  "idempotency_key": "claim-<stable attempt id>"
}

Reuse the same idempotency key when retrying the same claim call. Never reuse it for a new claim attempt.

Manage the lease

Keep the claim ID and token private. Before renew_after, call tg_manage_claim with action: "renew" and lease_seconds. When work ends or you cannot continue, call it with action: "release" when the claim should end without a status change.

If the agent may stop before the lease ends, release the claim. If the process fails, let the lease expire only when no safe release call is possible.

Record useful progress

Use tg_record_entry on the item for durable findings, decisions, notes, or comments. Taskgraph accepts ref, entry_type, and body; valid entry types include note, finding, decision, comment, and completion_summary.

Record a short decision before a major change and a completion summary before reporting success. Do not paste claim tokens into entries.

Report the outcome

Before completion, fetch the current item. If acceptance criteria remain pending, use tg_patch_item with the current version to mark them met or waived with a reason.

Call tg_report_work with ref, status, and a clear reason:

• completed marks the item done and ends its active claim.
• failed marks it failed. Include the cause and what remains.
• unable leaves it open and ends the claim. State the exact blocker and next action.
• open leaves it open and can be used for a normal status report.
• done is accepted as a direct status value, but prefer completed for a work outcome.

Use a non-empty reason for failed, unable, skipped, cancelled, or acceptance exceptions. If a hard dependency blocks the item, call tg_explain_blocked and report the returned reason rather than guessing.

After reporting, fetch the item again and inspect any newly ready work. Parent containers may roll up to done when all children finish.

Recover from errors

• NO_READY_ITEM: inspect blocked_examples from tg_peek_next, then use tg_explain_blocked on a useful candidate.
• CANDIDATE_CHANGED: peek again and decide whether to claim the new candidate.
• CLAIM_CONFLICT: do not retry blindly; inspect the item and queue.
• AGENT_CLAIM_LIMIT: release or finish an existing claim first.
• VERSION_CONFLICT: fetch the item, review the new version, and apply only still-valid updates.
• ACCEPTANCE_INCOMPLETE: update or waive pending criteria with a reason before retrying completion.
• Broad item: if the claimed action covers several unrelated deliverables, complete the part that is verifiable, record a finding recommending decomposition, and report unable so the plan can be split before the rest is claimed.

The pi extension publishes full schemas for every tool, including tg_patch_item and tg_record_entry. If a strict client rejects valid arguments, report the error; do not bypass the tools with direct file writes.