---
kind: epic
slug: convoy-lifecycle-mcp
title: Convoy lifecycle MCP — state machine and convoy_events
plan_slug: automation-foundation
status: done
priority: P1
tenant_id: global
cursor_epic_id: null
updated_at: "2026-07-03"
---

# Epic objective

Implement agent-pipeline **Phase 2a** convoy lifecycle in Echodo MCP: `create_convoy`, `create_brief`, `transition_convoy_status`, `log_convoy_event`, `query_manifest_status`, `reconcile_from_files`.

Server-enforced state machine (draft → convoy_review → ready → in_progress → pr_review → merged → released). Human gate actors (`human-gate-1/2/3`) only for their transitions.

Reference: agent-pipeline v0.4 plan §7; local-first `.convoys/` with `.pending-mcp-sync.jsonl` outbox.

## In scope / out of scope

**In scope**

- MCP tools in `apps/mcp-server`.
- `convoy_events` table (or extend `agent_runs` pattern).
- Map convoy → Echodo `project` object; brief → `task` child (per v0.4 object mapping).
- Extended status enum documented; UI filters updated in Epic 5.

**Out of scope**

- Orchestrator auto-dispatch (Epic 6).
- Deliverable templates (agent-pipeline Phase 2b).

## Dependencies

- Epic 2 (convoy file conventions).
- Epic 3 (workspace `convoys-<repo>` convention).

## Blocks

- Epic 5, 6, 9.

## Acceptance criteria

- [x] Invalid transition `draft → released` rejected with structured error.
- [x] `role-architect` cannot call `human-gate-1` transition.
- [x] Offline convoy edit reconciles via `reconcile_from_files`.

## Tasks

- [x] [Task-shared-convoy-state-machine](./Task-shared-convoy-state-machine.md)
- [x] [Task-db-convoy-events-migration](./Task-db-convoy-events-migration.md)
- [x] [Task-mcp-convoy-lifecycle-tools](./Task-mcp-convoy-lifecycle-tools.md)