79 lines
4.7 KiB
Markdown
79 lines
4.7 KiB
Markdown
|
# 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.
|