What actually changed between Amazon's AI-DLC v1 and v2 — and why did AWS rewrite it?

The one-paragraph answer

v1 and v2 are not two versions of the same software. They are two different kinds of thing. v1 was 34 markdown files and zero lines of code — a 25 KB core-workflow.md full of MANDATORY: and CRITICAL: instructions that you copied into your IDE's rules folder and hoped the model would obey. v2 is ~104,000 lines of TypeScript built around a deterministic engine that decides what runs next, with the LLM demoted from "the thing that decides the workflow" to "the thing that executes one stage well." AWS states the reason in its own spec: v1's "prescriptive stage definitions proved too opinionated, and that is where adoption friction arose," and the goal of v2 is to "march progressively towards autonomous software delivery — reducing human intervention as machine-checkable verification expands." The single sentence version: v1 asked an LLM to follow a process; v2 runs a process that calls an LLM.

---

Method — what could and could not be read

Primary sources only, read directly. Cloned awslabs/aidlc-workflows and read both branches — the v1 branch (frozen at 1.0.1) and main (2.7.1, v2 GA) — plus both CHANGELOGs, the git history back to the first commit, and the 6-page AI-DLC Workflows 2.0 Specification PDF that ships in the repo at assets/. Every claim below is from a file I opened or a commit I read.

What I could NOT read: the AWS DevOps blog post that defines the methodology (aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/) and the Method Definition Paper (prod.d13rzhkk8cj2z0.amplifyapp.com) — both refused by this container's egress proxy (EGRESS_BLOCKED, and curl fails at the CONNECT tunnel with 403). So the original methodology's publication date and its exact framing are UNVERIFIED here. Everything about the two implementations is VERIFIED.

---

§1 — Timeline (VERIFIED from git history and both CHANGELOGs)

