Running AI-DLC on Kiro IDE

One of the framework's harnesses: dist/kiro-ide/ 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 configs, 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 on your PATH (curl -fsSL https://bun.sh/install | bash)

[!TIP] 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

The copies below come from a clone of the aidlc-workflows repository on the v2 branch:

git clone https://github.com/awslabs/aidlc-workflows.git
cd aidlc-workflows
git checkout v2

mkdir -p your-project/.kiro your-project/aidlc
# 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
cp -R dist/kiro-ide/.kiro/. your-project/.kiro/
cp -R dist/kiro-ide/aidlc/. your-project/aidlc/     # the workspace shell (spaces/default/memory) — a sibling of .kiro/, not inside it
cp dist/kiro-ide/AGENTS.md your-project/AGENTS.md   # merge if you already have one

The removal loop is the v2.5.57 hook-name migration. An overlay copy cannot delete retired registrations; leaving them in place would register both the old and new names. The loop is a no-op 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 dist/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 dist/kiro-ide/ tree at once). /aidlc --doctor fails its "workspace shell ready" check if it is missing.

Open your-project/ in Kiro IDE. The install ships:

• .kiro/skills/aidlc/SKILL.md — the conductor loaded when you invoke /aidlc. The shipped .kiro/settings/cli.json and agent-v1 JSON files are CLI-only compatibility surfaces; they do not select an IDE default agent.
• .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 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 the first intent auto-births 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). Each hook runs a command that routes through the shared aidlc-kiro-adapter.ts shim, which normalizes the IDE's hook event into the shape the byte-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 reuses the synthetic identity retained by 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 without depending on them.

The payload acquisition is gated to payload-dependent targets (audit-and-sensors, log-subagent, rebuild-stage-graph) plus session-start and continue-workflow for their modern session_id. 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 block, 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: the same tools run from .kiro/tools/.

A project's aidlc/ workspace is harness-neutral. Moving a project between harnesses (or running both side by side) is supported-but-untested; /aidlc --doctor will warn if it detects a conflicting harness setup with an active workflow.

For framework developers

dist/kiro-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). bun scripts/package.ts --check is the drift guard and runs in CI. The authored Kiro IDE surfaces live in harness/kiro-ide/: the orchestrator skill (skills/aidlc/), always-included active-memory steering (steering/), CLI-compatibility agent JSONs (agents/), the hook adapter and v2 hook JSON files (hooks/), CLI-only settings/cli.json, and AGENTS.md — edit those (or core/), never the generated dist/kiro-ide.

The IDE harness differs from the CLI harness (harness/kiro/) in four ways: the /aidlc skill is its conductor rather than an agent selected through settings/cli.json; it ships v2 hook JSON files (the CLI relies on the agent-JSON hooks block, which the IDE ignores); it preloads standing rules through always-included steering rather than CLI-only agent resources; and its manifest injects a tools: frontmatter grant into delegation-target agent .md files (frontmatterAdditions), because the IDE resolves a delegated subagent's tools from the .md frontmatter rather than the agent-v1 JSON - without the grant an IDE delegate runs toolless. Note the frontmatter grant is unscoped (the IDE has no allowedCommands/allowedPaths equivalent there), wider than the CLI JSON sandbox. 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.