AI-DLC – one core, many harnesses

AWS Labs has released AI-DLC Workflows 2.0 as generally available on the main branch, turning AI agents into verifiable, self-correcting engineering workflows from a harness-neutral core that renders natively across Claude Code, Kiro IDE, Kiro CLI, Codex CLI, Cursor, opencode, and GitHub Copilot. The implementation runs a 14-agent roster through a 33-stage workflow with approval gates, and AWS warns that generative AI can make mistakes, advising users to review all output and costs.

AI-DLC Workflows 2.0 is GA on this repository's default main branch. Use main for new installations and upgrades. It turns AI agents into verifiable, self-correcting engineering workflows from one harness-neutral core rendered natively across Claude Code, Kiro IDE, Kiro CLI, Codex CLI, Cursor, opencode, and GitHub Copilot. Note Interfaces, stage definitions, the agent roster, and the install model are stable, but we will continue to optimize based on feedback; pin a known-good version for anything you depend on, and review all generated output before you act on it. See the roadmap https://awslabs.github.io/aidlc-workflows/roadmap.html for what's shipped, in flight, and planned. A native implementation of the AI-DLC methodology AI-Driven Development Life Cycle that runs on many harnesses from one source of truth — today Claude Code, Kiro IDE, Kiro CLI, Codex CLI, Cursor, opencode, and GitHub Copilot, and any capable harness you port it to. Run a full software-development lifecycle with a 14-agent roster — 11 domain experts, 2 review-only agents, and the adaptive-workflows composer — working through a 33-stage workflow, with you approving every gate. The methodology lives once, in a harness-neutral core/ ; each harness adds a thin surface that decides how it shows up on that harness. So you edit the methodology in one place, and every harness distribution is generated from it — no harness gets special treatment. See Repository layout repository-layout for how the pieces fit together. Note This implementation realizes the autonomous software development vision, the core principles, and the architecture specified in the AI-DLC Workflows 2.0 Specification https://github.com/awslabs/aidlc-workflows/blob/main/assets/AI-DLC-Workflows-2.0-Specification.pdf whitepaper, rendered natively across multiple CLI harnesses from one source. Important Generative AI can make mistakes. You should consider reviewing all output and costs generated by your chosen AI model and agentic coding assistant. See AWS Responsible AI Policy https://aws.amazon.com/ai/responsible-ai/policy/ . To learn more about AI-DLC, read this blog post https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/ and the Method Definition Paper https://prod.d13rzhkk8cj2z0.amplifyapp.com/ it references. Ad-hoc AI coding works until the project gets real. Then context drifts between prompts, the reasoning behind a decision goes unrecorded, and the model quietly does something you never asked for. AI-DLC puts structure around the work: each stage has a clear owner, every decision passes an approval gate before the next one starts, and this implementation records what it learns from your corrections so it stops repeating them. The same engine runs a throwaway proof-of-concept and a regulated enterprise rollout — it just runs more of the stages, in more depth. — Initialization, Ideation, Inception, Construction, Operation 5 phases, 33 stages /awslabs/aidlc-workflows/blob/main/docs/guide/04-phases-and-stages.md — 11 domain experts, 2 quality-gate reviewers, and the adaptive-workflows composer 14-agent roster /awslabs/aidlc-workflows/blob/main/docs/guide/06-agents.md enterprise through express, with the v1-style classic default — 11 adaptive scopes /awslabs/aidlc-workflows/blob/main/docs/guide/05-scopes-and-depth.md AWS AIDLC DEFAULT SCOPE overrides it — the full-lifecycle feature scope, and workshop retained for facilitated sessions plus an adaptive composer /awslabs/aidlc-workflows/blob/main/docs/guide/05-scopes-and-depth.md the-adaptive-composer /aidlc compose that proposes a tailored stage plan from your task, a scan report, or the running workflow Minimal/Standard/Comprehensive — control artifact detail per stage 3 depth levels /awslabs/aidlc-workflows/blob/main/docs/guide/05-scopes-and-depth.md the-3-depth-levels Minimal/Standard/Comprehensive — independent of depth for flexible test coverage 3 test strategy levels /awslabs/aidlc-workflows/blob/main/docs/guide/05-scopes-and-depth.md the-3-test-strategy-levels — jump to any stage or phase, check status, change scope/depth/test strategy mid-workflow CLI utilities /awslabs/aidlc-workflows/blob/main/docs/guide/12-cli-commands.md — you stay in control of all decisions Approval gates at every stage /awslabs/aidlc-workflows/blob/main/docs/guide/07-interaction-modes.md — methodology knowledge ships with the framework; team knowledge is user-managed Two-tier knowledge system /awslabs/aidlc-workflows/blob/main/docs/guide/08-knowledge.md — human corrections become persistent behavioral rules Rules and a learning loop /awslabs/aidlc-workflows/blob/main/docs/guide/09-rules-and-the-learning-loop.md - structured logging for enterprise traceability 91-event audit trail /awslabs/aidlc-workflows/blob/main/docs/guide/10-state-and-audit.md — continue from checkpoint, redo, jump to stage, or start fresh Session resume /awslabs/aidlc-workflows/blob/main/docs/guide/11-session-management.md AI-DLC is a methodology — a structured, gated approach to AI-driven software development, defined by AWS see the blog post https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/ and method paper https://prod.d13rzhkk8cj2z0.amplifyapp.com/ under References references . This repository is its native, multi-harness implementation — the methodology rendered as skills, agents, hooks, and tools from one harness-neutral core/ , so it runs natively inside Claude Code, Kiro IDE, Kiro CLI, Codex CLI, Cursor, opencode, GitHub Copilot, or any capable harness you port it to. The methodology is the what ; each harness distribution is the how for one runtime, and every distribution is generated from the same source. | Harness | Install copy into your project | Invoke | Install & usage guide | |---|---|---|---| Kiro IDE | dist/kiro-ide/.kiro/ + dist/kiro-ide/aidlc/ → <project / + dist/kiro-ide/AGENTS.md ; copy or merge the AI-DLC .gitignore section | /aidlc | | Kiro CLI ≥ 2.6 dist/kiro/.kiro/ + dist/kiro/aidlc/ → <project / + dist/kiro/AGENTS.md ; copy or merge the AI-DLC .gitignore section /aidlc Quick Start quick-start below + Running AI-DLC on Kiro CLI /awslabs/aidlc-workflows/blob/main/docs/guide/harnesses/kiro-cli.md . Claude Code dist/claude/.claude/ + dist/claude/aidlc/ → <project / copy or merge the AI-DLC .gitignore section /aidlc Quick Start quick-start below + Getting Started /awslabs/aidlc-workflows/blob/main/docs/guide/01-getting-started.md . Codex CLI ≥ 0.145.0 dist/codex/ → <project / .codex/ + .agents/ + aidlc/ + AGENTS.md $aidlc or /skills → aidlc Quick Start quick-start below + AI-DLC on Codex CLI /awslabs/aidlc-workflows/blob/main/docs/guide/harnesses/codex-cli.md . Cursor bun dist/cursor/install.ts <project /aidlc Quick Start quick-start below + AI-DLC on Cursor /awslabs/aidlc-workflows/blob/main/docs/guide/harnesses/cursor.md . opencode ≥ 1.17 dist/opencode/ → <project / .aidlc/ + .opencode/ + aidlc/ + opencode.json + AGENTS.md /aidlc Quick Start quick-start below + AI-DLC on opencode /awslabs/aidlc-workflows/blob/main/docs/guide/harnesses/opencode.md . GitHub Copilot CLI ≥ 1.0.74 / VS Code ≥ 1.130 dist/copilot/ → <project / .aidlc/ + aidlc/ + AGENTS.md ; MERGE .github/ /aidlc Quick Start quick-start below + AI-DLC on GitHub Copilot /awslabs/aidlc-workflows/blob/main/docs/guide/harnesses/copilot.md .The deterministic engine — state machine, audit log, and the referee that coordinates parallel agents — is byte-identical across every harness; only the shell differs. Each section in the Quick Start quick-start installs one harness end to end, and its guide above goes deeper on prerequisites and differences. Note AI-DLC on Kiro IDE or CLI works best with Claude Opus 4.8 , which requires a paid Kiro plan . On weaker models the conductor may skip optional stage steps reviewer pass, learnings ritual or rush approval gates. This release works better with Claude Opus 4.8 . We are sharpening it for previous model versions. Every harness runs the same TypeScript hooks and CLI tools through bun , so install bun first — it's the one requirement they all share. macOS / Linux curl -fsSL https://bun.sh/install | bash Windows PowerShell irm bun.sh/install.ps1 | iex :: Windows Command Prompt CMD — bun ships only a PowerShell installer, so invoke it from CMD powershell -c "irm bun.sh/install.ps1 | iex" On Windows, use either PowerShell or CMD, not both — your prompt shows PS C:\ in PowerShell and C:\ no PS in CMD. Everything runs on native Windows; WSL is not required. Git for Windows https://git-scm.com/downloads/win is recommended so harnesses that use a Bash tool can find one. Tip bun has to be on the PATH that non-interactive shells see, since that's what a harness uses to run a hook or tool. Those shells read ~/.zshenv zsh or ~/.bashrc bash , not ~/.zshrc — but the bun installer writes to ~/.zshrc . So if which bun works in your terminal yet the harness can't find bun, copy the BUN INSTALL / PATH export into ~/.zshenv or ~/.bashrc for bash and Git Bash . Model-provider setup is harness-specific. The shipped Claude Code configuration uses AWS Bedrock ; GitHub Copilot uses GitHub sign-in or BYOK; Kiro, Cursor, Codex, and opencode use the provider and credentials configured in their own runtime. Each harness section below has the specifics. Every install below copies from this repository's dist/<harness / trees. Clone the GA main branch: git clone --branch main https://github.com/awslabs/aidlc-workflows.git cd aidlc-workflows Run the cp commands in the sections below from this repository's root. With bun in place, pick your harness below and expand it — each section installs that CLI, sets up your project, and walks the first run end to end. Kiro IDE 1. Install Kiro IDE and sign in. 2. Set up your project mkdir -p your-project/.kiro your-project/aidlc cp -R dist/kiro-ide/.kiro/. your-project/.kiro/ cp -R dist/kiro-ide/aidlc/. your-project/aidlc/ the workspace shell — a sibling of .kiro/, not inside it cp dist/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 aidlc/ shell ships the pre-built aidlc/spaces/default/memory/ method tree the engine reads; /aidlc --doctor fails its "workspace shell ready" check without it. The .gitignore carries the workspace's commit/ignore split: the per-user cursors aidlc/active-space , aidlc/spaces/ /intents/active-intent and machine-local runtime 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 onboarding file assumes the AI-DLC rules are in place. Open your-project/ in Kiro IDE. The /aidlc command loads the shipped conductor skill, and .kiro/agents/aidlc.md exposes the conductor in the IDE agent selector. Agents are Markdown-only in this distribution; Kiro CLI's agent-v1 JSON files and settings/cli.json do not ship. The install registers the framework hooks in both formats: .kiro/hooks/aidlc- .json v2 schema for IDE = 1.0 and .kiro/hooks/aidlc- .kiro.hook legacy format for pre-1.0 IDEs . In the chat panel, run /aidlc --doctor to verify, then /aidlc <description to start. NOTE AI-DLC on Kiro works best with Claude Opus 4.8, which requires apaid Kiro plan. On weaker models the conductor may skip optional stage steps reviewer pass, learnings ritual or rush approval gates. Kiro CLI 1. Install Kiro CLI ≥ 2.6 and log in: kiro-cli --version confirm ≥ 2.6 kiro-cli login 2. Set up your project mkdir -p your-project/.kiro your-project/aidlc cp -R dist/kiro/.kiro/. your-project/.kiro/ cp -R dist/kiro/aidlc/. your-project/aidlc/ the workspace shell — a sibling of .kiro/, not inside it cp dist/kiro/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/.gitignore your-project/.gitignore fi cd your-project && kiro-cli chat The aidlc/ shell ships the pre-built aidlc/spaces/default/memory/ method tree the engine reads; /aidlc --doctor fails its "workspace shell ready" check without it. The .gitignore carries the workspace's commit/ignore split: the per-user cursors aidlc/active-space , aidlc/spaces/ /intents/active-intent and machine-local runtime 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 onboarding file assumes the AI-DLC rules are in place. The install ships .kiro/settings/cli.json with chat.defaultAgent set to aidlc , so /aidlc is active by default. Inside the session, run /aidlc --doctor to verify, then /aidlc <description to start. The Kiro CLI guide /awslabs/aidlc-workflows/blob/main/docs/guide/harnesses/kiro-cli.md has the full prerequisites and harness differences. NOTE AI-DLC on Kiro works best with Claude Opus 4.8, which requires apaid Kiro plan. On weaker models the conductor may skip optional stage steps reviewer pass, learnings ritual or rush approval gates. Claude Code 1. Install Claude Code macOS / Linux native install — recommended; auto-updates curl -fsSL https://claude.ai/install.sh | bash Windows PowerShell irm https://claude.ai/install.ps1 | iex :: Windows Command Prompt CMD curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd If && reports The token '&&' is not a valid statement separator , you're in PowerShell — use the PowerShell block above. Prefer Homebrew on macOS? brew install --cask claude-code . Verify with claude --version . 2. Set up your project Copy the implementation engine + the workspace shell sibling , then launch cp -r dist/claude/.claude/ your-project/.claude/ cp -r dist/claude/aidlc/ your-project/aidlc/ the workspace shell — a sibling of .claude/, not inside it Existing .gitignore: preserve it and merge only the section beginning " AI-DLC". if -e your-project/.gitignore ; then cp dist/claude/.gitignore your-project/.gitignore fi cd your-project && claude The aidlc/ shell ships the pre-built aidlc/spaces/default/memory/ method tree the engine reads; /aidlc --doctor fails its "workspace shell ready" check without it. The .gitignore carries the workspace's commit/ignore split: the per-user cursors aidlc/active-space , aidlc/spaces/ /intents/active-intent and machine-local runtime 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 onboarding file assumes the AI-DLC rules are in place. Then, inside the Claude Code session: /aidlc --doctor verify the setup /aidlc Build a task management API with user authentication start a workflow The shipped .claude/settings.json runs on AWS Bedrock AWS REGION=us-east-1 , Fable/Opus/Sonnet/Haiku pinned . Before your first run, enable Anthropic model access in your AWS account and have AWS credentials on your SDK credential chain — see Getting Started § AWS Bedrock Setup /awslabs/aidlc-workflows/blob/main/docs/guide/01-getting-started.md aws-bedrock-setup for the model-access form, IAM policy, credential options, and how to change the region. The full prerequisites table, PATH troubleshooting, and Bedrock configuration are in Getting Started /awslabs/aidlc-workflows/blob/main/docs/guide/01-getting-started.md . Codex CLI 1. Install Codex CLI ≥ 0.145.0 — earlier releases do not restore hook-provided workflow context immediately after a mid-turn compaction : codex --version confirm ≥ 0.145.0 The shipped config.toml runs on Amazon Bedrock ; set your AWS profile and region in the bedrock provider block. 2. Set up your project which must be a git repository — Codex only discovers a project .codex/hooks.json inside one : cp -r dist/codex/.codex/ your-project/.codex/ cp -r dist/codex/.agents/ your-project/.agents/ cp -r dist/codex/aidlc/ your-project/aidlc/ the workspace shell — a sibling of .codex/, not inside it cp dist/codex/AGENTS.md your-project/AGENTS.md or merge into yours The aidlc/ shell ships the pre-built aidlc/spaces/default/memory/ method tree the engine reads; $aidlc --doctor fails its "workspace shell ready" check without it. After copying, apply the .gitignore entries from the shipped AGENTS.md before your first workflow, pre-seed hook trust, then verify: cd your-project && bun .codex/tools/aidlc-utility.ts doctor Invoke the orchestrator with $aidlc or /skills → aidlc followed by a scope or description. The Codex guide /awslabs/aidlc-workflows/blob/main/docs/guide/harnesses/codex-cli.md covers the trust dialog, config merge, and sandbox/git notes in full. Cursor 1. Install Cursor — the IDE, or the Cursor CLI agent : Cursor CLI macOS / Linux — the IDE is a separate download from cursor.com curl https://cursor.com/install -fsS | bash One install serves both surfaces: the Cursor IDE and the CLI agent share the same .cursor/ discovery. Named models --model , per-agent pins need a paid Cursor plan; Free accounts use Auto , and the shipped personas carry no model pins so they inherit your session model either way. 2. Set up your project bun dist/cursor/install.ts your-project The aidlc/ shell ships the pre-built aidlc/spaces/default/memory/ method tree the engine reads; /aidlc --doctor fails its "workspace shell ready" check without it. The installer refuses project-owned file collisions, preserves .cursor/.gitignore and existing method memory, merges .cursor/hooks.json hook arrays and .cursor/cli.json permission arrays, and adds marked AI-DLC sections to existing AGENTS.md and .gitignore files. Re-running it upgrades framework-managed files while preserving the active-space pointer. Then verify: bun .cursor/tools/aidlc-utility.ts doctor Open your-project/ in the Cursor IDE or start agent in it and invoke the orchestrator with /aidlc followed by a scope or description. Cursor-native shortcuts expose /aidlc-status , /aidlc-jump --stage <slug or --phase <name , and /aidlc-scope <name through the same deterministic engine. The Cursor guide /awslabs/aidlc-workflows/blob/main/docs/guide/harnesses/cursor.md covers the hooks.json adapter, native subagents and skills, and what differs on this harness in full. opencode 1. Install opencode ≥ 1.17 : opencode --version confirm ≥ 1.17 The shipped project opencode.json pins no session model — your global opencode configuration supplies it. 2. Set up your project cp -r dist/opencode/.aidlc/ your-project/.aidlc/ the AIDLC engine opencode never scans it cp -r dist/opencode/.opencode/ your-project/.opencode/ native shell: subagents + /aidlc command + adapter plugin cp -r dist/opencode/aidlc/ your-project/aidlc/ the workspace shell — a sibling of .aidlc/, not inside it cp dist/opencode/opencode.json your-project/opencode.json or merge into yours keep skills.paths + instructions + permissions cp dist/opencode/AGENTS.md your-project/AGENTS.md or merge into yours The engine deliberately lives in .aidlc/ , NOT .opencode/ — opencode auto-imports .opencode/tools/ .ts as custom tools, which would crash on the engine's CLI scripts. opencode.json 's skills.paths points opencode at .aidlc/skills for discovery. After copying, apply the .gitignore entries from the shipped AGENTS.md before your first workflow, then verify: cd your-project && bun .aidlc/tools/aidlc-utility.ts doctor Invoke the orchestrator with /aidlc followed by a scope or description. The opencode guide /awslabs/aidlc-workflows/blob/main/docs/guide/harnesses/opencode.md covers the split layout, the adapter plugin, and what differs on this harness in full. GitHub Copilot 1. Install GitHub Copilot CLI ≥ 1.0.74 and/or VS Code ≥ 1.130 : copilot --version confirm ≥ 1.0.74 VS Code agent mode: code --version, confirm ≥ 1.130 One install serves both surfaces: the standalone Copilot CLI and VS Code agent mode. The shipped tree pins no model - signed-in Copilot works as-is, and BYOK works with no GitHub auth at all. 2. Set up your project mkdir -p your-project/.aidlc your-project/aidlc your-project/.github cp -R dist/copilot/.aidlc/. your-project/.aidlc/ the AIDLC engine neither surface scans it cp -R dist/copilot/aidlc/. your-project/aidlc/ the workspace shell - a sibling of .aidlc/, not inside it cp -R dist/copilot/.github/. your-project/.github/ MERGE - everything aidlc-prefixed cp dist/copilot/AGENTS.md your-project/AGENTS.md or merge; keep the @-import block The engine lives in .aidlc/ ; everything either Copilot surface discovers natively rides .github/ hooks, agents, skills , all aidlc -prefixed so the merge never overwrites your own .github/ content. After copying, apply the .gitignore entries from the shipped AGENTS.md before your first workflow, then trust the folder - add the project's absolute path to trustedFolders in ~/.copilot/config.json , or accept the CLI's interactive trust prompt untrusted folders silently skip every hook . Headless copilot -p runs additionally need GITHUB COPILOT PROMPT MODE REPO HOOKS=1 . Run /aidlc --doctor to verify, then invoke the orchestrator with /aidlc followed by a scope or description - in either surface. The GitHub Copilot guide /awslabs/aidlc-workflows/blob/main/docs/guide/harnesses/copilot.md covers the two surfaces, folder trust, BYOK setup, and what differs on this harness in full. Three guides, one per reader — pick by what you're trying to change: | For | Covers | | |---|---|---| | Building software with AI-DLC | Getting started, workflows, scopes, agents, interaction modes, troubleshooting | | Shaping how AI-DLC behaves | Stages, agents, scopes, rules, sensors, and team knowledge — configuration, not code | | Changing AI-DLC itself | Architecture, orchestrator, stage protocol, hooks, state machine, testing, contributing | Three zones: what AI-DLC is , how each harness speaks , and what users copy . You only ever edit the first two — bun scripts/package.ts regenerates the third. aidlc-claude/ │ ─────────── HAND-AUTHORED SOURCE — edit here ─────────── ├── core/ ONE harness-neutral source of truth │ ├── tools/ 48 aidlc- .ts engine and authoring tools │ ├── aidlc-common/ stage protocol + 33 stage files + conductor │ ├── agents/ 14 agents: 11 domain + 2 reviewers + composer │ ├── knowledge/ memory/ scopes/ sensors/ hooks/ │ ├── skills/ 3 session skills session-cost, replay, outcomes-pack │ └── templates/ onboarding skeleton → each harness's CLAUDE.md / AGENTS.md │ prose names the harness dir with the {{HARNESS DIR}} token — substituted at packaging │ ├── harness/ thin per-harness authored surfaces — small, divergent by design │ ├── claude/ manifest.ts · orchestrator skill · settings.json · onboarding fills │ ├── kiro-ide/ manifest.ts · orchestrator · conductor Markdown · v2 .json + legacy .kiro.hook files · onboarding fills │ ├── kiro/ manifest.ts · orchestrator · agent JSONs · settings · onboarding fills CLI — agent-JSON hooks │ ├── codex/ manifest.ts · emit.ts Codex-only emissions · orchestrator · hooks adapter │ ├── cursor/ manifest.ts · orchestrator · hooks adapter · installer · rules · onboarding fills │ ├── opencode/ manifest.ts · emit.ts · orchestrator · /aidlc command · adapter plugin │ └── copilot/ manifest.ts · emit.ts · orchestrator skill · hooks adapter │ ├── plugins/ optional, owned AIDLC plugins — new stages + the additive contribution seam │ └── test-pro/ reference fixture: .aidlc-plugin/plugin.json · stages/ · contributions/ · sensors/ · tools/ · tests/ │ ├── scripts/ │ ├── package.ts THE build entry: copy core+harness per manifest → graph compile → │ │ runner-gen → emit per tree. --check = total drift guard CI │ ├── build-binaries.ts release-only CLI bundles under ignored build/ │ └── manifest-types.ts shared manifest contract │ │ ─────────── GENERATED, COMMITTED, DRIFT-GUARDED — never hand-edit ─────────── ├── dist/ │ ├── claude/.claude/ what Claude Code users copy │ ├── kiro-ide/{AGENTS.md, .kiro/} what Kiro IDE users copy │ ├── kiro/{AGENTS.md, .kiro/} what Kiro CLI users copy │ ├── codex/{AGENTS.md, .agents/, .codex/} what Codex CLI users copy │ ├── cursor/{AGENTS.md, aidlc/, .cursor/} what Cursor IDE/CLI users install │ ├── opencode/{AGENTS.md, .aidlc/, .opencode/} what opencode users copy │ ├── copilot/{AGENTS.md, .aidlc/, .github/} what GitHub Copilot users copy │ └── plugins/<name /{claude,codex,copilot,cursor,kiro,kiro-ide,opencode}/ one real host plugin per harness — install alongside dist/<harness / │ │ ─────────── SUPPORTING ─────────── ├── tests/ all-TypeScript suite t .test.ts — resolves dist via AIDLC SRC └── docs/ guide/ · harness-engineering/ · reference/ core/ is what AI-DLCis. harness/ is how each harnessspeaks. dist/ is what userscopy. Only the first two are ever edited; bun scripts/package.ts regenerates the rest, and a hand-edit to dist/ is a CI failure. Maintainers edit the hand-authored source in core/ or a harness/<name / surface , then regenerate the committed dist/<harness / trees — never hand-edit dist/ , the drift guard fails CI. bun scripts/package.ts regenerate every dist/<harness / from core/ + harness/ bun scripts/package.ts <name regenerate one harness e.g. claude, kiro-ide, codex bun scripts/package.ts --check byte-parity drift guard run in CI Release binary artifacts are built separately after the drift guard is clean: bun scripts/build-binaries.ts native binary + mandatory smoke gates bun scripts/build-binaries.ts --all-targets release matrix Each target is emitted under build/binaries/<target / with the executable and a runtime/<harness / copy of every generated harness distribution it may dispatch into. Adding a whole new harness? See Porting to a New Harness /awslabs/aidlc-workflows/blob/main/docs/harness-engineering/09-porting-to-a-new-harness.md . The authoritative build reference is the Contributing Guide /awslabs/aidlc-workflows/blob/main/docs/reference/11-contributing.md development-workflow . bun tests/run-tests.ts default: smoke + unit + integration bun tests/run-tests.ts --ci smoke + unit + integration bun tests/run-tests.ts --release + e2e full acceptance bash tests/run-tests.sh --ci POSIX compatibility wrapper See Testing Reference /awslabs/aidlc-workflows/blob/main/docs/reference/09-testing.md for the full strategy and test registry. Most first-run trouble is one of these; each harness guide covers the rest. | Symptom | Harness | Fix | |---|---|---| which bun works in your terminal, but the harness can't find bun | all | bun isn't on the non-interactive PATH. Copy the BUN INSTALL / PATH export into ~/.zshenv zsh or ~/.bashrc bash/Git Bash — see the tip under | /aidlc --doctor reports a Codex CLI version below 0.145.0 | Codex | Upgrade to Codex CLI 0.145.0 or later. Older releases either delay compact-session workflow-context restoration or break subagent attribution and hyphenated agent TOML resolution. | Bedrock calls fail with AccessDenied or a model-not-found error | Claude, Codex | Enable model access for the harness's configured models in your AWS account and put working credentials on your SDK chain. Confirm AWS REGION is a region where you enabled them. | | Hooks never fire no audit rows, no gates | Codex | Trust the hooks: from the AI-DLC source checkout run bun install --frozen-lockfile , then bun scripts/package.ts codex trust --project <dir and replace any existing entries for that hook path; or start one TUI session and choose "Trust all." Untrusted hooks never run. | Plugin stages or contributions disappeared after copying a new dist/ | all | Re-run /aidlc plugin sync . Copying a fresh engine distribution restores the stock graph and core stage sources; compose-capable hosts also self-heal on the next session start. | Skills or rules don't take effect after you copy a new dist/ | all | Start a fresh session — harnesses load skills, agents, and rules at session start. | See Contributing Guide /awslabs/aidlc-workflows/blob/main/docs/reference/11-contributing.md for prerequisites, workflow, and submission process. AWS AI-DLC Blog Post https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/ AI-DLC Method Definition Paper https://prod.d13rzhkk8cj2z0.amplifyapp.com/ AI-DLC Workflows 2.0 Specification https://github.com/awslabs/aidlc-workflows/blob/main/assets/AI-DLC-Workflows-2.0-Specification.pdf AWS Labs whitepaper