Date	Event
2025-11-13	First commit in awslabs/aidlc-workflows
2025-11-20	Kiro CLI support + "multi-platform architecture" (PR #2, from an outside contributor)
2026-01-22	v1 0.1.0 — first tagged release
2026-04-20	v1 0.1.8
2026-04-24	v2 lineage 0.1.0 — "Initial public release." Already 5 phases, 32 stages, 11 agents, 9 scopes, TypeScript hooks. This is a parallel line, not a continuation of v1's numbering.
2026-06-17	v1 1.0.0 — its changelog literally includes the line "adding support for AIDLC v2 alpha (#284)"
2026-06-18	v2 lineage 2.0.0 — see the version-numbering trap in §2
2026-06-30	v1 1.0.1 — the last v1 release. v1 is frozen from here.
2026-07-22	"docs: announce AI-DLC Workflows 2.0 as GA in the README" (#627), and the 2.0 Specification PDF is updated the same day
2026-09-01	"docs: make main the v2 GA source of truth" (#991) — v2 takes over main; v1 is exiled to the v1 branch for existing installs and maintenance only. Also ships 2.7.0 / 2.7.1.

Current state as of 3 Sep 2026: main = 2.7.1 (v2, GA), v1 branch = 1.0.1, maintenance only.

The version-numbering trap (worth knowing before you read anything else)

There are three different numbering schemes in play, and conflating them is the easiest way to get this wrong:

1. v1's own line: 0.1.0 → 1.0.1. Ends 2026-06-30.
2. v2's implementation line: 0.1.0 (2026-04-24) → 2.7.1 (2026-09-01). Its 2.0.0 bump on 2026-06-18 was a small feature release — it added an optional reviewer: field to stage frontmatter and grew the agent roster 11 → 13. It is not the v1→v2 jump.
3. "AI-DLC Workflows 2.0" — the brand for the whole rewrite, defined by the spec PDF and announced GA on 2026-07-22.

So "AI-DLC v2" means #3. The 2.0.0 in the changelog is #2 and is nearly unrelated.

---

§2 — What each version physically is (VERIFIED by counting files in both branches)

	v1 (v1 branch, 1.0.1)	v2 (main, 2.7.1)
Shipped payload	aidlc-rules/ — 34 markdown files, 270,737 bytes	core/ — 217 files, ~104,476 lines of TypeScript + 144 markdown
Executable code	None. Pure prompt text.	50 aidlc-*.ts engine/authoring tools, TypeScript hooks, 468 *.test.ts files
The "brain"	one core-workflow.md (25 KB) the model reads	a compiled stage graph + state machine the engine owns
Distribution	download a release .zip, copy folders into .kiro/steering/, .amazonq/rules/, .cursor/rules/*.mdc, … per platform, by hand	bun scripts/package.ts generates 2,201 files across dist/<harness>/; hand-editing dist/ fails CI via a byte-parity drift guard
Install prerequisite	none ("Users shouldn't need to install anything" was a v1 tenet)	bun on every harness

That last row is the honest cost of v2 and worth saying out loud: v1's "methodology first, install nothing" tenet is gone. v2 requires a runtime.

---

§3 — The eight major changes, and the reason for each

1. LLM-decided progression → deterministic engine

v1: the workflow was a prompt. From the actual core-workflow.md:

# PRIORITY: This workflow OVERRIDES all other built-in workflows **CRITICAL**: When performing any phase, you MUST read and use relevant content from rule detail files.

Stages were marked ALWAYS, CONDITIONAL, or INTELLIGENT ASSESSMENT, and the model decided which applied. Nothing outside the model could tell whether it had.

v2: from the user guide — "A deterministic engine decides what happens next; the conductor (the /aidlc session) carries it out, then asks the engine for the next move." The spec's implementation guideline #1 is "Deterministic routing: stage order and workflow transitions are decided by the orchestration layer." State and audit transitions are tool-owned (guideline #5), not model-narrated.

Why: spec Principle 3 — self-correction only works when "the post-conditions must be checkable by a program the AI cannot modify." A rule the model can quietly skip is not a gate.

2. One monolithic rules file → Skills as the unit of composition

Why (this is the money quote, spec Principle 6, VERIFIED verbatim):

"Learning from customers over the last year, our prescriptive stage definitions proved too opinionated, and that is where adoption friction arose. For example, AI-DLC 1.0 treats Build & Test as one stage, but for almost all customers it spans multiple activities: reviews, builds, functional tests, security tests, and more. Similarly, some customers produce UI mock-ups alongside User Stories, while others defer them to the Design stage. Therefore, we need a finer-grained, ai-native building block that customers can compose freely."

The answer was Skills, explicitly following the agentskills.io specification: "A Skill represents a discrete capability or expertise that humans historically provided: database design, code review, security analysis etc."

3. 3 phases / ~14 stages → 5 phases / 33 stages

v1	v2
🔵 Inception, 🟢 Construction, 🟡 Operations (a placeholder — "future")	Initialization (3), Ideation (7), Inception (9), Construction (7), Operation (7) = 33

v1 shipped with its Operations phase openly unimplemented. v2 has a real Operation phase and adds a whole Ideation phase in front of Inception.

4. Zero agents → a 14-agent roster

v1 had no agent files at all — one model wearing whatever hat the rules described. v2 ships 11 domain experts (product, design, delivery, architect, aws-platform, compliance, devsecops, developer, quality, pipeline-deploy, operations) + 2 review-only agents + the composer.

Notably, v2's own guide argues against the obvious over-correction:

"Rather than dozens of narrow specialists (an approach that recreates waterfall handoff chains), AI-DLC uses 11 broadly capable agents that each participate across multiple stages… This mirrors how effective human teams work: a mob of 3-5 people covers an entire feature."

Execution topology is 29 inline / 2 subagent / 1 pipeline / 1 mob. Spec guideline #8: "No hidden delegation: agents do not recursively spawn other agents."

5. Per-IDE manual surgery → "one core, many harnesses"

v1: the README carried separate copy-paste instructions (macOS, PowerShell and CMD variants) for Kiro, Amazon Q, Cursor, Cline, Claude Code, GitHub Copilot and Codex. Every platform was hand-maintained.

v2: methodology lives once in harness-neutral core/; each harness adds a thin surface; bun scripts/package.ts generates every distribution. Seven harnesses today: Claude Code, Kiro IDE, Kiro CLI, Codex CLI, Cursor, opencode, GitHub Copilot. The README's claim: "The deterministic engine — state machine, audit log, and the referee that coordinates parallel agents — is byte-identical across every harness; only the shell differs."

Why: spec §5 explicitly refuses the lowest-common-denominator trap — the shared definition covers stage structure and contracts, and "does not cover tool-specific affordances… Each tool-specific emitter is responsible for layering its platform's native affordances on top."

6. Advisory prose checks → the three-compartment model (Generate → Verify → Learn)

Spec Principle 4 defines every stage in three compartments:

Compartment	The question	Content
1	"The What"	declared inputs, outputs, required intermediates — declarative, not imperative
2	"How Do We Know It's Right"	post-conditions the AI self-checks against
3	"What Did We Learn"	which runtime signals become candidate new rules

And a distinction v1 had no way to express — Compartment 2 supports two verification modes:

• Inferential (LLM-judged) — fine for nuance, e.g. most code-review rules. But: "a stage whose Compartment 2 contains only LLM-judged post-conditions will not self-halt on its own verification. It still presents its output to the human." AWS is explicit about the failure mode: the same model generating and grading itself will "satisfy the letter of the check without satisfying its intent."
• Computational (executables) — for zero-tolerance rules, the example given being "no code path shall delete a CloudFormation stack in a production environment."

v2 ships 6 such deterministic Sensors today (aidlc-linter, aidlc-traceability, aidlc-type-check, aidlc-upstream-coverage, aidlc-required-sections, aidlc-claim-sources).

7. Corrections evaporate → a learning loop that writes rules

Spec Principle 9: "Today, when a human corrects an AI output, that correction is typically applied once and forgotten."

v2's implementation: each stage keeps a memory.md diary (Interpretations, Deviations, …); at the approval gate candidates are surfaced; you confirm what to keep; kept items are written into a five-layer rule chain (org → team → project → phase → stage) that resolves strict-additive at workflow start. Spec guideline #7: "Controlled learning: new rules are admitted deliberately, not silently."

8. Adaptive-by-vibes → 11 scopes + a composer + a 91-event audit trail

v1 adapted by asking the model to judge (INTELLIGENT ASSESSMENT). v2 makes it selectable and inspectable: 11 named scopes (enterprise → express, plus classic — the v1-shaped default — and workshop), 3 depth levels × 3 test-strategy levels, an adaptive composer (/aidlc compose) that proposes a stage plan, and 91 audit event types for enterprise traceability.

---

§4 — Why: the two forces, in AWS's own words

Straight from §1 of the specification (VERIFIED verbatim):

"Version 1 demonstrated the value of running the SDLC as a sequence of stages with a human in the loop. Version 2 keeps the methodology and rebuilds the workflow layer to march progressively towards autonomous software delivery — reducing human intervention as machine-checkable verification expands. Two forces drove the redesign. Customer engagements surfaced demand for finer-grained, composable building blocks that teams could shape to their own delivery flows. The agent platform matured in parallel: new constructs for packaging discrete capabilities (Skills) and for modelling collaborating specialists (multi-agent runtimes) made it possible to express that granularity, and the verification rules that go with it, natively rather than through steering rules alone."

Note what that sentence concedes: v1 was built for a platform that didn't have Skills, subagents, or lifecycle hooks yet. It was written in steering rules because steering rules were all there was. Half of "why v2" is simply that the runtime caught up.

The other half is the destination. Principle 7 — "Autonomous Development in Safe Increments Rather than as a Big-Bang" — is candid that this is a slow path: every organisation's guardrails, compliance rules and tribal knowledge have to be distilled into machine-checkable post-conditions before the human gate can be removed, "No customer will complete it in one go." v2's design is the container for that hydration. Principle 1 says the quiet part: "While we have not yet reached consensus on whether human-in-the-loop can be eliminated entirely, we are aligned on the imperative that we must continue to drive down the human effort required at every stage."

---

§5 — What did NOT change

Worth stating, because "v2" makes it sound like everything moved:

• The methodology. Inception → Construction → Operation survives; v2 adds Initialization and Ideation around it.
• The vocabulary. Units of work, Bolts, walking skeleton, mob execution — all still in v2's glossary.
• Human approval at every stage. Still there, in both. Spec guideline #4: "non-bootstrap stages require explicit approval."
• The "AI proposes, human validates" stance. Unchanged as of 2.7.1 — the autonomy is a direction of travel, not a shipped state.

---

§6 — How a PM uses this

1. The methodology/implementation split is the reusable idea. AWS separates "AI-DLC the methodology" from "this repo, the implementation." Most AI-process debates in a PM's org conflate the two and argue about tools when the disagreement is about process (or vice versa).
2. "Too opinionated" is the adoption lesson, and it is not AI-specific. AWS shipped a prescriptive stage model, watched customers bounce off it because their Build & Test is five activities not one, and rebuilt around composable pieces. Any PM who has rolled out a delivery framework has this scar.
3. The verification distinction is the one to steal. Inferential (an LLM judges, nuance allowed, cannot self-halt) vs Computational (a program judges, zero tolerance, can self-halt). It is a clean way to answer "where can we let the agent run, and where must a human still sign?" — and it says the honest thing: a check the model grades itself on is not a gate.
4. Autonomy arrives by hydration, not by announcement. The human-in-the-loop count drops only as fast as your org converts tribal rules into machine-checkable ones. That is a backlog, and it is a PM's backlog.

---

Cross-References

Related: frameworks/ai-dlc

---

Sources

Primary — read directly (VERIFIED):

• awslabs/aidlc-workflows, branch main @ a277af2 (v2, 2.7.1) — README, docs/guide/, docs/reference/, core/, CHANGELOG.md
• awslabs/aidlc-workflows, branch v1 (v1, 1.0.1) — README, aidlc-rules/, CHANGELOG.md
• AI-DLC Workflows 2.0 Specification (6 pp.), assets/AI-DLC-Workflows-2.0-Specification.pdf on main. All quoted principles come from this file.
• Git history: first commit 2025-11-13; #627 (GA announcement, 2026-07-22); #991 (main→v2 cutover, 2026-09-01)
• Repository: https://github.com/awslabs/aidlc-workflows
• Skills specification referenced by the spec: https://agentskills.io/specification

Could not open (UNVERIFIED — flagged for a human to check):

• AWS DevOps blog, AI-Driven Development Life Cycle — https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/ — EGRESS_BLOCKED
• Method Definition Paper — https://prod.d13rzhkk8cj2z0.amplifyapp.com/ — EGRESS_BLOCKED

Both are the canonical definitions of the methodology (as opposed to the two implementations). Nothing in this digest depends on them, but the methodology's original publication date is not established here.