Spec Kit vs AWS AI-DLC

I first compared Spec Kit and AWS AI-DLC by looking at their review gates. That was the wrong place to start.

The gate is only one checkpoint. Long before an agent asks for approval, it has already interpreted the request, filled in missing details, chosen an architecture and divided the work. Those earlier decisions often matter more than the final review.

So I went back and traced the complete path from an idea to tested code.

As a software engineer and cloud architect, this is the part I care about. I want to know where a decision is recorded, how it becomes executable work and what happens when the code proves the plan wrong.

Spec Kit and AI-DLC share the same broad goal: replace a loose conversation with a repeatable development process. They put written intent ahead of code and try to keep requirements connected to implementation.

They take very different routes.

My shorthand is simple: Spec Kit is an artifact pipeline. AI-DLC is a process runtime.

Spec Kit turns one document into the next:

idea
  → spec.md
  → plan.md
  → tasks.md
  → code
  → convergence findings

AI-DLC builds a stateful workflow around the same transformation:

intent
  → requirements
  → user stories
  → architecture
  → Units of Work
  → dependency graph
  → per-unit plans
  → isolated implementation
  → integration evidence
  → deployment and operational feedback

That difference shows up everywhere: in the questions each tool asks, the way work is divided, what “parallel” means and how the workflow recovers when the implementation misses the requirement.

Scope of this comparison

Both projects are moving quickly. This article is based on repository inspection on 2 September 2026:

• AWS AI-DLC commit a277af2
• GitHub Spec Kit commit 0053c3a

This is an implementation comparison, not a productivity benchmark. Lines of code per hour would tell us little here; the result would depend on the model, project, existing codebase and amount of human review.

At a glance

How Spec Kit writes the spec

Spec Kit begins with /speckit.specify, or $speckit-specify in Codex skills mode.

The command turns a feature description into spec.md. I like that the template stays focused on the product rather than drifting into implementation too early. It asks for:

• Prioritised user stories
• Independent test descriptions
• Acceptance scenarios
• Edge cases
• Functional requirements
• Key entities
• Measurable success criteria
• Assumptions

The specification is supposed to describe what users need and why, without prematurely deciding how the feature will be implemented.

Spec Kit also gives uncertainty a visible representation. Important unresolved decisions are written as:

[NEEDS CLARIFICATION: specific question]

The current command limits these markers to three and applies reasonable defaults to less important omissions. It then creates a requirements-quality checklist and asks the agent to validate its own specification against criteria such as:

• No unresolved clarification markers
• Requirements are testable and unambiguous
• Acceptance scenarios are defined
• Success criteria are measurable
• Implementation details have not leaked into the product specification

For a small or medium-sized feature, this is a useful front end. One request becomes a readable product document without forcing the team through a long discovery process.

My concern is that the same model usually writes and reviews the document. The checklist helps, but words such as “complete,” “testable” and “unambiguous” still depend on model judgment.

How AI-DLC writes the spec

AI-DLC spreads the same work across several stages. When I followed the workflow, it felt less like completing a template and more like moving through a requirements process.

For a full feature workflow, it can perform:

1. Intent capture
2. Market and feasibility analysis
3. Scope definition
4. Existing-system reverse engineering
5. Team-practices discovery
6. Requirements analysis
7. User-story elaboration
8. Domain design
9. Unit decomposition
10. Contract design
11. Delivery planning

Requirements Analysis creates stable identifiers such as FR1, FR1.2 and NFR3. Before writing the requirements, it loads earlier context, examines functional and non-functional dimensions, asks structured questions, checks for vague answers and requests confirmation of a consolidated summary.

User Stories is a separate multi-agent stage. A product agent owns the draft, while design, development and quality agents review it from different perspectives. Stories receive IDs such as US1.1; acceptance criteria receive IDs such as AC1.1.1.

The stage then writes traceability.json, mapping every upstream requirement to one or more stories. Deferred or missing coverage is recorded rather than left implicit.

It feels closer to formal requirements engineering than filling out a feature template.

That can help on a large or regulated system. It can also be far too much ceremony for a small change. Scopes such as express, bugfix, mvp, feature and enterprise are therefore important, not decorative.

