diff --git a/cdk-contribution-skill/SKILL.md b/cdk-contribution-skill/SKILL.md index 7b6970f..3db3883 100644 --- 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 index 852f05a..f7a4fc7 100644 --- 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 index 036194d..92ba6e3 100644 --- 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 index 0445343..68ac972 100644 --- 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(): " ### 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- -yarn lint --fix - -# Run all unit tests for the module -cd packages/aws-cdk-lib -yarn test aws- -``` +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(): " ``` -## 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 index aacb52e..e2bece2 100644 --- 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- -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- -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 index c2d87d5..b42ebaa 100644 --- 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 index 4673f32..012ef98 100644 --- 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 index 573dfef..eb78e80 100644 --- 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 index a4115d7..f24e6f1 100644 --- 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/:` - - 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/:` -- **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)**: - **New Behavior (opt-in)**: - **Migration Path**: - -**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: ### Feature Flag Implementation (if Breaking Change) -**If Breaking Change = Yes, this section is REQUIRED:** - -- **Feature Flag Name**: `@aws-cdk/:` -- **Default Value**: `false` (preserves existing behavior) -- **Implementation Location**: -- **Behavior When Disabled (default)**: -- **Behavior When Enabled (opt-in)**: -- **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 @@ -523,17 +489,7 @@ Provide an ASCII diagram illustrating the proposed solution: - **Behavior**: ### Migration Steps for Users -1. **Test with Feature Flag**: Enable flag in cdk.json for testing - ```json - { - "context": { - "@aws-cdk/:": 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 diff --git a/cdk-contribution-skill/references/test-engineer-sop.md b/cdk-contribution-skill/references/test-engineer-sop.md index 4b92900..c4d5701 100644 --- a/cdk-contribution-skill/references/test-engineer-sop.md +++ b/cdk-contribution-skill/references/test-engineer-sop.md @@ -13,6 +13,10 @@ You are the Test Engineer, responsible for executing tests written by the Implem - Report test results back to Implementation Specialist for fixes - Validate 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: @@ -23,10 +27,7 @@ Before starting, read: ### Step 1: Start Watch Mode -```bash -cd packages/aws-cdk-lib -yarn watch -``` +Start incremental compilation (see `AGENTS.md § Quick Reference — Commands` for exact command). Benefits: - Automatic incremental compilation on file changes @@ -35,10 +36,7 @@ Benefits: ### Step 2: Execute Module Unit Tests -```bash -cd packages/aws-cdk-lib -yarn test aws- -``` +Run module unit tests (see `AGENTS.md § Quick Reference — Commands` for exact command). This validates: - Tests written by Implementation Specialist work correctly @@ -52,15 +50,7 @@ Analyze results: ### Step 3: Execute Integration Tests -```bash -cd packages/@aws-cdk-testing/framework-integ - -# List integration tests written by Implementation Specialist -ls test//test/integ*.js - -# Run integration tests with snapshot updates -yarn integ-runner --directory test//test/ --update-on-failed -``` +Run integ-runner (see `AGENTS.md § Quick Reference — Commands`). This validates: - CloudFormation template generation for the module