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, 33 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-domain-design) and per-scope (/aidlc-feature) runner skills are installed too.

Start the session from the project root. The conductor's engine calls are pre-approved as project-relative bun .kiro/tools/<tool>.ts commands, so a session whose working directory is elsewhere pushes the conductor toward command forms that need approval. Absolute paths, KIRO_PROJECT_DIR expansion, and cd <dir> && bun .kiro/tools/... chains deliberately remain gated. A path only has to be shaped like a tool path to match a pattern, not be trustworthy: pre-approving any /.../.kiro/tools/*.ts would also pre-approve a file planted in a world-writable directory, and neither a variable's value nor a chained working directory is knowable from the pattern.

Sessions with no approver stall rather than prompt. Anything outside the pre-approved set needs an interactive answer. Under kiro-cli chat --no-interactive there is nobody to ask, so Kiro refuses the command outright with non-interactive mode (no user to approve). Over ACP, your client must answer session/request_permission; a client that ignores those requests looks exactly like a permission failure. --trust-all-tools bypasses both the allow and deny lists, including the recursive-rm and git push denials. Use it only inside a disposable sandbox where blanket shell access is acceptable.

What's different on Kiro

Area	Claude Code	Kiro CLI
Gates & questions	`AskUserQuestion` widget	Numbered prose options (reply with a number); the questions FILE with `[Answer]:` tags stays the source of truth
Statusline	Current stage + model + context %	Not available — use `/aidlc --status` and the progress line at each gate
Dispatched stages (2.1 pipeline, 2.2 subagent, 2.4 mob, 3.5 subagent)	`Task` tool	Kiro `subagent` tool → the agent configs (all 14 personas ship configs)
Construction swarm	Parallel `Task` floor, optional ultracode Workflow	Subagent fan-out only; `AIDLC_USE_SWARM=1` is announced as a no-op
Session audit events	`SESSION_STARTED/RESUMED/ENDED`, `SESSION_COMPACTED`	`SESSION_STARTED` only (Kiro has no session-end / pre-compaction hooks)
Forwarding-loop enforcement (Stop hook)	Interactive + headless	Interactive sessions only — `--no-interactive` runs do not honor the stop-hook block
Permissions	`settings.json` allowlist	`aidlc` agent config: only project-relative framework `bun .kiro/tools/<tool>.ts` calls and `date -u` are pre-approved; other shell commands prompt
Welcome message	Rendered at session start from `settings.json` `companyAnnouncements`	None — Kiro has no welcome-render equivalent; the session-start hook injects resume context only
MCP servers	Ships 5 (`.mcp.json`: `context7` + four AWS servers)	Ships the same 5 in `.kiro/settings/mcp.json`, all disabled by default; flip `"disabled": false` per server to enable it. Context7 is keyless on Kiro because Kiro sends configured HTTP header values verbatim instead of expanding environment placeholders. All 14 delegated personas opt in through `includeMcpJson: true` plus `@<server>` tool grants; the conductor gets none.

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, settings/mcp.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 33 stages.
Scopes, Depth, and Test Strategy — right-sizing a run.
Glossary — every term defined.

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