How planning differs

Spec Kit’s /speckit.plan reads the specification and project constitution, then produces:

• plan.md
• research.md
• data-model.md
• Interface contracts
• quickstart.md

The plan captures the language, frameworks, dependencies, project structure, performance goals and technical constraints. Unknown technical decisions become research work. External interfaces become contracts. Domain entities become a data model.

The split is easy to follow:

spec.md     = what and why
plan.md     = how
tasks.md    = concrete implementation work

AI-DLC separates planning into more layers.

It distinguishes:

1. Architecture: What components and boundaries exist?
2. Topology: Which architectural units depend on which others?
3. Delivery strategy: In what order should the units be delivered to maximise value or reduce risk?
4. Implementation planning: What exact steps and tests are required for one unit?

One AI-DLC idea stood out to me: the dependency graph and the delivery plan are not the same thing.

A dependency graph can show that Unit B requires Unit A. It cannot decide whether the team should prioritise a walking skeleton, the riskiest integration or the highest-value customer journey. People still need to make that call.

From plan to work

Spec Kit: stories and tasks

/speckit.tasks reads the specification, plan, data model, contracts and research. It produces phases such as:

Phase 1: Setup
Phase 2: Foundational work
Phase 3: User Story 1
Phase 4: User Story 2
Phase 5: User Story 3
Final phase: Polish

Each task follows a strict format:

- [ ] T014 [P] [US1] Implement auth middleware
      in src/auth/middleware.ts

The components mean:

• T014: stable task identifier
• [P]: may run in parallel
• [US1]: maps to User Story 1
• The file path: scopes the expected implementation

It is practical. A coding agent can read the list and start working immediately.

The limitation is that the dependency model remains advisory. [P] usually means the model believes two tasks touch different files and do not depend on each other. It is useful guidance, but it is not an authoritative execution graph.

AI-DLC units

AI-DLC’s main implementation unit is the Unit of Work.

A unit might be:

• A deployable service
• A user-interface surface
• A reusable library
• A formal specification
• A packaging or deployment component

Stories are mapped onto these units, and one story can span several of them. This decomposition looks more like a system architecture or team ownership map than a backlog.

AI-DLC writes a machine-readable YAML dependency graph:

units:
  - name: identity-service
    kind: service
    depends_on: []

  - name: profile-api
    kind: service
    depends_on:
      - identity-service

The graph must be complete, well-formed and acyclic. The runtime parses it and computes dependency-ready batches.

Parallelism becomes an execution property, not just a label in a document.

One project, two workflows

To make this less abstract, I used the same project for both walkthroughs.

Shared requirements

The project is an internal expense-approval application:

• Employees submit an expense with amount, date, category, description and receipt.
• Receipts may be PDF, JPEG or PNG, up to 10 MB.
• Managers approve or reject expenses with a comment.
• Employees can view the current status and complete decision history.
• Decision history is immutable.
• The system sends email after submission and decision.
• Employees can only access their own expenses.
• Managers can only review expenses belonging to their team.
• Normal requests should complete within two seconds at p95.
• The MVP serves one business unit and does not initiate reimbursement payments.

The technical choices are also identical:

• React and TypeScript
• Node.js and Fastify
• PostgreSQL
• S3-compatible receipt storage
• Email provider behind an adapter
• Docker Compose
• Vitest and Playwright

Building it with Spec Kit

Installation

For Codex:

uv tool install specify-cli

mkdir expense-approval-speckit
cd expense-approval-speckit
git init

specify init --here \
  --force \
  --integration codex \
  --script sh

For a real project, I would pin a known release instead of installing an unpinned latest version.

Set project rules

$speckit-constitution

Use TypeScript throughout.
Keep business logic independent of Fastify and React.
Every API endpoint requires integration tests.
Security-sensitive authorisation logic requires unit tests.
Database migrations must be reversible.
Never store receipt contents in PostgreSQL.
Every status change must produce an immutable audit record.

This gives later planning and implementation commands a set of project-wide constraints.

Write the specification

