Execute

Execute — Claim to Submit in One Loop

Carry a ready task all the way to needs_review: fetch the work packet, read it in full, do the work, heartbeat the lease, run verification, and submit evidence. Nothing moves to needs_review without passing through here.

---

When to Use

• After anvil claim TASK_ID has succeeded — claim ID and branch are in hand.
• For execution: one task, one branch, straight to submit.

Do not use this skill to inspect the queue without taking work — use /anvil:state-ops. Do not use it to make the ship decision on completed tasks — that is /anvil:finish.

---

Prerequisites

An active claim by the current actor on TASK_ID. Verify before proceeding:

anvil list --status claimed

If the task does not appear, claim it first via /anvil:claim. Commands used in this skill:

Command	Role
anvil packet TASK_ID	render the work packet
anvil submit TASK_ID	record completion evidence
anvil apply TASK_ID	human review gate
anvil renew CLAIM_ID	extend the lease heartbeat
anvil release CLAIM_ID	return the task to the pool

---

Workflow

Step 1 — Fetch the work packet

anvil packet TASK_ID

Example:

anvil packet T012

The CLI echoes where it wrote the file (Wrote packet to <path>). That path lives under the active state layout (the HOME workspace by default, e.g. ~/.anvil/workspaces/<key>/.anvil/packets/T012.md), not necessarily in-repo. The packet holds the full operating context for this task: goal, acceptance criteria, likely files in scope, constraints, verification commands, and the update protocol. It is a derived view regenerated from canonical state, so it reflects the current snapshot, not a cached copy.

When present, read the packet’s Active PRD assumptions section as a declared constraint. An explicit autonomous delegation permits work within those bounded premises; it does not permit inventing new scope, obtaining external authority, or bypassing approval/evidence gates. If execution exposes an unstated premise with no bounded safe default, release the claim and surface it rather than silently broadening the work.

Read the packet immediately after fetching it. The acceptance criteria in the packet are the contract that submit validates against. Skipping the packet and working from memory or from show TASK_ID output risks submitting evidence that misses a required item.

To get the JSON form instead (useful when another tool or agent consumes the packet programmatically):

anvil packet T012 --format json

---

Step 2 — Confirm scope before writing code

Before touching any file, confirm:

1. The acceptance criteria are concrete and independently verifiable — not aspirational descriptions.
2. The likely_files list in the packet does not overlap with files another active claim owns. If overlap exists, resolve it via /anvil:state-ops before editing.
3. All acceptance criteria are unambiguous. If any are unclear, release the claim now rather than discovering the problem at submit time:

anvil release CLAIM_ID --reason "acceptance criteria ambiguous on T012 item 3"

Ask the user to clarify, update the PRD, re-parse, and re-claim once the criteria are concrete.

This check costs one minute. A wrong interpretation discovered at submit costs the full lease window plus rework.

---

Step 3 — Do the work

Do the work directly in this session. Read the work packet, implement against the acceptance criteria, and run the verification commands yourself (Step 5) when the implementation is complete.

---

Step 3a — Implementation discipline

Work where the claim lives: if the claim created a worktree (the default under worktree_isolation: require, or --worktree), do ALL edits inside that worktree directory — never in the shared checkout, where a concurrent loop's edits can collide with yours.

Commit incrementally to the claim's branch:

agent/t012-add-retry-backoff

