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 "rules file approach" implementation published on the AWS Blog in November 2025. It worked simply by copying core-workflow.md to each harness's configuration directory and supported 8 harnesses, but routing and stage management relied on LLM judgment.

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

v2 has been completely rebuilt as 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 v2 release history starts from 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 common stage definitions, knowledge, tools, and sensors, and dist/ outputs for each harness are generated by a build script (scripts/package.ts). Harness-specific differences (adapter hooks, configuration file formats) are isolated in harness/.

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

Verification Environment

Verification Details

Common: Repository Retrieval

Retrieve 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. The output may change with updates to the v2 branch.

Prerequisite: bun

v2 hooks and tools run on bun. bun must be in the 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 the 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 default launch of the aidlc agent and effort set to xhigh when using Claude Opus 4.8.

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

This setting does not fix the model; the 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 includes environment variables for Bedrock usage. The project configuration uses Claude Opus 4.8 (1M context). For direct Anthropic API usage, refer to settings.local.json.example and adjust the env accordingly.

Installing to Codex CLI

Since Codex CLI requires a git repository, run git init first if not already initialized, then copy the files.

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 includes 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 issued that model_provider and model_providers are ignored at the 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 settings need to 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, aidlc-docs/ not yet created is displayed 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 all common checks (bun, stage validation, graph integrity, etc.). Differences per harness are as follows:

※ Claude Code's adapter is not displayed as a standalone 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)

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

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

Notes

bun PATH Configuration

This was the first issue encountered during this verification. If bun is not installed, or if it is installed but cannot be found in the non-interactive shell's PATH, an error occurs during hook execution. In this verification, the following error appeared in a clean install environment:

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

Remedies:

• 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 the env of settings.json

Summary

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

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 settings require user-level config. Given the multi-featured nature of stages, agents, and sensors, 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)