$speckit-specify

Build an internal expense-approval application.

Employees submit expenses with an amount, date, category,
description and receipt.
Managers approve or reject them with a comment.
Employees can see the current status and decision history.

Receipts may be PDF, JPEG or PNG up to 10 MB.
Employees can only access their own expenses.
Managers can only review expenses for their team.
Send email after submission and decision.
Normal requests must complete within two seconds at p95.

The MVP supports one business unit.
It does not execute reimbursement payments.

The generated feature directory resembles:

specs/001-expense-approval/
├── spec.md
└── checklists/
    └── requirements.md

A representative specification might contain:

### User Story 1 - Submit Expense (P1)

As an employee, I want to submit an expense
with its receipt so my manager can review it.

Independent Test:
An employee can submit a valid expense and retrieve it
with Pending status.

Acceptance Scenarios:

1. Given an authenticated employee,
   when they submit a valid expense,
   then it is recorded with Pending status.
2. Given a receipt larger than 10 MB, when it is uploaded,
   then the submission is rejected.
3. Given an unsupported receipt format, when it is uploaded,
   then the submission is rejected.

### Functional Requirements

- FR-001: Employees MUST be able to submit an expense.
- FR-002: Store receipt metadata separately from its content.
- FR-003: Employees MUST only access their own expenses.
- FR-004: Managers MUST only access their team's expenses.
- FR-005: Every status change MUST create
  an immutable history event.
- FR-006: Notify relevant users after submission
  and decision.

I would run $speckit-clarify next. Likely questions include:

• Can an expense be edited after submission?
• Can a manager reverse a decision?
• What happens when email delivery fails?

The answers become part of the specification instead of remaining in conversation history.

Write the technical plan

$speckit-plan

Use a TypeScript monorepo.
Use React and Vite for the frontend and Fastify for the API.
Use PostgreSQL for transactional data.
Store receipts in S3-compatible object storage.
Put the email provider behind an adapter.

Use Docker Compose for local development.
Use Vitest for unit and integration tests.
Use Playwright for browser tests.
Keep domain logic independent of frameworks and storage.

The feature directory expands:

specs/001-expense-approval/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── expenses-api.yaml
│   └── notifications.md
└── checklists/
    └── requirements.md

The plan may choose this source layout:

apps/
├── api/
└── web/

packages/
├── domain/
├── database/
├── receipt-storage/
└── notifications/

Generate the tasks

$speckit-tasks

The resulting tasks.md might contain:

## Phase 1: Setup

- [ ] T001 Create pnpm workspace configuration
      in pnpm-workspace.yaml
- [ ] T002 [P] Create API package in apps/api/
- [ ] T003 [P] Create React application in apps/web/
- [ ] T004 Create Docker Compose services
      in docker-compose.yml

## Phase 2: Foundational

- [ ] T005 Create migration infrastructure
      in packages/database/
- [ ] T006 Implement authentication context
      in apps/api/src/auth/
- [ ] T007 Implement team authorisation
      in packages/domain/src/auth/
- [ ] T008 Define receipt-storage interface
      in packages/receipt-storage/

## Phase 3: User Story 1 - Submit Expense

- [ ] T009 [P] [US1] Add Expense model
      in packages/domain/src/expense.ts
- [ ] T010 [P] [US1] Add receipt validation
      in packages/domain/src/receipt.ts
- [ ] T011 [US1] Implement expense repository
      in packages/database/src/expenses.ts
- [ ] T012 [US1] Implement POST /expenses
      in apps/api/src/routes/expenses.ts
- [ ] T013 [US1] Build submission form
      in apps/web/src/features/expenses/
- [ ] T014 [US1] Add expense-submission integration test

I would then run:

$speckit-analyze
$speckit-implement
$speckit-converge

implement reads the artifacts, performs the tasks and changes completed checkboxes to [X].

converge compares the resulting code with the specification, plan and task list. If notification failures are recorded but never retried, it appends another phase:

## Phase 7: Convergence

- [ ] T029 [FR-006] Add retryable
      notification-outbox persistence
- [ ] T030 [FR-006] Add notification-worker integration test

