> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Instructions

Agent instructions are markdown files committed to your repo that tell Capy how to work in your codebase: how to build and test, which conventions to follow, and what to avoid. Capy reads the same `AGENTS.md` files used by other coding agents, so if you already maintain them, Capy works with zero setup.

## How instructions are loaded

Capy loads instructions from three sources with different timing:

| Source              | Files                                                | When it's loaded                                                            |
| ------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------- |
| Root instructions   | `AGENTS.md` or `CLAUDE.md` at the repo root          | Thread start                                                                |
| Nested instructions | `AGENTS.md` in any subdirectory                      | First time the agent touches a file in that directory's subtree             |
| Glob rules          | `.capy/rules/*.{md,mdc}`, `.cursor/rules/*.{md,mdc}` | Thread start if `alwaysApply: true`, otherwise on first matching file touch |

### Root instructions

Every agent reads the repo root's `AGENTS.md`, falling back to `CLAUDE.md` when no `AGENTS.md` exists. Per-agent instruction files (`.capy/BUILD.md`, `.capy/CAPTAIN.md`, `.capy/REVIEW.md`) are deprecated and no longer read; put agent guidance in `AGENTS.md`, nested files, or glob rules instead.

### Nested AGENTS.md

An `AGENTS.md` anywhere below the repo root is discovered automatically. It isn't loaded at thread start; it's injected into context the first time the agent reads, edits, searches, or lists a file inside that directory's subtree. A thread that never enters `packages/api/` never pays the context cost of `packages/api/AGENTS.md`.

Behavior to know:

* **Lazy, then sticky.** Each nested file is injected at most once per thread, on first contact with its subtree.
* **Deeper wins.** When instructions conflict, a more deeply nested `AGENTS.md` takes precedence over shallower ones (and nested files add to, not replace, the root file).
* **File tools only.** Injection is triggered by file-level operations: reading, editing, searching, and listing files. Shell commands do not trigger nested injection, so a repo-wide grep from the terminal won't pull in every nested file at once.
* **Plain markdown.** The whole file is treated as instructions. Frontmatter is not parsed; if you need globs or `alwaysApply`, use a [glob rule](#glob-rules) instead.

Discovery follows git: only tracked files are found, so anything gitignored never enters context. Root instructions and skill descriptions share one context budget; oversized content is truncated or shortened with a visible marker rather than silently dropped.

### Glob rules

Capy reads Cursor-style rules from `.capy/rules/` and `.cursor/rules/` (`.md` or `.mdc` files). YAML frontmatter controls when each rule loads: a rule needs `alwaysApply: true` or at least one `globs` pattern to be injected:

```markdown theme={null}
---
description: SQL migration conventions
globs:
  - "**/*.sql"
alwaysApply: false
---

- Every migration must be reversible
- Never drop columns without an explicit approval comment
```

* `alwaysApply: true` loads at thread start
* `globs` injects the first time the agent touches a matching file
* Rules are injected with their file path attached, and each rule is injected at most once per thread

Use `.capy/rules/` for Capy-native rules; `.cursor/rules/` is read natively so existing Cursor setups work unchanged.

### Skills

For deep, on-demand workflows (deploy runbooks, codegen procedures, large reference material), use [skills](/skills) instead of instruction files. Skills advertise only their name and description until an agent decides to load one, so they cost almost nothing when unused. Instruction files answer "how should you always behave here?"; skills answer "how do I do this specific thing?".

## What goes where

The failure mode to avoid is one giant root file that every thread pays for. Match each piece of guidance to the narrowest mechanism that still reaches it:

| Guidance                                                                   | Put it in                          | Why                                                  |
| -------------------------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------- |
| Stack summary, build/test/format commands, PR conventions, hard rules      | Root `AGENTS.md`                   | Every thread needs it                                |
| Per-package architecture, domain rules, local commands                     | Nested `AGENTS.md` in that package | Only loaded when working there                       |
| File-type conventions that cut across directories (`**/*.sql`, `**/*.tsx`) | Glob rule                          | Directory-scoped files can't express "all SQL files" |
| Multi-step workflows, long reference docs                                  | [Skill](/skills)                   | Loaded on demand, keeps always-on context lean       |

**Root `AGENTS.md`** carries cross-cutting truths: what the project is, how to install/build/test/lint, commit and PR conventions, and non-negotiable rules ("always use pnpm", "never commit generated files"). Keep it lean: a bloated root file taxes every request in every thread, and long instruction files dilute the agent's attention on the rules that matter.

**Nested `AGENTS.md`** carries what's true only inside a subtree. In a monorepo, keep the top-level file general and add a specific `AGENTS.md` per major subproject: `packages/api/AGENTS.md` for API conventions, `packages/web/AGENTS.md` for frontend rules. This is the same layout Amp and other agents recommend, so one set of files serves every tool.

**Glob rules** carry concerns that follow a file type rather than a directory: design-token rules for every `.tsx` file, migration rules for every `.sql` file. If the concern maps cleanly to one directory, prefer a nested `AGENTS.md` there instead.

### Anti-patterns

* **Duplicating a rule in multiple files.** State it once in the narrowest scope that covers it. Duplicates drift, and the agent has to reconcile conflicting copies.
* **Restating what the code already says.** Don't enumerate exports, list every directory, or paraphrase type signatures; the agent reads code. Document what it can't infer: intent, invariants, and commands.
* **Prompt-sized essays.** Ten sharp bullets outperform three pages of prose. "Use pnpm, not npm" beats "please make sure to use the correct package manager for this project".
* **Secrets or credentials.** Instruction files are committed to the repo and injected into model context. Never put tokens, passwords, or internal URLs that shouldn't leak into them.
* **Per-file trivia.** "This function retries three times because the upstream API flakes" belongs in a code comment next to the function, not in an instruction file.

## Examples

### A lean root AGENTS.md

```markdown theme={null}
# AGENTS.md

Acme is a TypeScript monorepo: `packages/api` (Fastify + Postgres), `packages/web` (React + Vite), `packages/shared` (types and utils).

## Commands

- Install: `pnpm install`
- Build: `pnpm build`
- Test: `pnpm test` (single package: `pnpm --filter @acme/api test`)
- Lint + format: `pnpm check`; run before finishing any task

## Rules

- Always use pnpm, never npm or yarn
- No `any` types; fix type errors instead of suppressing them
- New env vars must be added to `.env.example` and `packages/shared/src/env.ts`
- PR titles follow `type(scope): description` (e.g. `fix(api): handle null user`)
```

### A nested packages/api/AGENTS.md

```markdown theme={null}
# API package

Fastify server with route handlers in `src/routes/`, business logic in `src/services/`, and data access in `src/db/`.

- Route handlers validate input with zod schemas from `src/schemas/` and stay thin; logic lives in services
- All queries go through the repository layer in `src/db/`; never import the client directly in a route or service
- Every table uses soft deletes (`deleted_at`); filter it in every query
- Integration tests live in `src/__tests__/` and run against the Docker Postgres from `pnpm db:test`
```

### A glob rule

```markdown theme={null}
---
description: Design token rules for React components
globs:
  - "**/*.tsx"
---

- Use tokens from `packages/web/src/styles/tokens.css`, never raw hex colors or arbitrary Tailwind values
- Spacing comes from the `--space-*` scale; font sizes from `text-sm` through `text-2xl` only
```

## Migrating from other tools

* **From Claude Code**: nothing required; Capy reads root `CLAUDE.md` as a fallback. To standardize on `AGENTS.md` while keeping Claude Code working: `mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md`
* **From Cursor**: keep `.cursor/rules/` where it is; Capy reads it natively, including `globs` and `alwaysApply` frontmatter
* **From other agents using AGENTS.md** (Amp, Codex, Devin, ...): nothing required; root and nested `AGENTS.md` files work as-is

Changes to instruction files apply to the next thread or task.