AI-DLC for Claude Code

A Claude Code-native port of the AI-DLC methodology — the same three-phase, human-approval-gated software development lifecycle, rebuilt on Claude Code's native primitives (skills, subagents, workflows, hooks) instead of a generic markdown rule bundle.

Install

Copy the .claude/ directory into the root of your project:

cp -r claude-aidlc/.claude /path/to/your/project/.claude

Then start Claude Code in that project and run /aidlc-start.

How it maps to the original

Original aws-aidlc	This package	Native mechanism
core-workflow.md	.claude/CLAUDE.md	Auto-loaded context (does not execute)
Phase rule-detail files	.claude/rules/**	Loaded on demand via @path
"Load rules" instructions	.claude/skills/*/SKILL.md	/aidlc-* slash commands
Generation work	.claude/agents/*.md	Specialist subagents
Design/code review, traceability, evaluator scripts	.claude/workflows/*.js	Multi-agent workflows
Design-review bash hook	.claude/hooks/aidlc-gate.sh	PreToolUse hook
Audit trail	.claude/hooks/aidlc-audit.sh	PostToolUse hook
Session resume	.claude/hooks/session-start.sh	SessionStart hook
aidlc-state.md, question files	unchanged	same conventions

Key design decision: gates live in the main loop

The original methodology stops at an approval gate after every stage. Claude Code workflows run to completion and cannot pause for user approval, and subagents run autonomously and cannot ask the user mid-run. Therefore:

• The sequential, gated phases (Inception, Construction) are driven by skills in the main conversation loop, which spawns subagents for heavy generation and then stops at each gate.
• Only the batch, no-human-in-the-loop tools (design review, code review, traceability, evaluate) are implemented as workflows.

This is the one place the naive "everything is a workflow" port would have been wrong.

Layout

.claude/
  CLAUDE.md             # thin always-on context
  settings.json         # wires the 3 hooks by event name
  skills/               # /aidlc-* entry points (users invoke these)
  agents/               # reverse-engineer, app-designer, functional-designer,
                        #   code-generator, test-writer, infrastructure-designer,
                        #   ui-ux-designer, e2e-test-writer
  workflows/            # design-review, code-review, traceability, evaluate
  hooks/                # session-start, aidlc-gate (location enforcement), aidlc-audit
  design-kit/           # vendored UX/UI engine: DTCG tokens, 138 design systems,
                        #   taste/anti-slop, a11y specs + runnable gate scripts
                        #   (WCAG contrast / axe / responsive / focus-trap)
  testing/              # story_coverage.py — the story↔E2E coverage gate
  docs/                 # pipeline planning notes
  rules/
    common/             # session-continuity, context-assembler, aidlc-config,
                        #   framework-alignment-format, depth-levels, …
    inception/          # workspace-detection, requirements, stories, …
    construction/       # functional-design, nfr-*, infrastructure-design,
                        #   code-generation, build-and-test, ui-ux-design,
                        #   application-baseline, stacks/
    operations/
    extensions/         # security/, resiliency/, ui-ux/

aidlc-docs/ (written into your project at runtime):

aidlc-config.md         # user-editable project configuration (project root)
aidlc-docs/
  aidlc-state.md        # single source of truth for progress
  audit.md              # auto-appended audit trail
  _checkpoints/         # compact state summaries (context_compression: High)
  construction/
    _application/       # shared baseline — written once, referenced by all units
      nfr-baseline.md   #   shared NFR targets
      security-baseline.md
      tech-stack.md
      infrastructure-baseline.md
      adrs.md           #   cross-unit ADRs
      adr-index.md      #   one-line ADR summary index
      active-constraints.md  # accumulated downstream constraints from all stages
      design-system.md  #   (UI/UX) kit + DTCG token foundation, shadcn/tweakcn
      information-architecture.md  # (UI/UX) sitemap + global app-shell nav
    {unit-name}/        # per-unit deltas only
      ui-ux-design/     #   (UI/UX full) flows, wireframes, prototypes, component
                        #     map, states-coverage, design-review, a11y-audit
      …

Commands

Building a new project from scratch

Run these commands in order. Each one stops at an approval gate — you review the output and type Approve before it continues.

1. /aidlc-start          Detects whether the workspace is new or existing,
                         creates aidlc-docs/aidlc-state.md, and routes to
                         the right starting point.

2. /aidlc-inception      Runs all planning stages in sequence:
                           - Requirements Analysis (what to build + why)
                           - User Stories (personas, stories, ubiquitous language)
                           - Workflow Planning (which stages to execute)
                           - Application Design (components, services, ports)
                           - Units Generation (decompose into bounded contexts)
                         Each stage ends at a gate. You can stop and resume any time.

3. /aidlc-construction   Runs Construction for each unit in dependency order:
                           - Functional Design (business logic, data model)
                           - NFR Requirements (performance, security, tech stack)
                           - NFR Design (caching, retries, auth patterns)
                           - Infrastructure Design (cloud resources, deployment)
                           - Code Generation (application code + tests)
                         Repeats for each unit. Stops at every gate.

4. /aidlc-build-test     Stands the app up (docker compose) and runs functional +
                         story-acceptance E2E against the LIVE stack: generates
                         @story-tagged Playwright specs, runs them, and BLOCKS on
                         the story-coverage gate (every story needs a passing UI
                         test). Writes build/test instructions, coverage targets,
                         BDD scenarios, contract test lists, and the design-kit
                         frontend gates. Final gate before Operations.

5. /aidlc-operations     Deployment and monitoring planning (currently a
                         placeholder for future expansion).

Starting with an existing codebase

Same flow, but /aidlc-start detects existing source and runs /aidlc-reverse-engineer first — producing a business overview, architecture diagrams, API docs, and code inventory before Requirements Analysis begins.

---

Phase drivers

Command	What it drives
/aidlc-start	Entry point — detects workspace, resumes or begins
/aidlc-inception	All Inception stages in order (requirements through units)
/aidlc-construction	All Construction stages per unit, then Build and Test
/aidlc-operations	Operations phase (placeholder)

---

Re-running a specific stage

These commands run a single stage in isolation. You would not use them on a first run — they exist for targeted rework after feedback, or to resume partway through a session after clearing context.

Command	Stage	When to re-run it
/aidlc-reverse-engineer	Reverse Engineering	Existing codebase changed significantly and the RE artifacts are stale
/aidlc-requirements	Requirements Analysis	Requirements need to be updated after feedback or scope change
/aidlc-stories	User Stories	New personas or stories added; existing stories need rework
/aidlc-workflow-plan	Workflow Planning	Stage execution plan needs to change (add/skip a stage)
/aidlc-app-design	Application Design	Component or service boundaries need redesigning
/aidlc-units	Units Generation	Unit decomposition or bounded context mapping needs to change
/aidlc-functional-design [unit]	Functional Design	Business logic or data model for a specific unit needs rework
/aidlc-code [unit]	Code Generation	Re-generate or patch code for a specific unit after design changes
/aidlc-build-test	Build and Test	Re-run after all units are complete, or after adding new test scenarios

---

Review tools

These run as multi-agent workflows — they fan out multiple independent reviewers in parallel and return a consolidated report. They are LLM-advisory: findings are recommendations, not automated fixes. Run them at natural checkpoints, not after every small change.

Command	What it reviews	When to run it
/aidlc-design-review	Inception design artifacts (requirements, stories, application design, units)	After Inception is approved, before starting Construction
/aidlc-code-review	Generated code for a unit	After Code Generation is approved for a unit
/aidlc-traceability	End-to-end coverage: requirements → stories → code → tests	Before Build and Test gate, to catch gaps
/aidlc-evaluate	Overall quality of all artifacts in the current phase	Any time you want an independent quality assessment

---

Utilities

Command	What it does
/aidlc-status	Shows a summary of the current phase, completed stages, pending stages, and the next step — useful after resuming a session
/aidlc-reset	Archives all current aidlc-docs/ content with a timestamp and restarts from scratch. Use when starting a completely different project in the same workspace

Configuration

aidlc-config.md is created at your project root and controls workflow behaviour across sessions. Edit it directly — no code changes needed.

Key	Values	Default	What it controls
autopilot	off questions full	off	How much human input is required. questions auto-answers all question files with best-judgment and logs assumptions to audit.md, but still pauses at approval gates. full is completely unattended — auto-answers questions AND auto-approves all gates. All decisions logged to audit.md.
context_compression	None Medium High	None	Context management between stages. Medium pauses and prompts /compact; High auto-writes a checkpoint summary safe to /compact or /clear after.
ui_ux	off design-system full	full	Kit-driven UI/UX (see Design kit below). design-system (Level B) = DTCG token foundation + shadcn/Tailwind/tweakcn baseline + app-level information architecture. full (Level A) adds per-unit user flows, ASCII wireframes and rendered HTML prototypes, shadcn component mapping, 8-state coverage, a USP/marketing surface, a living style guide, dark mode, and design-review + a11y reports. UI/UX is mandatory for any unit with a frontend (off is only for API-only/CLI/library/infra projects).
stage_thoroughness	essential standard thorough	standard	How detailed stage artifacts are — questions asked, depth of analysis, richness of output docs.
coverage_gate	0–100	60	Minimum line coverage % required at Build and Test.
observability	basic full	basic	Observability scaffolding in generated code. full adds OpenTelemetry tracing and health endpoints.

Extensions

Optional constraint layers live under .claude/rules/extensions/. Their *.opt-in.md questions are presented during Requirements Analysis; opting in loads the matching full rules file. Enablement is recorded in aidlc-state.md.

Extension	Opt-in	Effect
Security Baseline	requirements-analysis-questions.md	OWASP ASVS controls, STRIDE threat modelling, Zero Trust — blocking constraints on all stages
Resiliency Baseline	requirements-analysis-questions.md	AWS Well-Architected Reliability Pillar guidance at NFR and Infrastructure Design stages
UI/UX Design	aidlc-config.md (ui_ux key)	Kit-driven token foundation, information architecture, wireframes + rendered prototypes, shadcn mapping, a11y gates — see Design kit and Configuration

Design kit (UI/UX)

When a project has a frontend, AIDLC drives a vendored UX/UI engine at .claude/design-kit/ (a port of the ux-ui-agent-skills kit) plus a set of design-* skills (design-prototype, design-brandkit, design-component, design-review, design-a11y-audit, design-apply-aesthetic, …). The ui-ux-designer agent uses them to produce, per the ui_ux level:

• Token foundation — DTCG 3-tier tokens + a single theme.css, anchored to a named design system chosen at Requirements (138 in the library — e.g. Vercel, Linear, Claude, Stripe). shadcn/ui + tweakcn remain the component layer.
• Information architecture — _application/information-architecture.md: sitemap, global app-shell navigation, auth boundary, public → signup → app entry path. (This is the fix for "generated apps have no navigation".)
• Wireframes + rendered prototypes — ASCII wireframes for review and real token-driven HTML prototypes (light + dark) per screen, including a USP/marketing surface and a living style guide.
• 8-state coverage — default / hover / focus / active / disabled / loading / error / selected, plus screen states (empty / loading skeleton / error / populated).

Blocking gates (real headless-Chrome measurement, not assertions): WCAG 2.2 contrast (light + dark), axe, responsive (no overflow at 280/320/414 px), focus-trap, no-hardcoded-values, no-emoji. Run at Build and Test from the app root via npm run design:* → .claude/design-kit/scripts/*. A gate that cannot run is a failure, never a silent pass. Prerequisite once per clone: cd .claude/design-kit && npm i.

Story coverage & end-to-end testing

A passing API or unit test does not prove a user story works in the UI — a green POST /auth/login says nothing about whether the app exposes a Sign-in path. AIDLC closes that gap with executable story acceptance:

• User Stories emit a Gherkin acceptance scenario per story and a story-test-index.md (story → scenario → route / persona / auth / type) — the contract the test layer consumes.
• Build and Test stands the stack up (docker compose up) and the e2e-test-writer agent generates @story-tagged Playwright specs that drive the real browser through each flow, then runs them.
• The story-coverage gate (.claude/testing/story_coverage.py) is blocking: it fails on any story without a spec (coverage) and, given the Playwright results, any story whose UI flow fails (execution). It produces bdd-scenarios.md and e2e-coverage-report.md — a precise per-story PASS/FAIL map, so a screen can never look done while being non-functional.

python3 .claude/testing/story_coverage.py \
    --index   aidlc-docs/inception/user-stories/story-test-index.md \
    --specs   <app>/e2e --results <app>/e2e-results.json

Frameworks

AIDLC applies industry-standard frameworks at every stage — not as a checklist, but as active constraints that shape artifacts and flow downstream. Each stage's framework-alignment.md records which frameworks were applied and what constraints they pass to the next stage. The full stage-by-stage mapping is in .claude/rules/common/framework-stack.md.

Architecture & Strategy

Framework	Where applied	What it does in AIDLC
TOGAF	Reverse Engineering, Workflow Planning	Establishes the as-is architecture baseline; maps planned stages to ADM phases to catch coverage gaps
Wardley Mapping	Workflow Planning	Classifies each capability as Genesis / Custom / Product / Commodity to drive build vs buy decisions
C4	Reverse Engineering, Application Design, Infrastructure Design	Context, Container, and Component diagrams at design; Deployment diagram at infrastructure
Hexagonal / Ports & Adapters	Application Design, NFR Design, Code Generation	Application core is isolated from infrastructure; ports are the design contract; adapters are the implementation
ADRs	Application Design, NFR Design, Infrastructure Design	Every non-trivial decision gets an Architecture Decision Record (Context, Decision, Consequences, Status)

Domain Modeling

Framework	Where applied	What it does in AIDLC
Domain-Driven Design (DDD)	User Stories, Units Generation	Ubiquitous language becomes code identifiers; bounded contexts define unit seams; context maps show upstream/downstream relationships
EventStorming	User Stories	Surfaces domain events, commands, and aggregates; domain events become the integration event contract
Entity-Relationship (ER)	Functional Design	Every entity has a primary key; relationships are explicit with cardinality
Canonical Data Model	Functional Design	Entities shared across units are defined once with an owning unit; downstream units reference, not redefine
Data Classification	Functional Design	Every entity field tagged PII / Sensitive / Internal / Public; PII and Sensitive fields must be encrypted at rest and masked in logs
CQRS	Application Design	Read and write models separated where write-side complexity warrants it; boundary is a non-negotiable module seam

Requirements

Framework	Where applied	What it does in AIDLC
Specification by Example	Requirements Analysis	Every functional requirement gets at least one Given / When / Then acceptance criterion; feeds directly to the test-writer agent
User Story Mapping	Requirements Analysis	Maps requirements to backbone activities and walking skeleton to verify completeness

Object-Oriented Design

Framework	Where applied	What it does in AIDLC
SOLID	Application Design, Functional Design, Code Generation	Single Responsibility and Dependency Inversion enforced explicitly; interfaces over implementations
GRASP	Application Design, Functional Design	Responsibility assignment patterns (Information Expert, Creator, Controller) applied when distributing logic
GoF Patterns	Application Design, Functional Design	Named when applied — e.g. "Strategy pattern for PaymentGateway port" — so the rationale is traceable

Security

Framework	Where applied	What it does in AIDLC
STRIDE	NFR Requirements	Threat model per unit: Spoofing, Tampering, Repudiation, Information Disclosure, DoS, Elevation of Privilege — each threat requires a mitigation and a test
OWASP ASVS	NFR Requirements, Code Generation	Controls selected at Level 1 / 2 / 3 based on sensitivity; every selected control must have an automated test
Zero Trust	NFR Requirements	No implicit trust between units; every cross-unit call authenticates and authorises explicitly; deny by default
Secure Coding (OWASP Top 10)	Code Generation	Input validation, parameterised queries, output encoding, secret management enforced at code generation

Infrastructure & Reliability

Framework	Where applied	What it does in AIDLC
AWS Well-Architected	NFR Design, Infrastructure Design	Five pillars evaluated per unit: Reliability, Security, Performance Efficiency, Cost Optimisation, Sustainability

Engineering Practices

Framework	Where applied	What it does in AIDLC
Clean Code	Code Generation	Intention-revealing names matching ubiquitous language; small single-purpose functions; no magic numbers
OpenAPI / AsyncAPI	Code Generation	API contract written before implementation code; implementation must conform to the contract, not the reverse
Conventional Commits	Code Generation	<type>(<scope>): <description> commit format enforced; violations flagged at code review

Testing

Framework	Where applied	What it does in AIDLC
Testing Pyramid	Build and Test	Target ratio documented: many unit, fewer integration, minimal e2e; coverage gate enforced before Operations
TDD	Code Generation, Build and Test	Tests written alongside implementation; coverage targets set before code generation begins
BDD / Gherkin	User Stories, Build and Test	Every story carries Given / When / Then acceptance scenarios (story-test-index.md); mapped to executable specs in bdd-scenarios.md
ATDD + Playwright story-acceptance E2E	Build and Test	The e2e-test-writer agent turns each story's acceptance scenario into an @story-tagged Playwright spec that drives the real browser against the running stack. The story-coverage gate (.claude/testing/story_coverage.py) blocks promotion unless every story has a passing UI acceptance test — a green API/unit test is not enough. See Story coverage & E2E.
Contract Testing	Build and Test	Consumer-driven contracts (e.g. Pact) for every API surface; a failing contract test is a breaking change and blocks promotion

Context management

AIDLC uses a layered strategy to keep agent context lean:

• _application/ baseline — shared content (NFR targets, OWASP controls, stack decisions, infrastructure topology) is written once by the first unit and referenced by all subsequent units. Unit docs contain deltas only.
• Context assembler (.claude/rules/common/context-assembler.md) — agents extract relevant sections from large application-level files (stories, requirements, components) using Grep + Read rather than loading whole files. Typically 5× reduction for agents working on a single unit.
• Active constraints (_application/active-constraints.md) — all downstream constraints from all prior stages accumulate in one file. Agents load this instead of hunting through N framework-alignment.md files.
• ADR index (_application/adr-index.md) — one-line ADR summary per decision. Full ADR text loaded only when a conflict is suspected.
• Checkpoints (_checkpoints/) — written when context_compression: High; safe anchor for /compact or /clear between stages.

Notes / caveats

• The aidlc-gate.sh and aidlc-audit.sh hooks parse the hook payload with python3 (present on macOS and most Linux). Adjust if your environment lacks it.
• Workflows require explicit user opt-in to run; invoking the corresponding /aidlc-* command is that opt-in.
• The review/traceability/evaluate workflows are LLM-driven and advisory — they do not replace running real linters/tests, and they do not auto-apply changes.