The loop is explicit:

implement
  → converge
  → append missing work
  → implement again

Building it with AI-DLC

Installation

AI-DLC is copied into each project:

git clone https://github.com/awslabs/aidlc-workflows.git

mkdir expense-approval-aidlc
cd expense-approval-aidlc
git init

mkdir -p .codex .agents aidlc

cp -R ../aidlc-workflows/dist/codex/.codex/. .codex/
cp -R ../aidlc-workflows/dist/codex/.agents/. .agents/
cp -R ../aidlc-workflows/dist/codex/aidlc/. aidlc/

The project’s existing AGENTS.md and .gitignore should be merged rather than overwritten.

Verify the installation:

bun .codex/tools/aidlc-utility.ts doctor

Start the workflow

For a normal feature, only one user-facing entry point is needed:

$aidlc --scope feature \
  Build an internal expense-approval application...

The equivalent scope shortcut is:

$aidlc-feature \
  Build an internal expense-approval application...

AI-DLC installs many other skills, but users do not need to run them in sequence.

The installed skills fall into four groups:

• $aidlc: the main workflow conductor
• Scope shortcuts such as $aidlc-feature, $aidlc-mvp and $aidlc-bugfix
• Isolated stage runners such as $aidlc-requirements-analysis and $aidlc-code-generation
• Utilities such as $aidlc-compose, $aidlc-session-cost and $aidlc-replay

The stage runners package --stage <name> --single. They produce one stage’s artifacts without advancing the live workflow. In normal use, $aidlc lets the state machine select the next stage.

Requirements and stories

AI-DLC creates an intent record:

aidlc/spaces/default/intents/260902-expense-approval/
├── aidlc-state.md
├── audit.md
├── runtime-graph.json
├── ideation/
├── inception/
├── construction/
├── operation/
└── verification/

Requirements Analysis might produce:

### FR1 - Expense submission

- FR1.1 Employees can submit an expense with amount, date,
  category and description.
- FR1.2 Each submission includes one receipt.
- FR1.3 Receipts may be PDF, JPEG or PNG
  and no larger than 10 MB.

### FR2 - Expense review

- FR2.1 Managers can approve their team's expenses.
- FR2.2 Rejection requires a manager comment.
- FR2.3 Approval and rejection decisions are final in the MVP.

### NFR1 - Performance

Normal API requests must meet a two-second p95 target.

### NFR2 - Authorisation

The system must prevent cross-employee and cross-team access.

The User Stories stage turns those into:

### US1.1 - Submit an expense

As an employee, I want to submit an expense
with its receipt so my manager can review it.

- AC1.1.1: A valid submission creates
  an expense with Pending status.
- AC1.1.2: A receipt larger than 10 MB is rejected.
- AC1.1.3: An unsupported receipt format is rejected.

### US2.1 - Decide an expense

As a manager, I want to approve or reject
an expense belonging to my team.

- AC2.1.1: Approval produces an immutable Approved event.
- AC2.1.2: Rejection requires a comment.
- AC2.1.3: A manager cannot decide
  an expense outside their team.

The traceability file makes the mapping explicit:

{
  "stage": "user-stories",
  "upstream_ids": ["FR1", "FR2", "NFR1", "NFR2"],
  "coverage": [
    {"id": "FR1", "status": "OK", "target": "US1.1"},
    {"id": "FR2", "status": "OK", "target": "US2.1"},
    {
      "id": "NFR1",
      "status": "Deferred",
      "target": "nfr-requirements"
    }
  ]
}

Generate architectural units

Instead of immediately creating file-level tasks, AI-DLC identifies Units of Work:

The machine-readable dependency graph might be:

units:
  - name: expense-domain
    kind: library
    depends_on: []

  - name: receipt-storage
    kind: library
    depends_on: []

  - name: expense-api
    kind: service
    depends_on:
      - expense-domain
      - receipt-storage

  - name: notification-worker
    kind: service
    depends_on:
      - expense-domain

  - name: expense-web
    kind: ui
    depends_on:
      - expense-api

  - name: local-platform
    kind: packaging
    depends_on:
      - expense-api
      - notification-worker
      - expense-web

