Running AI-DLC on Kiro IDE

One of the framework's harnesses: the Kiro IDE runtime runs the same AI-DLC methodology inside Kiro IDE. 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.

[!IMPORTANT] Run AI-DLC on Kiro IDE 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
• 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)

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 and run & $installer. An interactive run may omit the flag; redirected input, pwsh -NonInteractive, --yes, --json, and --quiet require it. 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 IDE shell before the project is opened. It merges the native aidlc engine * trust entry into .vscode/settings.json without replacing user-owned settings. Open your-project/ in Kiro IDE and run /aidlc --doctor in chat before the first workflow.

Versioned manual-copy alternative

Download and extract a specific release's aidlc-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/settings/cli.json
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 and settings files shipped by older IDE distributions. An overlay copy cannot delete retired files. 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.

Open your-project/ in Kiro IDE. 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 IDE workspace agent selector.
• .kiro/agents/aidlc-*-agent.md — all 14 delegation personas, carrying IDE-native tools: grants and permissions.rules. No agent-v1 JSON or settings/cli.json ships in the IDE distribution.
• .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/hooks/aidlc-*.json — the framework hooks registered in the IDE's native v2 hook format. They appear in the IDE's Agent Hooks panel. (Kiro IDE 1.x no longer executes the legacy .kiro.hook format the harness shipped before; on those builds legacy hooks are silently inert.)

In the chat panel, run /aidlc --doctor to verify the setup, then /aidlc <description> to start a workflow.

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.

How hooks work on Kiro IDE

Kiro IDE registers hooks through v2 hook JSON files ({"version":"v1","hooks":[{name,trigger,matcher,action}]}, PascalCase triggers) under .kiro/hooks/ (a different mechanism from Kiro CLI, which reads 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 delivers 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). Captured PostToolUse write/shell events leave tool inputs empty on both channels, so their written path must be recovered from the result text 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 v2 registration: the IDE's Stop trigger fires at the end of every assistant turn, not at conversation close, so registering it would append a spurious SESSION_ENDED between prompts in the same session. It stays legacy-only (agentStop, pre-1.0 builds) until the IDE exposes a genuine session-end event — on IDE 1.x no SESSION_ENDED is recorded.

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

What's different on Kiro IDE

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.

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.

The IDE harness differs from the CLI harness (harness/kiro/) in four ways: the /aidlc skill and agents/aidlc.md are its conductor surfaces rather than an agent selected through settings/cli.json; it ships v2 hook JSON files (the CLI 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 the IDE manifest adds native tools: and permissions.rules frontmatter. Kiro IDE does not read or ship the CLI's agent-v1 JSON or settings/cli.json surfaces. 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.