Randall Stillwell 9c1aaaa61f Bootstrap agent-context pipeline (L1 + L2 + L3)

Installs a 3-layer Cursor-aligned agent pipeline so future agent
sessions can orient quickly and stay inside guard rails:

L1 — context for any agent reading the repo:
  - AGENTS.md (top-level orientation, conventions, no-go zones)
  - .cursor/rules/ (no-go-zones, api-routes, prisma, prisma-schema-map)
  - .cursor/skills/ (add-api-route, add-prisma-model)
  - docs/SCHEMA_MAP.md generated from prisma/schema.prisma
  - scripts/generate-schema-map.ts (regenerate the map; wired up as
    `npm run schema:map`)

L2 — subagent roles for the 9-stage idea-to-feature pipeline:
  - .cursor/agents/role-*.md (conductor, architect, ia-architect,
    design-system-auditor, implementer, reviewer, ux-reviewer,
    a11y-auditor, doc-writer) with explicit multitask annotations.

L3 — pipeline scaffolding:
  - .github/CODEOWNERS, PR template, and CI workflows (ci.yml,
    preview-smoke.yml, visual-diff.yml, pr-health-rollup.yml).
    Test job is intentionally disabled until Playwright is wired up.
  - .convoys/ folder for per-feature run notes + scripts/log-convoy-event.sh.
  - scripts/wt.sh worktree helper.
  - src/lib/flags/index.ts simple env-driven feature flag wrapper.
  - tests/smoke/app.smoke.spec.ts (Playwright smoke; excluded from
    tsc until @playwright/test is installed — see tsconfig change).

Also writes .agent-context-manifest.yml so the sync-agent-context
skill can detect drift and offer selective updates from upstream.

Follow-ups (not in this commit):
  - Install @playwright/test and re-enable the test job in ci.yml.
  - Review .cursor/agents/role-*.md and trim any roles that don't
    apply to this codebase.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-23 14:55:18 -05:00

3.5 KiB

Raw Permalink Blame History

Agent Context System

A three-layer system that gives AI coding agents fast, accurate orientation in this repo so they can start coding immediately instead of grepping a thousand files.

The three layers

Layer	Location	What it does	Token cost
Intent	`AGENTS.md`	High-level architecture, conventions, gotchas — always loaded	Always on
Per-context guidance	`.cursor/rules/*.mdc`	Glob-scoped rules (e.g. only loaded when editing `src/app/api/**`)	Loaded only when matching files are open
On-demand recipes	`.cursor/skills/*`	Step-by-step skills the agent reads when its description matches	Loaded only when invoked
Schema map	`docs/SCHEMA_MAP.md`	Generated Prisma model reference grouped by feature area	Loaded when prisma-schema-map.mdc matches

Quickstart for a new task

Open the file you'll edit. Cursor automatically loads AGENTS.md and any .cursor/rules/*.mdc whose globs: match.
Describe the task. The agent has the conventions in scope; it does not need to grep for them.
Drafting. Agent proposes the change against the relevant rule's conventions (e.g. api-routes.mdc enforces requireApiAuthWithOrg + handleApiError).
Verify. npm run lint and npx tsc --noEmit.

How to extend

You want to...	Do this
Add a new convention scoped to a folder	Create `.cursor/rules/<topic>.mdc` with frontmatter `description` + `globs:`
Add a step-by-step recipe agents can invoke	Create `.cursor/skills/<name>/SKILL.md` with frontmatter `description`
Mark a path as "do not touch"	Add it to `.cursor/rules/no-go-zones.mdc`
Refresh the schema map after a Prisma change	`npm run schema:map` (regenerates `docs/SCHEMA_MAP.md`)
Re-categorize a Prisma model in the schema map	Edit `MODEL_GROUPS` in `scripts/generate-schema-map.ts`, then `npm run schema:map`

Always-on rules cost from a shared instruction budget — keep them tight. The "would removing this line cause a mistake the agent wouldn't otherwise make?" test is the gate.

The L2 subagent pipeline

In addition to the L1 context above, .cursor/agents/role-*.md defines 9 subagent roles for an idea-to-feature pipeline (conductor → ia-architect → ux-reviewer → architect → implementer → reviewer + design-system-auditor + a11y-auditor → doc-writer). Each role is read on invocation; they don't add to the always-on token budget. See .cursor/agents/role-conductor.md to get started.

Convoy files live in .convoys/ — see that folder's README for the convoy lifecycle.

What's intentionally NOT here

No commits of .cursor/mcp.json (per-developer MCP install is personal-only, in ~/.cursor/mcp.json).
No proprietary cloud-credential bundles.
No vendored screenshots / model weights — these belong in their own repos.

Pipeline manifest

.agent-context-manifest.yml at the repo root tracks which artifacts the bootstrap installed, where they came from, and their pipeline version. Don't edit by hand — use the sync-agent-context skill to apply updates.

Pipeline source: varutasu/agent-pipeline. Multitask playbook (audit fan-out + implementer fleets via Cursor 3.2 /multitask): docs/multitask-playbook.md.

3.5 KiB Raw Permalink Blame History