agency-agents Needs a Role Handoff Card Before It Needs More Personas

msitarzewski/agency-agents is an MIT-licensed collection of specialized AI agent roles with different personalities, processes, and deliverables. The repository is popular partly because a named role is easy to understand: frontend specialist, product manager, marketing expert.

But a convincing persona does not tell a reviewer what authority changed when work moved between roles.

The UI needs a handoff card.

Handoff model

Request
  -> Role selected
  -> Evidence gathered
  -> Draft produced
  -> Handoff requested
  -> Human or next role accepts/rejects

Enter fullscreen mode Exit fullscreen mode

Every transition should remain visible. Replacing one chat avatar with another is not sufficient.

The card

A handoff card should answer:

1. From whom? The role that produced the work.
2. To whom? The next role or human owner.
3. Why now? The condition that triggered handoff.
4. What evidence? Files, sources, tests, and unresolved assumptions.
5. What authority? Read, propose, approve, or execute.
6. What expires? Time, revision, or changed plan that invalidates approval.

Example:

from: frontend-specialist
to: accessibility-reviewer
reason: interaction implementation complete
evidence:
  - src/Dialog.tsx
  - test/dialog.keyboard.spec.ts
unresolved:
  - screen-reader announcement wording
authority_requested: review-only
base_revision: 81d09a2

Enter fullscreen mode Exit fullscreen mode

Recovery states

The reviewer must be able to reject the handoff without losing prior evidence. A rejection should require a reason and return ownership to the prior role. If the underlying revision changes, mark the old handoff stale rather than silently refreshing it.

Research protocol

Give five participants the same multi-role task and ask them to predict the next tool effect before approving a handoff. Measure:

• whether they identify the current role;
• whether they find unresolved assumptions;
• whether they distinguish review from execution;
• time to reject a stale handoff;
• confidence followed by correct prediction, not confidence alone.

Stop the session if a participant approves an action they believe is read-only when it can mutate state. That is a design safety failure, not user error.

Accessibility

The handoff history needs a semantic ordered list, clear headings, keyboard-operable approve/reject controls, and status text that does not depend on agent color or avatar. Announce important state changes without streaming every intermediate thought.

Limitations

This is a proposed interface and research protocol. I have not evaluated the repository’s user interface or tested these personas with participants. Check the current README for actual installation and role definitions.

Specialization becomes useful when responsibility moves cleanly. A persona explains style; a handoff card explains accountability.