How We Use This Repo

In plain English: AWS Labs built a tool called aidlc-workflows. It teaches your AI coding assistant (Claude Code, Cursor, etc. — we'll call this your "harness" throughout, since that's the word AWS uses) a structured, step-by-step way to build software instead of just guessing. To use it, we download it once, "build" it (turn it into files each tool understands), and then copy the right files into whichever project we're working on.

Our recipe: clone it, build it with bun, install it into a project.

flowchart LR
    A["1. Clone<br/>(its own folder)"] --> B["2. Install Bun<br/>(once per machine)"]
    B --> C["3. Build<br/>bun install + package.ts"]
    C --> D["4. Install into project<br/>aidlc config --harness ..."]
    D --> E["5. Verify<br/>aidlc doctor"]
    E --> F["6. Start<br/>/aidlc Build ..."]

Before You Start — Which OS Are You On?

The commands below are written for a macOS or Linux terminal (bash/zsh) — that's the environment this tool was built for.

On Windows? The smoothest path is WSL2 (Windows Subsystem for Linux) — a free, official Microsoft feature that gives you a real Linux terminal running inside Windows. Once it's set up (wsl --install from PowerShell as Administrator, then restart), every command on this page works exactly as written, no translation needed. This is what we'd recommend.

Don't want to set up WSL2? We've added a Windows (PowerShell) version under each step below where the command actually differs. A few caveats if you go this route:

• bun itself supports Windows natively, so Steps 1–3 work fine in plain PowerShell.
• The separate one-line curl installer for the native aidlc command (mentioned at the end of Step 4) is written for a Unix shell — we don't have a confirmed Windows equivalent for it, so on native Windows, stick to the clone-and-bun route this whole page walks through.
• Anything this page calls a "hook" (a small script the harness runs automatically) was written for bash — if a hook ever behaves oddly on native Windows, that's the likely reason. WSL2 sidesteps this entirely.

1. Clone It — In Its Own Folder

Why its own folder? This isn't part of any one project — it's a shared tool. One copy on your machine can serve every project you ever install it into, the same way you install VS Code once, not once per project.

macOS / Linux:

mkdir -p ~/dev/tools && cd ~/dev/tools
git clone https://github.com/awslabs/aidlc-workflows.git
cd aidlc-workflows

Windows (PowerShell):

mkdir $HOME\dev\tools; cd $HOME\dev\tools
git clone https://github.com/awslabs/aidlc-workflows.git
cd aidlc-workflows

(git clone is identical everywhere — it's the folder-creation step that differs.)

2. Install Bun

What's Bun? A JavaScript tool this repo's build script needs to run. Think of it like a required app you install once — you won't interact with it directly afterward.

macOS / Linux:

curl -fsSL https://bun.sh/install | bash
exec $SHELL          # reload so `bun` is on PATH
bun --version

Gotcha: this only patches ~/.zshrc. Hooks run in a non-interactive shell that reads ~/.zshenv/~/.bashrc instead — copy the PATH line there too if a hook ever can't find bun.

Windows (PowerShell):

powershell -c "irm bun.sh/install.ps1 | iex"

Then close and reopen your PowerShell window (so it picks up the new PATH), and confirm it worked:

bun --version

3. Build It

Same command everywhere — bun handles the OS differences internally:

bun install --frozen-lockfile
bun scripts/package.ts

What just happened? This reads the tool's source code (core/ + harness/<name>/) and writes out a ready-to-install copy for each harness, into dist/<harness>/. Nothing here is permanent — it's regenerated fresh every time you run this, and it's never something you'd commit to your own project's git history.

4. Install Into a Project

Cursor only: this build ships a real installer script — safer than a plain copy, since it merges configs instead of overwriting them:

macOS / Linux:

bun ~/dev/tools/aidlc-workflows/dist/cursor/install.ts /path/to/your-project

Windows (PowerShell):

bun $HOME\dev\tools\aidlc-workflows\dist\cursor\install.ts C:\path\to\your-project

Every other harness (Claude, Kiro, Kiro IDE, Codex, Copilot, opencode) has no installer script in this build — it's a straight recursive copy of the generated folder into the project instead:

macOS / Linux:

cp -R ~/dev/tools/aidlc-workflows/dist/claude/. /path/to/your-project/

Windows (PowerShell):

Copy-Item -Recurse -Force "$HOME\dev\tools\aidlc-workflows\dist\claude\*" "C:\path\to\your-project\"

(swap claude for kiro, kiro-ide, codex, copilot, or opencode)

Already have the official native aidlc command too — installed separately via AWS's own one-line curl installer (macOS/Linux/WSL2 only), not something this clone-and-bun recipe covers? Simpler, and it works the same way for every harness:

cd /path/to/your-project
aidlc config --harness cursor

5. Verify, Then Start

aidlc doctor

Then open the harness itself — not this terminal:

Once it's open, type into its chat — not the terminal we've been using so far:

/aidlc Build a REST API for inventory management

Keeping It Updated

Same commands on every OS (just adjust the path from Step 1 if you used the Windows one):

cd ~/dev/tools/aidlc-workflows && git pull
bun install --frozen-lockfile && bun scripts/package.ts

Repeat Step 4 for each project, then aidlc doctor to confirm.

Rules of Thumb

• ✅ Commit what lands inside a project — .cursor/, AGENTS.md, aidlc/
• ❌ Never commit dist//dist-release/ from the clone — it's regenerated output
• ❌ Never hand-edit inside the engine folder — re-run the install instead

Continue to: What It Installs, Tool by Tool