mirror of
https://github.com/saltbo/agent-kanban.git
synced 2026-09-19 09:01:47 +08:00
feat(skills): add ak-maintainer and rename worker skill
This commit is contained in:
jarvis
@@ -172,9 +172,10 @@ roles:
|
||||
|
||||
| Skill | Purpose |
|
||||
| --- | --- |
|
||||
| [`agent-kanban`](./skills/agent-kanban/SKILL.md) | Execute an assigned Task from an Enbor Session. |
|
||||
| [`ak-task`](./skills/ak-task/SKILL.md) | Create, assign, monitor, and review one Task. |
|
||||
| [`ak-plan`](./skills/ak-plan/SKILL.md) | Plan and execute a multi-Task project. |
|
||||
| [`ak-worker`](./skills/ak-worker/SKILL.md) | Execute an assigned Task from an Agency Session; automatic invocation allowed. |
|
||||
| [`ak-maintainer`](./skills/ak-maintainer/SKILL.md) | Proactively plan, coordinate, and review multi-Task work within an authorized project. |
|
||||
| [`ak-task`](./skills/ak-task/SKILL.md) | Create, assign, monitor, and review one Task; explicit user invocation required. |
|
||||
| [`ak-plan`](./skills/ak-plan/SKILL.md) | Plan and execute a multi-Task project; explicit user invocation required. |
|
||||
|
||||
## Architecture
|
||||
|
||||
|
||||
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
@@ -2,25 +2,32 @@
|
||||
"$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
|
||||
"skills": [
|
||||
{
|
||||
"name": "agent-kanban",
|
||||
"name": "ak-maintainer",
|
||||
"type": "archive",
|
||||
"description": "Work on an assigned Agent Kanban v2 Task through Realmroot Toolbox. Use when an Agent running in an Agency Session needs to inspect, claim, update, or submit assigned work.",
|
||||
"url": "/.well-known/agent-skills/agent-kanban.tar.gz",
|
||||
"digest": "sha256:32264376a444c18f86767530e9bedb2410cb9786a478051bd605b0e09eb189f8"
|
||||
"description": "Manage authorized project work through Agent Kanban and Realmroot Toolbox, typically in scheduled-task or heartbeat-triggered Sessions. Proactively inspect what needs doing, delegate execution to other Agents, and coordinate and review their Tasks as a manager.",
|
||||
"url": "/.well-known/agent-skills/ak-maintainer.tar.gz",
|
||||
"digest": "sha256:1a6fe0914c6e1c61ce519f6fe31a20facb6cb73f0e49b791851f3bb215481f80"
|
||||
},
|
||||
{
|
||||
"name": "ak-plan",
|
||||
"type": "archive",
|
||||
"description": "Plan and execute a multi-Task project through Agent Kanban v2 resources and Realmroot Toolbox. Use only when the user explicitly asks for AK Plan, an Agent Kanban project plan, or execution of a project through an AK board.",
|
||||
"description": "Plan and execute a multi-Task project through Agent Kanban resources and Realmroot Toolbox. Use only when the user explicitly asks for AK Plan, an Agent Kanban project plan, or execution of a project through an AK board.",
|
||||
"url": "/.well-known/agent-skills/ak-plan.tar.gz",
|
||||
"digest": "sha256:4529045afb3b8122c66572b6d5d72491f02473c1fc5d3d30507669c1e4440b1d"
|
||||
"digest": "sha256:faf850821af11839805e06350157d7df9782f7a846a9725593d7885add5796f3"
|
||||
},
|
||||
{
|
||||
"name": "ak-task",
|
||||
"type": "archive",
|
||||
"description": "Create, assign, monitor, and review one Agent Kanban v2 Task through Realmroot Toolbox. Use only when the user explicitly asks for an AK Task, Agent Kanban task delegation, or execution through an AK board.",
|
||||
"description": "Create, assign, monitor, and review one Agent Kanban Task through Realmroot Toolbox. Use only when the user explicitly asks for an AK Task, Agent Kanban task delegation, or execution through an AK board.",
|
||||
"url": "/.well-known/agent-skills/ak-task.tar.gz",
|
||||
"digest": "sha256:cfebf5fde13ef8545036c900acc73b0ea2583069d47d75d9eae7ea143b32e431"
|
||||
"digest": "sha256:9e7fab6d5d583663d37b9655c03723f8202c3639d5d11fe561b0603b6019754b"
|
||||
},
|
||||
{
|
||||
"name": "ak-worker",
|
||||
"type": "archive",
|
||||
"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.",
|
||||
"url": "/.well-known/agent-skills/ak-worker.tar.gz",
|
||||
"digest": "sha256:85807079fc82e972fa4f0980b80be5b88a935fa37bc37ef52e4a064d188acbf6"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -7,7 +7,7 @@ import {
|
||||
grantDefaultAgentPermissions,
|
||||
} from "./defaultPermissions";
|
||||
|
||||
const AGENT_KANBAN_SKILL = "saltbo/agent-kanban@agent-kanban";
|
||||
const AGENT_KANBAN_SKILL = "saltbo/agent-kanban@ak-worker";
|
||||
|
||||
export interface CreateAgencyAgentInput {
|
||||
name: string;
|
||||
|
||||
@@ -1,135 +0,0 @@
|
||||
---
|
||||
name: agent-kanban
|
||||
description: Work on an assigned Agent Kanban v2 Task through Realmroot Toolbox. Use when an Agent running in an Agency Session needs to inspect, claim, update, or submit assigned work.
|
||||
---
|
||||
|
||||
# Agent Kanban v2 assigned Agent
|
||||
|
||||
Use the Realmroot identity already attached to the Agency Agent. Never run the
|
||||
removed `ak` CLI or create AK credentials, Machines, runtime Sessions, mailbox
|
||||
state, signing keys, or Agent roles.
|
||||
|
||||
## Task lifecycle
|
||||
|
||||
1. Read the Task with the generic Toolbox resource operation:
|
||||
|
||||
```bash
|
||||
realmroot toolbox get agent-kanban/tasks/<task-id> --include --json
|
||||
```
|
||||
|
||||
Treat the returned representation as authoritative. Task PATCH operations
|
||||
perform their own optimistic concurrency check; if one returns `409`, reread
|
||||
the Task before deciding whether to retry.
|
||||
|
||||
2. Claim it before changing the target repository:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
realmroot toolbox post agent-kanban/tasks/<task-id>/notes \
|
||||
--content-type application/json \
|
||||
'{"detail":"Implemented the parser and verified malformed input."}' --json
|
||||
```
|
||||
|
||||
Realmroot Toolbox v0.5.0 or newer 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:
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
Submit an explicit empty representation when the Task has no pull request:
|
||||
|
||||
```bash
|
||||
realmroot toolbox patch agent-kanban/tasks/<task-id> \
|
||||
--content-type application/merge-patch+json \
|
||||
'{"status":"in-review"}' --json
|
||||
```
|
||||
|
||||
Before an Agency 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`.
|
||||
|
||||
## Published commands
|
||||
|
||||
Use Toolbox's generic verb-first operations for AK resources:
|
||||
|
||||
```bash
|
||||
realmroot toolbox get agent-kanban/tasks/<task-id> --json
|
||||
realmroot toolbox get agent-kanban/tasks/<task-id>/notes --json
|
||||
realmroot toolbox post agent-kanban/tasks/<task-id>/notes \
|
||||
--content-type application/json @note.json --json
|
||||
realmroot toolbox post agent-kanban/tasks/<task-id>/claims --json
|
||||
realmroot toolbox patch agent-kanban/tasks/<task-id> \
|
||||
--content-type application/merge-patch+json \
|
||||
'{"status":"in-review"}' --json
|
||||
realmroot toolbox agent-kanban task wait <task-id> in-review --wait-seconds 25 --json
|
||||
```
|
||||
|
||||
`task wait` is the only AK-generated resource-first convenience command. Do
|
||||
not use the removed `task claim`, `task release`, `task review`, `task reject`,
|
||||
`task complete`, or `task cancel` aliases.
|
||||
|
||||
If Toolbox still displays those removed aliases after the server contract is
|
||||
deployed, refresh its cached operation inventory once:
|
||||
|
||||
```bash
|
||||
realmroot toolbox sync agent-kanban
|
||||
```
|
||||
|
||||
If a generated command's request shape is unclear, inspect the contract instead
|
||||
of guessing flags:
|
||||
|
||||
```bash
|
||||
realmroot toolbox patch agent-kanban/tasks/<task-id> --generate-body
|
||||
```
|
||||
|
||||
Assignment starts an Enbor Session directly. Its 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 own attached Agent
|
||||
identity; never write or guess a Session ID. AK's Session annotation records the
|
||||
creation receipt, while Claim records the verified execution identity.
|
||||
|
||||
Review rejection sends feedback to the same Session. Reread the Task and Notes,
|
||||
continue under the existing Claim, and submit a new review when finished.
|
||||
Completion and cancellation close the associated Session. Inbox messages are
|
||||
not the startup or continuation mechanism.
|
||||
|
||||
For historical business references with a personal Owner ID encoded as
|
||||
`user:<subject-id>`, the Context ID is `<subject-id>`; use an organization Owner
|
||||
ID unchanged. Delayed scheduling is not implemented.
|
||||
|
||||
## Failure handling
|
||||
|
||||
- `401` or invalid DPoP: Realmroot authority is unavailable; do not create a
|
||||
fallback credential.
|
||||
- `403`: the verified actor or grant lacks the required authority; changing a
|
||||
request body cannot grant it.
|
||||
- `409`: reread the affected resource and decide from its current state; do not
|
||||
replay a conflicting transition blindly.
|
||||
- `412`: a conditional delete used a stale resource ETag; reread before deciding
|
||||
whether deletion remains appropriate.
|
||||
- `429` or `503`: honor `Retry-After`. After an unknown Task PATCH outcome,
|
||||
reread its current representation before deciding whether to retry. Claim
|
||||
creation is idempotency-key protected.
|
||||
@@ -0,0 +1,141 @@
|
||||
---
|
||||
name: ak-maintainer
|
||||
description: Manage authorized project work through Agent Kanban and Realmroot Toolbox, typically in scheduled-task or heartbeat-triggered Sessions. Proactively inspect what needs doing, delegate execution to other Agents, and coordinate and review their Tasks as a manager.
|
||||
---
|
||||
|
||||
# AK Maintainer
|
||||
|
||||
## Invocation and scope
|
||||
|
||||
Select this skill proactively when coordinating an authorized project through
|
||||
AK; the user does not need to name it. Typical entry points are Sessions
|
||||
started by a scheduled task or heartbeat to maintain an existing project or
|
||||
Board. Stay within the trigger's project objective and existing authorization.
|
||||
|
||||
Act as the manager: inspect, prioritize, decompose, assign, monitor, and review.
|
||||
Use AK Tasks to drive other Agents to perform the work. Do not claim or assign
|
||||
implementation Tasks to yourself, edit the target repository to implement them,
|
||||
or take over a worker's corrections. Repository inspection and acceptance
|
||||
verification are part of management; implementation belongs to the assigned
|
||||
worker using `ak-worker`. If no suitable worker is available, record the blocker
|
||||
instead of doing the work yourself.
|
||||
|
||||
## Recommended scheduled or heartbeat workflow
|
||||
|
||||
1. Read the trigger's objective and the current Board, Tasks, Notes, dependencies,
|
||||
and relevant repository state. Determine what needs doing now: missing work,
|
||||
ready unassigned Tasks, blocked dependencies, or submissions awaiting review.
|
||||
Use current AK resources as the source of truth across Sessions.
|
||||
2. Review pending submissions and resolve actionable coordination issues. Reuse
|
||||
or update existing Tasks before creating new ones; repeated wakeups must not
|
||||
duplicate work that is already planned, assigned, or completed. A Task that
|
||||
has not changed since the previous heartbeat is not by itself a reason to
|
||||
reassign it or create replacement work.
|
||||
3. Turn uncovered work into independently reviewable Tasks with clear goals,
|
||||
repositories, dependencies, and acceptance checks. Assign execution to other
|
||||
schedulable Agents through AK. Order overlapping work and let independent
|
||||
Tasks progress in parallel.
|
||||
4. Inspect meaningful progress and review completed submissions. Return required
|
||||
corrections to the assigned worker with a concrete reason; complete a Task
|
||||
only when its acceptance evidence is sufficient. Reassess dependent work
|
||||
after each completion.
|
||||
5. Respect the current Session's run budget. Record useful decisions, blockers,
|
||||
and next actions in the affected Task Notes so the next scheduled or heartbeat
|
||||
Session can resume from AK state. If nothing is actionable, finish quietly.
|
||||
Follow the trigger's reporting policy; normally notify only on meaningful
|
||||
completion, failure, or a decision requiring the user.
|
||||
|
||||
## Plan before creating
|
||||
|
||||
Read the repository and existing AK resources before decomposition:
|
||||
|
||||
```bash
|
||||
realmroot toolbox get agent-kanban/boards --json
|
||||
realmroot toolbox get agent-kanban/repositories --json
|
||||
realmroot toolbox get 'agent-kanban/tasks?boardId=<board-id>' --json
|
||||
```
|
||||
|
||||
Define the architecture direction, shared contracts, ownership boundaries, and
|
||||
dependency graph. Split work by independently reviewable behavior or module
|
||||
boundary, not by chronological steps or job titles. Avoid a final catch-all QA
|
||||
Task; each Task owns its implementation and proof.
|
||||
|
||||
Prepare a complete Board/Task preview with every Task's goal, assignee,
|
||||
repository, dependencies, and acceptance checks. Proceed when the existing
|
||||
request authorizes that work; ask for confirmation only when the concrete plan
|
||||
needs additional scope or authority.
|
||||
|
||||
## Create resources
|
||||
|
||||
Create a Board or Repository only when it does not already exist:
|
||||
|
||||
```bash
|
||||
realmroot toolbox post agent-kanban/boards --content-type application/json @board.json --json
|
||||
realmroot toolbox post agent-kanban/repositories --content-type application/json @repository.json --json
|
||||
```
|
||||
|
||||
Select an available Agent that reports `schedulable: true`:
|
||||
|
||||
```bash
|
||||
realmroot toolbox get 'agent-kanban/agents?schedulable=true' --json
|
||||
```
|
||||
|
||||
Use the selected Agent's `subject` as `assignedTo`. If no suitable
|
||||
Agent exists and the caller is authorized to provision one, create it through
|
||||
`agent-kanban/agents`.
|
||||
|
||||
For each authorized work item, create an unassigned Task, then patch its
|
||||
`assignedTo` field:
|
||||
|
||||
```bash
|
||||
realmroot toolbox post agent-kanban/tasks --content-type application/json @task.json --json
|
||||
realmroot toolbox patch agent-kanban/tasks/<task-id> \
|
||||
--content-type application/merge-patch+json \
|
||||
'{"assignedTo":"<realmroot-agent-actor-id>"}' --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.
|
||||
|
||||
Encode real prerequisites in `dependsOn`. Tasks with overlapping files or
|
||||
contracts should be combined or ordered; only independent Tasks should run in
|
||||
parallel.
|
||||
|
||||
## Coordinate and review
|
||||
|
||||
After assignment, follow progress within the current Session's run budget.
|
||||
Use bounded waits with continuation cursors when waiting is useful; scheduled
|
||||
or heartbeat Sessions may finish with Tasks still active and resume on the next
|
||||
existing trigger. Do not create another schedule merely to keep waiting.
|
||||
|
||||
```bash
|
||||
realmroot toolbox agent-kanban task wait <task-id> in-review --wait-seconds 25 --json
|
||||
```
|
||||
|
||||
When the Task reaches `in-review`, verify the submitted work, then reread the
|
||||
Task before making the review decision:
|
||||
|
||||
```bash
|
||||
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-progress","statusReason":"Describe the required correction"}' --json
|
||||
|
||||
realmroot toolbox patch agent-kanban/tasks/<task-id> \
|
||||
--content-type application/merge-patch+json \
|
||||
'{"status":"done"}' --json
|
||||
```
|
||||
|
||||
Reject when acceptance evidence or implementation is insufficient, then wait
|
||||
for a new `in-review` Task state. Complete only after the requested outcome is
|
||||
proven. Send corrections back to the worker instead of implementing them
|
||||
yourself. If the verified reviewer actor equals the Task's
|
||||
`assignedTo`, do not attempt either decision; another authorized principal
|
||||
must review.
|
||||
|
||||
When one prerequisite completes, reassess its dependent Tasks.
|
||||
When a report is warranted, include Task states, review outcomes, and unresolved
|
||||
external blockers without implying that active Tasks are complete.
|
||||
@@ -0,0 +1,2 @@
|
||||
policy:
|
||||
allow_implicit_invocation: true
|
||||
+29
-32
@@ -1,15 +1,9 @@
|
||||
---
|
||||
name: ak-plan
|
||||
description: Plan and execute a multi-Task project through Agent Kanban v2 resources and Realmroot Toolbox. Use only when the user explicitly asks for AK Plan, an Agent Kanban project plan, or execution of a project through an AK board.
|
||||
description: Plan and execute a multi-Task project through Agent Kanban resources and Realmroot Toolbox. Use only when the user explicitly asks for AK Plan, an Agent Kanban project plan, or execution of a project through an AK board.
|
||||
---
|
||||
|
||||
# AK Plan v2
|
||||
|
||||
Model the project as Boards, Tasks, dependencies, Repositories, and Claims.
|
||||
Assignment and review outcomes are Task fields and status transitions. Realmroot grants provide authority;
|
||||
there are no Agent role classes, maintainer, mailbox, handoff-routing, or
|
||||
AK-owned Agent/Machine runtime entities. AK exposes Agency-backed Agent and
|
||||
Machine projections as product resources.
|
||||
# AK Plan
|
||||
|
||||
## Plan before creating
|
||||
|
||||
@@ -32,25 +26,22 @@ acceptance checks.
|
||||
|
||||
## Create resources
|
||||
|
||||
Use Toolbox's generic verb-first operations. Create a Board or Repository only
|
||||
when it does not already exist:
|
||||
Create a Board or Repository only when it does not already exist:
|
||||
|
||||
```bash
|
||||
realmroot toolbox post agent-kanban/boards --content-type application/json @board.json --json
|
||||
realmroot toolbox post agent-kanban/repositories --content-type application/json @repository.json --json
|
||||
```
|
||||
|
||||
Discover executable Agents through AK's Agency-backed projection and select
|
||||
only an Agent that currently reports `schedulable: true`:
|
||||
Select an available Agent that reports `schedulable: true`:
|
||||
|
||||
```bash
|
||||
realmroot toolbox get 'agent-kanban/agents?schedulable=true' --json
|
||||
```
|
||||
|
||||
Use the selected Agent's `subject` as the Assignment actor ID. If no suitable
|
||||
Use the selected Agent's `subject` as `assignedTo`. If no suitable
|
||||
Agent exists and the caller is authorized to provision one, create it through
|
||||
AK's generic `/agents` collection operation; AK owns the Identity-plus-Agent
|
||||
orchestration. Do not call Agency directly or create an AK-local Agent row.
|
||||
`agent-kanban/agents`.
|
||||
|
||||
For each approved work item, create an unassigned Task, then patch its
|
||||
`assignedTo` field:
|
||||
@@ -62,14 +53,14 @@ realmroot toolbox patch agent-kanban/tasks/<task-id> \
|
||||
'{"assignedTo":"<realmroot-agent-actor-id>"}' --json
|
||||
```
|
||||
|
||||
Realmroot Toolbox v0.5.0 or newer generates the required idempotency key and
|
||||
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.
|
||||
|
||||
Encode real prerequisites in `dependsOn`. Tasks with overlapping files or
|
||||
contracts should be combined or ordered; only independent Tasks should run in
|
||||
parallel. Do not create AK-local Agent, Machine, Session, or subagent rows.
|
||||
parallel.
|
||||
|
||||
## Execute and review
|
||||
|
||||
@@ -80,20 +71,26 @@ stop. Use bounded waits with continuation cursors:
|
||||
realmroot toolbox agent-kanban task wait <task-id> in-review --wait-seconds 25 --json
|
||||
```
|
||||
|
||||
As Tasks reach review, follow the review procedure in the installed `ak-task`
|
||||
skill: read the current Task, verify the work, then patch it to
|
||||
`in-progress` with a reason or to `done` from a different verified actor. A
|
||||
rejection creates another work iteration and a new Task representation.
|
||||
When the Task reaches `in-review`, verify the submitted work, then reread the
|
||||
Task before making the review decision:
|
||||
|
||||
When one prerequisite completes, continue monitoring its dependents. Agency
|
||||
owns Agent execution; AK only exposes the updated dependency and Task state.
|
||||
```bash
|
||||
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-progress","statusReason":"Describe the required correction"}' --json
|
||||
|
||||
realmroot toolbox patch agent-kanban/tasks/<task-id> \
|
||||
--content-type application/merge-patch+json \
|
||||
'{"status":"done"}' --json
|
||||
```
|
||||
|
||||
Reject when acceptance evidence or implementation is insufficient, then wait
|
||||
for a new `in-review` Task state. Complete only after the requested outcome is
|
||||
proven. If the verified reviewer actor equals the Task's
|
||||
`assignedTo`, do not attempt either decision; another authorized principal
|
||||
must review.
|
||||
|
||||
When one prerequisite completes, reassess its dependent Tasks.
|
||||
Report the final Task states, review outcomes, and unresolved external blockers.
|
||||
|
||||
Ordinary published resource operations use generic verbs. Toolbox generates
|
||||
the required idempotency key for Task, Task Note, Agent, and Machine creation
|
||||
and reuses it across transient retries. Board and Repository creation do not
|
||||
require the header. Board labels and destructive management remain
|
||||
browser-owned in this release.
|
||||
Only bounded Task Event waiting retains the generated resource-first `task
|
||||
wait` command. All Task and Claim writes use generic Toolbox verbs. Never
|
||||
invoke the removed `ak` CLI or removed lifecycle aliases.
|
||||
|
||||
@@ -0,0 +1,2 @@
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
+11
-26
@@ -1,15 +1,9 @@
|
||||
---
|
||||
name: ak-task
|
||||
description: Create, assign, monitor, and review one Agent Kanban v2 Task through Realmroot Toolbox. Use only when the user explicitly asks for an AK Task, Agent Kanban task delegation, or execution through an AK board.
|
||||
description: Create, assign, monitor, and review one Agent Kanban Task through Realmroot Toolbox. Use only when the user explicitly asks for an AK Task, Agent Kanban task delegation, or execution through an AK board.
|
||||
---
|
||||
|
||||
# AK Task v2
|
||||
|
||||
Operate AK as a Realmroot Resource Server. There are no Agent role classes or
|
||||
board maintainer role: Realmroot grants authorize management operations, the
|
||||
Task's `assignedTo` field identifies the assigned Agent, and any authorized human or Agent
|
||||
may review a Task assigned to someone else. An Agent cannot reject or complete
|
||||
its own assigned Task.
|
||||
# AK Task
|
||||
|
||||
## Before creation
|
||||
|
||||
@@ -21,17 +15,15 @@ realmroot toolbox get agent-kanban/repositories --json
|
||||
realmroot toolbox get 'agent-kanban/tasks?boardId=<board-id>' --json
|
||||
```
|
||||
|
||||
Discover assignment candidates through AK's Agency-backed Agent projection:
|
||||
Find available Agents:
|
||||
|
||||
```bash
|
||||
realmroot toolbox get 'agent-kanban/agents?schedulable=true' --json
|
||||
```
|
||||
|
||||
Use the selected Agent's `subject` as the Assignment actor ID; never use its
|
||||
AK projection ID or an Agency object ID. If no suitable Agent exists and the
|
||||
caller is authorized to provision one, create it through AK's generic
|
||||
`/agents` collection operation. AK orchestrates the upstream Identity and
|
||||
Agent creation; execution remains owned by Agency.
|
||||
Use the selected Agent's `subject` as `assignedTo`. If no suitable Agent
|
||||
exists and provisioning is authorized, create one through
|
||||
`agent-kanban/agents`.
|
||||
|
||||
Resolve material ambiguity and show the user the exact Task preview before
|
||||
creating it. The preview must include title, Board, Repository, assignee,
|
||||
@@ -51,17 +43,15 @@ realmroot toolbox patch agent-kanban/tasks/<task-id> \
|
||||
'{"assignedTo":"<realmroot-agent-actor-id>"}' --json
|
||||
```
|
||||
|
||||
Realmroot Toolbox v0.5.0 or newer generates the required idempotency key and
|
||||
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.
|
||||
|
||||
The Task body uses lowerCamelCase resource fields such as `boardId`, `title`,
|
||||
`description`, `repositoryId`, `labels`, `dependsOn`, `createdFrom`, and
|
||||
`scheduledAt`. Delayed scheduling is not implemented: omit `scheduledAt` when
|
||||
creating Tasks. Non-null schedule writes return 422; an existing schedule can
|
||||
be cleared with null. Assignment records intent only; Agency owns starting and
|
||||
hosting the Agent. After an unknown PATCH outcome, reread the Task before
|
||||
`scheduledAt`. Omit `scheduledAt` when creating Tasks; delayed scheduling is
|
||||
not supported. After an unknown PATCH outcome, reread the Task before
|
||||
deciding whether another write is necessary; do not create another Task.
|
||||
|
||||
## Monitor
|
||||
@@ -78,7 +68,7 @@ operations. A cancelled Task is terminal.
|
||||
|
||||
## Review
|
||||
|
||||
When the Task reaches `in_review`, verify the submitted work, then reread the
|
||||
When the Task reaches `in-review`, verify the submitted work, then reread the
|
||||
Task before making the review decision:
|
||||
|
||||
```bash
|
||||
@@ -96,7 +86,7 @@ realmroot toolbox patch agent-kanban/tasks/<task-id> \
|
||||
Reject when acceptance evidence or implementation is insufficient, then wait
|
||||
for a new `in-review` Task state. Complete only after the requested outcome is
|
||||
proven. If the verified reviewer actor equals the Task's
|
||||
`assigned_to`, do not attempt either decision; another authorized principal
|
||||
`assignedTo`, do not attempt either decision; another authorized principal
|
||||
must review.
|
||||
|
||||
Cancel a non-terminal Task through the same Task patch:
|
||||
@@ -106,8 +96,3 @@ realmroot toolbox patch agent-kanban/tasks/<task-id> \
|
||||
--content-type application/merge-patch+json \
|
||||
'{"status":"cancelled"}' --json
|
||||
```
|
||||
|
||||
Use generic verb-first Toolbox operations for every Task mutation and Claim
|
||||
creation.
|
||||
`task wait` is the only generated resource-first convenience command. Never
|
||||
invoke the removed `ak` CLI or the removed lifecycle aliases.
|
||||
|
||||
@@ -0,0 +1,2 @@
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
@@ -0,0 +1,92 @@
|
||||
---
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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`:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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.
|
||||
@@ -0,0 +1,2 @@
|
||||
policy:
|
||||
allow_implicit_invocation: true
|
||||
@@ -78,20 +78,20 @@ describe("Agent Skills Discovery artifacts", () => {
|
||||
await mkdir(path.join(fixtureRoot, "scripts"), { recursive: true });
|
||||
await cp(path.join(root, "scripts", "build-agent-skills.mjs"), path.join(fixtureRoot, "scripts", "build-agent-skills.mjs"));
|
||||
await cp(skillsRoot, path.join(fixtureRoot, "skills"), { recursive: true });
|
||||
const reference = path.join(fixtureRoot, "skills", "agent-kanban", "references", "toolbox.md");
|
||||
const reference = path.join(fixtureRoot, "skills", "ak-worker", "references", "toolbox.md");
|
||||
await mkdir(path.dirname(reference), { recursive: true });
|
||||
await writeFile(reference, "initial instructions\n");
|
||||
|
||||
const script = path.join(fixtureRoot, "scripts", "build-agent-skills.mjs");
|
||||
execFileSync(process.execPath, [script]);
|
||||
const archive = await readFile(path.join(fixtureRoot, "public", ".well-known", "agent-skills", "agent-kanban.tar.gz"));
|
||||
const archive = await readFile(path.join(fixtureRoot, "public", ".well-known", "agent-skills", "ak-worker.tar.gz"));
|
||||
expect(readTarFiles(archive).get("references/toolbox.md")?.toString()).toBe("initial instructions\n");
|
||||
|
||||
await writeFile(reference, "changed instructions\n");
|
||||
const check = spawnSync(process.execPath, [script, "--check"], { encoding: "utf8" });
|
||||
|
||||
expect(check.status).not.toBe(0);
|
||||
expect(check.stderr).toContain("agent-kanban.tar.gz is stale. Run pnpm run build:skills.");
|
||||
expect(check.stderr).toContain("ak-worker.tar.gz is stale. Run pnpm run build:skills.");
|
||||
} finally {
|
||||
await rm(fixtureRoot, { recursive: true, force: true });
|
||||
}
|
||||
|
||||
@@ -743,7 +743,7 @@ describe("Agent and Machine projection HTTP resources", () => {
|
||||
systemPrompt: "Handle concurrent work",
|
||||
provider: null,
|
||||
model: null,
|
||||
skills: ["saltbo/agent-kanban@agent-kanban"],
|
||||
skills: ["saltbo/agent-kanban@ak-worker"],
|
||||
allowedTools: [],
|
||||
identity: { agentId: "realmroot-concurrent", subject: "agent-concurrent-subject", username: "concurrent-agent", runtime: "codex" },
|
||||
},
|
||||
|
||||
@@ -29,7 +29,7 @@ const input = {
|
||||
systemPrompt: "Build reliable APIs",
|
||||
provider: "openai",
|
||||
model: "gpt-5.6",
|
||||
skills: ["agent-kanban"],
|
||||
skills: ["example/custom-skill"],
|
||||
idempotencyKey: "agent-create-key",
|
||||
};
|
||||
|
||||
@@ -91,7 +91,7 @@ describe("Agent SDK orchestration", () => {
|
||||
systemPrompt: "Build reliable APIs",
|
||||
provider: "openai",
|
||||
model: "gpt-5.6",
|
||||
skills: ["agent-kanban", "saltbo/agent-kanban@agent-kanban"],
|
||||
skills: ["example/custom-skill", "saltbo/agent-kanban@ak-worker"],
|
||||
identityRef: "identity-1",
|
||||
},
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user