# Cdk Contribution Skill > Guide AWS CDK contributions from GitHub issue analysis to PR-ready code. Use when contributing to aws-cdk repository, analyzing CDK issues, implementing fixes, or preparing pull requests. Use when this capability is needed. - Skill: `tomevault-io/cdk-contribution-skill` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/cdk-contribution-skill` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/cdk-contribution-skill/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/cdk-contribution-skill --- # CDK Contribution Workflow Orchestrates specialized phases for AWS CDK contributions with human approval gates. ## MANDATORY: Present Workflow Overview FIRST BEFORE doing ANY work, you MUST present the ASCII workflow diagram below, explain the process, and wait for confirmation. This is NON-NEGOTIABLE. Display this to the user: ```text CDK Contribution Workflow for Issue # I'll guide you through a structured process with human approval gates: +------------------------------------------+ | MAIN ORCHESTRATOR | | (Me - Coordinates work) | +--------------------+---------------------+ | +---------------+--------------+ | PHASE 1: ANALYSIS | +---------------+--------------+ | v +-------------------------------+ | ISSUE ANALYST | | [subagent] Analyze issue, | | classify type, explore code | +---------------+---------------+ | +---------------+--------------+ | PHASE 2: PLANNING | +---------------+--------------+ | v +-------------------------------+ | SOLUTION ARCHITECT | | [subagent] Propose solution, | | tests, and impl approach | +---------------+---------------+ | v +-------------------------------+ | YOUR APPROVAL | | Issue at a glance (ASCII) | | Proposed solution (ASCII) | | Unit + integ test plan | | | | Continue? Yes | No | | | Something Else | +---------------+---------------+ [YES] | +---------------+--------------+ | PHASE 3: BUILD & IMPL | +---------------+--------------+ | v +-------------------------------+ | BUILD SETUP + IMPLEMENT | | Branch, env, write code | +---------------+---------------+ | +---------------+--------------+ | PHASE 4: PARALLEL VALID | +-------+-------+-------+------+ | | | v v v +------+ +-----+ +------+ | TEST | | QA | | DOCS | +--+---+ +--+--+ +--+---+ +-------+-------+ | +--------------+--------------+ | PHASE 5: SELF REVIEW | +-------+---------------------+ | | v v +------------+ +------------+ | SECURITY | | REGRESSION | | REVIEW | | REVIEW | +------+-----+ +-----+------+ +----------+---+ | v +--------------------+ | SYNTHESIZE | | REVIEW REPORT | +--------+-----------+ | v +-------------------------------+ | REVIEW FINDINGS | | Submit PR or fix issues | +-------------------------------+ Key Points: - Phase 1 (Analysis) runs first, then Phase 2 (Planning) runs after — sequential, not parallel - You review and approve the plan before any code is written - I pause for your input at critical decision points Should we start? Yes | No ``` STOP and wait for user response. Do NOT proceed until the user confirms. --- ## Reference Files **CRITICAL**: The reference files in the `references/` folder define the exact structure and content of each deliverable per phase. You MUST read the relevant reference file BEFORE executing each phase: | SOP | Phase | Purpose | |-----|-------|---------| | `issue-analyst-sop.md` | 1 – Analysis | Issue analysis and classification | | `solution-architect-sop.md` | 2 – Planning | Solution design and planning | | `build-engineer-sop.md` | 3 – Build & Impl | Build environment setup | | `implementation-specialist-sop.md` | 3 – Build & Impl | Code implementation | | `test-engineer-sop.md` | 4 – Validation | Unit and integration testing | | `quality-assurance-sop.md` | 4 – Validation | Lint, build, and quality checks | | `documentation-specialist-sop.md` | 4 – Validation | README and docs updates | | `security-reviewer-sop.md` | 5 – Self Review | Security review | | `regression-reviewer-sop.md` | 5 – Self Review | Regression review | | `review-report-generator-sop.md` | 5 – Self Review | Final review report synthesis | Supplementary references: `debug-ci.md`, `integ-testing.md` ## Deliverables Each phase MUST write its output to markdown files under `.kiro/contributions//`: | Phase | Output file | |---------|----------------------------------------------------------------| | Phase 1 | `.kiro/contributions//01-analysis.md` | | Phase 2 | `.kiro/contributions//02-solution.md` | | Phase 3 | `.kiro/contributions//03-build.md` | | Phase 4 | `.kiro/contributions//test-results.md` | | Phase 4 | `.kiro/contributions//quality-validation.md` | | Phase 4 | `.kiro/contributions//pr.md` | | Phase 4 | `.kiro/contributions//04-validation.md` | | Phase 5 | `.kiro/contributions//security-review.md` | | Phase 5 | `.kiro/contributions//regression-review.md` | | Phase 5 | `.kiro/contributions//05-review.md` | The subagent for each phase is responsible for writing its own deliverable file(s) before returning. The orchestrator reads the file as the handoff input to the next phase. ### Deliverable ASCII Diagram Requirement Every deliverable markdown file MUST include at least one ASCII diagram that visually summarises the key findings or structure of that phase. Examples by phase: - Phase 1: module/file dependency map or issue impact diagram - Phase 2: solution architecture diagram showing files to change and their relationships - Phase 3: branch/build setup flow - Phase 4: test coverage map (unit vs integ, pass/fail) - Phase 5: review findings summary (security + regression side by side) Use plain ASCII box-and-arrow style. No emoji. Example: ```text +----------------+ +------------------+ | affected.ts | ----> | test/foo.test.ts | +----------------+ +------------------+ | v +----------------+ | features.ts | (new feature flag) +----------------+ ``` --- ## Phase Execution Instructions ### When user says "Yes" to start: IMPORTANT: Phase 1 and Phase 2 are SEQUENTIAL — Phase 2 depends on Phase 1's output. Do NOT invoke them in parallel. Do NOT put them in the same subagent call. **Step A — Invoke Phase 1 subagent:** > **MANDATORY PRE-READ: Before executing this phase, you MUST read the instructions in `references/issue-analyst-sop.md`** > **Do NOT proceed until you have read the file and understand the required deliverables.** > > Analyze the GitHub issue at . > > To fetch issue data, use the following priority order: > > 1. PRIMARY - gh CLI (preferred): > - `gh issue view --repo aws/aws-cdk --json number,title,body,labels,comments,state` > - `gh issue view --repo aws/aws-cdk --comments` for full comment thread > - `gh pr list --repo aws/aws-cdk --search "" --json number,title,url` for linked PRs > > 2. FALLBACK - GitHub MCP server (only if gh CLI is unavailable or fails): > - Use MCP github tools with perPage: 3 to avoid token overflow > > Then explore the aws-cdk codebase to understand the affected module(s), existing patterns, test > conventions, and any related code. Classify the issue type (bug, feature, docs, etc.). > Produce a structured analysis: issue summary, affected files/modules, root cause or gap, > relevant CDK patterns observed, and any constraints or risks. > > Write your full analysis to `.kiro/contributions//01-analysis.md` before returning. **Step B — WAIT for Phase 1 to complete, then read its output:** Read `.kiro/contributions//01-analysis.md` to confirm it was written successfully. **Step C — Only AFTER Phase 1 is complete, invoke Phase 2 subagent:** Pass the content of `01-analysis.md` as `relevant_context` to the Phase 2 subagent: > **MANDATORY PRE-READ: Before executing this phase, you MUST read the instructions in `references/solution-architect-sop.md`** > **Do NOT proceed until you have read the file and understand the required deliverables.** > > Using the analysis provided in the context, propose a concrete solution for the CDK > contribution. Include: the implementation approach, which files need to change and how, > required unit tests (what to test and why), required integ tests (which integ test file, > what scenario to cover), and any breaking change considerations. Be specific about CDK > patterns to follow. > > Write your full proposal to `.kiro/contributions//02-solution.md` before returning. Do NOT ask the user for input between Phase 1 and Phase 2 — proceed automatically. --- ### After both subagents complete, present this proposal to the user: ``` ISSUE AT A GLANCE ================= Issue: # - Type: <bug | feature | docs | ...> Module: <e.g. aws-lambda, aws-s3, ...> Impact: <one line> Affected files: - <file 1> - <file 2> - ... Root cause / gap: <2-3 sentence summary> Constraints / risks: - <item> - ... PROPOSED SOLUTION ================= Approach: <concise description of the fix or feature> Files to change: +---------------------------+----------------------------------+ | File | Change | +---------------------------+----------------------------------+ | <path/to/file.ts> | <what changes> | | <path/to/other.ts> | <what changes> | +---------------------------+----------------------------------+ Unit tests: File: <test file path> +------------------------------------------+ | Test case | +------------------------------------------+ | <describe what is tested> | | <describe what is tested> | +------------------------------------------+ Integ tests: File: <integ test file path> Scenario: <what the integ test exercises> Snapshot update required: Yes | No Breaking changes: Yes | No <if yes, explain> Continue with this plan? Yes | No | Something Else ``` --- ## Phases 3-5 (after plan approval) ### Phase 3: Build & Implementation **STEP 0 — READ SOPs (non-negotiable, do this FIRST):** You MUST read BOTH of these files before ANY other action in this phase: 1. `references/build-engineer-sop.md` - provides instructions for the build phase 2. `references/implementation-specialist-sop.md` - provides instructions for the implementation phase After reading, confirm you understand the required deliverables and procedures. **STEP 1** Before doing anything, present this summary to the user: ```text PHASE 3: BUILD & IMPLEMENTATION ================================ Here's what I'm about to do: 1. Create local branch fix/issue-<NUMBER>-<slug> 2. Sync with upstream git fetch upstream && git rebase upstream/main 3. Assess build need read 02-solution.md to decide if yarn build is required 4. Implement apply all changes from the approved plan Kicking off now... ``` Then proceed immediately without waiting for a response. Steps (in order, no skipping): 1. Create a local PR branch named `fix/issue-<NUMBER>-<short-description>` from current HEAD 2. Sync with upstream main: - `git fetch upstream` - `git rebase upstream/main` - If no upstream remote exists: `git remote add upstream https://github.com/aws/aws-cdk.git` then fetch 3. Assess whether a build is required: - Read `02-solution.md` — if changes touch generated code, L1 constructs, or cross-package imports that require compilation, build the affected package(s) with `yarn build` - If changes are purely in `.ts` source + tests with no codegen dependency, skip the build and go straight to implementation - Document the decision in `03-build.md` 4. Implement all changes from the approved plan in `02-solution.md`. 5. Write deliverable to `.kiro/contributions/<ISSUE_NUMBER>/03-build.md` (with ASCII diagram) ### Phase 4: Parallel Validation **STEP 0 — READ SOPs (non-negotiable, do this FIRST):** You MUST read ALL THREE of these files before ANY other action in this phase: 1. `references/test-engineer-sop.md` - provides instructions for the testing subagent. Required deliverable: `test-results.md`. 2. `references/quality-assurance-sop.md` - provides instructions for the QA subagent. Required deliverable: `quality-validation.md` 3. `references/documentation-specialist-sop.md` - provides instructions for the documentation subagent. Required deliverable: `pr.md` After reading, confirm you understand the required deliverables and procedures. **STEP 1** Before doing anything, present this summary to the user: ```text PHASE 4: PARALLEL VALIDATION ============================== Here's what I'm about to do (all three run in parallel): +---------------------+ +------------------+ +------+ | TEST | | QA | | DOCS | +---------------------+ +------------------+ +------+ | - Run unit tests | | yarn lint | | Check| | for affected pkgs | | yarn build (tsc) | | README| | - Verify integ test | | for affected | | needs| | files exist and | | packages | | update| | are well-formed | | | | | | - Dry-run integ | | | | | | snapshot check | | | | | +---------------------+ +------------------+ +------+ | | | +------------------+------------------+ | 04-validation.md Kicking off now... ``` Then proceed immediately without waiting for a response. Run all three as parallel subagents simultaneously. Do NOT wait for one to finish before starting the next. - TEST subagent: - Run unit tests for all affected packages - Integ tests: 1. Check if new or updated integ test files exist (compare against `02-solution.md` plan) 2. If YES — run `yarn integ-runner --update-on-failed` on those files to deploy and regenerate snapshots 3. If NO — run `yarn integ-runner --update-on-failed` on the relevant module to confirm existing snapshots are intact and unchanged - QA checks (lint, build) - Documentation updates When all three subagents have succeeded, summarize the testing, QA and documentation details in `.kiro/contributions/<ISSUE_NUMBER>/04-validation.md`. ### Phase 5: Self Review **STEP 0 — READ SOPs (non-negotiable, do this FIRST):** You MUST read ALL THREE of these files before ANY other action in this phase: 1. `references/security-reviewer-sop.md` - provides instructions for the security review subagent. Required deliverable: `security-review.md`. 2. `references/regression-reviewer-sop.md` - provides instructions for the regression review subagent. Required deliverable: `regression-review.md` 3. `references/review-report-generator-sop.md` - provides instructions for creating the final review report. Required deliverable: `05-review.md` After reading, confirm you understand the required deliverables and procedures. **STEP 1** Before doing anything, present this summary to the user: ```text PHASE 5: SELF REVIEW ===================== Here's what I'm about to do (both run in parallel): +------------------+ +------------------+ | SECURITY | | REGRESSION | | REVIEW | | REVIEW | +------------------+ +------------------+ | - IAM/policy | | - Snapshot diff | | impact check | | - API surface | | check | | breaking change| | - Secrets/creds | | - Existing test | | exposure check | | coverage gaps | | - CDK nag rules | | - CloudFormation | +------------------+ | drift risk | | +------------------+ +--------+--------+ | 05-review.md | v SYNTHESIZE GO/NO-GO Kicking off now... ``` Then proceed immediately without waiting for a response. Run both as parallel subagents simultaneously. Do NOT wait for one to finish before starting the next. Synthesize findings into a go/no-go report in `.kiro/contributions/<ISSUE_NUMBER>/05-review.md` and present to user before PR submission. ### Phase 6: PR Submission After the user approves the go/no-go report, commit and create the PR. **MANDATORY**: Every PR description body MUST end with this marker line: ``` [comment]: <> (by cdk-contribution-skill) ``` This is a hidden Markdown comment that identifies PRs created via this workflow. It MUST be the last line of the PR body. Do NOT omit it. --- ## Prerequisites - Local clone of `aws-cdk` repository - Node.js v18+, Yarn - `gh` CLI (preferred for issue analysis) — `gh auth login` must be completed - GitHub MCP server (fallback if `gh` CLI is unavailable) --- > Source: [cdklabs/cdk-contribution-skill](https://github.com/cdklabs/cdk-contribution-skill) — distributed by [TomeVault](https://tomevault.io). <!-- tomevault:4.0:skill_md:2026-06-22 -->