Running AI-DLC on Kiro

This page covers Kiro (aidlc config --harness kiro), for Kiro IDE and Kiro CLI on its v3 engine (kiro-cli --v3). Kiro CLI (V2) (aidlc config --harness kiro-v2, started with kiro-cli --v2) has its own section at the end of the page: Kiro CLI (V2).

One of the framework's harnesses: this Kiro runtime runs the same AI-DLC methodology inside Kiro — Kiro IDE 1.x and Kiro CLI v3 run one agent harness and read the same .kiro/ tree. 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 surfaces, hook wiring, activation) differs.

Harness-specific onboarding lives in .kiro/steering/aidlc-onboarding.md, whose inclusion: always frontmatter loads it automatically. The root AGENTS.md block is harness-neutral and shared with other installed harnesses; engine directories must still differ (the Kiro CLI (V2) and Kiro distributions cannot share .kiro/; in a project with Kiro CLI (V2), aidlc config --harness kiro switches .kiro/ to this distribution in place; at a terminal it asks first, with --yes it switches, and without a terminal, or under --quiet or --json, it changes nothing and prints the command with --yes). AI-DLC 2.11.3 and earlier, and the 2.11.4 previews of 2026-11-04 and 2026-11-05, read the two Kiro names the other way: Kiro is --harness kiro-ide and Kiro CLI (V2) is --harness kiro, and they do not know kiro-v2. --harness kiro-ide names Kiro on those releases and on this one (Root Integrations and Ownership).

[!IMPORTANT] Run AI-DLC on Kiro with Claude Opus 4.8. The conductor drives a multi-step ritual per stage — clarifying questions, artifact generation, a reviewer pass, the learnings ritual, then the approval gate. Opus 4.8 follows the full ritual and pauses correctly at every gate. Weaker models skip optional steps (the reviewer pass and the learnings ritual) and may rush gates. Set the chat model to Claude Opus 4.8 before starting a workflow.

Prerequisites

• Kiro IDE 1.1.70 or later, signed in, or Kiro CLI 2.24.1 or later (kiro-cli --version), signed in. These are the oldest builds this distribution has been checked on. /aidlc --doctor warns when the kiro-cli on the PATH is older; it cannot read the Kiro IDE version.
• Claude Opus 4.8 selected as the chat model (see the note above)
• bun only when generating or running the source/development dist/ projection. Native installs and versioned release runtimes are self-contained.

[!TIP] For a source-generated dist/ install, bun must be on the PATH the IDE hands its hooks and tools. Opened from a terminal, the IDE hands them that terminal's PATH, so bun --version working there is enough. Opened from the dock or a desktop icon, it may not: if hooks can't find bun, run bun .kiro/tools/aidlc.ts doctor in such a terminal. Its Runtime hook PATH row names the directory to add and where; restart the IDE afterwards. Until then, open the IDE from that terminal.

Install

Native channel (recommended)

If you run these commands in Kiro IDE's own terminal in a project folder you have not trusted yet, Kiro first asks whether you trust it. Choose Trust Folder & Continue only for your own project or one you have checked; otherwise choose Cancel (see First run).

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 --harness kiro
aidlc doctor

The 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, allow scripts in that PowerShell window with Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force, and run & $installer. If Kiro was open while you installed, including when you ran the installer in Kiro's own terminal, quit Kiro fully and reopen it before your first /aidlc: Kiro keeps the PATH it started with, so its hooks, its agent and its other terminals cannot find aidlc until it restarts, and Developer: Reload Window is not enough. 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, after the same Set-ExecutionPolicy line.

aidlc config projects the Kiro shell before the project is opened. The native aidlc engine * trust grant, and the exact read-only and turn-back-on commands listed for a copied project below, ship inside the permissions of the conductor (.kiro/agents/aidlc-aidlc.md); every agent it hands work to is denied those commands. Some commands are held back from it: aidlc engine config set * changes a setting of your piece of work, aidlc engine adapter * is the entry the IDE's own hooks run, and an AI-DLC command holding $, a backtick, >, <, &, @(, @{, or a line break can run, expand, or redirect more than the one command. When an agent runs one of these, Kiro IDE asks you first. Earlier releases also merged it into .vscode/settings.json kiroAgent.trustedCommands; Kiro IDE 1.x no longer reads that key, so the entry can be removed. Before the first workflow, follow First run: open your-project/ in Kiro IDE, trust the folder and reload the window, choose aidlc in the chat panel's agent picker, and run /aidlc --doctor. In Kiro CLI, run kiro-cli --v3 in the project instead; it opens on the aidlc agent. The first time, Kiro CLI 2.33.0 or later asks whether you trust this workspace: if you know what is in this folder, choose Trust, continue, since Kiro CLI loads the folder's hooks and agents only then (Don't trust exits).

Versioned manual-copy alternative

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
# Safe on fresh installs; required when upgrading from v2.5.56 or earlier.
for retired_hook in \
  audit-logger block mint runtime-compile stop sync-statusline \
  enforce-approval-gate plan-approval-guard review-freeze state-transition-guard \
  terminal-command-guard rebuild-stage-graph sync-workflow-state \
  after-shell write-audit-log terminal-command
do
  rm -f \
    "your-project/.kiro/hooks/aidlc-${retired_hook}.json" \
    "your-project/.kiro/hooks/aidlc-${retired_hook}.kiro.hook"
done
rm -f \
  your-project/.kiro/agents/aidlc.json \
  your-project/.kiro/agents/aidlc-*-agent.json \
  your-project/.kiro/hooks/aidlc-*.kiro.hook
# The copy replaces .kiro/settings/cli.json; keep the project's own first.
if [ -f your-project/.kiro/settings/cli.json ]; then
  cp your-project/.kiro/settings/cli.json your-project/cli.json.before-aidlc
fi
cp -R "$RUNTIME_ROOT/kiro-ide/.kiro/." your-project/.kiro/
cp -R "$RUNTIME_ROOT/kiro-ide/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 kiro

