Running AI-DLC on Kiro CLI

[!NOTE] AI-DLC on Kiro CLI 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. The IDE-targeted distribution is documented separately in Running AI-DLC on Kiro IDE.

One of the framework's harnesses: dist/kiro/ runs the same AI-DLC methodology on Kiro CLI. One deterministic core — the tools, 32 stage files, protocols, knowledge, sensors, scopes, and rules — is byte-shared across every harness; only the shell (skills, agent configs, hook wiring, activation) differs.

Prerequisites

• Kiro CLI ≥ 2.6 (kiro-cli --version), logged in (kiro-cli login)
• bun on your PATH (curl -fsSL https://bun.sh/install | bash)

Install

The copies below come from a clone of the aidlc-workflows repository on the v2 branch:

git clone https://github.com/awslabs/aidlc-workflows.git
cd aidlc-workflows
git checkout v2

mkdir -p your-project/.kiro your-project/aidlc
cp -R dist/kiro/.kiro/. your-project/.kiro/
cp -R dist/kiro/aidlc/. your-project/aidlc/    # the workspace shell (spaces/default/memory) — a sibling of .kiro/, not inside it
cp dist/kiro/AGENTS.md your-project/AGENTS.md  # merge if you already have one

The aidlc/ directory is the workspace shell — it ships the pre-built aidlc/spaces/default/memory/ method tree the engine reads. It is a sibling of .kiro/, so copy it separately (or copy the whole dist/kiro/ tree at once). /aidlc --doctor fails its "workspace shell ready" check if it is missing.

Then start a session in your project:

cd your-project && kiro-cli chat

The install ships .kiro/settings/cli.json with chat.defaultAgent: "aidlc", so the AI-DLC conductor agent is active by default — /aidlc just works. This workspace setting takes precedence over a global default agent you may have configured; if you prefer your own default, remove that setting and use kiro-cli chat --agent aidlc instead.

No shipped agent pins a model: a pinned ID resolves only when that model is enabled on the user's Kiro install, so the conductor and all 14 personas inherit your session model (/model). The same cli.json also ships one CONDITIONAL per-model reasoning-effort default via chat.modelDefaults: xhigh for claude-opus-4.8, applied only when your session actually runs that model (the recommended setup) — inert otherwise. Kiro has no per-agent effort surface, so effort can only ride on the model this way. This file is read by the Kiro CLI only — the Kiro IDE ignores cli.json and applies its extension's per-model defaults instead. Override per session with /effort <level> in chat or kiro-cli chat --effort <level> (low|medium|high|xhigh|max) — a session flag and your user-level ~/.kiro/settings/cli.json both take precedence over the workspace default.

Usage

Start kiro-cli chat in the project, then invoke the conductor with /aidlc <description>. /aidlc --status reports position; /aidlc --doctor, --stage, --phase, --depth, and --test-strategy all work. Workspace navigation uses /aidlc intent [name], /aidlc space [name], and /aidlc space-create <name>. The per-stage (/aidlc-application-design) and per-scope (/aidlc-feature) runner skills are installed too.

What's different on Kiro

Everything else — state machine, audit trail, artifacts under the intent record dirs (aidlc/spaces/<space>/intents/<YYMMDD>-<label>/), the learnings ritual, sensors, scopes, depth/test-strategy — behaves identically, because it IS identical: the same tools run from .kiro/tools/.

A project's aidlc/ workspace is harness-neutral. Moving a project between harnesses (or running both side by side) is supported-but-untested; /aidlc --doctor will warn if it detects a conflicting harness setup with an active workflow.

For framework developers

dist/kiro is generated from core/ + harness/kiro/ by bun scripts/package.ts kiro (core copy with the {{HARNESS_DIR}} token substituted to .kiro and the rules/ → steering/ rename). bun scripts/package.ts --check is the drift guard and runs in CI (t145). The authored Kiro surfaces live in harness/kiro/: the orchestrator skill (skills/aidlc/), the agent JSONs (agents/), the hook adapter (hooks/aidlc-kiro-adapter.ts), settings/cli.json, and AGENTS.md — edit those (or core/), never the generated dist/kiro. See Porting to a New Harness.

A live TUI journey test exists alongside the Claude twins: tests/e2e/t-tui-kiro-intent-capture.serial.test.ts drives kiro-cli chat by keystroke against the shipped tree (numbered-prose gates answered with "1" = the recommended option, terminating on disk state). Opt in with AIDLC_KIRO_TUI_LIVE=1; it skips with a reason when tmux, kiro-cli, or a logged-in Kiro session is absent.

Next steps

Installed and activated? The methodology is the same on every harness — keep going with the neutral chapters:

• Your First Workflow — an annotated end-to-end run.
• Phases and Stages — the 5 phases and 32 stages.
• Scopes, Depth, and Test Strategy — right-sizing a run.
• Glossary — every term defined.

Other harnesses: AI-DLC on Codex CLI · the harness family index.