Skip to main content
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.

​
Example: .capy/BUILD.md

# 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

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