DEV Community: Pahud Hsieh

AI Can't Fix What It Can't See: How cdk diagnose Enables Autonomous CDK Remediation

Pahud Hsieh — Mon, 04 May 2026 18:27:26 +0000

AI Can't Fix What It Can't See: How `cdk diagnose` Enables Autonomous CDK Remediation

Current Behavior vs. What We Want

Today, when a CDK deployment fails through a pipeline, the remediation loop looks like this:

Developer ──▶ Push code ──▶ Pipeline ──▶ CFN deploy ──▶ ❌ Fails
                                                          │
    ┌─────────────────────────────────────────────────────┘
    │
    ▼
Developer manually:
    1. Opens pipeline UI
    2. Finds the failed stage
    3. Navigates to CloudFormation console
    4. Locates the failed change set
    5. Reads the CFN error message
    6. Mentally translates CFN → CDK
    7. Edits code, pushes, waits for pipeline again

🤖 Developer: "AI, fix this deployment for me"
🤖 AI: "Sure! I'll fix the CloudFormation template for you."
🤖 Developer: "...that's not how CDK works."

The AI has no access to the error, no construct path, no source location.
The best it can do is guess — and it guesses wrong, offering to edit
CloudFormation YAML instead of your CDK source code. Totally useless.

So what do we actually need for AI to address the root cause from CDK's perspective?

We need a diagnosis report that's actionable for AI to fix CDK code — not CloudFormation templates. Specifically, the AI needs:

What failed — which CloudFormation resource was rejected and why
Where in CDK — the construct path (MyStack/MyFunction/LogGroup) that maps the CFN logical ID back to your construct tree
Where in source code — the exact file and line number (lib/my-stack.ts:8:5) where the construct was created
What to do — enough context to reason about the fix (set a feature flag? import the existing resource? change the removal policy?)

That's exactly what cdk diagnose provides.

With cdk diagnose, the expected behavior becomes:

Developer ──▶ Push code ──▶ Pipeline ──▶ CFN deploy ──▶ ❌ Fails
                                                          │
    ┌─────────────────────────────────────────────────────┘
    │
    ▼
Developer (or AI agent):
    1. Runs: cdk diagnose MyStack
    2. Gets: construct path + error + source location
    3. Fixes the code
    4. Redeploys ✅

🤖 AI agent can do steps 1–4 autonomously.
   The entire loop is CLI-driven, machine-readable,
   and can be designed as an autonomous agent that
   diagnoses, fixes, and redeploys — without human intervention.

The difference: cdk diagnose turns a manual, console-bound, human-only workflow into a single command that both humans and AI agents can use. This is what makes AI-assisted remediation possible.

The Problem in Detail

Here's a scenario every CDK developer has lived through.

You write a perfectly valid CDK application. You run cdk synth — clean output, valid CloudFormation template, no errors. You push your code, the pipeline picks it up, and then... somewhere in the deployment, CloudFormation rejects it.

Now what?

If you deployed with cdk deploy, you're fine — the CLI catches the error, enriches it with your CDK construct path, and even points you to the source location in your code. But most teams don't deploy that way. They push to a pipeline — CDK Pipelines, CodePipeline, or an internal CI/CD system — and CDK only runs synth. The actual deployment happens through CloudFormation APIs directly.

When that deployment fails, the error is buried. You open the pipeline UI. Click through to the failed stage. Find the CloudFormation stack. Federate to the console. Navigate to the change set. And finally, you see something like:

Resource of type 'AWS::S3::Bucket' with identifier
'my-app-bucket' already exists.

Three to five clicks deep, in CloudFormation's language, with no connection back to your CDK code.

This is the gap that cdk diagnose fills.