The first removal loop is the v2.5.57 hook-name migration. The second removes Kiro CLI-format agent JSON shipped by older distributions and the IDE 0.x .kiro.hook registrations, which Kiro IDE 1.x never executes. An overlay copy cannot delete retired files. The copy also replaces .kiro/settings/cli.json, which asks Kiro CLI for its v3 engine and the aidlc agent (see the list below for which Kiro CLI releases read the engine there). That file is managed by AI-DLC like the rest of .kiro/: aidlc config stops with a conflict rather than overwrite a copy that differs from the shipped one, and --force replaces it. Keep your own Kiro CLI settings in the user-level ~/.kiro/settings/cli.json instead: Kiro CLI reads that file too, and the project file wins only for the keys it sets. If the project kept settings in .kiro/settings/cli.json, the block above saves them as cli.json.before-aidlc so you can move them there. Both removals are no-ops on a fresh install. After that cleanup, the cp -R <src>/. <dst>/ form copies the tree contents whether your-project/.kiro already exists or not. A plain cp -r "$RUNTIME_ROOT/kiro-ide/.kiro" your-project/.kiro nests a second .kiro inside an existing .kiro/ and the IDE never sees the new files.

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 $RUNTIME_ROOT/kiro-ide/ tree at once). /aidlc --doctor fails its "workspace shell ready" check if it is missing.

