39 lines
1.5 KiB
Markdown
39 lines
1.5 KiB
Markdown
|
# Convoy lifecycle
|
||
|
|
|
||
|
|
Server-enforced convoy state machine for the agent pipeline (Epic 4). Convoys map to Echodo `project` objects; briefs map to child `task` objects.
|
||
|
|
|
||
|
|
## Status enum
|
||
|
|
|
||
|
|
`draft` → `convoy_review` → `ready` → `in_progress` → `pr_review` → `merged` → `released`
|
||
|
|
|
||
|
|
Terminal / exceptional: `blocked`, `cancelled`
|
||
|
|
|
||
|
|
## MCP tools
|
||
|
|
|
||
|
|
| Tool | Purpose |
|
||
|
|
|------|---------|
|
||
|
|
| `create_convoy` | Create `project` at `draft` with convoy metadata in `content` |
|
||
|
|
| `create_brief` | Create child `task` brief under a convoy |
|
||
|
|
| `transition_convoy_status` | Enforce actor + transition rules; writes `convoy_events` |
|
||
|
|
| `log_convoy_event` | Append role metrics / analytics row |
|
||
|
|
| `query_manifest_status` | Convoy status, briefs, recent events |
|
||
|
|
| `reconcile_from_files` | Import `.convoys/*.md` into Echodo; report pending outbox |
|
||
|
|
|
||
|
|
## Gate actors
|
||
|
|
|
||
|
|
- `human-gate-1` — plan approval (`convoy_review` ↔ `ready` / `draft`)
|
||
|
|
- `human-gate-2` — PR merge gate (`pr_review` ↔ `merged` / `in_progress`)
|
||
|
|
- `human-gate-3` — prod promote (`merged` → `released`)
|
||
|
|
|
||
|
|
Pipeline roles (`role-architect`, `role-implementer`, …) cannot perform gate transitions.
|
||
|
|
|
||
|
|
## Local-first
|
||
|
|
|
||
|
|
Convoy markdown lives in `.convoys/` (see `.convoys/README.md`). Failed MCP calls should append to `.convoys/.pending-mcp-sync.jsonl`; `reconcile_from_files` reports and clears the outbox after sync.
|
||
|
|
|
||
|
|
## Implementation
|
||
|
|
|
||
|
|
- State machine: `packages/shared/src/convoy-lifecycle/`
|
||
|
|
- Events table: `packages/database/src/schema/convoy_events.ts`
|
||
|
|
- MCP: `apps/mcp-server/src/tools/*convoy*`
|