# 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`](../../AGENTS.md) | High-level architecture, conventions, gotchas — always loaded | Always on |
| **Per-context guidance** | [`.cursor/rules/*.mdc`](../../.cursor/rules) | Glob-scoped rules (e.g. only loaded when editing matching files) | Loaded only when matching files are open |
| **On-demand recipes** | [`.cursor/skills/*`](../../.cursor/skills) | Step-by-step skills the agent reads when its description matches | Loaded only when invoked |
| **Schema map** | [`docs/SCHEMA_MAP.md`](../SCHEMA_MAP.md) | Hand-curated DB table reference for token-efficient agent queries | Loaded only when read |

## Plus a fourth: the structural brain

This repo also indexes itself with the [`user-code-review-graph`](https://github.com/varutasu/code-review-graph) MCP server. It runs locally per-developer and parses the codebase with Tree-sitter into a queryable graph of files, functions, classes, calls, and imports.

| You can ask… | …and get |
| --- | --- |
| "What calls `getUserFromRequest`?" | A list of every handler that depends on the auth fallback bug |
| "Where is `withCollectionPermission` used?" | Every collection-scoped route |
| "Show me the flow from `/api/auth/login`" | Call graph with imports and DB writes |
| "Find functions over 100 lines" | Refactor targets |
| "Show me bridge nodes between communities" | High-coupling functions to test carefully |

To use it in this repo:

1. Install + start the MCP server (`brew install pipx && pipx install code-review-graph` or per the project's README).
2. Open this repo in Cursor.
3. The MCP picks up the repo root automatically.
4. Ask the agent natural questions — the graph is the data source.

The graph is per-developer; no `.code-review-graph/` directory ever gets committed (it's already in `.gitignore`).

## Quickstart for a new task

1. **Open the file you'll edit.** Cursor automatically loads `AGENTS.md` and any `.cursor/rules/*.mdc` whose `globs:` match.
2. **Describe the task.** The agent has the conventions in scope; it does not need to grep for them.
3. **Drafting.** Agent proposes the change against the relevant rule's conventions.
4. **Verify.** `npm run lint` (no test runner yet — adding `vitest` is in `.convoys/`).

## 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`](../../.cursor/rules/no-go-zones.mdc) |
| Regenerate the schema map | Re-read `scripts/setup-neon-db.js` + any new `scripts/add-*.js`, then update `docs/SCHEMA_MAP.md` |
| Refresh the code graph | Ask Cursor to call the `build_or_update_graph_tool` MCP tool |

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.

## Subagent pipeline (L2 + L3)

In addition to L1 context, this repo has:

- **L2 — 9 subagent roles** in [`.cursor/agents/`](../../.cursor/agents/) covering the idea → IA → UX → architecture → implementation → review → docs flow.
- **L3 — pipeline scaffolding** in `.github/workflows/`, `.github/PULL_REQUEST_TEMPLATE.md`, `.github/CODEOWNERS`, [`.convoys/`](../../.convoys/), `lib/flags/`, and `scripts/log-convoy-event.sh`.

See [`.convoys/README.md`](../../.convoys/README.md) for how convoys work and how to start one. The full role reference is in the [agent-pipeline repo](https://github.com/varutasu/agent-pipeline).

## Multitask + worktrees (Cursor 3.2+)

After role-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.

For parallel implementer briefs (when `slice_dependencies` allows it), use Cursor's native Agents Window worktrees. Full playbook: [agent-pipeline docs/multitask-playbook.md](https://github.com/varutasu/agent-pipeline/blob/main/docs/multitask-playbook.md).

## What's intentionally NOT here

- No commits of `.cursor/mcp.json` to this repo (any MCP install is personal-only, in `~/.cursor/mcp.json`).
- No measurement protocol yet — the colab repo's -53% token result is documented upstream; we'll measure tcg-vault's number after a few convoys.