cdklabs · chaodu-agent · May 18, 2026 · May 18, 2026
diff --git a/cdk-contribution-skill/SKILL.md b/cdk-contribution-skill/SKILL.md
@@ -7,6 +7,8 @@ description: Guide AWS CDK contributions from GitHub issue analysis to PR-ready
 
 Orchestrates specialized phases for AWS CDK contributions with human approval gates.
 
+**Global Prerequisite**: All phases MUST read the relevant sections of `AGENTS.md` (at aws-cdk repo root) before executing. It defines construct design, naming, props, security, error handling, and testing standards.
+
 ## MANDATORY: Present Workflow Overview FIRST
 
 BEFORE doing ANY work, you MUST present the ASCII workflow diagram below, explain the process,

diff --git a/cdk-contribution-skill/references/build-engineer-sop.md b/cdk-contribution-skill/references/build-engineer-sop.md
@@ -12,6 +12,10 @@ You are the Build Engineer, responsible for preparing clean development environm
 - Ensure clean development environment before implementation
 - Handle build processes and module compilation
 
+## Prerequisites
+
+> **Prerequisite:** All construct design, naming, props, security, and testing standards are defined in `AGENTS.md`. Read relevant sections before executing this phase.
+
 ## Input Requirements
 
 - Issue number (to create branch name)

diff --git a/cdk-contribution-skill/references/documentation-specialist-sop.md b/cdk-contribution-skill/references/documentation-specialist-sop.md
@@ -13,6 +13,10 @@ You are the Documentation Specialist, responsible for creating comprehensive PR
 - Write clear technical explanations for reviewers
 - Ensure proper conventional commit formatting
 
+## Prerequisites
+
+> **Prerequisite:** All construct design, naming, props, security, and testing standards are defined in `AGENTS.md`. Read relevant sections before executing this phase.
+
 ## Input Requirements
 
 Before starting, read available artifacts:

diff --git a/cdk-contribution-skill/references/implementation-specialist-sop.md b/cdk-contribution-skill/references/implementation-specialist-sop.md
@@ -13,6 +13,10 @@ You are the Implementation Specialist, responsible for writing the actual code c
 - Implement features/fixes according to the solution architect's plan
 - Handle TypeScript, API design, and CloudFormation template generation
 
+## Prerequisites
+
+> **Prerequisite:** All construct design, naming, props, security, and testing standards are defined in `AGENTS.md`. Read relevant sections before executing this phase.
+
 ## Input Requirements
 
 Before starting, read:
@@ -78,11 +82,7 @@ git commit -m "docs(<module>): <description>"
 
 ### Step 1: Start Watch Mode ⚠️ CRITICAL
 
-```bash
-# Start incremental compilation in background
-cd packages/aws-cdk-lib
-yarn watch
-```
+Start incremental compilation (see `AGENTS.md § Quick Reference — Commands`).
 
 Keep this running throughout implementation. It will:
 - Incrementally compile TypeScript changes
@@ -137,18 +137,7 @@ Write all tests as specified in `02-solution.md`:
 
 ### Step 4: Verify Implementation
 
-```bash
-# Verify watch mode shows no errors
-# Check the yarn watch output
-
-# Run linting
-cd packages/aws-cdk-lib/aws-<service>
-yarn lint --fix
-
-# Run all unit tests for the module
-cd packages/aws-cdk-lib
-yarn test aws-<service>
-```
+Run lint and unit tests (see `AGENTS.md § Quick Reference — Commands`).
 
 ### Step 5: Commit Changes
 
