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

```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>
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: <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-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](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`. **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](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). Model tiers: [`docs/model-routing-policy.md`](https://github.com/varutasu/agent-pipeline/blob/main/docs/model-routing-policy.md).