In a copied project, the aidlc agent runs AI-DLC's engine commands (bun .kiro/tools/aidlc.ts engine ...), its tool scripts, its read-only commands (doctor and --doctor, with or without --verbose, version, --version, status, --status, config --help, config --show and config <section> --show with or without --json, and config <section> --help) and turning a check back on (config flags --clear-bypass <switch> --yes) with no card. A native install runs the same commands, as aidlc ..., with no card too. Any other config change (bare config, the guided setup, included), the commands that change the machine's AI-DLC install (use, update, rollback, uninstall, system), and an AI-DLC command holding $, a backtick, >, <, &, @(, @{, or a line break show Kiro's card first. When the work you ask AI-DLC to start, or the change you ask it to make to the plan, holds one of them, the agent passes your words through a file it writes in aidlc/.aidlc-request-text/ instead, so those words put no card in front of you.

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-ide/ 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.

The install ships:

• .kiro/skills/aidlc/SKILL.md: AI-DLC's instructions to the aidlc agent. The agent has them, with question-rendering.md and composer.md beside them, from the first line of every chat, so it reads no file before acting on your request.
• .kiro/agents/aidlc-aidlc.md — the same conductor exposed in the workspace agent selector (named so it sorts before the aidlc-*-agent.md specialists: Kiro lists agents in file-name order, so aidlc comes first in the picker and in the / menu). It delegates through invoke_sub_agent (Kiro IDE) or orchestrate_subagent (Kiro CLI), the dispatch tools that run each persona under its own tools and deny rules.
• .kiro/agents/aidlc-*-agent.md — all 14 delegation personas, carrying tools: grants and permissions.rules. On a delegated call Kiro enforces a persona's deny rules but runs its commands under the conductor's allow, so each persona denies that allow except the AI-DLC commands a delegate may run. A delegate cannot move the workflow, change stage state, or switch or create an intent or space, however it quotes or spaces the command. Only the pipeline-deploy persona creates, merges, discards, and restores Bolt worktrees. No agent-v1 JSON ships. Their shell rules run AI-DLC's own commands and bun --version without asking; the project's own test and build commands still ask.
• .kiro/settings/cli.json — sets "chat.agentEngine": "v3" and "chat.defaultAgent": "aidlc". Kiro CLI's v2 engine runs none of the .kiro/hooks/ registrations, and a hook cannot detect that from inside, so start Kiro CLI with kiro-cli --v3. Kiro CLI 2.33.0 takes the engine only from the command line or your own Kiro CLI settings: it ignores the project file's engine value and refuses kiro-cli settings --workspace chat.agentEngine. Kiro CLI 2.24.1 to 2.32.x read the engine from this file. Kiro IDE does not read this file. kiro-cli acp reads its chat.defaultAgent but not its engine value, so an ACP client has to start kiro-cli acp --agent-engine v3 and declare clientCapabilities._meta.kiro.hooks as { enabled: true, v2: true } in its initialize request, or the session runs no hooks (see Kiro CLI hooks not running).
• .kiro/steering/aidlc-active-memory.md: always-included steering that carries the active space's memory text for the conductor and delegated agents. AI-DLC writes it from aidlc/spaces/<active-space>/memory/ for each chat and keeps it out of git; edit the memory files, never this one. A chat keeps the copy it started with, so after a memory edit the stage rules arrive with each step until a new chat starts.
• .kiro/steering/aidlc-onboarding.md — always-included harness setup and commands.
• .kiro/hooks/aidlc-*.json — the framework hooks in Kiro's v2 hook format. Both surfaces register them when a session starts; in Kiro IDE they appear in the Agent Hooks panel. Switching one off there writes "enabled": false into its file, and a file committed that way is off in Kiro CLI too, which has no such panel; /aidlc --doctor reports it, the next AI-DLC step says it once per change, and while aidlc-record-human-turn is off an approval tells you, rather than to trust the folder, to turn it back on under Agent Hooks in Kiro IDE, or in Kiro CLI to change "enabled": false to true in that file, then quit Kiro and start kiro-cli --v3 again in the folder, since the file is read when a session starts. AI-DLC never turns a hook back on for you. The IDE 0.x .kiro.hook format is no longer shipped: Kiro IDE 1.x never executes it.

First run

Kiro IDE runs a folder's hooks and loads its aidlc agent only after you trust the folder and reload the window. An untrusted folder opens in Restricted Mode: a banner at the top of the window, and "Restricted Mode" in the status bar. Until then the AI-DLC hooks do not run, the aidlc agent is missing from the agent picker, and the first approval question cannot see your reply.

Trust only a folder whose contents you know: your own project, or one you have checked. Trusting lets the folder's .kiro hooks run commands on your machine, so leave a project from someone else in Restricted Mode until you have reviewed it.

Kiro can ask for this trust earlier. If you open Kiro IDE's terminal in the folder before trusting it, for example to run aidlc config there, Kiro first asks "Do you trust the authors of the files in this folder?". For a folder you know, choose Trust Folder & Continue, which trusts it the same way step 1 does, and when aidlc config finishes, continue at step 2 to reload the window. Otherwise choose Cancel.

1. Open your-project/ in Kiro IDE. If the Restricted Mode banner shows at the top of the window and you know what is in the folder, select Manage on it, then Trust on the Workspace Trust page that opens.
2. Open the Command Palette (Ctrl+Shift+P, or Cmd+Shift+P on macOS) and run Developer: Reload Window.
3. Choose the aidlc agent in the chat panel's agent picker (see Start AI-DLC in a Kiro IDE chat).
4. In chat, run /aidlc --doctor to verify the setup, then /aidlc <description> to start a workflow.

On Kiro CLI, start kiro-cli --v3 in your-project/; if Kiro asks whether you trust this workspace and you know what is in this folder, choose Trust, continue. Then go to step 4.

When Kiro CLI 2.24.1 or later is on your PATH and setup runs outside Kiro IDE (not in its terminal), setup lists this Kiro CLI step first and the Kiro IDE steps after it; doctor's fix for "AIDLC hooks have not run in this project yet" does the same.

When kiro-cli is on your PATH, setup also offers Kiro CLI's session model, saved in your personal Kiro settings (~/.kiro/settings/cli.json). It is a Kiro CLI setting: Kiro IDE uses the model you choose in its own model picker. On this row setup saves the model only, never an effort, and recommends no model over Kiro auto: Enter keeps Kiro auto, and in Kiro IDE's own terminal the recommended setup does not ask, and under Kiro auto it says where each host chooses its model (Customize still asks in its step 2). aidlc config models --session-model <id> saves one later.

If doctor reports "AIDLC hooks have not run in this project yet" after you have sent a chat message, repeat steps 1 to 3. See Troubleshooting: Kiro IDE hooks not running.

Usage

Identical to the Claude Code harness: /aidlc <description> starts a workflow, /aidlc --status reports position, /aidlc --doctor, --stage, --phase, --depth, --test-strategy, and --config [section] all work, and the per-stage (/aidlc-domain-design) and per-scope (/aidlc-feature) runner skills are installed. There is no init command; the shipped shell scaffolds the workspace, and AI-DLC automatically creates the first intent on your first /aidlc.

Start AI-DLC in a Kiro IDE chat

Kiro IDE starts every new chat on its own Default agent, not on aidlc. The "chat.defaultAgent": "aidlc" line in .kiro/settings/cli.json is a Kiro CLI setting: it makes aidlc the default agent for kiro-cli sessions only, and Kiro IDE does not read that file. So in each new Kiro IDE chat:

1. Open the agent picker in the chat panel and choose aidlc (the first of AI-DLC's agents there; its description starts "AI-DLC. Choose this agent in the agent picker"). This agent lets AI-DLC's commands run without asking you, and lets AI-DLC bring in its specialist agents, and it already holds AI-DLC's instructions when a chat starts, so it reads no file before acting on your first line.
2. Type the whole request, then press Enter: for example /aidlc --doctor or /aidlc build a to-do app. A bare /aidlc works too: while the / menu is open, Enter completes the line to its first entry, which is /aidlc itself, and the next Enter sends it.
3. Picking aidlc from the / menu does not change which agent the chat uses. If the chat is still on Default, AI-DLC's first move on your first request is its own command, which Kiro asks you to approve, and then each command it runs asks. To avoid that, choose aidlc in the agent picker first (step 1). On Default (or Default v2), AI-DLC says this once in the chat when you type an /aidlc request, unless you already chose Always allow for AI-DLC's commands on one of Kiro's approval cards. The aidlc-...-agent entries in the / menu are the specialists AI-DLC brings in during a workflow; you do not start them yourself.

With the aidlc agent selected you can also ask in plain words, for example "start an AI-DLC workflow for a to-do app" or "continue my AI-DLC workflow". Kiro's welcome panel (Spec, Plan, Bug Fix, Quick Spec) lists Kiro's own workflows; AI-DLC does not appear there, so start it from the chat as above.

Supervised or Autopilot

The Autopilot switch at the bottom right of the chat box (also under Settings > Agent > Agent Autonomy) sets how often Kiro itself asks you to approve what the agent does. You can change it at any time, even in the middle of a workflow. It does not change which AI-DLC checkpoints stop for you.

• Supervised (switch off): after each turn that changes files, Kiro shows a Review changes card and waits until you choose Accept or Reject. AI-DLC keeps its questions, stage documents, and plans in files, so a workflow shows many of these cards on top of AI-DLC's own questions.
• Autopilot (switch on): file changes go through without the card. Select View changes in the chat to see what changed.
• In both modes, Kiro asks you to Allow any command that the aidlc agent does not already allow, such as your project's test command, a git push or a recursive delete. Your own commands meet no AI-DLC rule, so once you choose Always allow for one, Kiro remembers it, redirects and chains included. AI-DLC's own commands ask when one holds a redirect, a chain or a substitution (>, &&, $(...)), so an allowed AI-DLC command cannot be stretched into another. Kiro also asks before the two AI-DLC commands held back on purpose (see Native channel).
• In Kiro CLI (its v3 engine), when a side-by-side build's workers or reviewers ask, Kiro gathers their requests in a "tool approval pending" box; (f) Approve all pending and auto-approve future subagent requests lets them run whatever they ask without asking you, reviewers that start later included, though on Kiro CLI 3.1.0 you may see that box again later in the same chat, for example after you answer one of AI-DLC's questions; if it appears again, you can choose (f) again. Requests from the main chat still ask as before, and Kiro writes no setting for (f).
• In Kiro CLI 3.1.0 (its v3 engine), an approval card from the main chat for one of your own commands has no Always allow item: it includes Allow once and Create allow rule to approve future similar actions. The rule Kiro offers first is exact match · session for that command: choosing it lets the same command run again without a card, and a command with different arguments, such as another test file, is not covered by that rule.

In both modes, AI-DLC still stops and waits for your typed reply at each of its questions, at every approval gate, and at Code Generation's Approve Plan when plan approval is on (the default in every shipped scope except express and poc, and yours to switch; see Plan approval). Kiro's switch cannot skip these. AI-DLC's hooks run in either mode: one refuses code changes until the plan is approved or, with plan approval off, until AI-DLC has recorded that it builds the plan without asking. AI-DLC also accepts an answer or an approval only after you have typed a reply to the question. The AI-DLC setting that skips routine approvals is its own Construction choice Continue automatically (see Your First Workflow), not Kiro's Autopilot.

Use Supervised when you want to read every file change as it happens, for example on your first workflow or in code where every change matters. Use Autopilot when you want far fewer clicks: you still answer every AI-DLC checkpoint in chat, and can look over the changes afterwards.

When the chat fills up

Kiro shows you how full the chat is, but gives AI-DLC no figure while it works. Kiro IDE and Kiro CLI's v3 engine summarize the chat on their own when it reaches 80%, and from then on the agent works from that summary. AI-DLC reads Kiro's own record of the chat (~/.kiro/sessions/, read only), and at the first approval question or Unit checkpoint after Kiro summarized the chat it says so in one line, with an offer to pause and carry on in a new chat. If you turned Kiro's auto-compaction off, the same offer comes once the chat is 80% full. When the chat already reached half full or more in its first turn on the work, and still runs on the model that filled it, a new chat on that model would start about as full, so the line says that instead of offering one. Your answer decides: nothing pauses on its own, and the line is said once in a chat.

The line cannot appear in the middle of a stage (it comes only with a question you are asked anyway), for a chat with no record on this machine, or if a Kiro update changes how Kiro records the chat. On Kiro IDE with two AI-DLC chats open in one window, it can describe the chat that started last. You can always do the same by hand:

1. Stop at a stage boundary: approve and say you want to stop for now in the same reply, or type /aidlc park. /aidlc --status now shows Paused at <stage> (you stopped it); pick it back up with /aidlc --resume.
2. Start a new chat: on Kiro IDE, open a new chat and choose aidlc in the agent picker (a new chat starts on Kiro's Default agent; see Start AI-DLC in a Kiro IDE chat); in Kiro CLI, type /chat new.
3. Type /aidlc --resume. /aidlc --status no longer says Paused.

Anything the old chat discussed but did not write to a file does not carry over, which is why the end of a stage is the best moment (see Changing Model Mid-Workflow).

How hooks work on Kiro

Kiro IDE and Kiro CLI v3 register hooks through v2 hook JSON files ({"version":"v1","hooks":[{name,trigger,matcher,action}]}, PascalCase triggers) under .kiro/hooks/ (a different mechanism from the Kiro CLI (V2) distribution, which carries a hooks block inside the agent JSON). Native hook commands route through aidlc engine adapter kiro-ide; source/development copies route through the projected aidlc-kiro-adapter.ts shim. Both normalize the IDE event into the shape the shared core hooks expect. Which Kiro tools are writes, shells, delegations, and reads is set in one table, aidlc-kiro-tool-names.ts beside the adapter. The adapter reads it; the hook registrations are hand-written JSON whose matchers list the same shell, delegation, and audited write names.

Kiro IDE 1.x and Kiro CLI v3 deliver hook context as JSON on stdin (snake_case: { session_id, tool_name, tool_input, tool_response }; the older 0.12 builds instead set the USER_PROMPT environment variable with a camelCase equivalent, and the adapter accepts both). Earlier builds left PostToolUse write/shell tool inputs empty, so the adapter recovers the written path from the result text when the input carries none, and audit-tail hooks (rebuild-stage-graph, sync-workflow-state) run from the audit trail. The graph-rebuild route also retains the shell result and session identity so a successful intent-create binds to the invoking session: modern events carry the exact session_id, while the legacy channel derives a stable host-instance identity from the measured VSCODE_IPC_HOOK/VSCODE_PID environment and retains it at SessionStart. Modern Stop likewise prefers its event-local session_id, preventing one concurrent chat from consuming another chat's handoff after an intent is created or selected; legacy agentStop falls back to the retained identity. Later 1.x builds populate some PreToolUse and delegation inputs; the adapter preserves those fields. On Windows, deterministic utilities use those seams to avoid the IDE shell-result transport: builds that expose the submitted prompt run the utility at UserPromptSubmit, while builds such as 1.0.242 (whose prompt field is empty) fall back to the exact execute_pwsh PreToolUse command. The utility runs once per turn, its UTF-8 text is relayed without terminal protocol/control bytes, and the duplicate shell call is refused. Modern chats store turn and output state per session_id; context without a session identity uses one legacy compatibility bucket. Pre-1.0 camelCase payloads take the same fallback through toolArgs.command; raw prompt text is only a newer-generation compatibility shape.

The payload acquisition is gated to payload-dependent targets (audit-and-sensors, log-subagent, plan-approval-guard, rebuild-stage-graph, review-freeze, state-transition-guard, and the guard-tool-call, person-message and after-shell cards that run them), the terminal-command seams, plus session-start and continue-workflow for their modern session_id, and record-human-turn for the exact approval response. A non-empty USER_PROMPT is consumed immediately on 0.12 builds (which open stdin without ever writing); otherwise the adapter reads the 1.x stdin channel until Kiro closes it, so a message handed over late on a busy machine is still recorded whole, with a 60 s safety limit for a channel that never closes. When nothing arrives at all, your turn is not recorded (nothing says you typed nothing) and the agent is told to say that the last message in this chat did not reach AI-DLC's record, so if it answered one of its questions, you will be asked that question again. Every other target touches neither channel and keeps its zero-latency path.

aidlc-session-end has no registration: Kiro's Stop trigger fires at the end of every assistant turn, not at conversation close, on both surfaces, so registering it would append a spurious SESSION_ENDED between prompts in the same session. No SESSION_ENDED is recorded until Kiro exposes a genuine session-end event.

Kiro shows a "Run Command Hook" card each time one of these registrations runs: one before a file change, a command or a hand-off to another agent, none after it, none for a read or for a helper handing its answer back, one for each message you send, one at the end of each turn (which also finishes the turn's last write or command) and one when a helper finishes. A project whose hook files are older still has an after-write card, an after-command card and a second card for each message until config refreshes it, which removes aidlc-write-audit-log.json, aidlc-after-shell.json and aidlc-terminal-command.json.

Debugging hooks

If a hook isn't behaving as expected, turn on debug logging and each hook appends its decision path (which gate it took, the resolved paths, why it exited) to <record>/.aidlc-engine/hooks-health/hook-debug.log. It is off by default — no log is written and there is no overhead on a normal run. Two ways to enable it, either works:

• Filesystem marker (easiest on Kiro IDE): touch aidlc/.aidlc-hook-debug (in PowerShell, New-Item -ItemType File aidlc/.aidlc-hook-debug) in your project. It takes effect on the very next hook fire — no IDE restart — and rm aidlc/.aidlc-hook-debug turns it back off.
• Environment variable: export AIDLC_HOOK_DEBUG=1. Hooks see the environment the IDE started with, so quit the IDE, then open it from a terminal where the variable is exported. On Windows, set it as a user variable in PowerShell instead, [Environment]::SetEnvironmentVariable("AIDLC_HOOK_DEBUG", "1", "User"), then quit and reopen the IDE (run it again with $null in place of "1" to turn it off).

What's different on Kiro

Everything else — state machine, audit trail, artifacts under the per-intent record dir (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.

A Unit's reviewer reads only that Unit

During a Unit's review, the reviewer is meant to read only that Unit's files and the shared contracts it is given. On Claude Code and the other harnesses a hook holds it to that; on Kiro no hook can tell the reviewer's reads apart, so Kiro holds the reviewer to it instead. For each Unit review, AI-DLC writes a copy of the reviewer, .kiro/agents/aidlc-scoped-review-<id>.md, whose permissions deny reads in every other Unit's construction/ folder (a Unit of the same name in another piece of work included), and dispatches that copy. Kiro refuses such a read and leaves those files out of search results; a shell read such as cat is not covered and asks you first. The copy opens no other Unit's file, not even one the Unit's design names as an integration point: the reviewer notes that point as a finding instead. The copy shows in Kiro's agent list and / menu while the review runs; AI-DLC dispatches it, so there is no need to pick it. It is deleted when its verdict is recorded. A copy whose review is over without a verdict (you approved the Unit or the stage without it, outside an isolated --single run) goes later: while that piece of work is the folder's current one, AI-DLC deletes it when a chat in it starts or a review in it is asked for or recorded, once it can read the work's record. A copy of a review you sent back can stay until you approve that Unit or its stage. A copy a closed chat left, with nothing done since, stays: AI-DLC cannot tell it from a review still running in another chat, and you can delete it. AI-DLC's .gitignore block keeps a copy out of commits. When AI-DLC cannot write a copy it should write, or Kiro has no agent by the copy's name (an older Kiro build may not load it), AI-DLC dispatches the reviewer itself, as without the copy, and says in one line that this review runs without the check. Doctor then counts a hook drop: for a copy AI-DLC could not write, under reviewer-scope, naming the cause; for one Kiro did not load, under kiro-adapter, and that file (<record>/.aidlc-engine/hooks-health/kiro-adapter.drops) names the copy. Measured on Kiro CLI 2.31.0 and Kiro IDE 1.3.0, and in a whole workflow on Kiro CLI 2.31.1. There is no copy for Units built in parallel, or while the reviewer read-scope check is off: under Guard Policy off, the default of every plan but enterprise, with guard.reviewer-scope off, or with AIDLC_DISABLE_REVIEWER_SCOPE_HOOK=1; the reviewer is then held to its Unit by its instructions only. To have the copy on such a plan, ask in chat to turn the reviewer read-scope check on for the work (or type /aidlc config set guard.reviewer-scope on). A copy keeps the permissions it was written with, so turning the check off applies from the next Unit review.

One agent on its own model and effort

On Kiro every AI-DLC agent runs on your chat's model and effort (the model you pick in Kiro IDE, or Kiro CLI's session model) unless a model or effort is set for that agent. Kiro can run a delegated agent on its own model and effort, for example a reviewer on another model family:

aidlc config models --agent architecture-reviewer --model gpt-5.6-terra --effort high --project --yes

AI-DLC records the model and effort in aidlc.settings.json and writes model: (as a quoted string) and effortLevel: into that agent's .kiro/agents/aidlc-architecture-reviewer-agent.md; a Unit's reviewer copy keeps them. Kiro reads them when it next dispatches the agent, in a chat that is already open too. The model must be one your Kiro offers (kiro-cli chat --list-models, or Kiro IDE's model picker): one it does not offer can fail that agent's dispatch. An effort the model does not take runs at the model's own default, and an agent given a model but no effort runs at that model's default effort, not your chat's. --model default and --effort default take them out again. A preset or a group effort (--preset, --reviewing-effort) still changes nothing on Kiro, setup records no preset there, and the conductor keeps your chat's model.

AI-DLC owns the model and effort lines (model:, effortLevel:, and the effort:, variant: and tier: keys other tools use) of the agent files it ships, as it does on Claude Code: aidlc config writes those of the agents that have a setting, so change them through aidlc config models rather than by hand; aidlc config models --check reports a model: or effortLevel: line that does not match the setting, one you added by hand included. An agent file you added yourself is not touched.

An agent's effort is shared by every tool, while its model is recorded per tool, so an effort recorded for one agent for another tool applies on Kiro too. An aidlc config run that writes a model or effort value into a Kiro agent file that differs from what the file had, other than a value that run changes itself, says so in one line and names aidlc config models --show --harness kiro, which shows where each value is set; --effort default (or --model default) for that agent, with --project, --local or --global (machine settings) for the file it is in, and --harness kiro when the project has another harness, takes it out (an effort taken out this way is gone for every tool). effortLevel is not in Kiro's documentation. Measured on Kiro CLI 2.31.1 on its v3 engine and Kiro IDE 1.3.0.

Kiro's Workflows feature stops AI-DLC's reviews and helpers

Kiro IDE's Workflows feature (Settings > Kiro Agent > Workflows: Enabled, or the Enable Workflows command) runs work as background workflows. While it is on, a chat loses the sub-agent tool AI-DLC uses for its reviews and helpers: on the aidlc agent they never run and the main chat does their work itself; on the Default agent they run in the background, the chat's turn ends before they finish, every command they run asks in an Approval needed in agent-aidlc-... panel, and Kiro can hand an /aidlc request to its own workflow instead of AI-DLC. Workflows is off unless you turned it on.

The switch is a Kiro setting for all your projects: Kiro reads it only from your user settings, so a workspace .vscode/settings.json value does nothing. When it is on and you have not answered before on this computer, AI-DLC asks you once whether to turn it off: during aidlc config, or in your first Kiro IDE chat. aidlc config --yes takes the recommended answer and turns it off. Say yes and AI-DLC changes only that one setting; then run Developer: Reload Window from the Command Palette (Ctrl+Shift+P) so open chats pick it up. Say no and it stays on, and AI-DLC does not ask again.

To change it later, ask the agent to turn Kiro Workflows off or back on, or run:

aidlc config trust --kiro-workflows off --yes   # or: on

Kiro's own Disable Workflows and Enable Workflows commands do the same. /aidlc --doctor shows a warning while Workflows is on, and while Kiro's settings file has an error AI-DLC cannot read past (Kiro may still read Workflows as on from it; the next chat tells you once, and the fix is the error in that file).

Kiro CLI has a Workflows switch of its own (/settings > Features > Workflows, chat.enableWorkflows in your Kiro CLI settings, ~/.kiro/settings/cli.json). While it is on, Kiro CLI takes both sub-agent tools away from the aidlc agent, so AI-DLC's reviews and helpers do not run in your Kiro CLI chats; its "Workflows: sub-agent tool" setting does not bring them back (measured on Kiro CLI 2.31.1 and 2.32.0). Kiro CLI's chat reads the switch only from your own Kiro CLI settings, so a project's .kiro/settings/cli.json value does not turn it off. AI-DLC asks about it the same way, with an answer of its own: during aidlc config, or once in your first Kiro CLI chat; aidlc config --yes takes the recommended answer and turns it off. AI-DLC changes it through Kiro CLI's own kiro-cli settings command; quit Kiro CLI and start kiro-cli --v3 again afterwards. To change it later, ask the agent, or run:

aidlc config trust --kiro-cli-workflows off --yes   # or: on

/aidlc --doctor shows a warning while it is on.

Command Prompt as Kiro's terminal on Windows

Kiro IDE runs its agent's commands in your default terminal profile. When that is Command Prompt, Kiro hands AI-DLC a command's reply only when the command finishes within a second (Command Prompt has no shell integration, so Kiro reads the result one second after sending the command and shows exit code -1 for every run). Most AI-DLC steps take longer. So in Command Prompt every AI-DLC command prints one line first, AI-DLC reply: aidlc/.aidlc-sessions/replies/<id>.txt, and writes its reply to that file as well as to the terminal; when Kiro cuts the result off at that line or later in the reply, the agent goes on from the file instead of running the command again (the newest twenty replies are kept, in a folder git ignores). When a long command has not finished, the agent says so, and that it may be waiting for your answer in Kiro's terminal panel; when its reply still has not come on the next turn, the agent says so and checks what the command was meant to change. A value the agent wrote in single quotes, the PowerShell way, arrives from Command Prompt as several words with the quotes still on them; AI-DLC joins them back into the one value. Steps still take extra turns, so Kiro itself recommends PowerShell.

When Kiro's terminal is Command Prompt and you have not answered before on this computer, AI-DLC asks you once whether to set it to PowerShell: during aidlc config, or in your first Kiro IDE chat. aidlc config --yes takes the recommended answer and sets it. Say yes and AI-DLC changes only that one Kiro setting (terminal.integrated.defaultProfile.windows, for all your projects); then restart Kiro so its chats use it. Say no and it stays as it is, and AI-DLC does not ask again.

To set it later, ask the agent, or run:

aidlc config trust --kiro-terminal powershell --yes

Kiro's own Terminal: Select Default Profile command does the same. /aidlc --doctor shows a warning while Kiro's terminal is Command Prompt.

While your terminal is Command Prompt, every Kiro IDE chat is told how that terminal behaves and how to set PowerShell when you ask for it, so any chat can carry out "set Kiro's terminal to PowerShell". If you kept Command Prompt, the first time a step's reply is lost the agent tells you once what happened and that PowerShell avoids it; it does not ask again.

PowerShell without Kiro's shell integration on Windows

Kiro's PowerShell terminal tells Kiro when a command finishes through Kiro's shell integration, a script Kiro loads as the terminal starts. When that script does not load, the terminal behaves like Command Prompt: every command shows exit code -1, even when it worked, and Kiro hands over only what a command printed within about a second. PowerShell's execution policy is one cause: Restricted or AllSigned stops Kiro's unsigned script without a message. Kiro's setting terminal.integrated.shellIntegration.enabled turned off has the same effect.

AI-DLC notices this from its own commands. In such a terminal, in a project that has its aidlc/ folder, every AI-DLC command the agent runs prints the AI-DLC reply: line first and keeps its reply in that file, as in Command Prompt (output sent to a pipe gets no such line), and when the result stops at that line or the reply after it is cut off, the agent goes on from that file instead of running the command again. The first time in a chat the agent tells you in one line that the terminal runs without its shell integration, then goes on with your request. aidlc doctor run in Kiro's terminal shows a Kiro terminal warning with what to change; /aidlc --doctor typed in the chat runs outside the terminal, so it cannot see this.

To check, run this in Kiro's PowerShell terminal (Windows PowerShell and PowerShell 7 keep separate policies):

Get-ExecutionPolicy -List
$ExecutionContext.SessionState.LanguageMode

When MachinePolicy or UserPolicy is set, or the language mode is not FullLanguage (an organization's application control), your organization manages it; ask your IT team. When Process is set, Kiro took it from where it was started: start Kiro from the Start menu instead. When the policy in effect comes from CurrentUser or LocalMachine and is Restricted or AllSigned, you can let Kiro's script load for your own account, then restart Kiro:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

AI-DLC never changes the policy itself: it is your computer's security setting.

Command cards end with "dministrator: ...powershell.exe" on Windows

On Windows, a Kiro IDE command card can end with a line such as dministrator: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe, once or twice. That is the terminal window's title, cut short by Kiro when it shows the output. It does not change what the command did or what AI-DLC records.

If you added "terminal.integrated.windowsUseConptyDll": false to Kiro's settings, remove it and restart Kiro: it makes Kiro wrap command output, which can stop Code Generation.

Kiro memories carry old AI-DLC advice

Kiro IDE keeps memories outside your project, in .kiro/memories/memories.db under your home folder (%USERPROFILE%\.kiro\memories\memories.db on Windows), and can load them into every workspace you open. A memory an agent saved during an earlier AI-DLC run can hold a diagnosis or workaround that only fit that project and version, and is wrong or unsafe anywhere else: running a hook command such as record-human-turn by hand, setting AIDLC_SKIP_HUMAN_PRESENCE_GUARD=1, turning summary confirmation off, or calling Kiro IDE a "sessionless" harness. AI-DLC tells the agent never to save such advice and never to act on it, but memories saved before that still load.

If the agent says "per my memory" and suggests one of these, or tells you to resume "from Kiro IDE" while you are already in it:

1. Tell it to ignore that memory and follow what /aidlc says now. Guards and checkpoints are yours to switch: the agent names the command, you type it.
2. Delete only the memories that give that kind of advice: running an AI-DLC hook command by hand, setting a variable that skips a guard, turning a checkpoint off, calling Kiro IDE "sessionless", or telling you to resume from Kiro IDE while you are already in it. Keep the rest, including accurate Kiro IDE notes (for example that it has no status line), other AI-DLC notes, and debug tips such as AIDLC_HOOK_DEBUG (check Kiro's documentation for managing memories).
3. Keep a copy of memories.db before you delete anything, and close Kiro IDE first if you edit the file directly: it holds all of Kiro's memories, not only the AI-DLC ones.

For framework developers

dist/kiro-ide is generated from core/ + harness/kiro-ide/ by bun scripts/package.ts kiro-ide (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 IDE surfaces live in harness/kiro-ide/: the orchestrator skill (skills/aidlc/), always-included active-memory steering (steering/), the conductor Markdown (agents/aidlc-aidlc.md), the hook adapter and v2 hook JSON files (hooks/), the personas' delegate shell deny (delegate-shell-deny.ts), and onboarding fills — edit those (or core/), never hand-edit the generated dist/kiro-ide.

This harness differs from the Kiro CLI (V2) harness (harness/kiro/) in four ways: the /aidlc skill and the Markdown agents/aidlc-aidlc.md are its conductor surfaces (settings/cli.json also makes that agent Kiro CLI's default); it ships v2 hook JSON files (the Kiro CLI (V2) harness relies on the agent-JSON hooks block); it preloads standing rules through always-included steering rather than CLI agent resources; the shared Kiro projection removes the core persona's Claude-only disallowedTools key; and its manifest adds permissions.rules frontmatter to every persona, beside the tools: line both harnesses add (each persona a stage reads inline also ships without them, as .kiro/aidlc-common/personas/<agent>.md, the file the lead reads in its own chat). It does not ship the Kiro CLI (V2) harness's agent-v1 JSON. See Porting to a New Harness.

Kiro CLI (V2)

[!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 Kiro distribution is documented in the first part of this page.

[!IMPORTANT] This section covers the Kiro CLI (V2) harness (aidlc config --harness kiro-v2), which pins no Kiro engine; start it with kiro-cli --v2 (Kiro CLI 2.21.4 or later; for an older one, see Kiro CLI (V2) prerequisites). 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 harness (--harness kiro), listed as Kiro: it runs in Kiro CLI (started with kiro-cli --v3) as well as Kiro IDE. In an existing Kiro CLI (V2) project, aidlc config --harness kiro switches .kiro/ to it in place and keeps aidlc/ (at a terminal it asks first; with --yes it switches; without a terminal, or under --quiet or --json, it changes nothing and prints the command with --yes); a plain aidlc config refresh, or --harness kiro-v2, keeps Kiro CLI (V2). AI-DLC 2.11.3 and earlier, and the 2.11.4 previews of 2026-11-04 and 2026-11-05, read the two Kiro names the other way: Kiro CLI (V2) is --harness kiro there and Kiro is --harness kiro-ide, and they do not know kiro-v2; --harness kiro-ide names Kiro on those releases and on this one.

One of the framework's harnesses: the Kiro CLI (V2) 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 CLI (V2) and Kiro rows cannot share one .kiro/ install).

Kiro CLI (V2) prerequisites

• Kiro CLI ≥ 2.6 (kiro-cli --version), logged in (kiro-cli login). The commands in this section start Kiro CLI on its V2 engine with --v2, which needs Kiro CLI 2.21.4 or later. On an older one, see what kiro-cli chat --help lists:
• with --agent-engine (2.19.2 has it), put chat --agent-engine v2 in place of --v2: kiro-cli --v2 --agent aidlc becomes kiro-cli chat --agent-engine v2 --agent aidlc, and kiro-cli chat --v2 … becomes kiro-cli chat --agent-engine v2 …;
• without it, start with kiro-cli chat and no engine flag (for example kiro-cli chat --agent aidlc).
• bun only when generating or running the source/development dist/ projection. Native installs and versioned release runtimes are self-contained.

Kiro CLI (V2) install

Kiro CLI (V2) native channel (recommended)

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 doctor

The 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, allow scripts in that PowerShell window with Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force, 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, after the same Set-ExecutionPolicy line.

aidlc config projects the Kiro shell before the first chat session. Then start Kiro from the project root:

kiro-cli --v2

The 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.

Kiro CLI (V2) versioned manual-copy alternative

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 kiro-v2

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 $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 --v2

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 --v2 --agent aidlc instead.

Kiro CLI cancels a helper (a reviewer, a persona, a Unit builder) that shows no progress for api.subagentTimeout seconds; its default is 3600, and AI-DLC does not set it. If a helper that never starts holds a stage for an hour, you can lower it in your own Kiro CLI settings (~/.kiro/settings/cli.json; 900 is 15 minutes). Output counts as progress, silence does not: a helper whose command prints nothing for longer than that is cancelled too, and the command keeps running on its own, so keep the deadline above your longest quiet command (a deploy, a test run that prints only at the end).

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 (V2) session model and effort

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 --v2 --no-interactive run; pass --effort there):

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 --v2 --effort <level> (low|medium|high|xhigh|max; for older Kiro CLI, see Kiro CLI (V2) prerequisites). The Kiro IDE does not read cli.json.

Kiro CLI (V2) refresh and version skew

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 config

Config 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.

Kiro CLI (V2) usage

Start kiro-cli --v2 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 a worker writes in a Unit's checkout (.aidlc/worktrees/<unit>/) the same way: its code and records there go through without asking, and the checkout's own .git, .gitignore and other dot entries ask. On Kiro CLI's v2 engine the checkout's dot folders (its .kiro/, .github/) go through too, and stay in that checkout until the Unit lands. 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, reviewers that start later included, though on Kiro CLI 3.1.0 you may see that box again later in the same chat, for example after you answer one of AI-DLC's questions; if it appears again, you can choose (f) again. Requests from the main chat still ask as before, and Kiro writes no setting for (f).

Sessions with no approver stall rather than prompt. Anything outside the pre-approved set needs an interactive answer. Under kiro-cli chat --v2 --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.

Which Kiro CLI engine runs the hooks. 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, including over ACP: kiro-cli acp picks the agent from chat.defaultAgent, the same way kiro-cli --v2 does. Kiro CLI's v3 engine does not run the file as AI-DLC ships it. It runs the file once Kiro has upgraded it for v3, and the v2 engine still runs an upgraded file.

From Kiro CLI 2.37, Kiro makes that upgrade by itself when it starts on v3 (kiro-cli --v3, or a plain kiro-cli once you have chosen V3), unless chat.enableAutoAgentUpgrade is false in your own Kiro CLI settings. It rewrites every agent JSON file in .kiro/agents/ (the .md prompts beside them stay as they are) and keeps each original beside it as <name>.json.bak (.json.bak.1 and on when one is already there), so git status shows each agent JSON file there changed and a new backup beside it, files AI-DLC did not write. On Kiro CLI 3.1.0 the files had changed while Kiro was still asking whether to trust the folder, and they stayed changed when the answer was not to trust it; Kiro said nothing about it on screen. After that, the hooks run on v3 too. aidlc doctor --verbose counts those agent JSON files as upgraded by Kiro, not as your changes, and a refresh keeps them as Kiro left them except where Refresh Safety says otherwise. To undo the upgrade, first run kiro-cli settings chat.enableAutoAgentUpgrade false, or Kiro upgrades the files again at its next start on v3, then rename each agent JSON file's newest backup (the highest .json.bak.N, or .json.bak when there is no other) back to .json, and start Kiro CLI with kiro-cli --v2: v3 runs none of the hooks of files it has not upgraded.

Kiro does not upgrade the files while that setting is false, and kiro-cli acp --agent-engine v3 upgraded nothing on Kiro CLI 3.1.0. A session on v3 with the files not upgraded runs none of these hooks, and neither does a session that switches to another agent. 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. With another agent picked, type /agent and pick aidlc, then carry on in the same chat. When aidlc is not in that list, Kiro is on v3 with the files not upgraded (Kiro says agent "aidlc" needs upgrading for this agent engine on its start screen), and restarting on v3 alone does not fix it. AI-DLC's line then names these ways; take one:

• Type /upgrade-agent, choose the workspace agents, then quit Kiro and start kiro-cli --v3 again in this folder. The chat you typed it in stays on Kiro's default agent.
• Switch to the Kiro distribution, made for Kiro CLI's v3 engine: aidlc config --harness kiro switches .kiro/ to it in place and keeps aidlc/ (at a terminal it asks first; with --yes it switches; without a terminal, or under --quiet or --json, it changes nothing and prints the command with --yes); then start kiro-cli --v3 (when it asks to trust the folder and you know what is in it, choose Trust, continue).
• Quit and start kiro-cli --v2 --agent aidlc in this folder.

An ACP client starts kiro-cli acp --agent-engine v2, or, after the switch to Kiro, what Kiro's install names in its .kiro/settings/cli.json item. See Kiro CLI hooks not running.

When a Kiro CLI (V2) chat fills up

Kiro shows you how full the chat is, but gives AI-DLC no figure while it works. So AI-DLC reads the figure Kiro saves for the chat at the end of each turn (~/.kiro/sessions/cli/<chat id>.json, read only). Once it is 80% or more, the next approval question or Unit checkpoint carries one line saying how full the chat is, with an offer to pause and carry on in a new chat. When the chat already reached half full or more in its first turn on the work, and still runs on the model that filled it, a new chat on that model would start about as full, so the line says that instead of offering one. Your answer decides: nothing pauses on its own, and the line is said once in a chat.

The line cannot appear in the middle of a stage (it comes only with a question you are asked anyway), before Kiro has saved the chat's first turn, for a chat with no record on this machine, or if a Kiro update changes how Kiro saves the figure. When you see Kiro's own figure climb, you can do the same by hand:

1. Stop at a stage boundary: approve and say you want to stop for now in the same reply, or type /aidlc park. /aidlc --status now shows Paused at <stage> (you stopped it); pick it back up with /aidlc --resume.
2. Type /chat new for a new chat. Kiro keeps the old one, and /chat resume brings it back. Use it rather than /clear, which resets the chat you are in.
3. Type /aidlc --resume. /aidlc --status no longer says Paused.

Anything the old chat discussed but did not write to a file does not carry over, which is why the end of a stage is the best moment (see Changing Model Mid-Workflow).

What's different on Kiro CLI (V2)

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.

Kiro CLI (V2) 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). 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. The build appends ; exit $LASTEXITCODE to every hook command of those agent JSONs (the manifest's hookCommandSuffix): Kiro CLI starts a hook in PowerShell on Windows and in bash elsewhere, and that shape hands a hook's exit 2 back to Kiro in both, so a refusal stops the tool call on Windows too.

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.