AkurAI-Build

public

Latest change 30e6b8c347048d64c2c048dfd05a8ded219d37f6 - Host authenticated Git repositories over Smart HTTP with repo host/sync CLI by Ólafur Búi Ólafsson

# Pi-agent ownership and handoff

## Roles by flow state

| State | Primary role | Required output |
| --- | --- | --- |
| Inbox/Triage | coordinator or product agent | clear demand and routing |
| Discovery | planner/researcher | actionable spec, risks, acceptance, verification |
| Ready/In Progress | implementation agent | scoped changes and evidence |
| Review | independent reviewer/security agent | findings or clean verdict |
| Verification | quality/test agent | exact current check results |
| Release Ready | human/orchestrator | explicit approval decision |
| Done | coordinator | resolution and completion record |

Roles are responsibilities, not mandatory agent names. One agent may perform
several non-conflicting roles, but implementation should not self-approve its
independent review when a reviewer is available. Upstream Inbox, Triage,
Discovery, and Ready work may remain unowned and be refined by any named
coordinator; exclusive ownership starts at `claim`/In Progress and then changes
only through an accepted handoff.

## Agent start protocol

1. Read project `AGENTS.md`, this board README, the task card, and only relevant
referenced specs/decisions.
2. Run `node .kanban/bin/kanban.mjs validate`.
3. Use `next --json` to select work or use the specifically assigned task.
4. Claim only Ready work with `claim ID --agent NAME`.
5. Verify ownership and stop if another agent owns the task or write lock.
6. Work on one bounded task. Do not have multiple agents write the same
cwd/worktree.

## During work

- Update the card, not chat memory, when requirements, decisions, dependencies,
evidence, or blockers change.
- Store no secrets or credential material.
- Append exact status-bound evidence with `evidence --stage implementation|review|verification|release|resolution --result TEXT`.
- Use `block` immediately when external action prevents progress.
- Only the recorded owner may mutate or move owned work. Transfer ownership
through a durable handoff.
- Move only through allowed transitions; force is limited to P0 and requires an
approved reason.
- Keep task body concise. Link large artifacts instead of pasting transcripts.

## Handoff protocol

Create a handoff before ending a session with unfinished owned work:

```sh
node .kanban/bin/kanban.mjs handoff KB-ID \
--from CURRENT_AGENT --to RECEIVER \
--summary "bounded objective and why it matters"
```

Fill the generated handoff sections:

- objective;
- current state;
- changes and files;
- verification evidence;
- remaining work in order;
- risks and decisions;
- exact next action;
- stop conditions.

The sender remains owner until acceptance. The receiver must read the task and
handoff, re-check current files/external state, then run:

```sh
node .kanban/bin/kanban.mjs accept KB-ID --agent RECEIVER
```

Accepted handoffs remain as an audit artifact. Never rely on a session
transcript as the only handoff.

## Review handoff

An implementation-to-review handoff must include changed paths, contract/issue,
checks already run, known residual risks, and requested review scope. The
reviewer records concrete findings with severity and file/line evidence. A clean
review is evidence, not permission to merge or deploy.

## Verification handoff

A reviewer-to-quality handoff must state the reviewed artifact/head, resolved
findings, exact checks required, and any environment limitations. Verification
must be rerun after code changes; stale evidence cannot advance the task.

## Human approval boundary

Agents stop at Release Ready unless the user/orchestrator explicitly authorizes
the external action. Approval must identify the artifact being approved.