AI-DLC: How AWS Built Harness-Neutral Workflow Rules That Run in Claude Code, Cursor, and Seven Other Agents

AWS Labs released AI-DLC (AI-Driven Development Life Cycle) to solve a specific problem: every coding agent has its own orchestration model, and workflows written for Claude Code do not run in Cursor or GitHub Copilot. AI-DLC ships a single harness-neutral core that runs structured software-delivery workflows across nine different agent environments. Version 2.11.3 includes native installers for macOS, Linux, Windows, and WSL, and the project is trending at #11 in TypeScript with 5,739 stars.

The Harness-Neutral Architecture

AI-DLC separates workflow rules from execution environments. A single aidlc config --harness <name> command configures a project for Claude Code, Kiro CLI, Kiro IDE, Codex CLI, Cursor, opencode, or GitHub Copilot. The workflow rules stay the same. The harness adapter translates those rules into the specific API calls, file-watching hooks, and state-management primitives each agent expects.

The native aidlc command does three things:

Installs harness runtimes without requiring Bun or Node.js on the host system.
Runs verification hooks that check code changes before the agent commits them.
Manages project configuration through a single CLI surface across all supported agents.

The manual-copy path still exists for teams that cannot install native executables. Download the tarball, extract the runtime/<harness>/ directory into your project, and install Bun. This path skips the native command but requires you to manage runtime files yourself.

Workflow Rules and Verification Steps

AI-DLC workflows are structured as a series of steps. Each step includes:

A task description the agent reads.
A verification command that runs after the agent makes changes.
A rollback rule if verification fails.

Here is a minimal workflow configuration:

steps:
  - name: "add-feature"
    task: "Implement the user authentication endpoint"
    verify: "npm test -- auth.test.ts"
    on_failure: "revert"
  
  - name: "update-docs"
    task: "Update API documentation with new endpoint"
    verify: "npm run docs:validate"
    on_failure: "skip"

The agent reads the task, generates code, and AI-DLC runs the verification command. If the command exits non-zero, the workflow either reverts the change or skips to the next step, depending on the on_failure rule. This prevents agents from shipping broken changes in long-running workflows.

Harness Adapter Layer

Each harness adapter translates workflow rules into agent-specific primitives. The adapter for Claude Code uses the MCP (Model Context Protocol) to inject workflow state into the conversation context. The Cursor adapter writes workflow state to a .cursor/ directory and registers file-watching hooks. The GitHub Copilot adapter uses the Copilot Chat API to send workflow instructions as system messages.

The adapter layer handles three responsibilities:

State persistence: Where does the workflow store its current step, verification results, and rollback history?
Hook registration: How does the agent know when to run verification commands?
Context injection: How does the agent receive the current task description?

The table below shows how each harness handles these responsibilities:

Harness	State Persistence	Hook Registration	Context Injection
Claude Code	`.aidlc/state.json`	MCP tool calls	MCP context injection
Kiro CLI	`.aidlc/state.json`	CLI command wrappers	Stdin prompt injection
Kiro IDE	`.aidlc/state.json`	IDE extension hooks	Editor panel UI
Codex CLI	`.aidlc/state.json`	CLI command wrappers	Stdin prompt injection
Cursor	`.cursor/aidlc.json`	File watcher hooks	Chat API system message
opencode	`.opencode/state.json`	LSP protocol hooks	LSP diagnostic messages
GitHub Copilot	`.github/aidlc.json`	Copilot Chat API	Chat API system message

Installation and PATH Management

The native installer handles PATH registration differently on each platform. On Windows, it installs for the current user and automatically registers the bin directory in User PATH. The installer warns if you run it as administrator because installing as administrator is less safe. On macOS, Linux, and WSL, the installer prints a PATH instruction you must follow manually.

The Windows uninstall removes only the User PATH entry recorded as installer-owned. It does not touch System PATH or other User PATH entries.

If you skip the native install and use the manual-copy path, you must install Bun and manage the runtime files yourself. This path does not require the aidlc command, but you lose automatic verification hooks and cross-harness configuration management.

Feature Parity Across Harnesses

Harness-neutral design costs feature parity. Claude Code supports streaming responses and real-time verification feedback. Cursor supports inline diff previews. GitHub Copilot supports multi-file edits in a single suggestion. AI-DLC workflows cannot use these features because they are not available in all harnesses.

The workflow rules expose the lowest common denominator:

Task descriptions (all harnesses support text prompts).
Verification commands (all harnesses can run shell commands).
Rollback rules (all harnesses can revert file changes).

If you need streaming responses, inline diffs, or multi-file edits, you must write harness-specific workflows. AI-DLC does not abstract those features.

Observability and Debugging

AI-DLC writes workflow state to .aidlc/state.json (or the harness-specific equivalent). The state file includes:

Current step index.
Verification results for each step.
Rollback history.
Timestamp for each state transition.

The aidlc doctor command reads the state file and prints a diagnostic report. It checks for:

Missing verification commands.
Failed verification steps.
Orphaned rollback entries.
Harness configuration mismatches.

The doctor command does not fix problems. It reports them so you can fix them manually.

Security Boundaries

AI-DLC runs verification commands in the same shell environment as the agent. If the agent has access to production credentials, the verification commands have access to production credentials. There is no sandbox. There is no privilege separation.

The workflow rules are stored in .aidlc/workflows.yaml in the project root. If an attacker can modify that file, they can inject arbitrary shell commands into the verification steps. AI-DLC does not sign or validate workflow files.

Teams that need sandboxed verification should run AI-DLC inside a container or VM. Teams that need signed workflow files should build a wrapper that validates .aidlc/workflows.yaml before the agent reads it.

Deployment Shape

AI-DLC is a local development tool. It does not include a server component. It does not include a web UI. It does not include a CI/CD integration. The workflow runs on the developer’s machine, in the same environment as the agent.

If you want to run AI-DLC workflows in CI, you must:

Install the native aidlc command in the CI environment.
Configure the harness for a CLI agent (Kiro CLI or Codex CLI).
Run aidlc run in the CI script.

The CI environment must have access to the same verification commands the developer uses locally. If the verification commands depend on local credentials, the CI environment needs those credentials.

Likely Failure Modes

AI-DLC workflows fail in three predictable ways:

Verification command exits zero but the code is still broken. The verification command is not comprehensive enough. Add more tests.
Verification command times out. The command is too slow or the agent is stuck. Set a timeout in the workflow rules.
Rollback leaves the project in a broken state. The rollback rule is too aggressive or the agent made changes outside the tracked files. Use a more conservative rollback rule or track more files.

The harness adapter can also fail if the agent changes its API. AI-DLC does not version-lock agent APIs. If Claude Code ships a breaking change to the MCP protocol, the Claude Code adapter will break until AWS Labs ships a patch.

Technical Verdict

Use AI-DLC if you:

Work with multiple coding agents and want the same workflow rules in all of them.
Need structured verification steps that prevent agents from shipping broken changes.
Can tolerate the lowest-common-denominator feature set across harnesses.

Avoid AI-DLC if you:

Need streaming responses, inline diffs, or multi-file edits in your workflows.
Need sandboxed verification or signed workflow files.
Want a server-based orchestration system with a web UI and CI/CD integration.

AI-DLC is a local development tool that solves the harness-portability problem. It does not solve the observability problem, the security problem, or the CI/CD problem. It gives you one workflow core that runs in nine different agents. That is the entire value proposition.

Agentic AI, minus the noise.