diff --git a/.agent-context-manifest.yml b/.agent-context-manifest.yml new file mode 100644 index 0000000..a5ecb7d --- /dev/null +++ b/.agent-context-manifest.yml @@ -0,0 +1,135 @@ +# .agent-context-manifest.yml +# +# Generated by agent-pipeline bootstrap-agent-context skill (manual run; 2026-06-05). +# Tracks which artifacts the bootstrap installed in this repo, where they +# came from, and what pipeline version they correspond to. +# +# Read by the `sync-agent-context` skill to detect drift and propose updates. +# Don't edit by hand — use the bootstrap or sync skill in Cursor. +# +# Schema: https://github.com/varutasu/agent-pipeline/blob/main/docs/manifest-schema.md +# +# Notes for `tasks` specifically: +# - AGENTS.md is hand-curated (161 lines, pre-dates pipeline install) — NOT tracked +# - 4 stack rules (database.mdc, markdown-backlog.mdc, repo-overview.mdc, web-app.mdc) +# pre-date the pipeline and are hand-curated — NOT tracked +# - .cursor/mcp.json is per-repo MCP config — NOT tracked +# - .github/workflows/ci.yml was kept (better than template — pnpm + monorepo + +# concurrency + branches:[main]). NOT tracked (so sync won't suggest replacing it +# with the upstream template, which is npm-based and worse for this repo). +# - 3 artifacts are adapted (locally customized at install time) — flagged below. +# - L3 variant gap: no `nextjs-coolify/` template exists in the pipeline yet. +# pr-health-rollup.yml was adapted from `nextjs-prisma-coolify/`; CODEOWNERS from +# `nextjs/`. Filed as an open question in agent-pipeline/docs/CONSUMERS.md. + +schema_version: 1 +pipeline_version: "0.5.0" +pipeline_source: "https://github.com/varutasu/agent-pipeline" +installed_at: "2026-06-05T21:51:00Z" +last_synced_at: "2026-06-05T21:51:00Z" + +layers: + - L1 + - L2 + - L3 + +artifacts: + # L1 — only the always-apply no-go-zones rule is pipeline-managed. + # AGENTS.md and the 4 stack rules in .cursor/rules/ are hand-curated. + - path: ".cursor/agents/echodo.config.json" + source: "skills/bootstrap-agent-context/templates/L3-pipeline/_common/echodo-config.json.template" + version: "0.5.0" + installed_hash: "sha256:68207b3fc05d266a55fb2056610d2db94d5a2d083d360f6811786476451ae01c" + customized: true # filled in with workspace_slug=convoys-tasks + tasks-specific transport reference + + - path: ".cursor/rules/no-go-zones.mdc" + source: "skills/bootstrap-agent-context/templates/L1-context/no-go-zones.mdc" + version: "0.5.0" + installed_hash: "sha256:e042bfbb6a26806118e684b684fb6223b4c2fc19309ae9daafaa4fffe1680db3" + customized: true # adapted at install time for Echodo's monorepo + Drizzle + Coolify + + # L2 — 9 roles, copied verbatim. + - path: ".cursor/agents/role-a11y-auditor.md" + source: "skills/bootstrap-agent-context/templates/L2-roles/role-a11y-auditor.md" + version: "0.5.0" + installed_hash: "sha256:a59938deceb0246ebd7e477f1f9a442102f9fcbb81b0364f0ddc5f86e95a7930" + + - path: ".cursor/agents/role-architect.md" + source: "skills/bootstrap-agent-context/templates/L2-roles/role-architect.md" + version: "0.5.0" + installed_hash: "sha256:269bd62af1557c5d353a9f95a613960e3434be4ec6e0c0b5f6b099adf6872044" + + - path: ".cursor/agents/role-conductor.md" + source: "skills/bootstrap-agent-context/templates/L2-roles/role-conductor.md" + version: "0.5.0" + installed_hash: "sha256:bc75a3e6646217a015f7bb60c3610afd9b57ae91c7d2fc7a7971f4709b19368a" + + - path: ".cursor/agents/role-design-system-auditor.md" + source: "skills/bootstrap-agent-context/templates/L2-roles/role-design-system-auditor.md" + version: "0.5.0" + installed_hash: "sha256:d214cecb1e8482fc24f2815c8220c860191f08526614f89cf9a5797e4ee9110a" + + - path: ".cursor/agents/role-doc-writer.md" + source: "skills/bootstrap-agent-context/templates/L2-roles/role-doc-writer.md" + version: "0.5.0" + installed_hash: "sha256:d4e8bf8cee93153506b7b742848462422dbe5cc7fd012c62f6ffd50460e344d4" + + - path: ".cursor/agents/role-ia-architect.md" + source: "skills/bootstrap-agent-context/templates/L2-roles/role-ia-architect.md" + version: "0.5.0" + installed_hash: "sha256:69685a3a407c4ee25e2606d426c3107d6b917abee80f907e16ade4a16b439839" + + - path: ".cursor/agents/role-implementer.md" + source: "skills/bootstrap-agent-context/templates/L2-roles/role-implementer.md" + version: "0.5.0" + installed_hash: "sha256:b4f4d8596068679b90ffc3a2b6d2e1b6548caf8c68a50f7ed640ba8f638c1c4c" + + - path: ".cursor/agents/role-reviewer.md" + source: "skills/bootstrap-agent-context/templates/L2-roles/role-reviewer.md" + version: "0.5.0" + installed_hash: "sha256:1ff38349321402a0ac2be37878dc2c0bcab62e54caf74c422b919aa6d75f9b67" + + - path: ".cursor/agents/role-ux-reviewer.md" + source: "skills/bootstrap-agent-context/templates/L2-roles/role-ux-reviewer.md" + version: "0.5.0" + installed_hash: "sha256:3a1d4b66981f469b15e23a1cd34ab41352759966179e126b3d56ddc1eca4a03e" + + # L3 — pipeline scaffolding. NOT included: .github/workflows/ci.yml (kept the + # repo's own, which is better than the template), tests/smoke (Echodo uses + # vitest), lib/flags/index.ts (not used yet). + - path: ".convoys/README.md" + source: "skills/bootstrap-agent-context/templates/L3-pipeline/_common/convoys-readme.md.template" + version: "0.5.0" + installed_hash: "sha256:a48548cd3f5d0c40fc179106890661c3be5fcdc13eb705af7cfe9233e0b8b209" + + - path: ".github/CODEOWNERS" + source: "skills/bootstrap-agent-context/templates/L3-pipeline/nextjs/CODEOWNERS.template" + version: "0.5.0" + installed_hash: "sha256:8d7d3388f61cbfe2cdc6ae759ea944a4b60cf896f0b6e11c6946dc84ee3f1bf9" + customized: true # adapted for Echodo's apps/packages monorepo layout + + - path: ".github/PULL_REQUEST_TEMPLATE.md" + source: "skills/bootstrap-agent-context/templates/L3-pipeline/_common/PULL_REQUEST_TEMPLATE.md.template" + version: "0.5.0" + installed_hash: "sha256:89863e58b9ec194aef1c94d3596e892467833e8bc880a28994acca401b6d9635" + + - path: ".github/workflows/agent-context-drift.yml" + source: "skills/bootstrap-agent-context/templates/L3-pipeline/_common/agent-context-drift.yml.template" + version: "0.5.0" + installed_hash: "sha256:5505c296c1b61d023ee2aca222103097e2b5ed2e0e38da3679cc4f9754457785" + + - path: ".github/workflows/pr-health-rollup.yml" + source: "skills/bootstrap-agent-context/templates/L3-pipeline/nextjs-prisma-coolify/pr-health-rollup.yml.template" + version: "0.5.0" + installed_hash: "sha256:91472074a0906270f0cfaa7caa6fa2d4812de9281c0d35aa3f5ed368d6d0a72e" + customized: true # adapted for one-job CI (vs two-job template) and branches:[main] + + - path: "scripts/log-convoy-event.sh" + source: "skills/bootstrap-agent-context/templates/L3-pipeline/_common/log-convoy-event.sh" + version: "0.5.0" + installed_hash: "sha256:cd0413691066a177b6b4e6164a9a0978c20a853ad60222ae833b5d53b255818d" + + - path: "scripts/wt.sh" + source: "skills/bootstrap-agent-context/templates/L3-pipeline/_common/wt.sh" + version: "0.5.0" + installed_hash: "sha256:2a4f44a159f80a8ea6fe53ac507c01a2f91a4e2118d997a98b051808ac35e9a5" diff --git a/.convoys/README.md b/.convoys/README.md new file mode 100644 index 0000000..07502c4 --- /dev/null +++ b/.convoys/README.md @@ -0,0 +1,121 @@ +# 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) +├── .md (the convoy file — written by role-conductor) +└── / + ├── brief-1-.md (written by role-architect) + ├── brief-2-.md + └── ... +``` + +## Convoy file format + +Frontmatter (set by `role-conductor`, then appended-to by other roles): + +```yaml +--- +name: +classification: feature | hotfix | docs-only | infra-only | server-only | config-only +success_metric: +skip: + - +status: open | in-progress | merged | shipped | abandoned +created: +--- +``` + +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//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/.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-design-system-auditor + role-a11y-auditor +``` + +All three read the same diff and emit independent comments. Use group id `audit--` 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`. 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](https://github.com/varutasu/agent-pipeline/tree/main/analytics): + +```bash +cd ~/code/agent-pipeline/analytics +npx tsx analyze-convoys.ts [...] +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). + diff --git a/.cursor/agents/echodo.config.json b/.cursor/agents/echodo.config.json new file mode 100644 index 0000000..d9cb889 --- /dev/null +++ b/.cursor/agents/echodo.config.json @@ -0,0 +1,25 @@ +{ + "$schema": "https://agent-pipeline.varutasu.dev/schemas/echodo-config.v1.json", + "_comment": "Per-repo Echodo bridge config for the tasks repo (Echodo's own dogfood). Read by L2 role files to know which Echodo workspace this repo's convoys live in and how to behave when MCP is unreachable. The MCP server registration itself lives in .cursor/mcp.json (already configured for stdio + pnpm-filter dev path).", + "workspace_slug": "convoys-tasks", + "_workspace_note": "This is the workspace you created in Echodo at echodo.stillwell.cloud as part of Action 1 (Phase 0). Roles call create_convoy / create_brief / transition_convoy_status against this workspace.", + "fallback": { + "on_unreachable": "local-only", + "on_error": "local-only-with-warning" + }, + "_fallback_semantics": [ + "If MCP is unreachable when a role attempts create_convoy / create_brief / transition_convoy_status:", + " - The role still writes .convoys/.md and brief files locally (files are source of truth — see §7.6 of the v0.4 plan).", + " - The failed call is appended to .convoys/.pending-mcp-sync.jsonl as one JSON line.", + " - On the next reachable session, calling the MCP tool reconcile_from_files drains the outbox." + ], + "mcp_transport_reference": { + "_note": "Informational only — Cursor reads .cursor/mcp.json, not this block. Kept here so a future MCP host (Phase 4 workers, CI runners) has a single source of truth for transport config.", + "transport": "stdio", + "command": "pnpm", + "args": ["-s", "--filter", "@tasks/mcp-server", "mcp"], + "env": { + "DATABASE_URL": "${ECHODO_DATABASE_URL}" + } + } +} diff --git a/.cursor/agents/role-a11y-auditor.md b/.cursor/agents/role-a11y-auditor.md new file mode 100644 index 0000000..ddd7031 --- /dev/null +++ b/.cursor/agents/role-a11y-auditor.md @@ -0,0 +1,105 @@ +--- +name: role-a11y-auditor +description: >- + Accessibility audit on a UI diff. Checks for missing labels, keyboard + navigation, focus management, color contrast, semantic HTML, and ARIA + correctness. Read-only. Use after the implementer's PR draft on PRs that + touch UI files. Does not require a browser MCP — works from the diff + + static analysis. Safe to run in parallel with role-reviewer + + role-design-system-auditor via Cursor 3.2 /multitask. +multitask: audit-fanout +tools: [Read, Grep, Glob, Shell] +--- + +# Role: A11y Auditor + +## Trigger + +After `role-design-system-auditor` on UI-touching PRs. Skip when convoy frontmatter has `skip: a11y`. + +## Inputs + +- The PR diff (UI files only). +- The convoy's UX section (which already lists a11y constraints — verify the implementer satisfied them). +- Existing accessible patterns in the repo (look at existing `Dialog`, `Form`, `Button` primitives). + +## Outputs + +A structured comment for the PR Health rollup: + +```markdown +## A11y Audit + +| Check | Status | Count | +| --- | --- | --- | +| Labels | ✅ / ❌ | | +| Keyboard nav | ✅ / ❌ | | +| Focus management | ✅ / ❌ | | +| Color contrast | ✅ / ⚠️ | | +| Semantic HTML | ✅ / ❌ | | +| ARIA correctness | ✅ / ⚠️ | | +| UX constraint match | ✅ / ❌ | | + +### Critical (must fix) +- +... + +### Warnings (recommended) +- +... + +### Notes +- ... +``` + +## Checklist (apply per file) + +1. **Labels**: every ``, `