76dacff58d
Installs .convoys/README.md, log-convoy-event.sh, convoy-planning Cursor rule, and gitignored metrics JSONL. Documents Echodo dogfood kickoff and adds a shipped convoy record for Epic 1 model provider registry. Co-authored-by: Cursor <cursoragent@cursor.com>
123 lines
4.7 KiB
Markdown
123 lines
4.7 KiB
Markdown
# 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`](../.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
|
|
|
|
```text
|
|
.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):
|
|
|
|
```yaml
|
|
---
|
|
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](../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
|
|
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
|
|
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](../plans/Plan-automation-foundation/Plan-automation-foundation.md)
|
|
- [ADR model routing](../docs/adr-model-routing.md)
|
|
- [AGENTS.md](../AGENTS.md) — repo commands and multitenancy rules
|