The runtime can derive these batches:

Batch 1:
  expense-domain
  receipt-storage

Batch 2:
  expense-api
  notification-worker

Batch 3:
  expense-web

Batch 4:
  local-platform

Stories are mapped separately:

US1.1 → U1, U2, U3, U5
US2.1 → U1, U2, U4, U5
US3.1 → U1, U2, U5

This was the point where AI-DLC clicked for me. The user story still describes value, while the Unit of Work becomes the execution boundary.

Create the delivery plan

AI-DLC then produces an economic sequence:

### Bolt 1 - Submission Walking Skeleton

Units:
- expense-domain
- receipt-storage
- minimal expense-api
- minimal expense-web

Definition of Done:
An employee can submit an expense locally
and retrieve its Pending status.

Confidence hypothesis:
This proves the browser, API, database
and receipt-storage boundaries work together.

### Bolt 2 - Manager Decision

Definition of Done:
A manager can approve or reject a team expense.
The employee can see the immutable history.

### Bolt 3 - Reliable Notifications

Definition of Done:
Submission and decision events produce
retryable email notifications.

The Bolt sequence and dependency batches are related, but they answer different questions. The Bolt plan expresses learning and business value. The DAG expresses what can technically run next.

Plan and implement each unit

Before changing application source for expense-domain, AI-DLC creates a unit-specific code-generation plan:

## Code Generation Plan - expense-domain

- [ ] Step 1: Configure the unit-scoped Vitest command.
- [ ] Step 2: Add failing expense-creation tests.
- [ ] Step 3: Implement the Expense entity.
- [ ] Step 4: Add failing decision-transition tests.
- [ ] Step 5: Implement immutable state-transition events.
- [ ] Step 6: Add authorisation-policy tests.
- [ ] Step 7: Implement authorisation policies.
- [ ] Step 8: Run unit tests and type checking.

## Testing Contract

Methodology: TDD
Unit command: pnpm vitest packages/domain
Coverage floor: 90%

The plan, test instructions, unit identity and source state are fingerprinted. Code generation requires approval tied to that exact evidence.

For autonomous parallel construction, AI-DLC can create one worktree per dependency-ready unit:

.worktrees/
├── bolt-expense-domain/
└── bolt-receipt-storage/

Separate agents implement the units. A deterministic referee then reruns each unit’s check command, verifies its source manifest and review evidence, and serialises successful merges.

Build, test and recover

After unit construction, Build and Test can execute:

pnpm install
pnpm lint
pnpm typecheck
pnpm vitest
pnpm playwright test
docker compose config

Suppose the implementation records email failures but provides no retryable outbox.

Spec Kit’s Converge command would append remediation tasks.

AI-DLC can instead:

1. Record the failed requirement and evidence.
2. Identify notification-worker as the affected unit.
3. Jump back to Code Generation.
4. Invalidate stale completion and approval evidence.
5. Generate a revised unit plan.
6. Rebuild the unit.
7. Replay Build and Test.

The autonomous retry is bounded. If the workflow cannot converge, control returns to the human.

What changed in practice

Both approaches can produce a similar repository:

apps/
├── api/
└── web/

packages/
├── domain/
├── database/
├── receipt-storage/
└── notifications/

What changes is the route to that repository.

Spec Kit effectively hands the coding agent a specification, a plan and a task list.

AI-DLC hands it the current workflow state, a dependency-ready unit, an approved plan, a testing contract and a definition of acceptable evidence.

Spec Kit leaves the process visible in a small number of files. AI-DLC turns more of that process into executable state.

Where Spec Kit works better

Simpler mental model

The core lifecycle fits in a short command sequence:

specify
→ clarify
→ plan
→ tasks
→ analyze
→ implement
→ converge

The artifacts are ordinary files that I can review, edit and diff without first learning a runtime.

Less framework overhead

Spec Kit provides structure without asking every project to adopt a large runtime model. For normal feature work, that restraint is valuable.

Stories map to delivery

Tasks are grouped around independently testable user value. That will feel familiar to many product teams, especially when the feature fits inside one service or repository.

