Install AI-DLC v2.7.0 on Kiro IDE (macOS and Windows)

This sets up AI-DLC on one group PC so the workshop can start. It takes about 15 minutes. Do the macOS or the Windows section, then “Finish in Kiro IDE”.

Use exactly version v2.7.0 (commit 96b11d3, 1 Sep 2026). The workshop slides match this version, so do not install main or a newer one.

Optional: a permissions file so Kiro stops asking before everyday commands. Download it for macOS or Windows, save it as ~/.kiro/settings/permissions.yaml (macOS) or %USERPROFILE%\.kiro\settings\permissions.yaml (Windows), then restart Kiro. Deleting files, admin commands and git push still ask first.

What you end up with

Your project folder gets four things from dist/kiro-ide/:

Item	What it is
`.kiro/`	The engine: the `/aidlc` command, the main `aidlc` agent plus 14 role agents, 11 hooks (scripts Kiro runs automatically), tools, checks and scopes
`aidlc/`	Where AI-DLC keeps your team’s rules and the record of every decision. It sits next to `.kiro/`, not inside it
`AGENTS.md`	Onboarding notes the IDE loads
`.gitignore`	Which AI-DLC files are shared in git and which stay local

There is no init command. The first /aidlc creates the first piece of work under aidlc/spaces/default/intents/.

Before you start (both OS)

Need	Check
Kiro IDE, signed in	Open Kiro IDE, you see your account
Paid Kiro plan with Claude Opus 4.8	The repo says weaker models may skip reviewer passes or rush gates
git	`git --version`
Permissions file in place (optional)	See the download links at the top
An empty project folder, made a git repo	Steps below

macOS

Step 1 - Install bun

DO: In Terminal:

bun --version || curl -fsSL https://bun.sh/install | bash

SEE: a version number, or the installer finishing with “bun was installed successfully”.

Step 2 - Make bun visible to Kiro’s hooks

The IDE runs hooks in non-interactive shells, which read ~/.zshenv, not ~/.zshrc. The bun installer writes to ~/.zshrc.

DO:

grep -n BUN_INSTALL ~/.zshrc ~/.zshenv

SEE: two lines from ~/.zshrc: export BUN_INSTALL="$HOME/.bun" and export PATH="$BUN_INSTALL/bin:$PATH". If no lines come from ~/.zshenv (or it says the file does not exist, which is normal on a new Mac), add them:

echo 'export BUN_INSTALL="$HOME/.bun"' >> ~/.zshenv
echo 'export PATH="$BUN_INSTALL/bin:$PATH"' >> ~/.zshenv

Step 3 - Get v2.7.0

DO:

git clone --depth 1 --branch v2.7.0 https://github.com/awslabs/aidlc-workflows.git /tmp/aidlc-workflows-v2.7.0
git -C /tmp/aidlc-workflows-v2.7.0 log -1 --format=%h

SEE: 96b11d3. A warning that the tag “is not a commit” is normal for an annotated tag.

IF IT BREAKS: no internet on the PC - ask the facilitator for the v2.7.0 copy on USB and use that path instead of /tmp/aidlc-workflows-v2.7.0.

Step 4 - Create the project folder

DO (change my-project to the workshop project name):

git config --global user.name  >/dev/null || git config --global user.name  "Workshop Group 1"
git config --global user.email >/dev/null || git config --global user.email "group1@workshop.local"
mkdir -p ~/my-project && cd ~/my-project
git init && git commit --allow-empty -m "init"

The first two lines set a git name and email only if the PC has none; without them git commit fails on a fresh machine. Use your group’s name.

Step 5 - Copy the Kiro IDE harness in

DO: from inside ~/my-project:

S=/tmp/aidlc-workflows-v2.7.0/dist/kiro-ide
mkdir -p .kiro aidlc
cp -R "$S/.kiro/." .kiro/
cp -R "$S/aidlc/." aidlc/
[ -e AGENTS.md ] || cp "$S/AGENTS.md" AGENTS.md
[ -e .gitignore ] || cp "$S/.gitignore" .gitignore

Use the /. form exactly. cp -r .../.kiro .kiro puts a second .kiro inside the first and the IDE never sees it.

If the project already had AGENTS.md or .gitignore: merge the AI-DLC content into AGENTS.md, and append only the .gitignore section starting at # AI-DLC.

Step 6 - Check the layout

DO:

ls .kiro/skills/aidlc/SKILL.md .kiro/agents/aidlc.md aidlc/spaces/default/memory/org.md
ls .kiro/agents/aidlc-*-agent.md | wc -l
ls .kiro/hooks/aidlc-*.json | wc -l
ls .kiro/.kiro 2>/dev/null && echo "NESTED - redo step 5"

SEE: the three files listed, 14 agents, 11 hooks, and no “NESTED” line.

Step 7 - Commit

DO:

git add -A && git commit -m "Install AI-DLC v2.7.0 (kiro-ide)"

Committing now means the health check in step 9 will not warn about uncommitted files.

Then go to “Finish in Kiro IDE” below.

Windows 10/11

Use PowerShell (prompt shows PS C:\). The repo says everything runs on native Windows and WSL is not needed. Git for Windows is recommended.

Step 1 - Install git and bun

DO:

git --version
bun --version

If git is missing: install Git for Windows from https://git-scm.com/downloads/win, then reopen PowerShell.

If bun is missing:

irm bun.sh/install.ps1 | iex

