deckhearth/docs/agent-context

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 matching files)	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	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 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
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/ covering the idea → IA → UX → architecture → implementation → review → docs flow.
• L3 — pipeline scaffolding in .github/workflows/, .github/PULL_REQUEST_TEMPLATE.md, .github/CODEOWNERS, .convoys/, lib/flags/, and scripts/log-convoy-event.sh.

See .convoys/README.md for how convoys work and how to start one. The full role reference is in the agent-pipeline repo.

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.

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.