Running AI-DLC on Kiro IDE and Kiro CLI

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 and kiro-ide distributions cannot share .kiro/).

[!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, signed in, or Kiro CLI (kiro-cli), signed in
• 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 that non-interactive shells see — that's what the IDE uses to run a hook or tool. Those shells read ~/.zshenv (zsh) or ~/.bashrc (bash), not ~/.zshrc, but the bun installer writes to ~/.zshrc. If which bun works in your terminal yet hooks can't find bun, copy the BUN_INSTALL/PATH export into ~/.zshenv (or ~/.bashrc).

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-ide
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 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 project is opened. The native aidlc engine * trust grant ships inside the conductor's permissions (.kiro/agents/aidlc.md). Two command families are held back from it: aidlc engine config set * changes a setting of your piece of work, and aidlc engine adapter * is the entry the IDE's own hooks run. When the agent runs either one, 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 in the project instead; it opens on the aidlc agent.

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
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
cp "$RUNTIME_ROOT/kiro-ide/AGENTS.md" your-project/AGENTS.md   # merge if you already have one
# Existing .gitignore: preserve it and merge only the section beginning "# AI-DLC".
if [ ! -e your-project/.gitignore ]; then
  cp dist/kiro-ide/.gitignore your-project/.gitignore
fi

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 pins Kiro CLI to its v3 engine and the aidlc agent. 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.

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 guarded command copies the complete starter file only when the project has no .gitignore. If one exists, preserve every project-owned rule and merge only the section from # AI-DLC through the end of the shipped file; do not copy its generic starter rules. The ## Git Integration section of the installed AGENTS.md assumes the AI-DLC rules are in place before your first workflow.

The install ships:

• .kiro/skills/aidlc/SKILL.md — the conductor loaded when you invoke /aidlc.
• .kiro/agents/aidlc.md — the same conductor exposed in the workspace agent selector. It delegates through invoke_sub_agent (Kiro IDE) or orchestrate_subagent (Kiro CLI), the dispatch tools that run each persona under its own permissions.
• .kiro/agents/aidlc-*-agent.md — all 14 delegation personas, carrying tools: grants and permissions.rules. No agent-v1 JSON ships.
• .kiro/settings/cli.json — pins Kiro CLI to its v3 engine and the aidlc agent. Kiro CLI's default v2 engine runs none of the .kiro/hooks/ registrations, and a hook cannot detect that from inside. Kiro IDE does not read this file.
• .kiro/steering/aidlc-active-memory.md — always-included IDE steering whose live file references preload the active-space memory files for both the conductor and delegated agents.
• .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. 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 in your-project/, then go to step 4.

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 (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. When AI-DLC starts, Kiro asks you to allow Load skill: aidlc. Choose Always allow and keep Apply to: This workspace, and Kiro stops asking in new chats for this project. Allow covers only the current chat.
2. Type the whole request, then press Enter: for example /aidlc --doctor or /aidlc build a to-do app. Do not press Enter straight after typing /aidlc. The / menu is still open at that point, and Enter picks its first entry, which is a specialist such as aidlc-architect-agent rather than AI-DLC itself. Typing the space after /aidlc closes the menu; Esc does not.
3. Picking aidlc from the / menu does not change which agent the chat uses. If the chat is still on Default, Kiro asks you to approve loading AI-DLC and then each command it runs. To avoid that, choose aidlc in the agent picker first (step 1). 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. It also asks before the two AI-DLC commands held back on purpose (see Native channel).

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 the agent's tool calls while an approval gate waits for you, and another 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.

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

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 post-create handoff; 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), 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 with a 2s broken-channel ceiling. Every other target - including the approval floor, which fires on every PreToolUse - 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.

You will see a "Run Command Hook" line in chat each time one fires.

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. Because the IDE runs hooks in non-interactive shells, set it where those shells read it — add the export to ~/.zshenv (zsh) or ~/.bashrc (bash), then restart the IDE. 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.

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.md), the hook adapter and v2 hook JSON files (hooks/), and onboarding fills — edit those (or core/), never hand-edit the generated dist/kiro-ide.

This harness differs from the kiro CLI harness (harness/kiro/) in four ways: the /aidlc skill and the Markdown agents/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 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 tools: and permissions.rules frontmatter to every persona. It does not ship the kiro harness's agent-v1 JSON. See Porting to a New Harness.

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.