Easy to customise

Templates, constitutions, presets, extensions and integrations make the process easy to adapt. I can change the rules without first changing an execution engine.

Where AI-DLC works better

Explicit architecture

Units are typed, mapped to stories and connected through a machine-readable DAG. I can see why a unit is ready instead of trusting a [P] label.

Durable execution state

Progress is not represented only by editable checkboxes. Workflow state, audit events, runtime graphs, manifests and receipts provide stronger evidence.

Isolated parallel work

Dependency-ready units can run in separate Git worktrees, so one unit’s uncommitted changes do not automatically leak into another unit’s context.

Built-in recovery

A test failure can route work back to the stage that introduced the problem, invalidate stale evidence and replay the affected path. I find that more useful than simply appending another task and hoping the next pass fixes it.

Separate agent roles

Product, architecture, development, design, quality, delivery and operations agents have different responsibilities. The extra roles can expose disagreements that one general-purpose agent might otherwise smooth over.

What the model still decides

Neither system eliminates model judgment.

Spec Kit’s agent decides whether a requirement is testable, whether a task is parallel-safe and whether implementation satisfies the plan.

AI-DLC’s agents still author requirements, choose unit boundaries, write architecture, diagnose failures and propose fixes. Its runtime can validate structure, state transitions, hashes, file manifests and command exit codes. It cannot deterministically prove that the chosen architecture is good or that a requirement accurately represents what the stakeholder meant.

That limit is easy to miss. Deterministic machinery can enforce the process around a decision, but it cannot make the decision correct.

The trade-off

Spec Kit can be too trusting.

An agent can misunderstand a task, mark a checkbox complete too early or incorrectly decide that two tasks are independent. The files make that visible after the fact, but they do not always prevent it.

AI-DLC can become too heavy.

More stages, agents, artifacts, state transitions, hooks, fingerprints and worktrees mean more context, more tool calls and more framework code that can fail. A six-line bug fix does not need an enterprise lifecycle. Even a substantial feature may not need every possible design and operations artifact.

That is why AI-DLC’s scopes matter. They are what keep a small change from inheriting an enterprise-sized process.

Which would I use?

For most small and medium feature work, I would start with Spec Kit.

Its specification front end is clear, its artifacts are cheap to inspect and its task list gives a coding agent enough structure without burying the project under process.

I would lean towards AI-DLC when:

• Several architectural units can be built in parallel
• Multiple agents or teams need explicit ownership
• The project needs strong auditability
• Requirements must trace into implementation and tests
• A failed integration should automatically route work back upstream
• Deployment and operations are part of the requested lifecycle rather than somebody else’s problem

I am also testing a hybrid workflow that uses Spec Kit for specification and planning, then hands execution to AI-DLC. That method is not a native integration between the projects, and I want to verify it in a real repository before presenting it as established practice. I am documenting that experiment separately.

My take

AI-driven development is bigger than code generation or review gates.

The harder problem is preserving meaning as work moves through this chain:

intent
→ requirements
→ architecture
→ executable work
→ code
→ evidence
→ operational feedback

Spec Kit represents that chain as a compact set of documents. AI-DLC moves similar documents through a stateful runtime.

Neither approach is universally better.

The question I would ask is: how much of this process should remain understandable to a person reading files, and how much should software enforce?

For a single feature and one team, an artifact pipeline may be enough.

For a multi-unit system with parallel agents, compliance requirements and expensive failure modes, a process runtime starts to make sense.

I would not choose either framework because it has more commands or a more impressive lifecycle diagram. I would choose the smallest process that preserves intent, exposes uncertainty and gives me credible evidence that the software does what we asked for.

References

Repository revisions and source files were accessed on 2 September 2026.

1. AWS Labs. AI-DLC Workflows. GitHub repository, commit a277af2. Primary files consulted: Requirements Analysis, User Stories, Units Generation, Code Generation and Skill System.

2. GitHub. Spec Kit. GitHub repository, commit 0053c3a. Primary files consulted: Specify, Plan, Tasks, Implement, Converge and the full SDD workflow.