@@ -157,80 +146,9 @@ git add .
 git commit -m "feat(<module>): <description>"
 ```
 
-## CDK Implementation Standards
-
-### JSII Compatibility ⚠️ CRITICAL
-
-```typescript
-// ❌ WRONG - Cannot extend native Error class
-export class MyError extends Error { }
-
-// ✅ CORRECT - Use existing CDK error types (1st arg is an error code via `lit` tag)
-import { UnscopedValidationError } from '../../core';
-import { lit } from '../../core/lib/private/literal-string';
-throw new UnscopedValidationError(lit`InvalidPropValue`, 'Clear error message with suggested fix');
-
-// ✅ CORRECT - For construct-specific errors
-import { ConstructError } from '../../core';
-export class MyError extends ConstructError { }
-```
-
-### Error Handling Patterns
-
-```typescript
-// Always provide actionable error messages
-if (!isValidInput(input)) {
-  throw new UnscopedValidationError(
-    lit`InvalidInput`,
-    `Invalid input '${input}'. ${getValidationSuggestion(input)}`
-  );
-}
-```
-
-### Validation Implementation
+## CDK Standards Reference
 
-```typescript
-// Follow this pattern for input validation
-private validateProps(props: MyConstructProps): void {
-  if (props.value < 0) {
-    throw new UnscopedValidationError(
-      lit`NegativeValue`,
-      `'value' must be non-negative, got ${props.value}`
-    );
-  }
-}
-```
-
-### API Design Patterns
-
-```typescript
-// Props interface pattern
-export interface MyConstructProps {
-  /**
-   * Description of the property.
-   * @default - default value description
-   */
-  readonly propertyName?: string;
-}
-
-// Construct pattern
-export class MyConstruct extends Construct {
-  constructor(scope: Construct, id: string, props: MyConstructProps) {
-    super(scope, id);
-    this.validateProps(props);
-    // Implementation
-  }
-}
-```
-
-### CloudFormation Generation
-
-```typescript
-// Use CfnResource for CloudFormation mapping
-const cfnResource = new CfnMyResource(this, 'Resource', {
-  propertyName: props.propertyName,
-});
-```
+See `AGENTS.md § Implementation Patterns` for JSII compatibility, error handling, validation, API design, and CloudFormation generation patterns.
 
 ## Output Deliverable
 

diff --git a/cdk-contribution-skill/references/quality-assurance-sop.md b/cdk-contribution-skill/references/quality-assurance-sop.md
@@ -12,6 +12,10 @@ You are the Quality Assurance Specialist, responsible for final validation and q
 - Validate no regressions in existing functionality
 - Perform final quality checks before PR generation
 
+## Prerequisites
+
+> **Prerequisite:** All construct design, naming, props, security, and testing standards are defined in `AGENTS.md`. Read relevant sections before executing this phase.
+
 ## Input Requirements
 
 Before starting, read:
@@ -21,31 +25,9 @@ Before starting, read:
 
 ## Procedure
 
-### Step 1: TypeScript Compilation Check
-
-```bash
-cd packages/aws-cdk-lib/aws-<service>
-npx tsc --noEmit
-```
-
-### Step 2: Linting with Auto-fix
+### Step 1-3: Compilation, Linting, Build
 
-```bash
-# Module-level linting
-cd packages/aws-cdk-lib/aws-<service>
-yarn lint --fix
-
-# Integration testing framework linting
-cd packages/@aws-cdk-testing/framework-integ
-yarn lint --fix
-```
-
-### Step 3: Full Build Verification
-
-```bash
-cd packages/aws-cdk-lib
-yarn build --fix
-```
+See `AGENTS.md § Quick Reference — Commands` for tsc, lint, and build commands.
 
 ### Step 4: Verify Success Criteria
 

diff --git a/cdk-contribution-skill/references/regression-reviewer-sop.md b/cdk-contribution-skill/references/regression-reviewer-sop.md
@@ -13,6 +13,10 @@ You are the Regression Reviewer, responsible for identifying potential regressio
 - Assess impact on existing deployments
 - Verify feature flag implementation (if applicable)
 
+## Prerequisites
+
+> **Prerequisite:** All construct design, naming, props, security, and testing standards are defined in `AGENTS.md`. Read relevant sections before executing this phase.
+
 ## Input Requirements
 
 Read available artifacts:

diff --git a/cdk-contribution-skill/references/review-report-generator-sop.md b/cdk-contribution-skill/references/review-report-generator-sop.md
@@ -13,6 +13,10 @@ You are the Review Report Generator, responsible for synthesizing security and r
 - Generate actionable remediation plan
 - Create final review report for human decision
 
+## Prerequisites
+
+> **Prerequisite:** All construct design, naming, props, security, and testing standards are defined in `AGENTS.md`. Read relevant sections before executing this phase.
+
 ## Input Requirements
 
 Before starting, read:

diff --git a/cdk-contribution-skill/references/security-reviewer-sop.md b/cdk-contribution-skill/references/security-reviewer-sop.md
@@ -18,6 +18,10 @@ You are the Security Reviewer, responsible for identifying potential security co
 - Assess CloudFormation security implications
 - Generate security review findings
 
+## Prerequisites
+
+> **Prerequisite:** All construct design, naming, props, security, and testing standards are defined in `AGENTS.md`. Read relevant sections before executing this phase.
+
 ## Input Requirements
 
 Before starting, you MUST read available artifacts:
@@ -85,11 +89,6 @@ You MUST review credential handling:
 - [ ] Sensitive data in CloudFormation outputs
 - [ ] Unencrypted sensitive parameters
 
-**REQUIRED Best Practices:**
-- Implementations MUST use AWS Secrets Manager or Systems Manager Parameter Store
-- Implementations MUST use SecureString parameters
-- Implementations MUST NOT expose secrets in stack outputs
-- Implementations SHOULD use IAM roles instead of access keys
 
 ### Step 5: CloudFormation Security Review
 
@@ -335,45 +334,7 @@ You MUST create `security-review.md`:
 
 ## Security Review Guidelines
 
-### Common CDK Security Patterns
-
-**RECOMMENDED Pattern - Least Privilege IAM**:
-```typescript
-const role = new iam.Role(this, 'Role', {
-  assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
-});
-role.addToPolicy(new iam.PolicyStatement({
-  actions: ['s3:GetObject'],
-  resources: [bucket.arnForObjects('data/*')],
-}));
-```
-
-**MUST NOT Use - Overly Permissive**:
-```typescript
-const role = new iam.Role(this, 'Role', {
-  assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
-});
-role.addToPolicy(new iam.PolicyStatement({
-  actions: ['s3:*'],
-  resources: ['*'],
-}));
-```
-
-**RECOMMENDED Pattern - Encrypted S3 Bucket**:
-```typescript
-const bucket = new s3.Bucket(this, 'Bucket', {
-  encryption: s3.BucketEncryption.S3_MANAGED,
-  enforceSSL: true,
-  blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
-});
-```
-
-**RECOMMENDED Pattern - Input Validation**:
-```typescript
-if (!Token.isUnresolved(props.name) && !/^[a-zA-Z0-9-]+$/.test(props.name)) {
-  throw new Error('Name must contain only alphanumeric characters and hyphens');
-}
-```
+See `AGENTS.md § Security Rules` for common CDK security patterns (least privilege IAM, encryption, input validation).
 
 ## Success Criteria
 

diff --git a/cdk-contribution-skill/references/solution-architect-sop.md b/cdk-contribution-skill/references/solution-architect-sop.md
@@ -13,6 +13,10 @@ You are the Solution Architect, responsible for creating comprehensive implement
 - Identify risks and mitigation strategies
 - Present plan for human approval before build/implementation begins
 
+## Prerequisites
+
+> **Prerequisite:** All construct design, naming, props, security, and testing standards are defined in `AGENTS.md`. Read relevant sections before executing this phase.
+
 ## Input Requirements
 
 Before starting, read:
@@ -147,23 +151,7 @@ Analyze each dimension:
 **Final Assessment**: **Breaking Change: [Yes/No]**
 
 **If Breaking Change Detected:**
-⚠️ **STOP - Breaking changes require special handling:**
-
-1. **Feature Flag Required**: Introduce a feature flag to protect existing workloads
-   - New behavior behind feature flag (opt-in)
-   - Old behavior remains default (preserves BC)
-   - Document migration path for users to adopt new behavior
-
-2. **Feature Flag Design:**
-   - Flag name: `@aws-cdk/<module>:<feature-name>`
-   - Default value: `false` (preserves existing behavior)
-   - Documentation: Clear explanation of old vs new behavior
-
-3. **Migration Requirements:**
-   - Migration path documented
-   - Deprecation timeline (if applicable)
-   - User communication plan
-   - Examples showing before/after with feature flag
+⚠️ **STOP** — See `AGENTS.md § Feature Flags` for implementation requirements.
 
 **Regression Prevention Checklist:**
 - [ ] Existing unit tests still pass without modifications
@@ -424,20 +412,12 @@ Provide an ASCII diagram illustrating the proposed solution:
 **If Breaking Change = Yes:**
 
 ### Feature Flag Implementation Required
-- **Feature Flag Name**: `@aws-cdk/<module>:<feature-name>`
-- **Default Value**: `false` (preserves existing behavior)
-- **New Behavior**: Only active when flag is `true` (opt-in)
-- **Rationale**: Protects existing deployed workloads from breaking changes on CDK upgrade
+See `AGENTS.md § Feature Flags` for naming, defaults, and implementation pattern.
 
 ### Backward Compatibility Strategy
 - **Old Behavior (default)**: <describe existing behavior that will be preserved>
 - **New Behavior (opt-in)**: <describe new behavior behind feature flag>
 - **Migration Path**: <how users can safely adopt new behavior>
-
-**Regression Prevention:**
-- [ ] Existing unit tests pass without modification
-- [ ] Integration tests verify no template changes for existing code
-- [ ] Default behavior unchanged
 - [ ] Feature flag properly isolates new behavior
 
 ## Implementation Strategy
@@ -456,21 +436,7 @@ Provide an ASCII diagram illustrating the proposed solution:
 <API design decisions and rationale>
 
 ### Feature Flag Implementation (if Breaking Change)
-**If Breaking Change = Yes, this section is REQUIRED:**
-
-- **Feature Flag Name**: `@aws-cdk/<module>:<feature-name>`
-- **Default Value**: `false` (preserves existing behavior)
-- **Implementation Location**: <file path where flag is checked>
-- **Behavior When Disabled (default)**: <existing behavior preserved>
-- **Behavior When Enabled (opt-in)**: <new behavior activated>
-- **Flag Check Pattern**:
-  ```typescript
-  if (FeatureFlags.of(this).isEnabled(cxapi.FEATURE_FLAG_NAME)) {
-    // New behavior
-  } else {
-    // Existing behavior (default)
-  }
-  ```
+See `AGENTS.md § Feature Flags` for flag naming, check pattern, and implementation details.
 
 ### Error Handling
 <error handling approach>
@@ -523,17 +489,7 @@ Provide an ASCII diagram illustrating the proposed solution:
 - **Behavior**: <new behavior description>
 
 ### Migration Steps for Users
-1. **Test with Feature Flag**: Enable flag in cdk.json for testing
-   ```json
-   {
-     "context": {
-       "@aws-cdk/<module>:<feature-name>": true
-     }
-   }
-   ```
-2. **Validate Changes**: Review CloudFormation template diff
-3. **Deploy to Non-Production**: Test in staging environment
-4. **Deploy to Production**: Roll out with confidence
+See `AGENTS.md § Feature Flags` for the cdk.json context pattern and migration approach.
 
 ### Deprecation Timeline
 - **Current Release**: New behavior available behind feature flag