I tried installing AI-DLC Workflows v2, which was preview released, on Kiro CLI / Claude Code / Codex CLI

Introduction

The v2 branch of AI-DLC (AI-Driven Development Life Cycle) Workflows was released in preview on 2026-06-18.

v1 was a "rule file-based" implementation published on the AWS Blog in November 2025. It worked simply by copying core-workflow.md into each harness's configuration directory, and while it supported 8 harnesses, routing and stage management depended on LLM judgment.

https://aws.amazon.com/blogs/devops/open-sourcing-adaptive-workflows-for-ai-driven-development-life-cycle-ai-dlc/

v2 is a complete overhaul to a native TypeScript implementation. The biggest change is that LLM-dependent progression has been replaced by a deterministic engine. The main differences from v1 are summarized below.

The release history of the v2 series starts with v0.1.0 in April 2026, reaching 2.0.0 in about two months. Key milestones extracted from the CHANGELOG:

The v2 architecture follows a "One core, many harnesses" design. The core/ directory holds shared stage definitions, knowledge, tools, and sensors, and dist/ for each harness is generated by a build script (scripts/package.ts). Harness-specific differences (adapter hooks, configuration file formats) are separated into harness/.

This article covers installation and operation verification for the 3 CLI harnesses (Kiro CLI / Claude Code / Codex CLI).

Test Environment

Verification

Common: Repository Setup

Fetch the v2 branch with a shallow clone.

git clone --branch v2 --depth 1 https://github.com/awslabs/aidlc-workflows.git

Cloning into 'aidlc-workflows'...
remote: Enumerating objects: 1318, done.
remote: Counting objects: 100% (1318/1318), done.
remote: Compressing objects: 100% (866/866), done.
remote: Total 1318 (delta 371), reused 1146 (delta 332), pack-reused 0 (from 0)
Receiving objects: 100% (1318/1318), 3.10 MiB | 26.67 MiB/s, done.
Resolving deltas: 100% (371/371), done.

The dist/ directory of the cloned repository contains the distribution files for each harness. Output may change with updates to the v2 branch.

Prerequisite: bun

v2 hooks and tools run on bun. bun must be available in PATH for the user running each harness. The README also states:

which bun works in your terminal, but the harness can't find bun — add ~/.bun/bin to your non-interactive shell's PATH

Installing to Kiro CLI

Kiro CLI ≥ 2.6 is required (README "Pick your harness" table).

Copy the contents of dist/kiro/ to your project directory.

cp -r ../aidlc-workflows/dist/kiro/.kiro .

Directory structure after copying:

.kiro/
├── agents/
├── aidlc-common/
├── hooks/
├── knowledge/
├── scopes/
├── sensors/
├── settings/
├── skills/
├── steering/
└── tools/

settings/cli.json configures the aidlc agent as the default on startup, and sets effort xhigh when using Claude Opus 4.8.

{
  "chat.defaultAgent": "aidlc",
  "chat.modelDefaults": {
    "claude-opus-4.8": {
      "output_config": {
        "effort": "xhigh"
      }
    }
  }
}

This setting does not lock the model; actual model selection depends on the Kiro plan and configuration. The README explains:

AI-DLC on Kiro works best with Claude Opus 4.8, which requires a paid Kiro plan. On weaker models the conductor may skip optional stage steps (reviewer pass, learnings ritual) or rush approval gates.

Installing to Claude Code

Claude Code is used via AWS Bedrock.

cp -r ../aidlc-workflows/dist/claude/.claude .

Directory structure after copying:

.claude/
├── CLAUDE.md
├── agents/
├── aidlc-common/
├── hooks/
├── knowledge/
├── rules/
├── scopes/
├── sensors/
├── settings.json
├── settings.local.json.example
├── skills/
└── tools/

settings.json includes model settings and environment variables (excerpt):

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "AWS_REGION": "us-east-1",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "global.anthropic.claude-opus-4-8"
  },
  "model": "opus[1m]",
  "effortLevel": "xhigh"
}

The distributed settings.json sets environment variables for Bedrock usage. The project configuration is set up to use Claude Opus 4.8 (1M context). For direct Anthropic API usage, refer to settings.local.json.example to adjust the env settings.

Installing to Codex CLI

Codex CLI requires a git repository, so if not yet initialized, run git init first before copying.

Copy 3 items from dist/codex/:

cp -r ../aidlc-workflows/dist/codex/.codex .
cp -r ../aidlc-workflows/dist/codex/.agents .
cp ../aidlc-workflows/dist/codex/AGENTS.md .

Structure after copying:

.codex/
├── agents/
├── aidlc-common/
├── aidlc-rules/
├── config.toml
├── hooks/
├── hooks.json
├── knowledge/
├── rules/
├── scopes/
├── sensors/
├── tools/
└── trust-seed.toml

.agents/
└── skills/

config.toml contains configuration items for the model and provider:

model = "openai.gpt-5.5"
model_provider = "amazon-bedrock"
model_context_window = 1000000
model_reasoning_effort = "high"