(Or whatever branch prefix the project configured. The branch_prefix config key is host-project-configurable in the active layout's config.yaml; the default is agent/, and anvil claim echoes the actual branch on its Branch: line.)

Incremental commits create a recoverable trail. If the agent session is interrupted, the commits survive on the branch and the work does not need to restart from zero.

Three hook actions run automatically during this step — no manual action required:

hook dispatch check-claim (PreToolUse on Edit, Write, NotebookEdit) — warns when the file overlaps another actor's active claim scope. The warning is non-blocking: the edit proceeds. Heed it; overlap creates avoidable integration risk.

hook dispatch record-file-change (PostToolUse on Edit, Write, NotebookEdit) — appends a file_changed audit event for every editor-tool path touched. anvil submit still requires an explicit, complete --files-changed list; derive it from the actual diff rather than assuming the hook injects CLI arguments.

hook dispatch heartbeat (PostToolUse) — attempts a progress-gated lease renewal for the current actor/session. It renews only after new hook-observed file progress or a verified pending attestation.

---

Step 4 — Heartbeat the lease during long work

The default lease is 240 minutes unless project/global config or claim --lease overrides it. The automatic heartbeat handles qualified progress, but inspect anvil status and renew manually before the echoed expiry on long-running work:

anvil renew CLAIM_ID

Example:

anvil renew C004

Renewing extends lease_expires_at by the resolved lease duration from now and updates last_heartbeat_at only after qualifying progress. A missed heartbeat does not immediately lose the claim; the stale detector fires on the next coordination operation. Once the lease has expired, the task returns to ready and another agent can claim it mid-work.

Renewed claim 'C004'.
  New lease until: 2026-05-25T17:35:00.000000+00:00
  Last heartbeat:  2026-05-25T13:35:00.000000+00:00

Only the owning actor can renew. To check remaining lease time without renewing:

anvil list --status claimed

The output includes lease_expires_at for each active claim.

---

Step 5 — Run verification before submitting

Apply the work packet's structured hook_environment in the process that invokes tools, then execute the task's verification.commands. The shell-free capture-evidence dispatcher (PostToolUse Bash) captures stdout, stderr, and exit code into the claim's pending evidence buffer only when ANVIL_CLAIM_ID, ANVIL_ACTOR, active ownership, and any persisted session identity match exactly. It never guesses from a sole or actor-only claim. The legacy capture-evidence.sh wrapper delegates to the same capture command.

The verification commands are the objective acceptance gate. Submit only when all verification commands exit 0. If a command fails:

1. Read the error output.
2. Fix the code.
3. Re-run the verification command.

Do not submit failing evidence. The Review engine checks evidence_complete against the task's required_evidence list — missing or failed verification commands are flagged and block apply.

For tasks with expensive verification (integration tests, linting over a full codebase), run the cheap unit tests first to catch obvious failures before the slow gate.

---

Step 6 — Submit the completion

anvil submit TASK_ID --commands "pytest -x" --files-changed src/foo.py,src/bar.py

Additional flags:

anvil submit T012 \
  --commands "pytest -x,ruff check src/" \
  --files-changed src/anvil/claims/manager.py,src/anvil/cli.py \
  --output-file /tmp/pytest-out.log \
  --pr-url https://github.com/org/repo/pull/42

--commands and --files-changed are both required and repeatable: pass the flag once per value (one occurrence == one value, so commands or paths with embedded commas survive intact), or pass a single comma-separated occurrence for the simple case shown above. --output-file attaches up to 8000 characters as a descriptive excerpt; it never creates a typed proof or satisfies required_proofs. For an external/subagent run, repeat --command-proof-file ARTIFACT to import a bounded claim-bound proof batch. Every proof must match the explicit claim owner/context and an exact --commands value or the whole submission is refused. --pr-url links the branch's PR if one exists.

Signed command proofs also depend on current issuer membership in ANVIL_TRUST_LIST or ~/.anvil/trust.txt during both append and replay. Back up and restore that trust list with state and retain the signing key or fingerprint; missing membership fails closed. Self-attested proof replay is trust-list independent.

submit does the following atomically:

1. Writes an Evidence row to state.db with the commands run, files changed, and output excerpt.
2. Auto-releases the claim (claim.released event).
3. Transitions the task from claimed to needs_review (task.status_changed event).

The CLI prints the evidence summary immediately:

Evidence submitted for task 'T012'.
  Evidence ID:  EV066F22C4
  Claim ID:     C004 (auto-released)
  Submitted by: agent
  Commands:     ['pytest -x', 'ruff check src/']
  Files:        ['src/anvil/claims/manager.py', 'src/anvil/cli.py']

Task 'T012' status → needs_review.
Run `anvil apply T012` when ready for human review.

If the task declares required_evidence that the submission does not satisfy, the CLI appends an Evidence gate: INCOMPLETE block listing the missing items. That is advisory at submit time but blocks a strict apply.

Review the printed evidence summary before walking away. If a field looks wrong (wrong file list, missing command), inspect with anvil show T012 and coordinate with the human reviewer before they invoke apply.

---

Step 7 — Wait for apply

anvil apply TASK_ID is a human-only step. The task stays in needs_review until the human reviewer invokes it. The /anvil:finish skill drives that decision — surfacing the evidence, picking a disposition (accept, reject, hold, discard), and running apply.

Until apply is called:

• The branch persists on the claim's git branch.
• The task is visible in anvil list --status needs_review.
• No other agent can re-claim the task.

No action required here. Proceed to the next task in the queue:

anvil next

---

Edge Cases

Verification fails mid-work: do not submit. Fix and re-run. The packet's verification.commands are the contract; submit only when they all exit 0.

Claim went stale mid-work: the task has returned to ready. Re-claim it:

anvil claim T012

The branch's commits are preserved on agent/t012-<slug>. Continue work on the same branch; the new claim ID replaces the expired one. If another agent claimed the task in the window between expiry and re-claim, coordinate via anvil show T012 to check the current holder.

Need to abandon: release the claim so the task returns to the pool:

anvil release CLAIM_ID --reason "blocked on upstream T009 — not merged yet"

The --reason string is stored in the Claim row and logged in events.jsonl. Another agent picks up the task via anvil next.

Packet is stale: if the PRD was revised after the packet was generated, re-fetch:

anvil packet T012

The command overwrites the previous packet file (the CLI re-echoes Wrote packet to <path>). Re-read the packet before continuing.

---

Common Pitfalls

• Working from memory instead of the packet. anvil show TASK_ID is a summary; the packet is the full operating context. Always read the packet before writing code.
• Submitting without running all verification commands. The Review engine checks completeness at apply time. Submitting partial evidence delays the ship decision and may require reopening the task.
• Ignoring the echoed lease expiry. The automatic heartbeat is progress-gated and cannot extend a claim indefinitely without new evidence. Inspect status and renew before expiry when work is genuinely continuing.
• Submitting an incomplete file list. The record-file-change hook creates audit events, but submit takes explicit --files-changed values. Derive the complete list from the actual diff.

---

Composition with Other Skills

Position	Skill
Before this skill	/anvil:claim — active claim required before execute starts
If scope is ambiguous before step 3	Return to /anvil:state-ops to inspect conflicts; resolve before editing
If complexity >= 4 at packet read	Return to /anvil:plan — the task should have been expanded; release claim first
After submit	/anvil:finish drives the apply step and ship decision
If task returns nothing from next after submit	/anvil:state-ops to diagnose queue state

---

Surface Notes

Every command in this loop ships in the current engine. The execution surface is:

Surface	Where
anvil packet TASK_ID	renders the packet; --format json for the machine form
anvil submit TASK_ID	records evidence and auto-releases the claim
anvil apply TASK_ID	human review gate (accept / reject)
anvil conflicts	persisted conflict groups (overlapping likely_files)
hook dispatch capture-evidence	PostToolUse Bash; buffers verification output
hook dispatch check-claim	PreToolUse Edit/Write/NotebookEdit; warns on overlap with another actor's active claim scope
MCP generate_work_packet	the packet over MCP for tools/agents that consume it programmatically