> ## 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.

# Agent instructions

> Write markdown instruction files that tell Capy's Build, Captain, and Review agents how to work in your codebase — coding standards, review rules, and more.

Agent instructions are markdown files in your repo that tell each agent how to work in your codebase.

* **Build** reads `.capy/BUILD.md`
* **Captain** reads `.capy/CAPTAIN.md`
* **Review** reads `.capy/REVIEW.md`

Each agent reads only its own instruction file.

## Fallback behavior

If an agent's `.capy/*.md` file is missing, it falls back in this order:

1. `AGENTS.md` at the repo root
2. `CLAUDE.md` at the repo root

The first file found wins. This applies to all three agents — Build, Captain, and Review.

This means if you already maintain `AGENTS.md`/`CLAUDE.md` for other tools, all agents can use it automatically without any `.capy/` setup.

## Path-scoped rules

Capy also reads Cursor-style project rules from `.capy/rules/*.md`, `.capy/rules/*.mdc`, `.cursor/rules/*.md`, and `.cursor/rules/*.mdc`.

Use `.capy/rules` for Capy-native path-scoped guidance, such as design-system or architecture standards that should live close to repository config. Capy injects matching rules as custom user instructions with the rule path attached; they do not replace `.capy/*.md`, `AGENTS.md`, or `CLAUDE.md`.

```markdown theme={null}
---
description: Backend conventions
globs:
  - packages/backend/**/*.ts
alwaysApply: false
---

- Use typed Effect errors in backend core logic
- Add ownership checks to database queries
```

Rules with `alwaysApply: true` are included at the start of the session. Rules with `globs` are included after a matching file is read, searched, listed, or edited.

## Example: `.capy/BUILD.md`

```markdown theme={null}
# Build instructions

## Project setup

- Always run `pnpm install` before making changes
- Use TypeScript strict mode

## Code style

- Follow existing patterns in `src/`
- Use functional components with hooks
```

## Example: `.capy/REVIEW.md`

```markdown theme={null}
# Review instructions

## Do not flag

- Snapshot ID changes are normal workflow
- Intentional fallback patterns are backward compat
- Defensive defaults are project convention

## Severity

- Only flag medium+ for user-facing bugs
- Style/preference issues should be low priority
```

Changes to instruction files apply to the next agent session.