(From CMD instead: powershell -c "irm bun.sh/install.ps1 | iex".)

SEE: the installer finishes and says bun was added to your PATH.

Step 2 - Make bun visible to Kiro

The installer adds bun to the user PATH, but running programs do not see it yet.

DO: close every PowerShell window and quit Kiro IDE fully (check the system tray). Open a new PowerShell and run bun --version.

SEE: a version number. If it still fails, sign out of Windows and back in.

Step 3 - Get v2.7.0

DO:

git clone --depth 1 --branch v2.7.0 https://github.com/awslabs/aidlc-workflows.git "$env:TEMP\aidlc-workflows-v2.7.0"
git -C "$env:TEMP\aidlc-workflows-v2.7.0" log -1 --format=%h

SEE: 96b11d3.

IF IT BREAKS: no internet - ask the facilitator for the v2.7.0 copy on USB and use that path.

Step 4 - Create the project folder

DO (change my-project):

if (-not (git config --global user.name))  { git config --global user.name  "Workshop Group 1" }
if (-not (git config --global user.email)) { git config --global user.email "group1@workshop.local" }
New-Item -ItemType Directory -Force "$env:USERPROFILE\my-project" | Out-Null
Set-Location "$env:USERPROFILE\my-project"
git init; git commit --allow-empty -m "init"

The first two lines set a git name and email only if the PC has none; without them git commit fails on a fresh machine. Use your group’s name.

Step 5 - Copy the Kiro IDE harness in

DO: from inside the project folder:

$S = "$env:TEMP\aidlc-workflows-v2.7.0\dist\kiro-ide"
New-Item -ItemType Directory -Force .kiro, aidlc | Out-Null
Copy-Item "$S\.kiro\*" .kiro\ -Recurse -Force
Copy-Item "$S\aidlc\*" aidlc\ -Recurse -Force
if (-not (Test-Path AGENTS.md))  { Copy-Item "$S\AGENTS.md" . }
if (-not (Test-Path .gitignore)) { Copy-Item "$S\.gitignore" . }

The \* copies the folder contents, so nothing nests. Same merge rule as macOS if AGENTS.md or .gitignore already existed.

Step 6 - Check the layout

DO:

Test-Path .kiro\skills\aidlc\SKILL.md, .kiro\agents\aidlc.md, aidlc\spaces\default\memory\org.md
(Get-ChildItem .kiro\agents\aidlc-*-agent.md).Count
(Get-ChildItem .kiro\hooks\aidlc-*.json).Count
Test-Path .kiro\.kiro

SEE: True True True, 14, 11, then False (no nested folder).

Step 7 - Commit

DO:

git add -A; git commit -m "Install AI-DLC v2.7.0 (kiro-ide)"

Finish in Kiro IDE (both OS)

Step 8 - Open and set the model

DO: Quit Kiro IDE fully and reopen it, so it reads the new hooks and PATH. Open the project folder. In the chat panel, set the model to Claude Opus 4.8.

SEE: the Agent Hooks panel lists the aidlc-* hooks. The agent selector offers aidlc.

Step 9 - Health check

DO: in a new chat, type:

/aidlc --doctor

SEE: every line ticked and 0 failed. It checks bun, the hooks, the aidlc/ folder, the 33 stages, the 11 scopes and their references.

Step 10 - Start the lab

DO:

/aidlc --scope workshop <the project idea in one sentence>

SEE: setup (Phase 0) runs by itself, Ideation is skipped, and on an empty project 2.1 (reading existing code) is skipped too, leaving 25 stages. The first questions come from 2.2 Practices Discovery: branching, walking skeleton, testing, deploy, language/stack.

Fixing failures

Doctor or symptom	Fix (from the v2.7.0 docs)
bun not installed / hooks say bun not found	macOS: step 2 (`~/.zshenv`). Windows: step 2 (restart IDE, sign out/in)
Hook not present	Redo step 5 for `.kiro/`
Workspace shell missing	Redo step 5 for `aidlc/`
`/aidlc` not offered	`.kiro` nested or missing `SKILL.md`; step 6
Hooks never fire	Turn on hook debug: create an empty file `aidlc/.aidlc-hook-debug`, retry, read `.aidlc-hooks-health/hook-debug.log` inside the work folder under `aidlc/spaces/default/intents/`. Delete the file to turn it off
Health check warns about uncommitted changes under `aidlc/`	Commit (step 7)
`git commit` says “Please tell me who you are”	Set the git name and email (step 4)
Need help from the facilitator	`/aidlc --doctor --export` and send the `.tar.gz` (redacted, no work product)

Upgrading later

Not for the workshop. If you ever move off v2.7.0, follow that version’s docs/guide/harnesses/kiro-ide.md, which lists retired hook and agent files to delete before copying.

Kiro CLI instead of Kiro IDE

Same steps, but copy from dist/kiro/ instead of dist/kiro-ide/ (it also ships .kiro/settings/cli.json), need Kiro CLI 2.6 or later (kiro-cli --version, kiro-cli login), and start with cd my-project && kiro-cli chat.

Sources

This guide follows the install method in the v2.7.0 repo. The only change: the repo clones main, this guide clones --branch v2.7.0. - README.md - Install bun, Get the code, Install a harness > Kiro IDE - docs/guide/harnesses/kiro-ide.md - Prerequisites, Install, Debugging hooks - docs/guide/01-getting-started.md - Verify the Setup, Fixing failures - docs/guide/15-troubleshooting.md - Hooks Not Firing