# Per-repo AGENTS.md templates

Reference templates for stack-specific conventions that belong in each target
repo rather than in the shared agent prompt. Both the coding agent and the
deterministic reviewer read `AGENTS.md` from the repo root.

## How to use these

For each target repo, merge the applicable templates into a single `AGENTS.md`
at the repo root:

| Repo uses | Templates to merge |
|---|---|
| SAM + Lambda | `AGENTS.md.aws` + `AGENTS.md.sam` |
| CDK + Lambda | `AGENTS.md.aws` + `AGENTS.md.cdk` |
| CDK + EC2 | `AGENTS.md.aws` + `AGENTS.md.cdk` + `AGENTS.md.ec2` |
| Plain CloudFormation | `AGENTS.md.aws` |

Strip any convention that does not apply to the specific repo. Do not carry
role ARNs, account IDs, VPC IDs, or other deployment specifics — these
templates keep the principle, not the configuration.

## Where each convention lives

| Convention | Channel | Template |
|---|---|---|
| SAM-default; Lambda defaults; exact-pin CDK lib versions | Committed `AGENTS.md` or per-repo dashboard instructions | `AGENTS.md.aws` |
| Never remove `overrideLogicalId` | Committed `AGENTS.md` | `AGENTS.md.cdk` |
| Persistent EBS: standalone `Volume` + `RETAIN`; snapshot before EC2-replacing deploy | Committed `AGENTS.md` | `AGENTS.md.ec2` |
| SAM directory layout + layer `BuildMethod` nesting gotcha | Committed `AGENTS.md` | `AGENTS.md.sam` |
| CDK directory layout + ARM64/QEMU build note | Committed `AGENTS.md` | `AGENTS.md.cdk` |

## Operator-managed overrides

Rules that are operator-managed and should not live in the repo belong in the
dashboard's per-repo custom-instructions store (`/dashboard/agents/instructions`
or `/dashboard/api/agent-instructions`). Use this for:
- Temporary deployment freezes
- Repo-specific model or sandbox configuration
- Rules that change with the team, not the code