# AGENTS.md
<!-- Universal agent instructions file. Read by GitHub Copilot Coding Agent
     and most other coding agents. Keep this concise (~100 lines) and point
     to deeper docs rather than duplicating content here. -->

## Build & Run

```bash
[INSTALL_COMMAND]        # Install dependencies
[DEV_COMMAND]            # Start development server
[BUILD_COMMAND]          # Production build
[TEST_COMMAND]           # Run all tests
[TEST_SINGLE_COMMAND]    # Run a single test file
[LINT_COMMAND]           # Lint
[TYPECHECK_COMMAND]      # Type-check
```

## Project Structure

```
[PROJECT_ROOT]/
  [DIRECTORY]/   # [PURPOSE]
  [DIRECTORY]/   # [PURPOSE]
  [DIRECTORY]/   # [PURPOSE]
  [DIRECTORY]/   # [PURPOSE]
  [DIRECTORY]/   # [PURPOSE]
```

Replace every placeholder before publishing this file into a real project.

See [ARCHITECTURE.md](./ARCHITECTURE.md) for full architecture details.

## Architecture Overview

- **[LAYER_1]**: [BRIEF_DESCRIPTION -- e.g., "Presentation layer -- React components, no business logic"]
- **[LAYER_2]**: [BRIEF_DESCRIPTION -- e.g., "Application layer -- use cases, orchestration"]
- **[LAYER_3]**: [BRIEF_DESCRIPTION -- e.g., "Domain layer -- pure business logic, no I/O"]
- **[LAYER_4]**: [BRIEF_DESCRIPTION -- e.g., "Infrastructure layer -- DB, HTTP, external APIs"]

Dependencies flow inward: [LAYER_1] -> [LAYER_2] -> [LAYER_3]. [LAYER_4] implements [LAYER_3] interfaces.

## Code Style

- [RULE -- e.g., "Use named exports, not default exports"]
- [RULE -- e.g., "Prefer immutable data: const, readonly, Object.freeze"]
- [RULE -- e.g., "No abbreviations in public APIs (use `repository`, not `repo`)"]
- [RULE -- e.g., "Error handling via Result types, not exceptions"]
- [RULE -- e.g., "Max function length: 40 lines. Extract helpers if longer."]

File naming: [CONVENTION -- e.g., "kebab-case for files, PascalCase for components"]

## Testing

- [CONVENTION -- e.g., "Unit tests required for all business logic"]
- [CONVENTION -- e.g., "Tests colocated with source: foo.ts -> foo.test.ts"]
- [CONVENTION -- e.g., "Use test factories, not raw fixtures"]
- [CONVENTION -- e.g., "Mock at boundaries only (HTTP, DB), not internal modules"]

Test pattern:
```
test('[scope] should [behavior] when [condition]', () => {
  // Arrange -> Act -> Assert
});
```

## Common Patterns

### [PATTERN_NAME_1 -- e.g., "API Route Handler"]
See: `[PATH_TO_EXAMPLE -- e.g., src/server/routes/invoices.ts]`

### [PATTERN_NAME_2 -- e.g., "Database Repository"]
See: `[PATH_TO_EXAMPLE -- e.g., src/lib/repositories/invoice-repository.ts]`

### [PATTERN_NAME_3 -- e.g., "React Component with Data Fetching"]
See: `[PATH_TO_EXAMPLE -- e.g., src/app/invoices/page.tsx]`

## Key Docs

- [ARCHITECTURE.md](./ARCHITECTURE.md) -- System architecture and package layering
- [docs/design-doc-template.md](./docs/design-doc-template.md) -- Design document template
- [docs/adr/](./docs/adr/) -- Architecture Decision Records
- [[CUSTOM_DOC_LINK]]

## Verification

Before submitting, ensure:
1. `[TEST_COMMAND]` -- all tests pass
2. `[TYPECHECK_COMMAND]` -- no type errors
3. `[LINT_COMMAND]` -- no lint warnings
4. New code has tests
5. No secrets in committed code

## Agent-Specific Notes

- If a task is ambiguous, state your assumptions before writing code.
- Write a failing test before fixing a bug.
- When adding database fields, create a new migration -- never edit existing ones.
- [CUSTOM_NOTE]