rstillwell/ubiquitous-invention
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
ubiquitous-invention/.convoys/README.md
Randall Stillwell dab939bcd5 feat(mcp): agent-pipeline bridge — 6 lifecycle tools + convoy_events + L1/L3 scaffolding 
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>
2026-06-05 20:59:45 -05:00

4.3 KiB
Raw Blame History

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

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

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.