/ak-worker

name: ak-worker
description: Work on an assigned Agent Kanban Task through Realmroot Toolbox. Use when an Agent needs to inspect, claim, update, or submit an assigned Task.

AK Worker

Use your existing Realmroot Agent identity.

Task lifecycle

1. Read the Task with the generic Toolbox resource operation:

   realmroot toolbox get agent-kanban/tasks/<task-id> --include --json

Read the current Task instructions and acceptance checks before acting.

2. Claim it before changing the target repository:

   realmroot toolbox post agent-kanban/tasks/<task-id>/claims --json

If the claim is rejected, stop without modifying the repository. Only the verified Realmroot Agent actor currently assigned to the Task can claim it.

3. Record useful progress as Task Note resources:

   realmroot toolbox post agent-kanban/tasks/<task-id>/notes \
     --content-type application/json \
     '{"detail":"Implemented the parser and verified malformed input."}' --json

Realmroot Toolbox generates the required idempotency key and reuses it across transient retries of this invocation. Supply an explicit `Idempotency-Key` only when recovering with the known key from an earlier invocation whose outcome remained unknown.

4. Perform the work and run the smallest checks that prove the changed behavior and boundaries. Put repository work on a reviewable branch. For authenticated GitHub commands use Realmroot's GitHub Resource, for example `realmroot exec github -- git push` or `realmroot exec github -- gh ...`.

5. Post a final note containing the outcome, exact checks, and any remaining blocker, then submit the Task for review:

   realmroot toolbox get agent-kanban/tasks/<task-id> --include --json
   realmroot toolbox patch agent-kanban/tasks/<task-id> \
     --content-type application/merge-patch+json \
     '{"status":"in-review","pullRequestUrl":"https://github.com/owner/repo/pull/123"}' --json

When the Task has no pull request, omit `pullRequestUrl`:

   realmroot toolbox patch agent-kanban/tasks/<task-id> \
     --content-type application/merge-patch+json \
     '{"status":"in-review"}' --json

Before the work Session stops, its claimed Task must be submitted for review. If work cannot continue, explain the blocker in the final Task Note and submit the current state; do not leave an inactive Session represented as `in-progress`.

Task context and command discovery

If the request fields are unclear, inspect the accepted body:

realmroot toolbox patch agent-kanban/tasks/<task-id> --generate-body

The Session's initial prompt supplies the Task ID and exact AK Context ID. Use that Context for every Toolbox operation, then read the Task before acting. Claim the Task using your existing Agent identity.

On review rejection, reread the Task and Notes, continue under the existing Claim, and submit a new review when finished. Completion and cancellation end the work Session.

Failure handling

• `401` or `403`: stop and report the authentication or permission blocker.
• `409`: reread the affected resource and decide from its current state; do not

replay a conflicting transition blindly.

• `429` or `503`: honor `Retry-After`. After an unknown Task PATCH outcome,

reread its current representation before deciding whether to retry.