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.