┌──────────────┐     ┌──────────────┐     ┌──────────────────────┐
│  Developer   │────▶│  cdk synth   │────▶│  Pipeline / CI/CD    │
│  writes CDK  │     │  ✅ Looks     │     │  deploys to CFN      │
│              │     │     great!    │     │                      │
└──────────────┘     └──────────────┘     └──────────┬───────────┘
                                                     │
                                                     ▼
                                          ┌──────────────────────┐
                                          │   CloudFormation     │
                                          │   ❌ Deploy fails     │
                                          └──────────┬───────────┘
                                                     │
                          ┌──────────────────────────┴──────────────────────────┐
                          │                                                     │
                          ▼                                                     ▼
               ┌─────────────────────┐                            ┌──────────────────────┐
               │  WITHOUT diagnose   │                            │  WITH cdk diagnose   │
               │                     │                            │                      │
               │  1. Open Pipeline   │                            │  $ cdk diagnose      │
               │  2. Find stage      │                            │                      │
               │  3. Find stack      │                            │  ❌ MyFunction        │
               │  4. Open console    │                            │    🛑 LogGroup        │
               │  5. Find changeset  │                            │       already exists  │
               │  6. Read CFN error  │                            │    📍 stack.ts:8:5   │
               │  7. Translate to    │                            │  One command.         │
               │     CDK manually    │                            │  Source location.     │
               │                     │                            │  AI can act on this.  │
               │  🤖 AI can't help   │                            │  🤖 AI fixes code ✅  │
               └─────────────────────┘                            └──────────────────────┘

What is cdk diagnose?

cdk diagnose is a new CDK CLI subcommand that inspects a CloudFormation stack's last failed deployment and surfaces the root cause with CDK-aware context — construct paths, source locations, and actionable fix suggestions.

cdk --unstable=diagnose diagnose MyStack

It queries CloudFormation directly via DescribeChangeSet and related APIs, then enriches the raw error using CDK metadata (aws:cdk:path) to map CloudFormation logical IDs back to your constructs and source code.

The key insight: it works regardless of how the stack was deployed. Pipeline, cdk deploy, manual CloudFormation API call — doesn't matter. If the stack exists and it failed, cdk diagnose can tell you why.

A Real Example: The CDK Upgrade That Breaks Everything

