Submatter/.convoys

Convoys (Echodo / tasks repo)

A convoy is a multi-PR work-stream coordinated by the agent pipeline. One convoy = one feature, bug fix, or epic slice. Each convoy is a Markdown file in this directory plus an optional sub-directory of implementer briefs.

Not Cursor Plan mode. Pipeline convoys live here (.convoys/*.md). Cursor's native Plan feature writes to .cursor/plans/*.plan.md — a different artifact. For pipeline work, invoke role-conductor (when L2 roles are installed) and write .convoys/<slug>.md. See .cursor/rules/convoy-planning.mdc.

Product backlog items still live under plans/ and sync to Echodo via markdown import. Convoys track how a slice is executed (roles, briefs, gates) — not the canonical plan tree.

File layout

.convoys/
├── README.md                              (this file)
├── .metrics.jsonl                         (local analytics — gitignored)
├── <slug>.md                              (convoy file — role-conductor)
└── <slug>/
    ├── brief-1-<kebab-title>.md           (role-architect)
    └── ...

Convoy file format

Frontmatter (set by role-conductor, appended by other roles):

---
name: <kebab-slug>
classification: feature | hotfix | docs-only | infra-only | server-only | config-only
success_metric: <one sentence>
skip:
  - ia
status: open | in-progress | merged | shipped | abandoned
created: <YYYY-MM-DD>
model_policy:
  roles:
    role-conductor: claude-planning
    role-implementer: qwen-coder
  escalate_to: claude-planning
---

Use registry alias names in model_policy (not Cursor model slugs). See docs/adr-model-routing.md.

Body sections (typical order):

1. ## Why (Conductor)
2. ## Scope (Conductor)
3. ## Roles invoked (Conductor)
4. ## Todos (Conductor → Architect)
5. ## IA (IA Architect — skip if ia in skip:)
6. ## UX (UX Reviewer)
7. ## Architecture (Architect)

After Architect, briefs live in .convoys/<slug>/brief-N-*.md. Implementers read only their brief.

Skip flags

Flag	Skips
ia	IA Architect
ux	UX Reviewer
arch	Architect (rare — use only for trivial hotfixes)
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 (human gates): plan-approval, pr-merge, prod-promote.

Echodo server work often uses classification: server-only with skip: [ia, ux, design, a11y, visual, smoke].

Status lifecycle

• open — convoy created; no briefs in flight
• in-progress — at least one brief active or PR open
• merged — all briefs merged; release pending
• shipped — in production
• abandoned — closed without shipping

Kickoff ritual (this repo)

1. Open Cursor in the tasks repo on a feature branch.
2. Prompt: "Start a new convoy: <idea>. Success = <metric>."
3. Conductor writes .convoys/<slug>.md with classification and skip flags.
4. Echodo dogfood: each implementer session should claim_task on the matching plans/.../Task-*.md, implement, then complete_task with modelAlias / modelTier.
5. Architect maps briefs 1:1 to tasks when possible.

Example (Epic 1 — done): model provider registry convoy with server-only, briefs aligned to Epic-model-provider-registry tasks.

Next convoys: orchestrator (Epic-apps-orchestrator), convoy lifecycle MCP (Epic-convoy-lifecycle-mcp), connected repos (Epic-connected-repos).

Self-analytics

Each L2 role appends one event via:

bash scripts/log-convoy-event.sh role=role-implementer convoy=<slug> brief=1 \
  duration_s=120 model=qwen-coder model_tier=local outcome=complete

.convoys/.metrics.jsonl is gitignored by default (metadata only, no prompts). Remove that line from .gitignore if you want team-visible metrics in git.

Validate a line was written:

bash scripts/log-convoy-event.sh role=role-conductor convoy=test duration_s=1
tail -1 .convoys/.metrics.jsonl | python3 -m json.tool

Multitask (Cursor 3.2+)

Use /multitask for audit fan-out (role-reviewer + design + a11y) or parallel implementers when architect marks briefs as disjoint. Set multitask_group=audit-<convoy>-<pr> on log lines for wall-clock analytics.

Related docs

• Plan automation foundation
• ADR model routing
• AGENTS.md — repo commands and multitenancy rules