However, a warning is shown that model_provider and model_providers are ignored in project-level config:

⚠ Ignored unsupported project-local config keys in .codex/config.toml:
  model_provider, model_providers.
  If you want these settings to apply, manually set them in your user-level config.toml.

The Bedrock provider must be configured in the user-level ~/.codex/config.toml.

Doctor Check (3 Harness Comparison)

/aidlc --doctor was run for Kiro CLI / Claude Code, and $aidlc --doctor for Codex CLI. The following is the Kiro CLI output (after init; before init, the missing aidlc-docs/ directory is shown as failed):

AI-DLC Health Check
─────────────────────────────────────
✓  bun installed (required for CLI tools and hooks)
✓  aidlc-audit-logger.ts present
✓  aidlc-sync-statusline.ts present
✓  aidlc-validate-state.ts present
✓  aidlc-log-subagent.ts present
✓  aidlc-session-start.ts present
✓  aidlc-session-end.ts present
✓  aidlc-statusline.ts present
✓  aidlc-kiro-adapter.ts present
✓  agents/aidlc.json present (hook + permission wiring)
✓  settings/cli.json present (workspace default-agent activation)
✓  AWS_AIDLC_DEFAULT_SCOPE (unset — no project default)
✓  aidlc-docs/ directory exists
✓  Hooks last fired: (timestamps omitted)
✓  State Version: 7
✓  Orphan worktrees: 0 observed
✓  Stale branches: 0 observed (not a git repo)
✓  Orphan state files: 0 observed
✓  Orphan audit: 0 observed
✓  Practices staleness: never affirmed (informational)
✓  MERGE_DISPATCH: 0 orphan INVOKED (0 bracketed)
✓  Cycle detection: 0 cycles
✓  Orphan stage files: 32 graph entries all have files
✓  Scope validation: 9 scopes valid (29 advisories)
✓  Schema validation: 32/32 stages validated
✓  Graph references: 122 artifacts + edges resolved
✓  Keyword overlap: no conflicts
✓  Rule drift: no team/project rule overlaps org policy
✓  Paired sensor coverage: no sensor-bound rules (0 feedforward-only)
─────────────────────────────────────
29 passed, 0 failed

All 3 harnesses passed the common checks (bun, stage validation, graph integrity, etc.). Differences per harness are as follows:

※ Claude Code's adapter is not displayed as a separate item in the doctor log.

Workspace Initialization (Common to All 3 Harnesses)

Init was run on each harness. All 3 harnesses produced identical scaffold output:

Workspace scaffolded:
  aidlc-docs/knowledge/           (team knowledge — 11 agent dirs + aidlc-shared)
  aidlc-docs/initialization/      (3 stage artifact dirs)
  aidlc-docs/ideation/            (7 stage artifact dirs)
  aidlc-docs/inception/           (7 stage artifact dirs)
  aidlc-docs/construction/        (2 stage artifact dirs)
  aidlc-docs/operation/           (7 stage artifact dirs)
  aidlc-docs/verification/
State initialized: poc scope, 7 stages, Minimal depth
Project type: Greenfield
First post-init stage: intent-capture (IDEATION)

When AWS_AIDLC_DEFAULT_SCOPE is not set, the default scope is poc. After init completes, intent-capture (IDEATION) is shown as the next stage, and execution stopped at clarifying question generation and interactive mode selection.

The utility executed is common across harnesses (aidlc-utility.ts init).

Notes

bun PATH Configuration

This was the first issue encountered during verification. If bun is not installed, or if it is installed but cannot be found in the non-interactive shell's PATH, hook execution will fail. In this verification, the following error occurred in a fresh installation environment:

SessionStart:startup hook error
Failed with non-blocking status code: /bin/sh: 行 1: bun: command not found

Solutions:

• If bun is not installed: install with curl -fsSL https://bun.sh/install | bash
• If installed but PATH is not set: add ~/.bun/bin in ~/.bash_profile or ~/.zshenv
• For Claude Code, it can also be specified in settings.json under env

Summary

AI-DLC Workflows v2 was installed on 3 harnesses (Kiro CLI, Claude Code, Codex CLI), and doctor and init were verified. Installation mainly involves copying from dist/, and it works once prerequisites such as bun PATH and Codex CLI user-level settings are in place.

The "One core, many harnesses" design means the same workflow foundation is shared across different harnesses. In the distributed configuration, Kiro CLI includes effort settings for when Claude Opus 4.8 is used, and Claude Code includes the Claude Opus 4.8 model specification. Codex CLI has model = "openai.gpt-5.5" specified, but provider configuration requires user-level config. Given the expanded functionality of stages, agents, and sensors, please be mindful of costs during evaluation.

Reference Links

• AI-DLC Workflows 2.0 Specification (whitepaper)
• AI-DLC Method Definition Paper (Design philosophy document linked from AWS Blog. Defines 10 principles and 3-phase structure)