deckhearth/.convoys/README.md

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.

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 and write .convoys/<slug>.md; do not create .cursor/plans/ files. See .cursor/rules/convoy-planning.mdc.

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):

---
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>
model_policy:
  default_session: auto
  roles: { ... }   # see docs/model-routing-policy.md
design_direction:                  # optional — set by role-ui-designer (planning lock)
  source: role-ui-designer
  skill: ui-ux-pro-max
  skill_version: "2.5.0"
  version: 1
  locked_at: YYYY-MM-DD
  product_type: ""
  pattern: ""
  style: ""
  stack: nextjs
---

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. ## Design direction (UI Designer — optional; skip when ui-design set)
7. ## UX (UX Reviewer)
8. ## 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
ui-design	UI Designer (planning; ui-ux-pro-max skill)
arch	Architect
test	Component tests
review	Reviewer
visual	Visual diff
a11y	A11y auditor
design	Design-system auditor
security	Security 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: . Success = ."
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) 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-security-auditor + 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 for the full guardrail set.

Self-analytics

Each L2 role appends one event to .convoys/.metrics.jsonl via scripts/log-convoy-event.sh. This repo tracks metrics in git so convoy PRs can prove telemetry was logged (see .github/workflows/convoy-metrics-gate.yml). Events contain metadata only — no code, no prompts.

Aggregate across repos and render a dashboard with the agent-pipeline analytics scripts:

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. Model tiers: docs/model-routing-policy.md.