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.
Important
This page covers the kiro harness, which pins no Kiro engine. The
interactive aidlc config lists it as Kiro CLI (V2); when it detects Kiro
CLI 2.24.1 or later, it makes it the default over Kiro, except in Kiro IDE's
own terminal, where Kiro leads. For Kiro's v3 engine on Kiro CLI 2.24.1 or
later, use the kiro-ide harness, listed as Kiro: it pins that engine and
runs in Kiro CLI as well as Kiro IDE. In an existing kiro project,
aidlc config --harness kiro-ide switches .kiro/ to it in place and keeps
aidlc/.
One of the framework's harnesses: the Kiro runtime 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.
Harness-specific onboarding lives in .kiro/steering/aidlc-onboarding.md,
loaded through the conductor agent's resources. The root AGENTS.md block
is harness-neutral and shared with other installed harnesses; engine directories
must still differ (the kiro and kiro-ide rows cannot share one .kiro/
install).
- Kiro CLI ≥ 2.6 (
kiro-cli --version), logged in (kiro-cli login) - bun only when generating or running the source/development
dist/projection. Native installs and versioned release runtimes are self-contained.
tmp="$(mktemp -d)"
curl -fsSL \
https://github.com/awslabs/aidlc-workflows/releases/latest/download/install.sh \
-o "$tmp/install.sh"
sh "$tmp/install.sh"
rm -rf "$tmp"
cd your-project
aidlc config
aidlc doctorThe installer verifies the release metadata, executable, and all-harness runtime archive against the published SHA-256 checksums. The installed runtime does not require Bun, Node.js, or Git. Harness selection happens in aidlc config.
On Windows, download install.ps1 and run
& $installer. See Windows installation
for account scope, automatic User PATH registration, and -NoModifyPath.
For an air-gapped package, use
install.sh --from <release-directory> --offline on Unix or
& $installer -From <release-directory> -Offline on Windows.
aidlc config projects the Kiro shell before the first chat session. Then start
Kiro from the project root:
kiro-cli chatThe native projection allows aidlc engine * engine commands and the exact
read-only and turn-back-on commands (aidlc doctor, aidlc config <section> --show --json
and the others listed under the session start below). It also ships
.kiro/settings/cli.json with chat.defaultAgent: "aidlc", so /aidlc is
active without an agent flag. Run /aidlc --doctor in chat before the first
workflow.
Download and extract a specific release's aidlc-copy-runtime-X.Y.Z.tar.gz as described in
Install and Lifecycle: Copy Channel,
then set RUNTIME_ROOT to the extracted runtime/ directory.
mkdir -p your-project/.kiro your-project/aidlc
cp -R "$RUNTIME_ROOT/kiro/.kiro/." your-project/.kiro/
cp -R "$RUNTIME_ROOT/kiro/aidlc/." your-project/aidlc/ # the workspace shell (spaces/default/memory) — a sibling of .kiro/, not inside it
cd your-project && bun .kiro/tools/aidlc.ts config --from "$RUNTIME_ROOT" --harness kiroThe 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
$RUNTIME_ROOT/kiro/ tree at once).
/aidlc --doctor fails its "workspace shell ready" check if it is missing.
The versioned runtime uses the native aidlc command. Framework developers who
need the Bun-shaped source projection can clone the repository, run
bun install --frozen-lockfile and bun scripts/package.ts, then use the
ignored local dist/kiro/ output instead.
The shipped .gitignore carries the workspace's commit/ignore split: the
per-user cursors (aidlc/active-space, aidlc/spaces/*/intents/active-intent)
and machine-local runtime (aidlc/.aidlc-clone-id, runtime-graph.json, sensor
caches, spaces/*/knowledge/.sources.local.json) stay untracked, while the
shared records — method memory, state, audit shards, artifacts — travel with
git. The last line, the copy's own setup, adds those lines and AI-DLC's part of
AGENTS.md after everything already in your files, or creates the files when
the project has none, so the AI-DLC rules are in place before your first
workflow.
Then start a session in your project:
cd your-project && kiro-cli chatThe 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. A chat, and each of the 14
personas the conductor dispatches, starts on your session model: the one
saved in your Kiro settings (Kiro auto when you have saved none). /model
changes only the chat you are in, so the conductor follows it and the
personas still start on the saved model. To move them too, save the switch
with /model set-current-as-default, or choose the model with
aidlc config models --session-model <id>.
Kiro CLI runs each AI-DLC session on one model and has no per-agent effort
surface, so AI-DLC keeps the session's model and effort in your personal
Kiro settings (~/.kiro/settings/cli.json, the file Kiro's own
/model set-current-as-default writes), never in the project. Model lists
differ per Kiro account, and a project model a teammate's account lacks fails
every prompt they send. A project chat.modelDefaults would also replace your
whole personal map inside the project, so the shipped cli.json carries none.
First-run setup's step 2, "Session model", lists the models your Kiro account
offers, in Kiro's order, with each model's credit multiplier and a preview or
internal tag. Under Kiro auto (Kiro's own default, where Kiro picks the model
for each task), AI-DLC recommends choosing a model, so your effort preset
applies to it. The preset then sets one effort for the whole interactive
session (Kiro CLI 2.28.0 does not apply the saved effort to a
kiro-cli chat --no-interactive run; pass --effort there):
| Preset | Session effort |
|---|---|
minimal |
low |
balanced |
medium |
thorough |
xhigh (extra-high) |
A model without that level gets its next level down, and a model with no
effort setting keeps only the model. The recommended defaults fill the effort
only where you have not saved one for your model: an effort you already saved
stays, and setup says so in one line when it differs from the preset. Choosing
a preset yourself (in step 3 or with aidlc config models) or a session model
with aidlc config models sets the preset's effort; an agent or group setting
leaves it alone. aidlc config models offers the same
choice later ("1 session model, 2 preset"), and
aidlc config models --session-model <id> saves a model from your account's
list without prompts. A saved model your account no longer offers fails every
prompt, so setup asks for another instead of keeping it. --dry-run shows the
personal Kiro settings change too and writes nothing. When Kiro refuses a write,
AI-DLC says exactly what was saved and config models exits 5 (action needed).
aidlc doctor checks the live setting: the model is still offered, its saved
effort is one the model offers (when a preset is recorded and Kiro lists the
model's effort levels), and no project file overrides it. An effort you saved
that differs from the preset is yours: doctor names the preset's level and the
command that applies it, without a warning. Refreshing a project set
up by an earlier release removes AI-DLC's old effort map (claude-opus-4.8 at
extra-high) from .kiro/settings/cli.json and says so; run
aidlc config models to choose the session model.
Override one session with /effort <level> in chat or kiro-cli chat --effort <level> (low|medium|high|xhigh|max). The Kiro IDE does not read cli.json.
aidlc update updates the machine runtime but leaves project files unchanged.
aidlc doctor reports a project stamp that differs from the selected engine.
Between workflows, preview and apply the refresh with:
aidlc config --dry-run
aidlc configConfig preserves user-owned content and reports local framework edits as conflicts. A refresh while a workflow is open is done and says your open work carries on. Upgrade and rollback remain safe during a workflow because they do not modify the project.
Start kiro-cli chat in the project, then invoke the conductor with
/aidlc <description>. /aidlc --status reports position;
/aidlc --config [section] gathers project configuration changes in-session;
/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.
Status, doctor, help, version, and workspace-navigation commands are dispatched by the Kiro hook before the model can turn them into workflow work. Their child output is decoded as UTF-8 and terminal protocol/control bytes are removed only at that plain-text relay boundary; ordinary Unicode, paths, tabs, newlines, and literal escape-looking text remain unchanged.
Start the session from the project root. Native installs pre-approve the
installed aidlc engine ... commands and, exactly as written, the same
read-only and turn-back-on commands listed next, run as aidlc ....
Source/development copies pre-approve only
AI-DLC's own workflow commands, run project-relative: the engine commands
(bun .kiro/tools/aidlc.ts engine ...), the read-only doctor, version,
--version, --doctor (doctor with or without --verbose), status,
--status, config --help, config --show and
config <section> --show with or without --json, and
config <section> --help, turning a check back on with
config flags --clear-bypass <switch> --yes, and the AI-DLC tool scripts
(bun .kiro/tools/aidlc-<tool>.ts). Any other config change (turning a check
off included), the commands that change
the machine's AI-DLC install (use, update, rollback, uninstall,
system) with the tool scripts behind them (aidlc-doctor.ts, aidlc-init.ts,
aidlc-lifecycle.ts, aidlc-machine-config.ts), absolute paths,
KIRO_PROJECT_DIR expansion, and a line that adds a command that is not
pre-approved (a cd before it, or a pipe or && into another command) still
ask.
What still asks you. The developer agent and the aidlc agent write
project files without asking: any path inside the project whose top-level name
does not start with a dot. In a side-by-side build they also write each unit's
own records in its checkout (.aidlc/worktrees/<unit>/aidlc/spaces/) without
asking; the worker's edits to your code there still ask. Their writes into .kiro/ (apart from the aidlc agent's own
.kiro/sensors/ files), .git/, or any other
top-level dot entry, and anything outside the project, still ask. Your
project's own test and build commands (bun test, npm test, pytest, and so
on), a git push and a recursive delete still ask, so you see each one before
it runs. In a side-by-side build the workers and reviewers run the test command
you approved through AI-DLC's own swarm check, which does not ask. When a
side-by-side build's workers or reviewers ask, Kiro gathers their requests in a
"tool approval pending" box; choosing (f) Approve all pending and
auto-approve future subagent requests there lets them run whatever they ask,
without asking you again, for the rest of that chat, reviewers that start later
included. Requests from the main chat still ask as before, and Kiro writes no
setting for it.
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 runs every command
without asking, a git push and a recursive delete included. Use it only
inside a disposable sandbox where blanket shell access is acceptable.
The hooks run on Kiro CLI's v2 engine, including over ACP. This
distribution registers its hooks in .kiro/agents/aidlc.json. Kiro CLI runs
that block on its v2 engine while the aidlc agent is active. kiro-cli acp
picks the agent from chat.defaultAgent, the same way kiro-cli chat does.
Kiro CLI's v3 engine does not run the file as AI-DLC ships it, so if a session
starts on v3 (for example when a client starts kiro-cli acp --agent-engine v3)
or switches to another agent, none of these hooks run. With no hooks, no
HUMAN_TURN receipts are recorded, so every approval and confirmation is
refused. No write events are recorded either, so reviews are refused.
A prompt Kiro makes itself (for example the [SYSTEM] Sub-agent synthesis: message a newer
kiro-cli sends after a sub-agent returns) is not counted as your turn: it is recorded as
HOST_TURN and answers no question. Your own messages count whatever their words; Kiro's
chat record says which is which, and anything unknown is yours.
After the first workflow stage, /aidlc --doctor reports this as "Hooks have
never executed". Before that, doctor warns that AI-DLC's hooks have not run in
this project yet and names the same step. Restarting on the v3
engine does not fix it. With another agent picked, type /agent and pick
aidlc, then carry on in the same chat. On the 3.0 engine (Kiro prints
agent "aidlc" needs upgrading for this agent engine under its replies), quit
and start kiro-cli chat --agent-engine v2 --agent aidlc in this folder
instead (an ACP client starts kiro-cli acp --agent-engine v2). To run Kiro
CLI on its v3 engine, use the
Kiro IDE distribution instead; in an existing project,
aidlc config --harness kiro-ide switches .kiro/ to it in place and keeps
aidlc/. See
Kiro CLI hooks not running.
| 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 |
Source-generated projection: AI-DLC's own project-relative workflow commands (engine, read-only dispatcher commands, AI-DLC tool scripts); native and versioned release runtimes: aidlc engine *. 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. AI-DLC's own chat and its 14 delegated personas get every server in this file and in your ~/.kiro/settings/mcp.json as of the last time config ran, and each call asks you first; a server you add later reaches them after you run config again. On Kiro CLI's v3 engine a persona gets every server in those files without a config run, from its second step. |
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: native installs dispatch through aidlc, while source copies run
the corresponding tools 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.
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). The output is
ignored and local. bun scripts/package.ts --check builds twice in independent
temporary roots and byte-compares the results as the CI determinism guard. 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 onboarding.fills.ts — edit
those (or core/), never hand-edit 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.
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.