Let me walk through a scenario that hit hundreds of real CDK users as a P0 issue (aws-cdk#34612). It's the kind of failure that makes cdk diagnose invaluable — because the developer did nothing wrong.

The Setup

You have a Lambda function that's been running in production for months:

import * as cdk from 'aws-cdk-lib';
import * as lambda from 'aws-cdk-lib/aws-lambda';

export class MyAppStack extends cdk.Stack {
  constructor(scope, id, props) {
    super(scope, id, props);

    new lambda.Function(this, 'MyFunction', {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('lambda'),
      logRetention: cdk.aws_logs.RetentionDays.ONE_WEEK,
    });
  }
}

Standard code. Deployed and working. No issues.

Then you upgrade aws-cdk-lib from 2.199.0 to 2.200.0 — a routine version bump. You change nothing else in your code.

Synth: Looks Perfect

$ cdk synth

No errors. The template looks fine. You push to your pipeline.

Deploy: Fails

CREATE_FAILED | AWS::Logs::LogGroup | MyFunctionLogGroup
Resource of type 'AWS::Logs::LogGroup' with identifier
'/aws/lambda/MyFunction' already exists.

Wait — what? You didn't add a log group. You didn't change anything. Why is CloudFormation suddenly trying to create one?

What Happened

CDK 2.200.0 introduced a new feature flag @aws-cdk/aws-lambda:useCdkManagedLogGroup that defaults to true. This causes CDK to add an explicit AWS::Logs::LogGroup resource to your template for every Lambda function. The intent is good — CDK wants to manage the log group lifecycle so it can set retention policies and clean up on deletion.

But here's the catch: when your Lambda function first ran, AWS Lambda automatically created a log group named /aws/lambda/MyFunction. That log group already exists. Now CDK's template tries to create the same log group, and CloudFormation rejects it.

The developer did nothing wrong. The synth output looks correct. The failure only happens at deploy time because it depends on the runtime state of the AWS account.

Diagnose: Root Cause + Source Location

$ cdk --unstable=diagnose diagnose MyAppStack

🔍 Synthesizing with debug information. This may take a bit longer.
❌ Stack MyAppStack:
 └─ MyAppStack
     └─ MyFunction
         └─ LogGroup  (AWS::Logs::LogGroup MyFunctionLogGroupXXXXXXXX)
            🛑 Resource of type 'AWS::Logs::LogGroup' with identifier
               '/aws/lambda/MyFunction' already exists.
            Source Location: new MyAppStack (lib/my-app-stack.ts:8:5)

Now an AI agent has everything it needs:

What failed: AWS::Logs::LogGroup for /aws/lambda/MyFunction already exists
Where in CDK: MyAppStack/MyFunction/LogGroup — it's the log group associated with the Lambda construct
Where in source: lib/my-app-stack.ts:8:5 — the new lambda.Function(...) call
Context to reason about the fix: this is a known issue with the useCdkManagedLogGroup feature flag in CDK 2.200+

The AI-Assisted Fix

An AI agent reading this diagnosis can reason through the fix:

The log group already exists because Lambda auto-created it
CDK 2.200+ now tries to explicitly manage it
Fix option A: Set the feature flag to false to restore previous behavior:

   // cdk.json
   { "context": { "@aws-cdk/aws-lambda:useCdkManagedLogGroup": false } }

Fix option B: Import the existing log group so CDK can manage it going forward

This isn't a trivial "remove the hardcoded name" fix. It requires understanding CDK feature flags, Lambda log group lifecycle, and the tradeoffs between the two fix options. That's exactly the kind of reasoning AI agents excel at — when they have the right input.

Another Example: The Named Resource Trap

The Lambda log group issue is subtle — it only surfaces during a CDK upgrade. But there's an even more common class of failures that hits teams every day: named resources that already exist (aws-cdk#16686, aws-cdk#6183).

new s3.Bucket(this, 'DataBucket', {
  bucketName: 'my-team-data-bucket',
});

Perfectly valid CDK. Synth passes.

But if that bucket already exists in the account — from a previous stack that was torn down, from another team, or from a manual aws s3 mb — CloudFormation rejects it:

Resource of type 'AWS::S3::Bucket' with identifier
'my-team-data-bucket' already exists.

Same pattern with IAM roles, SQS queues, or any resource with a hardcoded physical name. CDK can't catch this at synth time because it's a runtime check against the actual state of your AWS account.

And here's what you see in the CloudFormation console — not helpful at all:

With cdk diagnose:

$ cdk --unstable=diagnose diagnose MyAppStack

❌ Stack MyAppStack:
 └─ MyAppStack
     └─ DataBucket
         └─ Resource  (AWS::S3::Bucket DataBucketXXXXXXXX)
            🛑 Resource of type 'AWS::S3::Bucket' with identifier
               'my-team-data-bucket' already exists.
            Source Location: new MyAppStack (lib/my-app-stack.ts:6:5)

An AI agent sees this and can reason: "The bucket name conflicts with an existing resource. I should either remove the hardcoded bucketName to let CloudFormation generate a unique name, or import the existing bucket with cdk import."

Simple to understand, but impossible for AI to act on without cdk diagnose surfacing the error in the first place.

Why This Matters for AI

Here's where it gets interesting.

Without cdk diagnose, an AI agent has no way to help you fix a deployment failure. The error is locked behind a multi-step console navigation that requires browser interaction, AWS console federation, and human eyeballs. There's no CLI command, no API, no machine-readable output for the agent to consume.

With cdk diagnose, the entire remediation loop becomes automatable:

Pipeline fails
    │
    ▼
AI runs: cdk diagnose MyStack
    │
    ▼
AI reads structured output:
  "LogGroup '/aws/lambda/MyFunction' already exists
   at MyAppStack/MyFunction/LogGroup
   source: lib/my-app-stack.ts:8:5"
    │
    ▼
AI reasons: "CDK 2.200+ feature flag issue.
  Fix: set @aws-cdk/aws-lambda:useCdkManagedLogGroup to false"
    │
    ▼
AI edits cdk.json, redeploys
    │
    ▼
✅ Deployment succeeds

This is AI-assisted remediation. The AI agent can:

Diagnose — run cdk diagnose to get the structured error with construct path and source location
Reason — understand this is a CDK version upgrade issue involving feature flags and Lambda log group lifecycle
Fix — edit cdk.json to set the feature flag, or import the existing log group
Verify — redeploy and confirm the fix works

This isn't a simple text substitution. The AI needs to understand CDK concepts, feature flags, and AWS service behavior to pick the right fix. But it can only do that reasoning if it has the structured diagnosis as input. cdk diagnose is that input.

Putting It Together: Kiro CLI as the Autonomous Remediation Agent

So we have cdk diagnose producing structured, machine-readable error output. But who runs it? Who reads the output, reasons about the fix, edits the code, and redeploys?

This is where Kiro CLI comes in. Kiro CLI's chat subcommand supports a headless mode — set the KIRO_API_KEY environment variable and use --no-interactive, and Kiro runs programmatically without a browser or interactive session. Same tools, same agents, same capabilities — but fully automated.

# After a failed pipeline deployment, just run:
KIRO_API_KEY=your-api-key \
kiro-cli chat --no-interactive --trust-all-tools \
  "My CDK deployment of MyAppStack failed. \
   Run cdk diagnose to find the root cause and fix it."

The KIRO_API_KEY lets Kiro authenticate without a browser — essential for CI/CD pipelines and automated workflows. The --no-interactive flag executes the task and exits. The --trust-all-tools flag lets the agent run shell commands (like cdk diagnose and cdk deploy) without pausing for approval.

Here's what happens under the hood:

┌─────────────────────────────────────────────────────────┐
│  kiro chat (headless agent)                             │
│                                                         │
│  1. Runs: cdk --unstable=diagnose diagnose MyAppStack   │
│                                                         │
│  2. Reads output:                                       │
│     "LogGroup '/aws/lambda/MyFunction' already exists"  │
│     "Source: lib/my-app-stack.ts:8:5"                   │
│                                                         │
│  3. Reads lib/my-app-stack.ts to understand context     │
│                                                         │
│  4. Reasons: "CDK 2.200+ feature flag issue.            │
│     The log group was auto-created by Lambda.            │
│     Fix: set useCdkManagedLogGroup to false"            │
│                                                         │
│  5. Edits cdk.json:                                     │
│     + "@aws-cdk/aws-lambda:useCdkManagedLogGroup": false│
│                                                         │
│  6. Runs: cdk deploy                                    │
│                                                         │
│  7. ✅ Deployment succeeds                               │
└─────────────────────────────────────────────────────────┘

The key: Kiro CLI operates entirely in the terminal. No browser, no console, no clicking. It can run in a CI/CD pipeline's post-failure hook, in an SSH session, or on a developer's laptop. Combined with cdk diagnose, it closes the full loop from failure detection to automated fix.

This is what the autonomous remediation workflow looks like end to end:

Pipeline deploys ──▶ CFN fails
                        │
                        ▼
              Post-failure hook triggers:
              KIRO_API_KEY=$SECRET \
              kiro-cli chat --no-interactive --trust-all-tools \
                "diagnose and fix MyAppStack"
                        │
                        ▼
              Kiro CLI (headless):
                cdk diagnose → read error → edit code → cdk deploy
                        │
                        ▼
                   ✅ Fixed and redeployed
                   (or: opens PR with the fix for human review)

No human in the loop for the diagnosis and fix. A human reviews the PR if you want that gate — but the heavy lifting is done.

Here's what it looks like in practice — Kiro CLI diagnosing, fixing, and redeploying a failed stack in under 2 minutes:

$ kiro-cli chat --no-interactive --trust-all-tools \
    "My CDK stack CdkDiagnoseStack failed to deploy. \
     Run cdk diagnose to find the root cause and fix it."

> Let me start by running cdk diagnose to understand what went wrong.

🔍 Synthesizing with debug information. This may take a bit longer.
❌ Stack CdkDiagnoseStack:
Early validation failed for change set cdk-deploy-change-set:
 └─ CdkDiagnoseStack
     └─ MyBucket
         └─ Resource  (AWS::S3::Bucket MyBucketF68F3FF0)
            🛑 Resource of type 'AWS::S3::Bucket' with identifier
               'cdk-diagnose-demo-903779448426-us-east-1' already exists.
            Source Location:
              new CdkDiagnoseStack (lib/cdk-diagnose-stack.ts:12:5)

> The issue is clear: the S3 bucket has a hardcoded name that already
  exists. The fix is to remove the hardcoded name and let CloudFormation
  generate a unique one.

Updating: lib/cdk-diagnose-stack.ts
  12, 12:     new s3.Bucket(this, 'MyBucket', {
- 13    :       bucketName: 'cdk-diagnose-demo-903779448426-us-east-1',
  14, 13:       removalPolicy: cdk.RemovalPolicy.DESTROY,

> Now let me destroy the failed stack and redeploy:

 ✅  CdkDiagnoseStack: destroyed

CdkDiagnoseStack: deploying... [1/1]
CdkDiagnoseStack | 7/7 | CREATE_COMPLETE | AWS::CloudFormation::Stack

 ✅  CdkDiagnoseStack

✨  Deployment time: 36.28s

> ✅ Done. Here's what happened:
  1. cdk diagnose identified the root cause: hardcoded bucket name
     already existed, causing "resource already exists" error.
  2. Fix: Removed the hardcoded bucketName property.
  3. Redeployed successfully.

 ▸ Credits: 1.74 • Time: 1m 38s

Try It

cdk diagnose is available now in the latest CDK CLI (v2.1120.0+) behind the unstable flag:

npx cdk --unstable=diagnose diagnose <stack-name>

The --unstable flag indicates the API may still change, but the feature is production-ready and fully supported.

To try the full autonomous remediation flow with Kiro CLI:

# 1. Install Kiro CLI: https://kiro.dev/downloads/
# 2. Generate an API key at https://app.kiro.dev (account settings)
# 3. After a failed deployment:
KIRO_API_KEY=your-api-key \
kiro-cli chat --no-interactive --trust-all-tools \
  "My CDK stack MyAppStack failed to deploy. \
   Run cdk diagnose, find the root cause, and fix the code."

If you want a hands-on demo, here's a minimal CDK app that will fail on deploy:

// lib/my-app-stack.ts
import * as cdk from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
import { Construct } from 'constructs';

export class MyAppStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    new s3.Bucket(this, 'MyBucket', {
      bucketName: 'cdk-diagnose-demo-bucket',
      removalPolicy: cdk.RemovalPolicy.DESTROY,
      autoDeleteObjects: true,
    });
  }
}

Then run:

# 1. Pre-create the bucket so it conflicts
aws s3api create-bucket --bucket cdk-diagnose-demo-bucket

# 2. Deploy — this will fail
npx cdk deploy --require-approval never

# 3. Diagnose
npx cdk --unstable=diagnose diagnose MyAppStack

# 4. Let Kiro fix it
kiro-cli chat --no-interactive --trust-all-tools \
  "My CDK stack MyAppStack failed to deploy. \
   Run cdk diagnose, find the root cause, and fix the code."

# 5. Cleanup
aws s3 rb s3://cdk-diagnose-demo-bucket --force
aws cloudformation delete-stack --stack-name MyAppStack

The gap between "deployment failed" and "here's what to fix" just got a lot smaller. With cdk diagnose and Kiro CLI, it can be fully automated.

cdk diagnose was implemented by Rico Huijbers with contributions from Momo Kornher on the AWS CDK team. The feature landed in aws-cdk-cli#1378.

From Manual to Intent: 7 Years of CDK Contribution

Pahud Hsieh — Mon, 04 May 2026 17:56:44 +0000

Where It All Began: 2019 re:Invent

AWS CDK had just gone GA that year with TypeScript and Python support. At re:Invent 2019, I saw AWS present how to contribute to CDK for the first time. There was no AI back then — everything was manual. Clone the entire monorepo, figure out the Lerna project structure, manually build dependent packages, write L2 constructs, write tests, submit a PR. Every step was something you had to figure out on your own.

I was blown away.

A construct I write, a bug I fix — once it's merged, it ships with the next version of aws-cdk to the entire world. Developers everywhere use this thing every day, and I can directly change it. I thought that was incredibly cool.

I later wrote a post on community.aws called Contributing to AWS CDK, documenting the entire process so others wouldn't have to figure it all out from scratch like I did.

2019–2024: The Live Contribution Walkthrough Era

Over the next few years, I made a lot of live contribution walkthrough videos. I'd stream the whole thing — pick an issue, analyze it, implement the fix, write tests, submit the PR. All live.

In 2021, Werner Vogels called CDK a game changer.

That validated what many of us in the community already felt — CDK was becoming the way to build on AWS.

But honestly, the barrier was still there.

During that time I was completely passionate about writing CDK PRs. In 2020, I was at Penghu's MZG airport waiting for a flight, writing a Lambda filesystem support PR while my daughter played Animal Crossing next to me. All manual, no AI. That's just how it was — you did everything yourself.

A full CDK contribution involves quite a lot:

Understanding what the issue is about and how far the impact reaches
Finding the right module and files in a massive monorepo
Following CDK's own coding patterns (L1/L2 constructs, props interface design, etc.)
Writing unit tests and integration tests that meet the standards
Passing lint, build, and snapshot checks
Writing a PR description in the required format

Even experienced developers need hours or days. For newcomers, it's even worse.

The Pain of a First-Time Contributor

Imagine this scenario.
You're using CDK and you hit a bug, or you need a feature that doesn't exist yet. You want to help, so you open the aws-cdk GitHub repo, find the issue, and think: "I'll fix this!"
Then you open CONTRIBUTING.md.

It's incredibly long. It tells you how to set up your dev environment, install build tools, build the entire monorepo, run tests, handle snapshots, write PR descriptions…… but all you wanted was to change a few lines of code.

This is painful. You just wanted to make a small fix, but setting up the environment alone takes half a day, and it might not even build. A lot of people give up right here. My first time, I was up until midnight just getting the environment working. Honestly, I never wanted to do it manually again.

July 2025: Kiro and the Multi-Roles Pattern

After Kiro launched in July 2025, we started trying a new approach: composing a workflow pipeline from multiple agent roles. We called it the multi-roles pattern.

The idea is straightforward — analyzing an issue and writing code require different skills. Designing a solution and running tests are different too. Instead of having one agent do everything end to end (which usually doesn't work well), we split each phase out, assign it to a specialized agent role, and connect them with an orchestrator.

In practice, the results were much better than a single agent. Each role focuses on one thing, and the output quality clearly improves.

2025 re:Invent: From Multi-Roles to Power

At re:Invent that same year, Kiro released the Power feature. This let us formalize the multi-roles pattern — define explicit phases, set approval gates, control subagent execution order and parallelism.

The biggest change for me was that this was no longer just "letting AI write code." It became a structured engineering process with human approval checkpoints. AI handles the repetitive work it's good at, humans make the decisions.

We started designing CDK Contribution Power with this architecture.

My manager Joey Wang gave a talk at the Open Source Developers Lounge during 2025 re:Invent: "Automating Open Source Contributions with AI Agents — How We Use Multi-Agent Workflows to Maintain AWS CDK," showing how this multi-agent workflow works in practice.

February 2026: Agent SKILL

In February 2026, Kiro started supporting Agent SKILL.

This was a big turning point. SKILL is a standardized format that isn't tied to any specific agent tool. That means we can package the entire CDK Contribution workflow as a single skill, and it works across Kiro, Claude Code, Codex, Gemini, Copilot, OpenCode, and other compatible agent tools.

Before this, what we built with Power only ran inside Kiro. With SKILL, the same workflow works cross-platform. We'd always wanted this — not locking the workflow into a single tool.

The Design of CDK Contribution Skill

cdk-contribution-skill was officially released at the end of March 2026.

The core is a 6-phase orchestrated workflow, with clear inputs, outputs, and deliverables for each phase:

+------------------------------------------+
|           MAIN ORCHESTRATOR              |
|        (coordinates all phases)          |
+--------------------+---------------------+
                     |
     +---------------+--------------+
     |       PHASE 1: ANALYSIS      |
     |   Analyze issue, classify,   |
     |   explore affected code      |
     +---------------+--------------+
                     |
                     v
     +---------------+--------------+
     |       PHASE 2: PLANNING      |
     |   Propose solution, plan     |
     |   tests & impl approach      |
     +---------------+--------------+
                     |
                     v
     +-------------------------------+
     |      HUMAN APPROVAL GATE      |
     |   Review analysis + plan      |
     |   Continue? Yes | No          |
     +-------+---------------+-------+
       [NO]  |               |  [YES]
       back  |               |
       to    |               v
     PHASE 2 |   +---------------+--------------+
             |   |    PHASE 3: BUILD & IMPL     |
             |   |   Branch, env setup, code    |
             |   +---------------+--------------+
             |                   |
             |                   v
             |   +---------------+--------------+
             |   |   PHASE 4: PARALLEL VALID    |
             |   +-------+-------+-------+------+
             |           |       |       |
             |           v       v       v
             |       +------+ +-----+ +------+
             |       | TEST | |  QA | | DOCS |
             |       +--+---+ +--+--+ +--+---+
             |          +-------+-------+
             |                  |
             |                  v
             |   +-----------------------------+
             |   |    VALIDATION AGGREGATE     |
             |   | Any blocker? -> human gate  |
             |   +-------------+---------------+
             |                 |
             |                 v
     +---------------+--------------+
     |     PHASE 5: SELF REVIEW     |
     +----------+----------+--------+
                |          |
                v          v
        +------------+ +------------+
        |  SECURITY  | | REGRESSION |
        |   REVIEW   | |   REVIEW   |
        +------+-----+ +-----+------+
               +-------+------+
                       |
                       v
              +------------------+
              | SYNTHESIZE REPORT|
              +--------+---------+
                       |
                       v
     +-------------------------------+
     |      HUMAN APPROVAL GATE      |
     |   Go or No-Go?               |
     +-------+---------------+-------+
     [NO-GO] |               | [GO]
     fix and |               |
     re-run  |               v
     PHASE 4 |   +-------------------------------+
             |   |        PHASE 6: PR            |
             |   |   Commit, create PR           |
             |   +-------------------------------+

Here are the key design decisions.

Human Approval Gates

After Phase 2 and Phase 5, the workflow stops and waits for human approval. This is mandatory — you can't skip it.
Why? Because CDK is an infrastructure tool, and a single breaking change can affect a huge number of users. AI can help you analyze, write code, and run tests, but "should we go in this direction" and "should we submit this PR" — those decisions have to be made by a human. I didn't want a fully automated system sending PRs to aws-cdk without anyone looking at them.
It comes down to trust but verify. AI hallucinates, writes code that looks correct but has security risks, and misses edge cases that cause regressions. Human review isn't a formality — it's the last line of defense against these things.
If a proposal is rejected at an approval gate, the workflow doesn't force forward. It goes back to planning, readjusts, and enters the next round of review. This isn't a one-way pipeline — it can loop back.
Structured Deliverables and Artifact Lifecycle
Each phase writes its output to markdown files under .kiro/contributions//. These files serve two purposes:

Handoff interface between phases — the next phase's agent reads the previous phase's deliverable as input. This is the communication channel between agents.
Review evidence — humans can read these files at approval gates to understand what the agent did and why.

These intermediate artifacts stay in the local working directory after PR submission — they don't go into the PR itself. They're records of the work process, not final deliverables.

Sequential + Parallel Hybrid Execution

Phase 1 through Phase 3 are strictly sequential — you can't start writing code before you've finished analyzing the issue. But Phase 4's three tasks (testing, QA, documentation) and Phase 5's two tasks (security review, regression review) run in parallel, because there are no dependencies between them.

The coordination works like this: each subtask independently produces its own deliverable, then the orchestrator collects all results and aggregates them into a summary. If any subtask reports a blocking issue, the entire phase is marked as needing human intervention. No subtask can override another's conclusions.

ASCII Diagrams

Every deliverable must include at least one ASCII diagram. This isn't for aesthetics — in a terminal environment, ASCII diagrams are the most reliable form of visualization, rendering correctly in any agent tool.

For example, Phase 1's analysis deliverable maps out affected file relationships:

  +----------------+       +-------------------+
  |  affected.ts   | ----> | test/foo.test.ts  |
  +----------------+       +-------------------+
         |
         v
  +----------------+
  |  features.ts   |  (new feature flag)
  +----------------+

Phase 4's validation deliverable shows test coverage status:

  +---------------------+   +------------------+   +--------+
  |        TEST         |   |        QA        |   |  DOCS  |
  +---------------------+   +------------------+   +--------+
  | unit:  12/12 PASS   |   | lint:    PASS    |   | README |
  | integ: 3/3  PASS    |   | build:   PASS    |   | OK     |
  +---------------------+   +------------------+   +--------+

These diagrams aren't decoration. They're how you quickly grasp status in a terminal.

Agent Team

The essence of this skill isn't "one powerful AI" — it's an entire agent team, each with its own role:

Issue Analyst analyzes the issue, reads all comments, explores the CDK codebase to understand the current design, cross-references how other modules are implemented
Solution Architect takes over, proposes solutions, analyzes pros and cons
You review the options and pick a direction
Build Engineer gets the repo into a development-ready state
Coder writes the code
Tester runs the tests
QA Specialist checks code style and quality
Documentation Specialist fills in documentation
Two Reviewers do self-review from security and regression perspectives
All results are aggregated into a report for you
You say go or no-go

Between approval gates, the agent team automatically builds a PR from scratch. You don't need to read all of CONTRIBUTING.md, set up the environment from zero, or memorize CDK coding patterns. But you're still responsible for the final PR — you need to check whether the approach is right, the code makes sense, and the tests are sufficient.

This isn't a PR vending machine. It's a team that handles the repetitive work for you. The decision-making stays in your hands.

Intention-Driven Development

The developer experience we're going for is intention-driven.

You express your intent, the agent analyzes the problem, explores the codebase, and proposes an approach. You say LGTM, and the code gets written, tests pass, PR gets submitted.

Intent in, PR out, CI green.

That's the goal. But I'll be honest — we're not 100% there yet.

For complex issues — changes spanning multiple modules, or cases requiring deep understanding of CDK internals — the agent still goes off track sometimes and needs human correction. For simple to medium-complexity issues, this workflow already runs smoothly. Complex cases are a work in progress.

Looking further ahead, I'm excited about developers being able to kick off this process without sitting at a computer. Send an instruction from your phone during your commute, and a cloud agent runs the entire workflow automatically. By the time you get to the office, there's a report and a PR waiting for your review. Technically feasible today, but the experience still needs polish.

From Manual to Automated, From Closed to Open

Looking back at how things have changed:

| Period | Approach | Barrier |
|--------|----------|---------|
| 2019 | Fully manual, re:Invent workshop | Very high |
| 2019–2024 | Live walkthrough videos | High |
| 2025 H2 | Kiro multi-roles + Power | Medium |
| 2026 Q1 | Agent SKILL (cross-platform) | Low |

From being blown away at re:Invent 2019 by the fact that anyone can contribute to CDK, to building a cross-platform contribution skill in 2026 — it took seven years.

The barrier has definitely come down a lot. But I won't say it's gone — you still need a basic dev environment (Node.js, Yarn, gh CLI), you still need to understand what you're doing, and you're still responsible for the PR you submit.

What's changed is that the most painful parts — setting up the environment, finding files, memorizing patterns, writing boilerplate tests — the agent can handle those now. You get to spend your time where a human brain is actually needed: understanding the problem, making design decisions, reviewing the final result.

Give It a Try

If you want to try it, I'd suggest starting with a small, well-defined aws-cdk issue. Don't jump straight into a massive change spanning ten modules.

Installation is simple — type this in your coding agent:

"Install https://github.com/cdklabs/cdk-contribution-skill to my skills"

Then point it at an issue:

"contribute this aws/aws-cdk#12345"

The agent will start Phase 1 analysis. A few minutes later you'll see the first analysis report, telling you what the issue is about, how far the impact reaches, and how it recommends fixing it.

Looking Forward

Boris Cherny from Anthropic, said something that stuck with me: "There's a good chance by end of year people aren't using IDEs anymore."

The trend is clear: coding agents are moving from desktop IDEs to the cloud, into sandboxed environments with strong isolation. The future we see is one where developers walk away from their desktop IDE, speak out their intention, and a remote coding agent in the cloud turns that intention into reality.

You might be driving, waiting for an Uber, going through airport security, on a plane with terrible WiFi, playing Nintendo Switch, or even at a BBQ. The only dev tool you need is a phone and Discord — or whatever IM you already use. You no longer need to sit in front of a desktop IDE. You are building anywhere, anytime, with the coding agent on the cloud.

SKILL is just the start of that journey.

It gives us a way to standardize and package an engineering workflow so it can be reused across tools and platforms. Today it's CDK contribution. Over time, the same pattern could be applied to other open source workflows.

This road is just beginning.

And I'd love to share everything I've learned in this journey in this series of blog posts. So stay tuned! This is going to be an amazing journey!

Questions or feedback? Poke me on X @pahudnet.

cdk-contribution-skill is open source: github.com/cdklabs/cdk-contribution-skill

Opinions expressed here are my own.

This blog post was made by the intent from Pahud Hsieh and co-authored by Kiro, Claude Code, Codex, and Gemini.