open-swe/docs/repo-conventions

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