Copilot instructions

1---
2applyTo: "**/*.ts, **/cdk.json, **/*.tf, **/*.tfvars, **/template.yaml, **/samconfig.toml, **/cloudformation/**/*.yaml, **/cdk/**/*.ts"
3description: "AWS architecture standards: Well-Architected Framework, CDK TypeScript patterns, Terraform HCL conventions, IAM least-privilege, and tagging strategy."
4---
5 
6## Context
7 
8This instruction file applies to AWS infrastructure code: CDK TypeScript stacks, Terraform HCL modules, CloudFormation templates, and SAM application templates. All AWS infrastructure must be designed and reviewed against the AWS Well-Architected Framework six pillars.
9 
10---
11 
12## Well-Architected Non-Negotiables
13 
14### Operational Excellence
15- All resources must emit structured logs to CloudWatch Logs
16- All stateful changes must produce CloudTrail audit events
17- Runbooks must exist for all P1/P2 failure modes before go-live
18 
19### Security
20- **No hardcoded credentials** in any IaC file — use Secrets Manager, Parameter Store, or IAM roles
21- **No `*` in IAM policies** without SCPs as compensating controls and documented justification
22- All data at rest encrypted: S3 SSE-KMS (or SSE-S3 minimum), RDS KMS, EBS KMS
23- All data in transit over TLS 1.2+; no HTTP endpoints for sensitive data
24- VPC endpoints for S3, ECR, SSM, Secrets Manager to avoid NAT Gateway costs and internet exposure
25- Enable GuardDuty, Security Hub, and CloudTrail in all accounts
26 
27### Reliability
28- **Multi-AZ for all production workloads** — minimum 2 AZs, prefer 3
29- RDS Multi-AZ enabled in production; Aurora Global Database for RPO < 1 min
30- ECS/EKS workloads must have `minHealthyPercent: 100` during deployments
31- SQS DLQ configured for all consumer-facing queues
32- Circuit breakers on all external service calls
33 
34### Performance Efficiency
35- Right-size before deploying: use Graviton (ARM) instances where workload is compatible
36- CloudFront in front of S3 static assets and API Gateway for edge caching
37- ElastiCache (Redis) for session state and expensive read-only lookups
38- Auto-scaling configured with warm-up periods; never fixed-capacity in production
39 
40### Cost Optimisation
41- Use Graviton instances (e.g., `t4g`, `m7g`, `r7g`) — ~20% cheaper than x86 equivalents
42- S3 Intelligent-Tiering for infrequently accessed objects > 128 KB
43- Reserved Instances or Savings Plans for stable baseline workloads
44- NAT Gateway: one per AZ max; use VPC endpoints where possible
45- Lambda: set memory correctly — over-allocated Lambda is wasted spend
46 
47### Sustainability
48- Consolidate workloads to reduce idle capacity
49- Prefer serverless (Lambda, Fargate, Aurora Serverless) where workload is bursty
50 
51---
52 
53## CDK TypeScript Standards
54 
55- **Use L2/L3 constructs** — prefer CDK patterns libraries over raw L1 CloudFormation resources
56- **Stack props typed via interface** — no `any` types in CDK code
57- **Environment-aware stacks** — read `env` from CDK context, never hardcode account/region
58- **`RemovalPolicy.RETAIN`** for stateful resources (RDS, DynamoDB, S3) in production environments
59- **CDK Aspects for tagging** — apply mandatory tags via `Aspects.of(app).add(new TaggingAspect(tags))`
60- **Secrets via `SecretValue.ssmSecure()` or `Secret.fromSecretNameV2()`** — never `SecretValue.unsafePlainText()`
61 
62```typescript
63// CORRECT: Environment from context
64const env = app.node.tryGetContext('env') ?? 'dev';
65const isProd = env === 'prod';
66 
67// CORRECT: Conditional removal policy
68new s3.Bucket(this, 'DataBucket', {
69  removalPolicy: isProd ? cdk.RemovalPolicy.RETAIN : cdk.RemovalPolicy.DESTROY,
70  autoDeleteObjects: !isProd,
71});
72```
73 
74---
75 
76## Terraform Standards
77 
78- **Remote state in S3 + DynamoDB locking** — no local state files committed to git
79- **Modular structure**: `main.tf`, `variables.tf`, `outputs.tf`, `versions.tf` per module
80- **`versions.tf` pins provider versions** with `~>` constraint — no unpinned providers
81- **`default_tags` on AWS provider** for consistent resource tagging
82- **Workspaces or directory-per-env** for environment isolation (prefer directory-per-env for production separation)
83 
84```hcl
85# CORRECT: Provider with default tags
86provider "aws" {
87  region = var.aws_region
88  default_tags {
89    tags = {
90      Project     = var.project_name
91      Environment = var.environment
92      ManagedBy   = "Terraform"
93      Owner       = var.team_name
94    }
95  }
96}
97```
98 
99---
100 
101## Mandatory Tagging Strategy
102 
103All AWS resources must carry:
104 
105| Tag Key | Example Value | Required |
106|---------|-------------|---------|
107| `Project` | `smart-retail` | Yes |
108| `Environment` | `prod` / `staging` / `dev` | Yes |
109| `Owner` | `platform-team` | Yes |
110| `CostCentre` | `CC-1234` | Yes |
111| `ManagedBy` | `CDK` / `Terraform` | Yes |
112 
113---
114 
115## IAM Least Privilege Checklist
116 
117- [ ] No `*` actions without documented justification
118- [ ] No `*` resources; use specific ARNs with `${AWS::AccountId}` / `${AWS::Region}`
119- [ ] Conditions used where applicable: `aws:RequestedRegion`, `aws:SourceAccount`
120- [ ] Task roles for ECS/Lambda have only the permissions needed for that function
121- [ ] Cross-account trust uses `aws:PrincipalOrgID` condition, not account IDs
122