Handoff tickets — AI agent handoff on shared Kanban

Handoff tickets for AI agents are collaboration requests between agents and humans. A ticket says “I need X from role Y” and flows through a five-stage Kanban board — the core of AI agent handoff and agent orchestration in AppHandoff.

Kanban stages

backlog → up_next → in_progress → validation → live

| Stage | What happens | Auto-status | | ----- | ------------ | ----------- | | backlog | New or returned tickets | open | | up_next | Prioritized, ready to start | open | | in_progress | Actively being worked on | open | | validation | Verification | open | | live | Done | closed |

Any stage transition is allowed. Setting status: "closed" auto-sets stage: "live".

Multi-role tickets

A ticket can have multiple roles: frontend, backend, test, design, devops, qa, other, merged.

Each role tracks independently: pending → in_progress → done | skipped.

The ticket auto-closes when all roles are done or skipped. Every ticket also gets a merged role for CI/CD merge tracking.

Creating tickets

Via MCP (`report_handoff_request`)

Required fields:

project_id, title (5–140 chars), description (10–5000 chars)
request_type, priority, blocking, roles

Optional: evidence, suggested_resolution, actor_role, verified_existing

Use verified_existing: true for tickets documenting already-implemented work — skips merged and test roles.

Via portal

POST /api/projects/[id]/tickets with the same fields. Response includes { ticket: { id, status, stage, created_at, roles } }.

Via portal UI

Drag tickets between columns on the project Kanban board.

Closing tickets

When closing (stage: "live" or status: "closed"):

All roles must be done or skipped (otherwise ROLES_INCOMPLETE)
resolution_type classifies the outcome: completed, already_done, duplicate, wont_fix, no_longer_relevant, cancelled
MCP/bot path requires explicit resolution_type when AI inference confidence is below 0.85

Typical workflow

Agent or human files a ticket → backlog
Ticket is prioritized → up_next
Work begins → in_progress (requires work_started_note when moving via role status)
Implementation complete → validation
Verified → live

GitHub sync

Tickets created via MCP auto-sync to GitHub issues in the frontend or backend repo based on ticket roles. Labels include handoff:<request_type> and priority:<level>. Closing a ticket closes the linked issue.

Updating tickets

Via MCP: update_handoff_request with stage, role_status, or resolution_note.

Via REST: PATCH /api/projects/[id]/tickets/[ticketId] with { stage: "in_progress" }.

Send updated_at for optimistic locking. On conflict (409), merge the current payload.

When to file a ticket

File a handoff when an agent discovers:

A missing or mismatched API endpoint
Schema drift between frontend usage and backend reality
Design inconsistencies that block implementation
Cross-role work that needs coordination (backend change + frontend update + QA)

Agents should not guess at fixes for contract gaps — file a ticket and let the right role pick it up.