dab939bcd5
Implements the Phase 2a Echodo bridge described in agent-pipeline's v0.4 plan (.cursor/plans/pipeline_v0.4_design_+_echodo_54a3bdb7). Echodo becomes the projection layer over the local .convoys/ tree; local files remain source of truth per the local-first contract. MCP lifecycle tools (apps/mcp-server/src/tools/): - create-convoy.ts: registers create_convoy. Creates a Drizzle `project` object with status="draft" + appends initial "## Status log" to the description. Takes workspace_slug + slug + title + classification + skip_flags + success_metric + idea_markdown + repo. - create-brief.ts: registers create_brief. Creates a `task` child of the convoy project. Takes convoyId + briefNumber + title + files_allowlist + depends_on + acceptance_criteria + brief_markdown. - transition-convoy-status.ts: registers transition_convoy_status. Enforces the 9-status state machine from plan §7.3 with valid transitions + actor-permission gates. Appends an audit entry to the description's ## Status log per transition. - log-convoy-event.ts: registers log_convoy_event. Inserts events into the new convoy_events table (one row per role hand-off, with classification, skip-flags, duration, stack-class, outcome, multitask-group metadata). - query-manifest-status.ts: registers query_manifest_status (stub — depends on the Phase 4 pipeline_drift_reports table; documented). - reconcile-from-files.ts: registers reconcile_from_files implementing the local-first recovery path. Reads .convoys/.pending-mcp-sync.jsonl from the given repoPath, replays queued log_convoy_event + transition_convoy_status calls, updates the outbox file on success/failure. Resolves the SPOF risk: failed MCP calls during offline windows reconcile when the bridge returns. Database (packages/database/): - src/schema/convoy_events.ts: new Drizzle schema. Columns: id, workspaceId, convoyId, convoySlug, role, brief, classification, skipFlags, durationS, stackClass, repo, outcome, multitaskGroup, metadata, ts. 4 indexes for per-workspace + per-convoy + role-filtered reads. - src/schema/index.ts: re-exports the new table. - migrations/0010_wandering_the_professor.sql + meta snapshot: generated via drizzle-kit generate. Pure-additive (CREATE TABLE + indexes + FKs). - package.json: db:migrate / db:push / db:studio now use node --env-file to load ../../.env (consistent with the existing mcp-server tsx pattern). db:generate stays as-is (offline operation, no env needed). L1 + L3 agent-pipeline scaffolding installed per agent-pipeline/skills/bootstrap-agent-context v0.5.0: - .agent-context-manifest.yml: tracks 17 artifacts at pipeline version 0.5.0 with sha256 hashes. 4 artifacts flagged customized:true (no-go-zones, CODEOWNERS, pr-health-rollup.yml, echodo.config.json) — adapted from templates for Echodo's monorepo + Drizzle + Coolify + workspace_slug. - .convoys/README.md: explains convoy file convention. - .cursor/agents/echodo.config.json: workspace_slug=convoys-tasks (the workspace created in Echodo UI). Fallback policy: local-only. - .cursor/rules/no-go-zones.mdc: adapted for Drizzle migrations, Coolify deploy infra, mcp-server boundaries. - .github/CODEOWNERS: @rstillw as sole maintainer; targeted rules for apps/, packages/, auth, deploy infra, DB schema, MCP server, agent context. - .github/PULL_REQUEST_TEMPLATE.md: pipeline PR template. - .github/workflows/agent-context-drift.yml: drift monitor against upstream agent-pipeline. - .github/workflows/pr-health-rollup.yml: adapted for tasks' pnpm monorepo + Coolify deploy (no per-PR preview by default). - scripts/log-convoy-event.sh: convoy event logger shim. - scripts/wt.sh: worktree helper stub (deprecated — points at Cursor 3.2 native worktrees). - .gitignore: excludes .convoys/.metrics.jsonl + .convoys/.pending-mcp-sync.jsonl (local agent analytics + MCP outbox). Co-authored-by: Cursor <cursoragent@cursor.com>
121 lines
4.3 KiB
Markdown
121 lines
4.3 KiB
Markdown
# Convoys
|
|
|
|
A **convoy** is a multi-PR work-stream coordinated by an agent pipeline. One convoy = one feature, bug fix, or epic. Each convoy is a Markdown file in this directory plus an optional sub-directory of implementer briefs.
|
|
|
|
## File layout
|
|
|
|
```
|
|
.convoys/
|
|
├── README.md (this file)
|
|
├── <slug>.md (the convoy file — written by role-conductor)
|
|
└── <slug>/
|
|
├── brief-1-<kebab-title>.md (written by role-architect)
|
|
├── brief-2-<kebab-title>.md
|
|
└── ...
|
|
```
|
|
|
|
## Convoy file format
|
|
|
|
Frontmatter (set by `role-conductor`, then appended-to by other roles):
|
|
|
|
```yaml
|
|
---
|
|
name: <kebab-slug>
|
|
classification: feature | hotfix | docs-only | infra-only | server-only | config-only
|
|
success_metric: <one sentence>
|
|
skip:
|
|
- <flag1>
|
|
status: open | in-progress | merged | shipped | abandoned
|
|
created: <YYYY-MM-DD>
|
|
---
|
|
```
|
|
|
|
Body sections (added in order by the pipeline roles):
|
|
|
|
1. `## Why` (Conductor)
|
|
2. `## Scope` (Conductor)
|
|
3. `## Roles invoked` (Conductor)
|
|
4. `## Todos` (Conductor → refined by Architect)
|
|
5. `## IA` (IA Architect)
|
|
6. `## UX` (UX Reviewer)
|
|
7. `## Architecture` (Architect)
|
|
|
|
After Architect, briefs live in `.convoys/<slug>/brief-N-*.md`. Implementers read only their brief, not the whole convoy.
|
|
|
|
## Skip flags
|
|
|
|
The Conductor sets `skip:` based on classification. These flags map to pipeline stages that no-op when set:
|
|
|
|
| Flag | Skips |
|
|
| --- | --- |
|
|
| `ia` | IA Architect |
|
|
| `ux` | UX Reviewer |
|
|
| `arch` | Architect |
|
|
| `test` | Component tests |
|
|
| `review` | Reviewer |
|
|
| `visual` | Visual diff |
|
|
| `a11y` | A11y auditor |
|
|
| `design` | Design-system auditor |
|
|
| `smoke` | Staging smoke |
|
|
| `qa` | Manual QA |
|
|
| `docs` | Doc Writer |
|
|
| `flag` | Flag rollout |
|
|
|
|
Never skipped (mandatory human gates): `plan-approval`, `pr-merge`, `prod-promote`.
|
|
|
|
## Status lifecycle
|
|
|
|
- `open` — Conductor created the convoy; no work started.
|
|
- `in-progress` — At least one brief has an open or merged PR.
|
|
- `merged` — All briefs merged to umbrella; release PR to develop pending.
|
|
- `shipped` — Release to main complete; flag rollout (if any) underway.
|
|
- `abandoned` — Convoy closed without shipping; reason in convoy body.
|
|
|
|
Update status by editing the convoy frontmatter as you progress.
|
|
|
|
## Adding a new convoy
|
|
|
|
1. Open Cursor in this repo.
|
|
2. Prompt: *"Start a new convoy: <one-paragraph idea>. Success = <metric>."*
|
|
3. The `role-conductor` subagent writes `.convoys/<slug>.md`.
|
|
4. Run subsequent roles in order per the convoy's `Roles invoked` list.
|
|
|
|
See `.cursor/agents/role-conductor.md` for the Conductor's full spec.
|
|
|
|
## Multitask + worktrees (Cursor 3.2+)
|
|
|
|
[Cursor 3.2 (Apr 24, 2026)](https://cursor.com/changelog/04-24-26) added `/multitask` async subagents and native worktree management in the Agents Window. The pipeline uses both:
|
|
|
|
**Audit fan-out** — after an implementer ships a PR draft:
|
|
|
|
```
|
|
/multitask role-reviewer + role-design-system-auditor + role-a11y-auditor
|
|
```
|
|
|
|
All three read the same diff and emit independent comments. Use group id `audit-<convoy>-<pr>` so analytics can compute wall-clock savings.
|
|
|
|
**Implementer fleet** — after architect's plan is approved (gate 1), if `slice_dependencies:` declares parallel-safe briefs (`depends_on: []`, disjoint `files:`):
|
|
|
|
```
|
|
/multitask role-implementer briefs 1, 2, 3
|
|
```
|
|
|
|
Use Cursor's Agents Window to create a worktree per brief — one click each. The legacy `scripts/wt.sh` is now a deprecation stub.
|
|
|
|
See the [multitask playbook](https://github.com/varutasu/agent-pipeline/blob/main/docs/multitask-playbook.md) for the full guardrail set.
|
|
|
|
## Self-analytics
|
|
|
|
Each L2 role appends one event to `.convoys/.metrics.jsonl` via `scripts/log-convoy-event.sh`. The file is gitignored by default — events stay local. To opt-in to commit team-shared metrics, remove `.convoys/.metrics.jsonl` from `.gitignore`.
|
|
|
|
Aggregate across repos and render a dashboard with the [agent-pipeline analytics scripts](https://github.com/varutasu/agent-pipeline/tree/main/analytics):
|
|
|
|
```bash
|
|
cd ~/code/agent-pipeline/analytics
|
|
npx tsx analyze-convoys.ts <repo-path> [<repo-path>...]
|
|
npx tsx render-dashboard.ts
|
|
open ~/agent-pipeline-data/dashboard.html
|
|
```
|
|
|
|
Schema: [`analytics/schemas/convoy-event.json`](https://github.com/varutasu/agent-pipeline/blob/main/analytics/schemas/convoy-event.json).
|
|
|