From fdf1ad24dcaa7df3ac63ab7d727850500d69a020 Mon Sep 17 00:00:00 2001
From: "seahaven-openswe[bot]"
 <296972425+seahaven-openswe[bot]@users.noreply.github.com>
Date: Tue, 28 Jul 2026 19:54:49 +0000
Subject: [PATCH] Add AGENTS.md with CDK + EC2 + persistent-EBS conventions
 (#26)

Co-authored-by: seahaven-openswe[bot] <296972425+seahaven-openswe[bot]@users.noreply.github.com>
Co-authored-by: Adam Moussa <166072409+amoussa1229@users.noreply.github.com>
---
 AGENTS.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4cb7e3b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,57 @@
+# AGENTS.md
+
+Instructions for coding agents working in this repository.
+
+## Infrastructure as Code principles
+
+- **CDK + EC2**: this repo deploys an EC2 instance via CDK TypeScript. No Lambda, no SAM.
+- **Lambda defaults (does not apply)** — this is a pure EC2 stack.
+- **Exact-pin all CDK library versions** (`aws-cdk-lib`, `aws-cdk`, `constructs`). Never use `*` or `^` ranges.
+- **Never commit** account IDs, role ARNs, VPC IDs, subnet IDs, or volume IDs in new code. The existing `cdk.context.json` already contains resolved values — do not add new deployment-specific identifiers without documented defaults.
+- **Deploy with least-privilege IAM.** The instance role already has only `AmazonSSMManagedInstanceCore` + Secrets Manager read on `file-share/*`.
+- **Verify**: `npm run build && npx cdk synth && npx cdk diff` before pushing. Do not commit `cdk.out/`.
+
+## CDK directory layout
+
+```
+.
+├── bin/
+│   └── app.ts              # CDK app entrypoint
+├── lib/
+│   └── file-share-stack.ts  # All resource definitions
+├── cdk.json                  # CDK context + config
+├── cdk.context.json          # Resolved context (committed)
+├── package.json              # Exact-pinned CDK dependencies
+├── tsconfig.json
+└── .github/
+    └── workflows/            # CI/CD
+```
+
+## `overrideLogicalId` — never remove
+
+Removing `overrideLogicalId` on a deployed resource forces replacement. Never remove an existing call without documenting the replacement impact.
+
+## Persistent EBS volumes
+
+This repo's data volume (`vol-04d951cccacc435b5`) is **imported by ID**, not managed by CloudFormation. It survives instance replacement and stack deletion.
+
+### Snapshot before an EC2-replacing deploy
+
+Before any deploy that would replace the EC2 instance (AMI change, user-data change, instance type change):
+
+1. Run `cdk diff` to confirm the instance will be replaced.
+2. **Stop and ask for confirmation** — an instance replacement detaches the imported volume. A snapshot is the safety net.
+3. If a DLM snapshot already exists from the same day, reference it rather than creating a duplicate.
+
+## Security group rules
+
+- Never open 0.0.0.0/0. All rules use specific CIDR ranges (`10.10.0.0/16` VPN, `10.20.0.0/16` VPC).
+- SSM Session Manager for instance access — no SSH key, no public port 22.
+
+## Secrets
+
+Stored in AWS Secrets Manager (`file-share/smb-password`, `file-share/filebrowser-password`). The instance role reads them at boot. Do not embed secrets in UserData or source files.
+
+## Documentation
+
+The Confluence "AWS Architecture Map" (page 1540098) should be updated alongside any architecture change.
\ No newline at end of file