Please πŸ–±οΈ here for Github Blogs

The AI-DLC Approach to Fintech Software Development

  • August 25, 2026
Table of Contents

Two approaches to AI in software development

Dominant approaches to using AI in software development, they are the two ends of a spectrum of autonomy; see Stages of AI Development Autonomy:

AI-assisted development

  • AI enhances specific tasks: code completion, documentation, test generation.
  • The human writes the code; the AI speeds up individual steps. Think GitHub Copilot in its default mode.
  • The human controls the process end-to-end; the AI is a faster keyboard.

AI-managed development

  • AI is expected to generate entire applications from a prompt, with minimal human intervention.
  • The the AI plans, codes, tests and deploys, “vibe coding” tools that build a full-stack app from a paragraph of instructions.
  • Human surrenders granular control in exchange for speed.
  • A common pitfall: mostly AI is more helpful to a fault β€” it does more than what you need, so much so its a problem.
  • If you ask it to modify a database query - it rewrites schema, migration scripts, ORM layer and API endpoints. This is both the appeal and the risk: the output looks complete but may include decisions you never validated, patterns you never chose and scope you never approved.

Both extremes have problems:

  • AI-assisted development

    • constrains AI’s capabilities and reinforces outdated inefficiencies β€” you still plan, document and hand off the same way, just faster.
    • Raja SP argues (re:Invent 2025, DVT214) that in AI-assisted mode, the process stays the same as the pre-AI era: “people throwing documents at each other and attending many meetings to solve problems.”
    • AI saves time on individual tasks, but that time gets consumed by Scrum ceremonies β€” planning, refinement, stand-ups, retrospectives, estimation β€” that were designed for a world where iteration were slower and expensive.
    • The operations team waits for dev, QA waits for release, circular dependencies create escalation meetings and alignment meetings, and someone later says “what you did is wrong, go back and redo it.”
    • AI makes coding faster, but the meeting overhead that surrounds it remains unchanged. The result: velocity improvement is not significant.
    • Data supports parts of this β€” employees spend 31 hours/month in meetings, roughly half considered wasted; 71% of senior managers say meetings are unproductive (meeting statistics 2026).
    • The counter-argument (Scrum.org): the issue is not meetings per se, but that the meeting cadence was designed for slower iteration.
  • AI-managed development produces suboptimal results in velocity and quality

    • Velocity (speed): looks fast but isn’t. The AI churns out code immediately, but problems aren’t caught until late, so you spend time fixing, re-explaining and redoing. Net speed ends up slower than it seemed.
    • Quality: lower. The AI makes hundreds of invisible architectural decisions per second, and nobody reviews them until production breaks β€” so bugs, wrong patterns and unapproved scope slip through.

AI-DLC positions itself between these two extremes. AI drives the process

  • It drafts requirements, proposes architecture, writes code and tests
  • Pauses to ask clarifying questions and get human sign-off before proceeding, at every step.
  • The human does not write code; the human validates AI’s decisions.
  • This is the HITL/OHOTL/AHOTL spectrum: how much autonomy AI gets is a deliberate choice per Unit, not a blanket decision.

Source:

What Changes for People and Teams

Today’s product owners, Scrum masters, developers, QA engineers and SREs are organised around an SDLC designed for human-paced work. Waterfall and agile practices assume that iteration is expensive, so teams use handoffs, documents, approval gates and recurring ceremonies to coordinate. AI can change the cost and scale of iteration; adding AI to the old process without redesigning the workflow can preserve the overhead while only accelerating individual tasks.

That does not make judgment or accountability less important. A useful comparison is a doctor with an 85% diagnostic success rate, an AI system with a 90% success rate and a doctor using AI: the combination keeps human judgment and accountability while using the model as an aid. In software, the same principle means engineers need enough fundamentals to evaluate AI’s options. AI may suggest nine good options; the engineer should be able to choose the best one or propose a tenth. Generating a long document and asking someone else to take responsibility for it is not accountable use of AI.

This points toward a jack of all trades and master of one shape: people need enough breadth to work across the lifecycle, alongside depth in an area that lets them judge its trade-offs.

The roles can shift from producing and handing off artifacts toward setting intent, supplying domain context, validating decisions and owning outcomes. One practitioner observation behind this view was a discussion with eight managers who followed AI developments; all expected their people to remain significant and to keep improving as AI scaled. That is an anecdotal observation, not a workforce forecast.

Jevons’ paradox is another useful lens: efficiency gains can increase demand for the work rather than eliminate it. The claim that AI will replace people often assumes a fixed volume of work; if lower costs create more demand, the total amount of work can grow instead. See Satya Nadella’s post referencing Jevons’ paradox.

Resisting AI does not protect a role from change. As tools become more intuitive and reduce the learning curve, the practical response is to build the judgment needed to use and oversee them well.

AI-Assisted Software Development and the AI-DLC

Before deciding the roles of each persona its necesaary to understand the full set of practices that define AI-assisted software development and the lifecycle that governs how that AI work is planned, gated and reviewed.

The Pillars of AI-Assisted Development

AI-assisted software development is the practice of using LLM-based agents as collaborators across the SDLC, with humans supplying business context, judgment and accountability.

There is no single canonical list of pillars β€” different authors and organisations group the practice differently.

PillarWhat It CoversKey References
Prompt engineeringHow you talk to the model: wording, examples, formatting and instruction hierarchy. Determines how clearly the model is asked, not what it can knowChip Huyen, AI Engineering, ch 5; GitHub Blog, agentic primitives
Context engineeringCurating what the model sees: context window, memory layers, scoping, compression and selective loading. The difference between an agent that guesses and an agent that knowsBirgitta BΓΆckeler, Context Engineering for Coding Agents (martinfowler.com)
Retrieval and groundingPulling the right external knowledge into the window: chunking, embeddings, re-ranking, freshness. Grounds the model in your data instead of its training corpusHuyen, AI Engineering, ch 6 (context construction);
Spec-driven developmentStructured, versioned specifications become the source of truth and agents derive implementation, tests and documentation from themGitHub Spec Kit; arXiv process taxonomy of AI dev frameworks
Evaluation (evals)Testing non-deterministic output: the eval pyramid, golden datasets, invariants, model-graded metrics and CI gates. You cannot improve what you do not measureOpenAI Evals, Promptfoo, Braintrust, pytest, Hypothesis, ToolCallCheck; Huyen, ch 3-4
Agents, tools and harnessesThe execution layer: agent SDKs, tool calling, protocols and the harness that mediates context, tools, memory, verification and permissions. Includes agent skills β€” reusable packages that shape behaviour, such as adversarial “grill me” skills that interrogate intent and assumptions before work startsModel Context Protocol (MCP), Anthropic docs (https://www.anthropic.com/docs), OpenAI developer docs (https://platform.openai.com/docs), Multi-agent systems, OpenCode; Anthropic, Building Effective Agents; obra/superpowers (composable skills framework); addyosmani/agent-skills (production-grade skills with Planβ†’Buildβ†’Verifyβ†’Reviewβ†’Ship stages and evals); arXiv AI Harness Engineering
Guardrails, safety and securityPrompt injection defence, hallucination mitigation, permissions, secrets handling and supply-chain scanning for AI-generated codeHuyen, AI Engineering (safety chapter); OWASP Top 10 for LLM Applications
Observability, tracing and costMonitoring model and agent behaviour, logging, tracing, token budgets and cost governance. You cannot improve what you do not measureHuyen, AI Engineering (infrastructure layer); Context Engineering for Coding Agents
Model selection and adaptationChoosing the right model and adapting it: prompt vs RAG vs fine-tuning vs structured output. Start with prompting and retrieval before reaching for trainingHuyen, AI Engineering; Context Engineering for Coding Agents
Human oversight and governanceDeciding how much autonomy AI gets: HITL, OHOTL or AHOTL modes, review workflows, approval boundaries, traceability and audit trailsAI-DLC (below); arXiv Agentic Software Engineering (SE 3.0)

The AI-Driven Development Lifecycle (AI-DLC)

Origins and Provenance

AI-DLC (AI-Driven Development Life Cycle) is a framework that is about restructuring how humans and an AI coding assistant work together to build software: the AI drafts requirements, proposes architecture, writes code and tests and handles deployment configs β€” but always pauses to ask clarifying questions and get human sign-off before proceeding, at every step.

SourceOwnerStatusContribution
AI-Driven Development Life Cycle blog also AWS re:Invent 2025AWS blogsFoundational and officialThe three-phase model, Mob Elaboration, Mob Construction and core terminology (Intent, Unit, Bolt)
awslabs/aidlc-workflows, open-sourced November 2025AWS LabsOfficial reference implementationAdaptive workflow scaffolds (Rules and Steering files), mandatory vs conditional stages, checkpoints and audit trails
AI-DLC 2026 paper, ai-dlc.dev/paper, January 2026The Bushido CollectiveIndependent community synthesis, not an AWS publicationHITL/OHOTL/AHOTL operating modes, Bolts, Passes, harness-enforced quality gates and completion criteria

Core Terminology

  • Core terminologies that are AI-DLC specific β€” AWS draws equivalences to agile terms (Epic β†’ Unit, Sprint β†’ Bolt), but these can be misleading. The scope is narrower: an Intent is a feature or technical outcome, not an Epic that spans multiple teams, repos and sprints. The pattern across all of them: traditional terms assume humans plan and document, AI-DLC terms assume AI executes and humans set direction, define boundaries and review outcomes. AI-DLC sits between AI-assisted (AI helps with tasks) and AI-managed (AI does everything) β€” AI drives the process but humans validate every decision.

AI-DLC covers Inception, Construction and Operations β€” the phases where AI actively collaborates on building AI-DLC reimagines SDLC and build methodology within it. Source:

  • AI-DLC is an AI-centric transformative approach to software development" β€” AWS blog
  • ; the three phases (Inception, Construction, Operations) cover requirements/design, build, and deploy β€” not maintenance or decommissioning. - AIDLC - Method definition
Intent
  • Traditional Equivalent: None β€” new concept. The hierarchy is Intent β†’ Unit β†’ Bolt.
  • Definition: Describes what should be achieved β€” a business goal, a feature or a technical outcome (e.g., “Add OAuth login”, “Reduce API latency by 50%”, “Migrate from monolith to microservices”). Serves as the starting point for AI-driven decomposition into Units.
  • What Changed: An Epic describes what to build β€” a solution the team already understands. An Intent describes why β€” an outcome the AI must first clarify through questions before proposing a solution. Epic decomposes; Intent discovers.
  • Note:
    • The AWS blog (2025) says - Epics are replaced by “Units” of Work (dont misunderstand it for intent). The hierarchy is Intent β†’ Unit β†’ Bolt. Source: AWS blog and method definition PDF.
    • In traditional agile, an Epic is big β€” it spans multiple features, teams, repos and sprints. A Unit in AI-DLC is feature-scoped: a focused piece of work within a single Intent. Epics are generally bigger than Units. The scope shrinks because AI handles the decomposition that traditionally required human planning β€” backlog grooming, Epic writing, story splitting. The AI-managed part of AI-DLC is that decomposition work, which is why Unit replaces Epic at a smaller granularity.
    • In traditional agile, an Epic holds the full scope, stories, acceptance criteria and dependencies in one document. AI-DLC distributes that across the repository: the Intent holds purpose, the Unit decomposition holds scope, the Unit DAG (Directed Acyclic Graph) holds dependencies and the Knowledge Artifacts hold domain context. No single file replaces the Epic β€” the repository is the source of truth.
    • For greenfield projects this creates a gap: before Mob Elaboration there is nothing between the Intent and the Units. The decomposition only exists after the AI asks questions and the team validates. In traditional agile you would write the Epic first with full scope, then decompose. In AI-DLC the Intent is deliberately vague β€” the AI is supposed to discover the scope through questions. See Core Terminology: Mob Elaboration for the greenfield gap, AI question bias risk and grill-me workflow.
Unit
  • Traditional Equivalent: Feature / Work package
  • Definition: A cohesive, self-contained work element derived from an Intent, specifically designed to deliver measurable value. Each Unit gets its own Bolt with a chosen operating mode (HITL, OHOTL, AHOTL). Units are loosely coupled, independently deployable and have clear boundaries.
  • What Changed: A Feature is a chunk of functionality. A Unit is the unit of autonomy, not just the unit of scope β€” it determines how much human oversight the work requires.
  • Note: The AWS blog says Epics β†’ Units. The method definition says Units are “analogous to Subdomains in DDD or Epics in Scrum.” Both agree Unit replaces Epic, but disagree on whether Intent also replaces Epic or sits above it. The 2026 community paper sides with the method definition: “Units are analogous to Bounded Contexts in DDD or Epics in Scrum.” Source: AWS method definition and Bushido Collective 2026 paper.
Bolt
  • Traditional Equivalent: Sprint
  • Definition: The smallest iteration unit in AI-DLC, measured in hours or days, run in supervised (HITL), observed (OHOTL) or autonomous (AHOTL) mode. A Unit can be executed through one or more Bolts, which may run in parallel or sequentially.
  • What Changed: A Sprint is time-boxed (two weeks, fixed cadence). A Bolt is sized to the work and runs in a chosen operating mode. Small fixes get a short autonomous Bolt; complex features get a longer supervised one.
Pass
  • Traditional Equivalent: Discipline iteration
  • Definition: A typed iteration through the standard loop (elaborate, units, execute, review) through a design, product or development lens. Passes add a disciplinary lens over the standard loop, and later passes can pass work back to earlier ones when new constraints appear.
  • What Changed: In traditional agile, disciplines work sequentially (design β†’ dev β†’ test). Passes add a lens over the same loop with backward flow β€” a later pass discovering a constraint that invalidates an earlier assumption sends work back without anyone declaring failure.
Mob Elaboration
  • Traditional Equivalent: Requirements gathering
  • Definition: The whole team validates AI’s questions, assumptions and proposed units in a single session with a shared screen, led by a facilitator. AI converts intent into candidate requirements, user stories and units; the team validates or corrects the result.
  • What Changed: Requirements gathering produces documents through meetings. Mob Elaboration is the AI asking clarifying questions and the team validating in real time β€” the conversation is the artifact.
  • Key activities:
    • AI converts intent into candidate requirements and units
    • AI asks questions to uncover missing context (functional scope, business rules, edge cases, technical constraints)
    • The team validates assumptions and constraints
    • Completion criteria are defined for each unit
    • Bolt structure and supervision mode are selected
  • Grill-me workflow: The /grill-me skill fits into Mob Elaboration as the adversarial interrogation step. Two approaches work:
    • Option A: Brainstorm β†’ Team agreements β†’ Grill-me interrogates the agreed plan β†’ Revised plan β†’ Build. This catches flaws after convergence β€” cheap compared to catching them in Construction.
    • Option B (stronger): Brainstorm β†’ Grill-me interrogates during brainstorming β†’ Team agrees on a plan that has already survived interrogation β†’ Build. This hardens the plan before anyone commits to it, so agreements are already stress-tested.
    • Either way, grill-me turns the agent from a passive assistant into an interrogator: it challenges the intent, attacks assumptions, hunts for missing edge cases and forces the team to defend the business case before anything is built. Running it here is cheap β€” catching a wrong assumption during Elaboration costs minutes, while catching it in Construction or Production costs a full rework cycle. Source: grill-me skill; AI Hero, /grill-me.
  • Adversarial spec review:
    • An isolated subagent challenges the specs against defined categories. The kabaka/ai-dlc adversarial-reviewer community implementation probes for:
      • faithfulness defects (claims that misstate behaviour)
      • triggering/routing failures (descriptions that won’t fire)
      • cross-platform breakage (guidance that silently breaks other tools)
      • hidden incompleteness (stubs, placeholders, fabricated “green” results)
      • design fragility (loops that thrash, ambiguous ownership, scope creep).
    • The asdlc.io adversarial code review pattern checks spec violations, security issues, edge cases and anti-patterns. High-confidence mechanical fixes apply automatically; everything else goes back to the team. The AI-DLC 2026 implementation formalises both halves: the adversarial spec review interrogates specs during Inception and the adversarial workflow β€” the red-team hat tries to break the implementation while the blue-team hat hardens it β€” repeats the exercise against code during Construction.
  • Tool compatibility: The principle is fresh eyes β€” a different model or clean session reviews the output, not the same model that generated it. Claude Code can spawn new subagents (strongest form). Cursor, Copilot and VS Code cannot spawn subagents, but you can open a new chat window for the critic or use a different model (GPT vs Claude). Any tool can run adversarial review as a CI/CD gate in GitHub Actions, which is the most portable approach. The asdlc.io pattern notes this is currently manual β€” “as of December 2025, this requires manual orchestration” β€” but CI/CD integration and IDE integration are on the automation roadmap. Source: asdlc.io (“Not Automated (Yet)”); cross-model adversarial review (fresh eyes principle).
  • Knowledge bootstrap: Brownfield intents begin with a knowledge bootstrap phase that synthesises the existing codebase into knowledge artifacts complete with confidence scores; greenfield intents seed empty scaffolds.
  • Greenfield gap: Before Mob Elaboration there is nothing between the Intent and the Units. The decomposition only exists after the AI asks questions and the team validates. In traditional agile you would write the Epic first with full scope, then decompose. In AI-DLC the Intent is deliberately vague β€” the AI is supposed to discover the scope through questions.
  • AI question bias risk: The AI’s training corpus is its mental set (Einstellung effect). In Mob Elaboration the AI’s questions frame the solution space. If those questions are biased toward familiar patterns, the answers will be too. The methodology relies on context engineering (loading domain-specific knowledge into the window) and human oversight (the team validates or corrects) to counter this. For greenfield projects this risk is highest: no existing codebase, no Knowledge Artifacts, nothing domain-specific to ground the AI’s questions. The human-in-the-loop defence only works if the humans can see what the AI cannot.
Mob Construction
  • Traditional Equivalent: Development
  • Definition: AI proposes architecture, domain models, code solutions and tests while the team clarifies decisions in real time. Multiple units run in parallel through Mob Execution, with teams exchanging integration specifications at human checkpoints.
  • What Changed: Traditional development is individuals writing code against specifications. Mob Construction is the AI proposing architecture, code and tests while the team clarifies decisions as they emerge.
  • Domain relationship: Construction does not invent the domain model β€” it realizes it. The domain design (bounded contexts, ubiquitous language, entities, interfaces) is produced and validated during Mob Elaboration and stored at <record>/inception/domain-design/, which every Construction design stage reads as an input (see Mob Elaboration). A Unit is itself domain-grained: the method definition calls Units “analogous to Subdomains in DDD or Epics in Scrum”, and the community paper says “Units are analogous to Bounded Contexts in DDD or Epics in Scrum” (see Unit). Construction is therefore domain-aware but per-unit in execution β€” the domain boundaries are set in advance during Inception and Construction fills them in.
  • Key activities:
    • AI proposes architecture and technical design. Design techniques are tools, not requirements: DDD, TDD and BDD are applied when domain complexity warrants them and skipped when verification can validate correctness faster β€” the test suite, not the architecture document, becomes the source of truth
    • AI implements code and supporting artifacts, unit by unit
    • AI generates tests and validation checks
    • Multiple units run in parallel through Mob Execution: collocated teams each own a unit, exchange integration specifications (API contracts, event schemas) and coordinate cross-unit concerns at human checkpoints while autonomous bolts execute concurrently
    • The team reviews trade-offs and higher-risk decisions
    • Quality gates provide backpressure when output fails
  • Roles: AI collapses the designer-to-developer handoff β€” the artifact is the design β€” so every discipline builds through the same loop: designers steer with aesthetic judgment, engineers with architectural pattern knowledge and PMs with business context. Experience acts as a multiplier; high-quality output still requires seasoned operators, whether reviewing directly or guiding mob execution.
  • Construction stages: Per-unit design stages (conditional) β†’ Code Generation Planning β†’ Code Generation β†’ Build and Test (unit, integration, performance, security, contract and end-to-end tests). See Stage reference.
  • Verification gate (Construction β†’ Operation): The official AWS implementation runs a boundary gate before Construction completes that checks architecture-to-code-to-tests alignment, that all code traces to design, and that test coverage meets acceptance criteria. This is separate from per-Bolt gates β€” it validates the integrated codebase, not individual units. Source: aidlc-workflows construction stages.
  • How accuracy is ensured: Quality gates provide backpressure β€” the harness blocks progress until all gates pass (cross-reference the Quality Gates and Completion Criteria section for full detail). Gates are add-only with a ratchet: unit-specific gates may be added during construction but never removed. The test suite is the source of truth. The TDD workflow writes failing tests before implementation, and a BDD-style custom workflow extends that to acceptance tests written before implementation. The adversarial workflow repeats the red-team/blue-team exercise against code during Construction (see Adversarial spec review for the companion Elaboration half).
  • How success is measured: Accuracy is tracked through requirements precision, design stability and code acceptance rate. Measure the complete development lifecycle including rework and revision cycles, not just how fast AI generates initial artifacts. Use end-to-end metrics β€” time from idea inception to launch β€” and track defect escape rate and failed-deployment rate alongside velocity. Source: community measurement guide; Raja SP, re:Invent 2025 DVT214 (end-to-end metrics).
  • How to learn from mistakes: The community implementation adds a Reflection phase after Execution, where outcomes feed back so failures are not repeated. Persistent memory stores what was tried and what worked (cross-reference Persistent Context for the memory layers). Passes have backward flow β€” a later pass discovering a constraint sends work back without declaring failure. In the financial-services narrative, monitoring feeds back into the coding agent’s context and informs future Inception cycles, creating a virtuous loop.
  • Standards caveat: There is no single canonical verification standard for AI-DLC. AWS provides workflow-level gates (per-Bolt gates, the Construction β†’ Operation verification gate). The community contributes backpressure, Reflection and memory patterns. These are methods and defaults, not formal standards β€” teams must define the measurable success criteria for their own domain. Source: AWS blog; Bushido Collective 2026 paper. How the community mechanisms are actually done:
    • Backpressure is harness-enforced quality gates, not “please run the tests”. A stop hook injects context on every Stop event and the agent cannot advance, hand off or declare work complete until all gates pass. Gates are frontmatter-driven β€” the discovery skill inspects repo tooling (package.json, go.mod, pyproject.toml, Cargo.toml) and proposes gate commands (tests, lint, types) the team confirms. Enforcement is scoped: only building hats (builder, implementer, refactorer) are gate-enforced while planner, reviewer and designer hats skip silently, and a stop_hook_active flag lets an already-blocked subagent stop on its second attempt to avoid deadlock in nested scenarios. Full detail in the Quality Gates and Completion Criteria section.
    • Reflection is an explicit user-invoked phase (/ai-dlc:reflect) run after Execution and Operation complete, which analyzes the finished cycle and captures learnings. Those learnings are written to the ephemeral scratchpad (.ai-dlc/{slug}/state/scratchpad.md) and documented blockers to blockers.md, so they feed the next cycle’s context rather than being lost across /clear. Backward-flow passes reinforce this: a later pass that discovers a new constraint sends work back to earlier phases instead of declaring failure, and in the financial-services narrative monitoring feeds back into future Inception cycles, creating a virtuous loop.
    • Memory (“artifacts are memory”): intent, unit progress and decisions persist as committed artifacts in .ai-dlc/ (intent.md, unit-*.md, discovery.md) so the context window can be reset without losing ground truth, while ephemeral state (.ai-dlc/{slug}/state/ β€” iteration.json, scratchpad.md, blockers.md) tracks the current hat and learnings only within a session. On top of this sit the five memory-provider layers (Rules, Session, Project, Organisational, Runtime β€” see Persistent Context) and the project knowledge layer (.ai-dlc/knowledge/) persisting design, architecture, product, conventions and domain artifacts across intents.
Completion Criteria
  • Traditional Equivalent: Definition of Done
  • Definition: Verifiable conditions that determine whether a unit is complete β€” precise enough that an autonomous agent can iterate toward them without hand-holding.
  • What Changed: DoD is a shared checklist. Completion Criteria are precise, verifiable conditions per Unit β€” the difference between “code is reviewed” and “users can reset passwords, reset tokens expire after 15 minutes, all auth endpoints have tests and the security scan has no critical findings.” Precision enables autonomy.
  • Forward-looking idea β€” evidence-backed completion verification (proposed, not yet a standard): Today completion criteria are checked by automated gates (tests, lint, types) plus the reviewer hat. A further step is to make the gate itself produce a human-reviewable proof document rather than a bare pass/fail:
    • Extract a structured document from the code via code β†’ AST β†’ documentation, generated against a fixed markdown template.
    • Compare the filled template against the knowledge base produced in the Inception/Elaboration phase (domain design, requirements, unit criteria β€” the Knowledge Artifacts).
    • Score each criterion against a rubric to measure how much of it the implementation actually satisfies, and derive a confidence level from a weightage across criteria.
    • Output a document for manual approval carrying per-criterion scores, justification and proof (line-level references, tests, trailer links), so a human reviews evidence rather than trusting a pass/fail and the gate’s verdict is inspectable and auditable rather than a black box.

The appeal is that it keeps the checkpoint meaningful β€” the gate produces an audit trail instead of an opaque binary, aligning with the auditable checkpoints pattern for regulated domains. It is a proposal for how Completion Criteria could evolve, not a documented AI-DLC mechanism.

Hat
  • Traditional Equivalent: Role
  • Definition: A markdown definition of an agent’s behaviour, boundaries and quality gates in the community implementation. Each Hat defines the role’s required steps, completion signal and what it can and cannot do. Built-in hats include Planner, Builder, Reviewer, Designer, Test Writer, Implementer, Refactorer, Red Team, Blue Team, Observer, Hypothesizer, Experimenter and Analyst.
  • What Changed: A Role is a job title and responsibilities. A Hat is executable, not aspirational β€” the agent follows the Hat’s instructions exactly.
  • Two levels: base hats and personas. The built-in hats are functional primitives (what work gets done). Teams compose them into personas that model company roles (Product Owner, Business Analyst, Solution Architect, Developer, SRE, Chapter Lead) as layers bundling the hats the role orchestrates, the phases and decisions it owns and the gates it must satisfy. See Company Roles as Personas.
Company Roles as Personas

The built-in hats are functional primitives β€” Planner, Builder, Reviewer, Test Writer, Red Team, Blue Team, Observer and the rest describe what work gets done, not who owns it. A team can compose those primitives into its own personas: a company role modelled as a named layer that bundles the hats the role would orchestrate, the phases and decisions it owns, and the quality gates it must satisfy. Personas are a conceptual reorganisation of the real, documented customization mechanism (project hats and workflows) β€” a forward-looking framing rather than a separate standard.

The mental model is two levels:

Persona (company role β€” who owns it)         e.g. Developer
└── Bundled base hats (what gets done)       Planner β†’ Builder β†’ Test Writer β†’ Implementer β†’ Refactorer β†’ Reviewer
    └── Owned phases / decision rights       Construction: trade-off choices within a unit
    └── Quality gates it must satisfy        unit tests pass, lint/types clean, coverage floor, completion criteria met

The tree below expands each persona into the hats and agents it uses, showing how the reusable base hats are composed per role:

AI-DLC Personas
β”œβ”€β”€ PRODUCT OWNER
β”‚   β”œβ”€β”€ hats:   red-team, blue-team, grill-me review
β”‚   β”œβ”€β”€ owns:   intent, success criteria, sign-off
β”‚   └── gates:  requirements approval, release approval
β”‚       └── uses agent: product-agent (requirements objection)
β”œβ”€β”€ BUSINESS ANALYST
β”‚   β”œβ”€β”€ hats:   planner, reviewer
β”‚   β”œβ”€β”€ owns:   requirements elicitation, domain modelling
β”‚   └── uses agents: product-agent, compliance-agent (rules check)
β”œβ”€β”€ SOLUTION ARCHITECT
β”‚   β”œβ”€β”€ hats:   designer, reviewer (architect lean)
β”‚   β”œβ”€β”€ owns:   design gates, ADRs, trade-offs
β”‚   └── gates:  design review vs NFRs + domain knowledge
β”‚       └── uses agent: architect-agent
β”œβ”€β”€ DEVELOPER
β”‚   β”œβ”€β”€ hats:   planner, builder, test-writer, implementer, refactorer, reviewer
β”‚   β”œβ”€β”€ owns:   construction β€” per-unit code and tests
β”‚   └── gates:  unit completion criteria, coverage floor, lint/types
β”‚       └── uses agent: developer-agent
β”œβ”€β”€ TESTER / SDET
β”‚   β”œβ”€β”€ hats:   test-writer, reviewer, red-team
β”‚   β”œβ”€β”€ owns:   test strategy, traceable test evidence
β”‚   └── gates:  coverage floor, acceptance tests pass
β”‚       └── uses agent: quality-agent
β”œβ”€β”€ SRE
β”‚   β”œβ”€β”€ hats:   observer + scheduled/reactive operations
β”‚   β”œβ”€β”€ owns:   operations, rollback, SLOs
β”‚   └── gates:  runbooks, rollback readiness, SLO conformance
β”‚       └── uses agent: operations-agent, pipeline-deploy-agent
β”œβ”€β”€ LEAD ENGINEER
β”‚   β”œβ”€β”€ hats:   reviewer, refactorer, architect lean
β”‚   β”œβ”€β”€ owns:   technical quality, cross-unit concerns, mentoring
β”‚   └── gates:  design review, code review on higher-risk decisions
β”œβ”€β”€ CHAPTER LEAD
β”‚   β”œβ”€β”€ hats:   observer, reviewer (standards conformance)
β”‚   β”œβ”€β”€ owns:   method (memory/ + knowledge layers), people growth
β”‚   └── gates:  standards conformance
└── COMPLIANCE / SECURITY (AppSec, GRC, DPO)
    β”œβ”€β”€ hats:   reviewer (security/compliance lean)
    β”œβ”€β”€ owns:   security and compliance gates
    └── gates:  auditable checkpoints, automated compliance gates
        └── uses agent: compliance-agent, devsecops-agent

The composer principle holds throughout: each persona is a thin layer over a handful of reusable base hats and agent types, not a bespoke agent per title. Note the provenance of each column: the hats are the community implementation’s built-ins (Bushido Collective plugin, see Hat); the agents are the AWS official aidlc-workflows agent catalogue (Product, Architect, Developer, Quality, Operations, Pipeline & Deploy, Compliance, DevSecOps β€” see AI-DLC Key Sources); and the personas, ownership and gates are the forward-looking composition proposed here, not a single industry standard.

Developer β€” the execution persona. Bundles Planner, Builder, Test Writer, Implementer, Refactorer and Reviewer. Owns Construction: it proposes and writes code and tests, resolves trade-offs within the boundaries of a unit, and must satisfy the unit’s completion criteria before its gate passes. The writer hats are gate-enforced by the harness; the reviewer hat verifies the diff and criteria.

Product Owner β€” the intent-owning persona. Owns the requirement and success side rather than the build: it writes user stories and acceptance criteria with AI assistance, owns the Intent’s success criteria and completion sign-off, and uses the adversarial red-team/blue-team or grill-me review to interrogate whether the plan is right before anything is built. It is the decision maker at requirements sign-off and release approval checkpoints.

Solution Architect β€” the design-owning persona. Owns the design gates: it bundles the Designer hat plus the architect lean (ADR authoring, trade-off analysis) and reviews each design stage against the domain knowledge base and non-functional requirements. It is where architecture-level decisions are surfaced and approved, sitting between Inception’s domain design and Construction’s realisation.

Site Reliability Engineer (SRE) β€” the operations-owning persona. Owns Operations and the production loop: it bundles the Observer hat for monitoring, owns scheduled and reactive operations (rollback on error-rate spikes, secret rotation, runbook readiness) and monitors the feedback loop that feeds production behaviour back into future Inception cycles. Its gates check SLOs, runbooks and rollback readiness placed in the Deployment Unit.

Chapter Lead β€” the people-and-method-owning persona, distinct from delivery personas. It does not produce units; it owns people growth, guild standards and the shared method (the memory/ and knowledge layers). It bundles Observer and Reviewer hats for standards conformance and owns how the team works and what it knows, rather than owning specific code.

The personas in this post map onto the fintech personas post, which covers the full roster β€” including Business Analyst, SME, Product Manager, UX Designer, Data Engineer, Tech Lead, Test Automation Engineer, Release Manager, AppSec Engineer, Support Engineer, Enterprise Architect and Cloud Engineer β€” and maps each to lifecycle phases and operating modes.

PersonaBundled base hatsOwnsGate it must satisfy
DeveloperPlanner, Builder, Test Writer, Implementer, Refactorer, ReviewerConstruction: per-unit code and testsUnit completion criteria, coverage floor, lint/types
Product OwnerRed Team, Blue Team, grill-meIntent, success criteria, sign-offRequirements and release approval
Solution ArchitectDesigner, Reviewer (architect lean)Design gates, ADRs, trade-offsDesign review against NFRs and domain knowledge
SREObserver + scheduled/reactive operationsOperations, rollback, SLOsRunbooks, rollback readiness, SLO conformance
Chapter LeadObserver, Reviewer (standards)Method, people growth, knowledge layerStandards conformance

The role names are not a one-to-one mapping to hats. A persona can combine hats according to the decisions and outcomes it owns, and a single person may work through different hats in different parts of a Unit. This gives a practical way to describe how familiar delivery roles can evolve:

Previous role groupingEvolving responsibility
Product Owner / PM / Business Analyst / Scrum master / SMEIntent owner. Defines the outcome and success criteria, then validates the AI’s discovery rather than owning a pre-decomposed Epic. Planner, Reviewer and Red / Blue hats may apply.
UX / Product Designer / SMEDesigner across Inception and Construction. Shapes requirements and per-Unit design, then guides implementation with user and aesthetic judgment. Designer, Builder and Reviewer hats may apply.
Scrum Master / Delivery ManagerWorkflow composer. Chooses which conditional stages apply and helps select each Unit’s operating mode instead of relying on a fixed ceremony cadence. Planner, Integrator and Reviewer hats may apply.
Solutions / Technical ArchitectDesigner and curator. Owns domain models and architecture boundaries that Construction realizes. Planner, Designer, Builder, Reviewer and Integrator hats may apply.
Engineering Leader / DevSecOps EngineerAdversarial reviewer and gate curator. Challenges designs and implementations, keeps attack and remediation perspectives distinct and maintains quality gates. Builder, Reviewer and Red / Blue hats may apply.
DeveloperBuilder. Implements the agreed plan in small steps, writes tests and iterates against gate feedback. Planner, Builder and Reviewer hats may apply.
QA / TesterGate curator. Defines precise completion criteria and maintains evidence-backed quality gates. Builder, Reviewer and Red / Blue hats may apply.
Pipeline / Deployment EngineerDeployment automation owner. Builds release orchestration, rollback and bounded agent-run operations. Builder, Integrator and Reviewer hats may apply.
SRE / Operations EngineerObservability steward. Owns monitoring, runbooks, SLOs and operational feedback into future Inception cycles. Builder, Reviewer and Integrator hats may apply.

These are possible responsibility shifts, not prescribed job titles. The hats remain reusable work modes; teams decide how to combine them based on their domain, governance and risk.

The necessary caution is the 19-agent trap already noted above: personas are compositions of a few hats inside a single bolt loop, not a licence to scaffold one full agent per job title. Complex swarms consistently underperform simple loops with rich relevant context, so the persona framing succeeds when it bundles review and oversight hats around one build loop rather than spawning a dedicated agent per role.

Named Workflow
  • Traditional Equivalent: Prescribed process
  • Definition: An ordered hat sequence that gives a Bolt its internal rhythm. The community plugin ships five built-ins β€” default, adversarial, design, hypothesis and tdd β€” and teams can define custom workflows following the same mechanism.
  • What Changed: A process lives in documentation. A Named Workflow is an ordered hat sequence (planner β†’ builder β†’ reviewer) that the Bolt executes automatically. The process runs, not just exists.
Operation
  • Traditional Equivalent: Runbook task
  • Definition: File-based operational spec declaring type (scheduled, reactive or process), owner, trigger and runtime. Each intent ships a Deployment Unit bundling code, configuration, infrastructure definitions and validation suites.
  • What Changed: A runbook is human-written instructions. An Operation is a file-based spec the agent can execute autonomously within boundaries, not just follow.
Knowledge Artifact
  • Traditional Equivalent: Documentation
  • Definition: Structured institutional memory in the project knowledge layer: design (visual language, component patterns), architecture (module boundaries, data flow), product (business rules, personas), conventions (coding standards) and domain (entities, bounded contexts). Brownfield synthesis populates them automatically with confidence scores.
  • What Changed: Documentation is scattered across wikis and tickets. Knowledge Artifacts are structured, persistent memory the agent reads every session instead of searching for them.
Completion Announcement
  • Traditional Equivalent: Release communications
  • Definition: Communication artifacts generated on Intent completion: changelog, release notes, social posts or blog draft. An intent declares its announcement channels in frontmatter and the completed artifacts generate the outputs automatically.
  • What Changed: Release notes are written manually after deployment. Completion Announcements are produced from the same artifacts that declared the work done β€” closing the gap between code-complete and users knowing about it.
Workflow and Implementation Terms

These terms describe how AI-DLC works in practice rather than what things are called.

Rules files

Markdown configuration committed to the repository and auto-loaded into every agent session. In the AI-DLC implementation they carry the process logic β€” the full operating manual the agent reads before doing anything. Concretely, that “process logic” decomposes into three things:

  • Stage library β€” the catalog of every stage the workflow knows about: workspace detection, reverse engineering, requirements analysis, user stories, application design, units of work planning, code generation planning, code generation, build and test, deployment and so on. Each entry describes what the stage does, when it makes sense and what it must produce. The library tells the agent what building blocks exist.
  • Heuristics for deciding which stages apply β€” the rules of thumb that make the workflow adaptive rather than linear. Not every task runs every stage; the agent assesses the request’s complexity and shape, then selects which stages to execute. This is the mandatory-versus-conditional split: a one-line bug fix should skip planning and go straight to code generation, while a complex feature should run requirements analysis and architectural design. The heuristics encode that judgment (see Mandatory (green) stages and Conditional (yellow) stages).
  • Checkpoint instructions β€” the rules governing human approval gates between stages: when the agent must pause, present its plan plus clarifying questions and wait for explicit sign-off before advancing (see Checkpoints).

A simplified rules file might read:

# Project Workflow Rules

## Stage Library

The workflow consists of: Discovery, Requirements, Design, Code, Build,
Deploy. See the stage details in aidlc-rule-details/.

## Which Stages Apply

- Execute required: Discovery -> Code -> Build -> Deploy
- Design runs only if the request touches new or complex architecture
- Requirements runs only if the request is not already fully specified

## Checkpoints

- After every stage, present the plan and ask before proceeding
- Do not advance until the user explicitly confirms

The actual core-workflow.md in the AWS release is this same idea written out in full prose (~25 KB) β€” the whole state machine the agent follows. See below for the file layout.

How Rules relate to spec-driven development. They operate at different layers, so they complement rather than compete. Rules and Steering files are the process layer β€” they describe how work happens, apply project-wide, and are written once and committed. They are abstract in the sense that they mention no specific feature. Spec-driven development (see The Pillars of AI-Assisted Development) is the per-Intent content layer β€” each Intent gets its own concrete specification (requirements, units, completion criteria, domain design) that becomes the source of truth for that feature’s implementation, tests and documentation. The layering:

Rules / Steering files   HOW work happens β€” process, all work, once
        β”‚ (consulted every session)
        β–Ό
Spec (per Intent)        WHAT this feature is β€” produced in Inception,
                         source of truth for this feature's build
        β”‚
        β–Ό
Implementation / Tests   derived from the spec

Rules say “how will the team and agent work?”; specs say “what is this feature and when is it done?”. Every feature’s spec is created using the rules β€” the rules decide which stages run (including whether requirements analysis runs at all), and the spec that results is what Construction consumes. Rule files never reference a feature; specs never define the process.

Steering files

The Kiro equivalent of Rules: persistent markdown context (product overview, repo structure, tech conventions) loaded into every session so the agent steers by project knowledge rather than per-prompt instructions. Where a Rules file describes the process, a Steering file describes the project β€” the standing facts and conventions the agent should know without being told each session. A simplified example:

# Project Steering

## Product Overview

Fintech payments orchestration platform. Core value: routing payments
across PSPs with retry and reconciliation.

## Repo Structure

- /api β€” REST services (Node/TypeScript, Fastify)
- /web β€” admin dashboard (React)
- /shared β€” shared types and libraries

## Conventions

- Money values are integer cents, never floats
- Every money mutation is wrapped in a transaction and audit-logged
- Secrets come from the vault, never from env vars committed to git

The distinction from skills matters: instructions (Rules and Steering) are always-in-context declarative knowledge (“know this, obey this”), while skills are lazy-loaded procedural packages invoked when a task matches (“when doing X, follow these steps”). AI-DLC deliberately chose the former so the process transfers across tools and models unchanged.

Mandatory (green) stages

Stages that always run regardless of task size: workspace detection, requirements analysis or reverse engineering, workflow planning, code generation planning, code generation and build/test.

Conditional (yellow) stages

Stages that run only when complexity assessment justifies them: user stories, application design, per-unit design. A bug fix skips them; a new feature runs them.

Checkpoints

Human approval gates between stages: the agent pauses, presents its plan plus clarifying questions and waits for explicit sign-off before advancing.

Audit trails

End-to-end traceability: every artifact, decision, approval and conversation logged as it happens, producing an inspectable record for accountability and compliance.

HITL (human-in-the-loop)

Supervised mode: the human approves before each significant step.

OHOTL (observed human-on-the-loop)

Observed mode: AI works continuously while a human watches in real time and can interrupt at any moment.

AHOTL (autonomous human-on-the-loop)

Autonomous mode: AI iterates within quality gates until done and the human reviews at completion.

On disk, these rule files take the specific forms described in the Appendix: Directory Structure and Layout, including the aidlc-rules/ folder tree, where each tool installs them, and the two concrete rule-file formats in use today (the AI-DLC extension convention and the path-scoped convention). The key point is that they are resident markdown instructions rather than executable skills β€” no scripts, no trigger-on-match loading, just standing orders the agent reads every session. AI-DLC deliberately chose this declarative form so the process transfers across tools and models unchanged.

The 2026 paper is equally explicit about its intellectual inputs:

ContributorIdeaRelevance to AI-DLC
Geoffrey Huntley, Ralph Wiggum technique (“deterministically bad in an undeterministic world”)The try-fail-iterate autonomous loop β€” let the agent attempt work freely, accept that early attempts will be wrong and iterate until the quality gates passUnderpins the Bolt execution model: the agent runs autonomously within a loop, failing fast and adjusting rather than requiring a perfect plan upfront
Anthropic, Building Effective AgentsHarness design for long-running agents β€” structured orchestration with tool calling, memory and verification boundariesProvides the runtime architecture: rules files, checkpoints and quality gates that keep the agent within bounds during extended Construction and Operations phases
Steve Wilson (OWASP)Human-on-the-loop governance β€” the human observes and interrupts rather than approving every stepShapes the HITL/OHOTL/AHOTL operating mode taxonomy: the human’s role shifts from approving each action to defining outcomes, setting gates and intervening when needed
paddo.devSDLC-collapse analysis and the 19-agent trap β€” sequential phases dissolve when iteration is cheap; one agent per job title loses context at every handoffDrives the core claim that phases compress into continuous flow with checkpoints, and argues against multi-agent org-chart mirroring in favour of simpler loops with rich context
HumanLayer, 12 Factor AgentsContext engineering guidance β€” how to scope, load and manage what an agent seesInforms the persistent context model: five memory layers (rules, session, project, organisational, runtime) that keep the agent grounded across Bolts without starting from scratch

Why It Exists: The Middle Path

The AWS post argues that most organisations use AI in two limited ways:

  • AI-assisted development β€” AI improves specific tasks such as documentation, code completion and testing.
  • AI-managed development β€” AI is expected to generate whole applications from user requirements with little human involvement.

AWS reports that both patterns produce suboptimal outcomes in velocity and quality. AI-DLC is the proposed middle path: AI performs the heavy execution work while humans supply business context, judgment, validation and accountability. In the financial-services version of the story, the developer’s role shifts from writing code to managing and validating AI-generated outputs. The 2026 community paper frames the same idea with a Google Maps analogy: humans set the destination, AI provides step-by-step directions and humans maintain oversight.

Reimagine Rather Than Retrofit: The Collapsing SDLC

The 2026 paper goes further than the AWS framing: its foundational claim is that sequential phases are not being accelerated but dissolved. Phase boundaries existed because iteration was expensive β€” handoffs between specialised roles, documents to transfer context and approval gates made economic sense when rework took weeks. With AI driving iteration cost toward zero, context loss at handoffs becomes the dominant cost, so the phases collapse into continuous flow punctuated by checkpoints.

Handoff (traditional SDLC)Checkpoint (AI-DLC 2026)
Work stops completelyWork pauses briefly
Context transfers to another partySame agent continues with feedback
Documents carry knowledgeFiles and git carry knowledge
Approval required to proceedReview identifies needed adjustments

Rituals calibrated to slow cadences lose their rationale: story-point estimation blurs when AI flattens simple and complex tasks, velocity measures activity rather than value and upfront design becomes a tax when try-fail-adjust cycles take seconds. Backward flow also becomes normal rather than exceptional β€” a later pass discovering a constraint that invalidates an earlier assumption sends work back without anyone declaring failure. The paper’s slogan for this first-principles rethink: we need automobiles, not faster horse chariots.

The Three Phases

The AWS version describes three phases. The 2026 community paper keeps 3 phases:

Inception β€” WHAT to build and WHY. AI transforms business intent into requirements, user stories, units, risks, non-functional requirements and completion criteria. The central ritual is Mob Elaboration - See Core Terminology: Mob Elaboration for the full workflow, including grill-me integration, adversarial spec review and knowledge bootstrap. In short: AI asks clarifying questions, the team validates or corrects the result, and adversarial skills challenge assumptions before anything is built. This phase also produces the domain design β€” bounded contexts, ubiquitous language, entities, interfaces β€” that Construction later consumes and realizes (see Core Terminology: Mob Construction).

Construction β€” HOW to build it. Using the validated context from Inception, AI proposes architecture, domain models, code solutions and tests. In the 2025 AWS framing this is Mob Construction; in the 2026 community paper it is Execution through Bolts.

  • See Core Terminology: Mob Construction for the full set of activities, stages, verification gates, accuracy mechanisms, measurement and learning-from-mistakes. In short: AI proposes and builds, the team reviews trade-offs and higher-risk decisions, and quality gates provide backpressure when output fails.

Operations β€” run and maintain it. AI applies the accumulated context to deployment, infrastructure as code, monitoring, rollback and ongoing maintenance. Operational work itself becomes file-based: each operation lives as a spec in .ai-dlc/{intent}/operations/, typed as scheduled (cron-driven tasks such as secret rotation or cache warming), reactive (trigger-driven responses such as rollback on error-rate spikes) or process (human-cadence routines such as quarterly security reviews), with an ownership model of agent-owned scripts executing autonomously within boundaries or human-owned checklists tracked by the agent. Each intent ships a Deployment Unit bundling code artifacts, configuration, infrastructure definitions and validation suites with automated rollback procedures. The important point is continuity: plans, requirements, design artifacts and operational knowledge are stored in the repository so later sessions do not start from scratch β€” and when an intent completes, configured completion announcements generate changelog entries, release notes, social posts or blog drafts from the same artifacts, closing the gap between code-complete and users knowing about it. In the financial-services narrative, monitoring feeds back into the coding agent’s context and informs future Inception cycles, creating a virtuous loop.

**How AI-DLC maps onto the SDLC.

    flowchart TD
	    subgraph SDLC[Classic SDLC Phases]
	        S1[Discovery] --> S2[Requirements]
	        S2 --> S3[Architecture]
	        S3 --> S4[Development]
	        S4 --> S5[Testing]
	        S5 --> S6[CI/CD and Release]
	        S6 --> S7[Production]
	        S7 --> S8[Maintenance]
	    end
	
	    subgraph AIDLC[AI-DLC Phases]
	        I[Inception<br>Mob Elaboration]
	        C[Construction<br>Mob Construction]
	        O[Operations]
	    end
	
	    S1 -.-> I
	    S2 -.-> I
	    S3 -.-> C
	    S4 -.-> C
	    S5 -.-> C
	    S6 -.-> O
	    S7 -.-> O
	    S8 -.-> O

So the two diagrams are complementary: the classic SDLC Flow shows the phases a product goes through, and this one shows which AI-DLC phase this post proposes absorbs the work of each SDLC phase.

The Adaptive Workflow

The official open-source implementation turns the three phases into an adaptive workflow with stages. Some stages are mandatory (green) and some are conditional (yellow); the workflow chooses which to run based on context and complexity. A simple bug fix skips planning and goes straight to code generation; a complex feature runs requirements analysis, architectural design and detailed testing.

PhaseStages (mandatory or conditional)
InceptionWorkspace Detection (greenfield vs brownfield) β†’ Reverse Engineering (brownfield) or Requirements Analysis (greenfield) β†’ Workflow Planning. Conditional: User Stories, Application Design, Units of Work Planning
ConstructionPer-unit design stages (conditional) β†’ Code Generation Planning β†’ Code Generation β†’ Build and Test (unit, integration, performance, security, contract and end-to-end tests) β€” full detail in Core Terminology: Mob Construction
OperationsDeployment automation, infrastructure as code, monitoring and observability setup, production readiness validation

The AWS open-sourcing blog identifies three properties that make this work:

  1. Adaptive decisioning β€” the workflow conforms to the problem’s shape, intelligently skipping or deepening stages based on contextual assessment rather than predetermined rules.
  2. Transparent checkpoints β€” human approvals are embedded at every decision gate, preserving oversight while maintaining velocity.
  3. End-to-end traceability β€” every artifact, decision and conversation is logged, creating an inspectable trail that supports accountability and improvement.

At each gate the workflow asks clarifying questions, creates an execution plan and waits for approval. The implementation uses Rules and Steering files that convert AI from a passive assistant into an adaptive decision engine.

The AI-DLC Flow

The diagram below combines the three phases, the adaptive workflow stages, the operating modes and the quality-gate loop into one picture. Dashed edges are conditional stages; the workflow only runs them when the context warrants it. Solid edges are mandatory.

Hat legend:

IconHatRolePersonas
🎩PlannerDecompose intent into units and boltsBusiness Analyst, Developer
πŸ‘’DesignerDesign lens, UX, architecture reviewSolution Architect
πŸ‘·BuilderWrite code, tests and artifactsDeveloper
πŸ•΅οΈReviewerVerify completion criteria, reviewBusiness Analyst, Solution Architect, Developer, Tester/SDET, Lead Engineer, Chapter Lead, Compliance/Security
πŸͺ–Red / BlueAdversarial security attack-defendProduct Owner, Tester/SDET
🧩IntegratorIntent-level integrationβ€”
    flowchart TD
	    A["Business Intent <sub>[🎩]</sub>"] --> B{Workspace Detection}
	
	    subgraph INC[Inception Phase β€” Mob Elaboration]
	        B -->|Greenfield| D["Requirements Analysis <sub>[🎩]</sub>"]
	        B -->|Brownfield| E["Reverse Engineering <sub>[🎩]</sub>"]
	        D --> F["Workflow Planning <sub>[🎩]</sub>"]
	        E --> F
	        F -.-> G1["User Stories <sub>[🎩]</sub>"]
	        F -.-> G2["Application Design <sub>[πŸ‘’]</sub>"]
	        F -.-> G3["Units of Work Planning <sub>[🎩]</sub>"]
	        F -.-> G4["Adversarial Spec Review <sub>[πŸͺ–]</sub>"]
	        G1 -.-> H["Units and Completion Criteria <sub>[πŸŽ©πŸ•΅οΈ]</sub>"]
	        G2 -.-> H
	        G3 -.-> H
	        G4 -.-> H
	    end
	
	    subgraph CON[Construction / Execution Phase]
	        H --> I{Operating Mode}
	        I -->|HITL| J1["Supervised Bolt <sub>[πŸ‘·]</sub>"]
	        I -->|OHOTL| J2["Observed Bolt <sub>[πŸ‘·]</sub>"]
	        I -->|AHOTL| J3["Autonomous Bolt <sub>[πŸ‘·]</sub>"]
	        J1 --> K["Per-Unit Design <sub>[πŸ‘’]</sub>"]
	        J2 --> K
	        J3 --> K
	        K --> M["Code Generation Planning <sub>[πŸŽ©πŸ‘·]</sub>"]
	        M --> N["Code Generation <sub>[πŸ‘·]</sub>"]
	        N --> O["Build and Test <sub>[πŸ‘·πŸ•΅οΈ]</sub>"]
	        O --> P{"Quality Gates <sub>[πŸ•΅οΈπŸͺ–πŸ§©]</sub>"}
	        P -->|Fail| Q["Backpressure: Feedback and Pass-Back <sub>[πŸŽ©πŸ•΅οΈ]</sub>"]
	        Q --> K
	        P -->|Pass| R["Review and Integration <sub>[πŸ•΅οΈπŸ§©πŸͺ–]</sub>"]
	    end
	
	    subgraph OPS[Operations Phase]
	        R --> S["Deploy, Monitor and Maintain"]
	        S --> T["Persistent Context and Knowledge <sub>[πŸŽ©πŸ‘’πŸ‘·πŸ•΅οΈ]</sub>"]
	    end
	
	    T --> B

Note the two feedback loops. The inner loop is construction backpressure: failed quality gates push the unit back through design, code generation and testing. The outer loop is lifecycle continuity: operations captures persistent context and knowledge, which feeds the next Inception cycle so no session starts from scratch.

Operating Modes: HITL, OHOTL and AHOTL

The 2026 community paper distinguishes three operating modes that form a spectrum of human involvement, not a maturity ladder:

ModeHuman InvolvementApproval ModelBest For
HITL (human-in-the-loop)Continuous, blockingBefore each significant stepNovel domains, architecture decisions, production data, security and compliance risk, foundational work
OHOTL (observed human-on-the-loop)Continuous, non-blockingAny time (interrupt)UX, design, copy and subjective quality work, training, medium-risk changes
AHOTL (autonomous human-on-the-loop)Periodic, on-demandAt completionWell-defined tasks with measurable acceptance criteria, batch operations, work validated by tests, types and linting

The key insight is that the human does not disappear β€” the human’s function changes, from micromanaging execution to defining outcomes, observing progress and building quality gates. A companion mode-selection skill published by the community scores the choice across measurable factors:

FactorHITLOHOTLAHOTL
Requirements clarityLowMediumHigh
Risk levelHighMediumLow
Test coverageLowMediumHigh
Domain familiarityLowMediumHigh
ReversibilityDifficultModerateEasy

Default modes per phase: Elaboration HITL, Planning HITL, Building OHOTL, Review HITL. The general rule is to start new or unknown work in HITL and escalate autonomy only as requirements stabilise, test coverage grows and trust is earned. Downgrades (AHOTL β†’ OHOTL β†’ HITL) are signals to investigate root causes, not punishments.

The paper’s own decision framework is blunter β€” pick by the shape of the work:

ScenarioModeRationale
Implement a new algorithmHITLNovel, requires judgment
Add CRUD endpointsAHOTLWell-understood pattern
Migrate a database schemaHITLHigh risk, data integrity
Build a UI componentOHOTLSubjective design quality
Update documentationAHOTLClear criteria, low risk

Its governing principle: default to more supervision when uncertain β€” loosening control later is easier than recovering from an autonomous mistake. Modes are also provisional rather than fixed: shifting work between modes mid-stream as understanding develops is a first-class feature of the methodology.

Backpressure, Quality Gates and Completion Criteria

Backpressure over prescription. Instead of prescribing every implementation step, AI-DLC defines quality gates that reject non-conforming work. The 2026 paper describes harness-enforced quality gates: structured, frontmatter-driven checks that the harness runs on every Stop event. The agent cannot stop β€” cannot advance, cannot hand off, cannot declare work complete β€” until all gates pass. This is qualitatively different from asking AI to “run the tests”: the agent cannot rationalise its way around a failing hook.

Four properties make the enforcement robust:

  • Auto-detection during elaboration β€” the discovery skill inspects repository tooling (package.json, go.mod, pyproject.toml, Cargo.toml) and proposes the right gate commands, which the team confirms before construction begins.
  • Additive merge with a ratchet β€” confirmed gates are saved to the Intent’s frontmatter and builders may add unit-specific gates during construction. Unit gates add to intent gates, never replace them, and gates are add-only thereafter: the reviewer verifies gate integrity as part of the review and removing a gate triggers a request-changes decision. Quality standards can only move forward.
  • Scoped enforcement β€” only building hats (builder, implementer, refactorer) are gate-enforced; planner, reviewer and designer hats skip enforcement silently because a failing test should not block a mid-review objective.
  • Loop prevention β€” a stop_hook_active flag lets a subagent that has already been blocked once stop on its second attempt, preventing deadlock in nested agent scenarios.

One further mechanism completes the picture:

  • Completion criteria enable autonomy β€” autonomy depends on precise criteria. “Make auth better” is too vague; “users can reset passwords, reset tokens expire after 15 minutes, all auth endpoints have tests and the security scan has no critical findings” gives the agent a target it can iterate toward.

Visual and design backpressure. The principle extends beyond code into design fidelity. Visual gates activate automatically when signals suggest they matter: the unit’s discipline is frontend or design, the spec references design artifacts or the changeset touches UI files. When active, the system resolves a reference image through a three-level priority β€” an external design-tool export such as Figma, a screenshot from the previous successful bolt or a wireframe from elaboration β€” captures the implementation through pluggable infrastructure (Playwright-based capture is the web default) and has a vision model compare the pair, producing a structured pass/warn/fail verdict with annotated differences. A failing verdict feeds back into the bolt loop exactly like a failing test. A missing reference logs a warning instead of blocking; absence of a reference is itself a signal worth surfacing.

Persistent Context: Artifacts Are Memory

AI-DLC’s answer to the context-window problem is committed artifacts and ephemeral state. Intents, unit progress and decisions persist in version-controlled files, so the context window can be reset without losing the project’s ground truth β€” the community implementation treats /clear as a feature, not a bug.

The paper generalises this into memory providers β€” five queryable layers of organisational memory an agent can draw on:

LayerLocationSpeedPurpose
RulesProject rule filesInstantConventions, patterns, constraints
SessionWorking files, scratchpadsFastCurrent task context and progress
ProjectGit history, codebaseIndexedWhat was tried and what worked
OrganisationalConnected systems via MCPQueryInstitutional knowledge: tickets, ADRs, runbooks
RuntimeMonitoring systemsQueryProduction behaviour and incidents

The filesystem stays the simplest provider but connected organisational memory dramatically expands what an agent can know β€” a debugging agent can pull incident history for similar symptoms and an architect agent can retrieve precedent ADRs.

Abundance still demands economy. Model performance degrades once the window passes roughly 40–60% utilisation β€” the “dumb zone” β€” and material buried mid-context receives less attention than whatever sits at the edges. The paper’s warning against the 19-agent trap (scaffolding one agent per job title, mirroring the org chart) makes the same point structurally: every handoff loses context and orchestration overhead consumes attention, so complex swarms consistently underperform simple loops with rich relevant context. The practical countermeasures: monitor the context budget with alerts at set thresholds, extract static reference material into companion files read on demand, inject prior-bolt learnings lazily at the point of use and scope context per role β€” the reviewer hat sees the diff and completion criteria, never the full elaboration history. This is exactly the context engineering discipline from the Context Engineering post, applied to the development process itself.

The Community Implementation: Four Phases and Hats

The Bushido Collective’s open-source plugin for Claude Code implements the methodology as four phases β€” Elaboration, Execution, Operation and Reflection β€” using git worktrees, automated tests/lint/types as quality gates, pull requests and deployment workflows. Inside each unit, the AI cycles through specialist agents, each wearing a “hat”: a markdown file that defines the role’s required steps, boundaries and quality gates (the built-in hats are listed under Core Terminology: Hat). Passes add a disciplinary lens (design, product or dev) over the standard loop, and later passes can pass work back to earlier ones when new constraints appear.

The hat list is where the “grill me” idea becomes a formal role. The Red Team hat attacks assumptions and design decisions during Elaboration and Review; the Blue Team hat defends them; the Observer hat stays detached and reports what the agents actually did. Teams can express the same idea with simpler tooling β€” a reusable grill-me skill that interrogates intent, requirements and design before the harness gates run. Either way the principle is identical to backpressure: challenge the work before it is accepted, not after.

Bolts get their internal rhythm from named workflows β€” predefined hat sequences chosen per unit in frontmatter:

WorkflowHat SequencePurpose
defaultplanner β†’ builder β†’ reviewerStandard execution cycle
adversarialplanner β†’ builder β†’ red-team β†’ blue-team β†’ reviewerSecurity-focused: break the implementation, then harden it
designplanner β†’ designer β†’ reviewerVisual and UX execution for design-discipline units
hypothesisobserver β†’ hypothesizer β†’ experimenter β†’ analystScientific debugging and investigation
tddtest-writer β†’ implementer β†’ refactorer β†’ reviewerTest-driven development with explicit red-green-refactor phases

These five are the plugin’s built-ins, per the README. Teams often add others as custom workflows β€” for example a bdd workflow (planner β†’ acceptance-test-writer β†’ builder β†’ reviewer) that writes acceptance tests before implementation, using a custom acceptance-test-writer hat defined in .ai-dlc/hats/.

Custom workflows follow the same mechanism: ordered hats, each with its own instructions and completion signal, executed inside the bolt loop.

Three further pieces of the community implementation matter for adopting teams:

  • Lifecycle entry points β€” elaborate starts a fresh intent, follow up iterates on a completed intent linked through iterates_on and adopt reverse-engineers a feature built outside AI-DLC into completed intent artifacts with traceable test evidence. Adopt is the primary on-ramp for bringing brownfield estates under governance without pretending to rebuild history.
  • Project knowledge layer β€” .ai-dlc/knowledge/ persists five artifact types across intents: design (visual language, component patterns), architecture (module boundaries, data flow, technology choices), product (business rules, personas, domain vocabulary), conventions (coding standards, tooling config) and domain (entities, bounded contexts, ubiquitous language). Brownfield synthesis populates them automatically with confidence scores; greenfield projects scaffold them empty and seed them through the design-direction step.
  • Completion announcements β€” an intent declares its announcement channels in frontmatter and the completed artifacts generate changelog entries, release notes, social posts or blog drafts.

Two evolution notes: the HITL/OHOTL/AHOTL taxonomy is already being superseded inside the community’s broader HΒ·AIΒ·KΒ·U framework by five operating modes and a “stages” model that replaces Passes. Treat these community constructs as fast-moving rather than settled.

Adoption and Getting Started

The AWS financial-services blog recommends a three-phase adoption path:

  1. Executive alignment β€” confirm the leadership understands how AI-DLC differs from Agile and tie adoption to measurable business outcomes.
  2. Technical enablement β€” build deep knowledge of agentic coding tools (such as Amazon Q Developer, Kiro or Claude Code) and best practices.
  3. Hands-on pilots β€” run immersive two-to-three-day pilot sprints on real codebases to generate proof points and momentum.

The methodology is deliberately tool and platform agnostic β€” the state-persistence, backpressure and oversight patterns transfer across Claude Code, Cursor, Kiro, OpenCode or a custom harness. For a tool-agnostic start: pick one low-risk feature, write an Intent with explicit completion criteria, decompose it into one or two Units, choose a mode deliberately, store decisions and outcomes in the repo and add quality gates before increasing autonomy.

Measuring AI-DLC Effectiveness

The paper trades activity metrics (lines of code, story points) for four outcome metrics:

MetricWhat It Measures
Cycle TimeTime from intent to production
Bolt Success RateBolts completing without human rescue
Churn RateIterations per bolt β€” high churn usually means poorly written criteria
Criteria Escape RateDefects discovered after deployment

The measurement philosophy: measure what matters to the business, not what is easy to count.

Compliance and Audit Integration

For regulated domains β€” the fintech setting this post is framed around β€” the paper prescribes two patterns. Auditable checkpoints place human audit points at requirements sign-off, design approval, code review and release approval, with autonomous work permitted between them. Automated compliance gates double as compliance verification with audit logging attached to every run. The property auditors care most about falls out of the artifact model for free: every artifact links forwards and backwards and every decision is logged, so the workflow is the audit trail rather than something assembled retrospectively. Framework mappings for SOC 2, HIPAA and PCI DSS ship in the paper’s companion compliance-audit runbook.

Limitations and Caveats

AI-DLC is useful but not complete by itself. Teams still need to define:

  • Security and compliance controls for their domain
  • Human approval boundaries for production and data access
  • Repository conventions for persistent context
  • Quality gates that actually reflect product risk
  • Evaluation metrics for productivity, defect rate, user impact and maintainability
  • Rules for when autonomous work must stop and escalate

It is also worth remembering that the fuller, more operational version of the methodology (modes, passes, quality gates) comes from an independent community project, not from AWS, so teams evaluating it for enterprise use should weigh that provenance accordingly. See the AWS framing at https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/ and the community paper at https://ai-dlc.dev/paper for additional perspectives.

AI-DLC Key Sources

SourceWhat It Contributes
AI-DLC: AI-Driven SDLCSee AWS: https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/ and the community paper at https://ai-dlc.dev/paper
Raja SP (AWS), AI-Driven Development Life Cycle: Reimagining Software EngineeringThe original methodology post, 31 July 2025
AWS, Open-Sourcing Adaptive Workflows for AI-DLCAdaptive decisioning, checkpoints and traceability, November 2025
AWS, Building with AI-DLC using Amazon Q DeveloperStage-by-stage walkthrough with conditional stages and audit trails
awslabs/aidlc-workflowsOfficial open-source reference implementation (Rules and Steering files)
The Bushido Collective, AI-DLC 2026 PaperIndependent community paper: modes, passes, quality gates, hats, January 2026
AWS, AI-Driven Development Lifecycle for Financial ServicesFintech framing and three-phase adoption path, May 2026
AI-DLC 2026 companion runbooks (via ai-dlc.dev/paper)Playbooks referenced by the paper: mode selection, autonomous bolts, incremental adoption, metrics and compliance-audit framework mappings

Appendix

Stages of AI Development Autonomy

The main text introduces the “two approaches” framing (AI-assisted versus AI-managed) as the extreme ends of a spectrum, and this appendix records the fuller picture. AI in software development is better described as a spectrum of autonomy β€” how much of the work, and which decisions, fall to the AI rather than the human β€” and several frameworks describe compatible levels within it:

    flowchart LR
	    subgraph ASSISTED[AI-assisted -- human holds the process]
	        direction LR
	        A[Autocomplete] --> B[Co-Developer]
	        B --> C[Supervised Agent]
	        C --> D[Autonomous Agent]
	    end
	
	    subgraph MANAGED[AI-managed -- AI holds the process]
	        direction LR
	        E[Full Autonomy]
	    end
	
	    D -.->|escalation| E
	
	    B -.- bd([Human reviews every change])
	    C -.- cd([Human audits logged decisions])
	    D -.- dd([Human sets policy, audits results])
	
	    classDef approved fill:#e3f2fd,stroke:#1976d2;
	    classDef independent fill:#fff3e0,stroke:#f57c00;
	    class A,B approved;
	    class C,D,E independent;

The shaded line marks the critical boundary these taxonomies draw: on the left (blue) the agent executes only with human approval; on the right (orange) it decides and executes independently and the human only audits. That is the same boundary the HITL/OHOTL/AHOTL modes draw in AI-DLC.

  • Bitloops describes a four-level continuum β€” Autocomplete β†’ Co-Developer β†’ Supervised Agent β†’ Autonomous Agent β€” where each step shifts decision-making and trust from the human toward the agent: autocomplete suggests tokens the human accepts or rejects; a co-developer implements well-specified tasks under human review; a supervised agent executes within guardrails while the human audits its logged decisions; an autonomous agent operates with minimal human gatekeeping within domain constraints (Bitloops, AI as Co-Developer vs. Autonomous Agent).
  • Several independent frameworks converge on a five- to six-level scale analogized to the SAE J3016 autonomous-driving standard (none β†’ full autonomy), including the Cloud Security Alliance’s autonomy levels for agentic AI and DeepMind’s levels of AGI (Cloud Security Alliance, Autonomy Levels for Agentic AI). The critical dividing line across these taxonomies is between an agent that executes only with human approval and an agent that decides and executes independently β€” the same boundary the HITL/OHOTL/AHOTL modes draw in AI-DLC.
  • The same CSA analysis notes that production systems today cluster at the lower approval-gated levels, and that full autonomy is widely considered unsafe for enterprise deployment (Cloud Security Alliance, Autonomy Levels for Agentic AI).
  • A concrete fixture: Antigravity (Google). Antigravity, Google’s agentic coding platform integrated with Android Studio, sits on the managed side of the spectrum. The developer states the intent in natural language; the agent plans, writes code, runs tests, fixes failures and iterates in a persistent, sandboxed thinking session before presenting a change for human review. It is not full autonomy because the human still sets the goal, approves the plan and reviews the resulting change, and Google ships it as a preview. So it is best placed at the Autonomous Agent tier β€” orange on the diagram, not the far right. Notably, Google’s own tagline calls it “AI-assisted software development,” a reminder that the assisted-versus-managed labels are contested and any single tool can cross the line (Google, Introducing Google Antigravity).

AI-DLC sits on this spectrum rather than at an extreme: AI drives the process but pauses for human sign-off at every step, and how much autonomy it gets is a deliberate choice per Unit (HITL, OHOTL or AHOTL), not a blanket decision. Source: AWS blog; Bitloops, AI as Co-Developer vs. Autonomous Agent.

Directory Structure and Layout

AI-DLC work lands on disk in three different ways depending on the implementation, and the folder names are easy to conflate. They are not the same thing:

  • aidlc/ β€” the AWS official awslabs/aidlc-workflows neutral workspace directory at the project root. Committed to git, browsable, holds everything AI-DLC produces. This is the layout to care about.
  • .aidlc/ (dot prefix) β€” the AWS harness-specific engine directory, but only on the opencode and GitHub Copilot harnesses. On other harnesses it is .claude/, .kiro/ or .codex/.
  • .ai-dlc/ (dot + dash) β€” the Bushido Collective community plugin layout for Claude Code. A different folder, a different file schema and different conventions from the AWS layout above.

Read every occurrence of aidlc/ in this post’s body text as the AWS neutral workspace, and .ai-dlc/ as the community plugin. The two are related but not interchangeable.

The AWS Official aidlc/ Workspace

The AWS reference implementation copies its engine into a single harness-specific directory and keeps everything else under a neutral aidlc/ directory organized by space, then by intent:

my-project/
β”œβ”€β”€ aidlc/                        EVERYTHING AI-DLC β€” neutral, committed, browsable
β”‚   β”œβ”€β”€ active-space              cursor: which space you are in (gitignored, per-user)
β”‚   └── spaces/
β”‚       β”œβ”€β”€ default/              the only space most teams ever see
β”‚       β”‚   β”œβ”€β”€ memory/           THE METHOD β€” how this team works (committed)
β”‚       β”‚   β”‚   β”œβ”€β”€ org.md        framework defaults
β”‚       β”‚   β”‚   β”œβ”€β”€ team.md       your team's practices (overrides org)
β”‚       β”‚   β”‚   β”œβ”€β”€ project.md    project-specific practices (overrides team)
β”‚       β”‚   β”‚   β”œβ”€β”€ phases/       phase-scoped rules
β”‚       β”‚   β”‚   └── templates/    output-format overrides, one per artifact
β”‚       β”‚   β”œβ”€β”€ knowledge/        DOMAIN KNOWLEDGE β€” standards an agent reads (committed)
β”‚       β”‚   β”‚   β”œβ”€β”€ documents/    your originals: PDFs, Word, Markdown (you own this)
β”‚       β”‚   β”‚   └── documentkb/   THE CATALOG β€” derived from documents/ (tool-owned)
β”‚       β”‚   β”‚       β”œβ”€β”€ index.json
β”‚       β”‚   β”‚       └── <doc-id>/   metadata.json + extracted content.md
β”‚       β”‚   β”œβ”€β”€ codekb/           CODE KNOWLEDGE β€” what each repo is (committed)
β”‚       β”‚   β”‚   └── <repo>/         architecture, component inventory, freshness marker
β”‚       β”‚   └── intents/          THE RECORD β€” one subdir per piece of work
β”‚       β”‚       β”œβ”€β”€ active-intent cursor: which intent is current (gitignored)
β”‚       β”‚       β”œβ”€β”€ intents.json  the registry: every intent + scope/repos/status
β”‚       β”‚       └── 260624-export-bug/   an intent record dir
β”‚       β”‚           β”œβ”€β”€ aidlc-state.md   where this intent is in the lifecycle
β”‚       β”‚           β”œβ”€β”€ audit/          the decision trail
β”‚       β”‚           └── inception/…     construction/{unit}/…  operation/…
β”‚       β”‚
β”‚       └── payments-team/        another SPACE (another team) β€” identical shape
β”œβ”€β”€ repo-a/                       your code repos live as siblings (each its own git)
└── repo-b/

The meaning of each piece:

PathPurpose
aidlc/active-spaceCursor recording which space is active (gitignored, per-user so two teammates can sit in different spaces)
spaces/<name>/One team’s self-contained world: its method, knowledge, code knowledge and intent record. spaces/default/ is free; adding a team is purely additive
memory/The method: org.md (framework defaults) β†’ team.md (your practices) β†’ project.md (most specific wins), plus phases/ for phase-scoped rules and templates/ for output-format overrides
knowledge/documents/Your original source documents (PDFs, Word, Markdown). You own and organise these; AI-DLC never reorganises them
knowledge/documentkb/The tool-derived catalog: index.json plus per-document metadata and extracted content. Rebuildable by /aidlc knowledge sync, so hand-editing it is a mistake
codekb/<repo>/Per-repo code knowledge: architecture, component inventory, a freshness marker
intents/The record of every piece of work: an intents.json registry (uuid, slug, dirName, scope, repos, status) plus one record dir per intent
<record>/ (e.g. 260624-export-bug/)A single intent’s record: aidlc-state.md (lifecycle position), audit/ (decision trail), inception/ (including domain-design/), construction/{unit}/ and operation/ artifacts
intents/<YYMMDD>-<label>/Record dirs sort chronologically by compact UTC date; identity itself is the UUIDv7 in intents.json, not the directory name
active-intentCursor recording which intent is current (gitignored, per-user)

The rule of thumb for what is committed: cursors and runtime scratch are local, the shared work is committed. active-space, active-intent, runtime-graph.json, per-session bindings and the document sync journal are gitignored; memory/, knowledge/, codekb/, intents.json and every record’s state, audit shards and artifacts are committed so the team shares them. An optional repos.json manifest at the workspace root declares the expected sibling repos for an intent that spans more than one codebase.

Sources: Spaces and Intents; Construction stage reference.

The Bushido Collective .ai-dlc/ Layout

The community plugin for Claude Code uses a hidden .ai-dlc/ directory at the project root:

.ai-dlc/
  add-oauth-login/              an Intent (slugified name)
    intent.md                   intent definition + frontmatter (workflow, git, announcements)
    unit-01-setup-provider.md   a Unit, with its own frontmatter
    unit-02-callback-handler.md
    discovery.md                domain discovery notes from elaboration
    state/                      EPHEMERAL β€” cleared on /ai-dlc:reset
      iteration.json            current hat, iteration count, status
      scratchpad.md             learnings and progress notes
      blockers.md               documented blockers
  knowledge/                    project knowledge layer persisted across intents
  hats/                         custom hats (project override wins over plugin built-ins)
  workflows.yml                 custom named workflows
PathPurpose
{intent-slug}/One directory per Intent, named by a slugified version of the intent (e.g. add-oauth-login/)
intent.mdThe intent definition with frontmatter: workflow, git strategy, announcements, status, epic reference
unit-{NN}-{slug}.mdA Unit, with frontmatter: status, depends_on (DAG ordering), branch, discipline, workflow override, ticket
discovery.mdDomain discovery notes captured during elaboration
state/Ephemeral, session-scoped state cleared on reset β€” the current hat, learnings and blockers
knowledge/The project knowledge layer persisting the five artifact types (design, architecture, product, conventions, domain) across intents, as described in Persistent Context
hats/Custom hats; project hats resolve before plugin built-ins so a team can override or add roles, as discussed under Hat
workflows.ymlCustom named workflows beyond the built-in default, adversarial, design, hypothesis and tdd

The distinction between intent.md/unit-*.md/discovery.md (committed β€” artifacts are memory) and state/ (ephemeral β€” cleared on reset) mirrors the AWS workspace’s committed-versus-gitignored split.

Source: The Bushido Collective ai-dlc README.

Harness-Specific Engine Directories

The AWS reference copies its engine into a harness-specific directory that is the only part of the layout that differs by tool:

HarnessEngine dir
Claude Code.claude/
Kiro (CLI and IDE).kiro/
Codex CLI.codex/
opencode and GitHub Copilot.aidlc/

This directory holds the engine’s tools, hooks, skills and agents. You never browse it β€” it just runs /aidlc. Everything else AI-DLC produces lives under the neutral aidlc/ directory regardless of harness, so teams switch tools without moving their work. The Bushido plugin is distributed differently: it installs into Claude Code as a plugin (.claude-plugin/) rather than via a harness engine directory.

Source: AI-DLC Workflows β€” Spaces and Intents.

What the Two Implementations Share

Different folder names and schemas hide a common set of principles:

  • Artifacts are memory β€” intent, unit and progress files are committed so the context window can be reset without losing ground truth; ephemeral state tracks only the current session.
  • Committed versus ephemeral split β€” shared work is version-controlled while cursors, runtime state and scratchpads are per-user or cleared on reset.
  • Domain and code knowledge live separately β€” a knowledge layer for standards and domain vocabulary and a code-knowledge layer for repository structure, so agents read them every session rather than searching afresh.
  • Multi-team isolation β€” the AWS layout uses named spaces; the community plugin scopes everything under the project’s own .ai-dlc/ directory.

The takeaway: the names and locations differ, but the pattern β€” committed artifacts plus ephemeral runtime state, with knowledge layered in β€” is consistent. Check which implementation a project uses, then read its layout accordingly.

Rule File Formats and Conventions

Beyond the workspaces above, the rule and steering files themselves have no industry-standard format. Each tool ships its own convention, and the de facto open baseline (AGENTS.md) is deliberately minimal β€” plain Markdown with no required headings and no mandatory frontmatter β€” so it carries the “how this project works” layer but nothing structured. For the structured parts β€” what a rule file must contain, how rules are scoped to paths, how opt-in extensions are declared β€” there is no shared schema; every tool (and every rule pack) rolls its own.

The official AWS release ships two folders (awslabs/aidlc-workflows):

aidlc-rules/
β”œβ”€β”€ aws-aidlc-rules/
β”‚   └── core-workflow.md        ← the entire adaptive workflow described in
β”‚                                 prose (~25 KB): stages, decision heuristics,
β”‚                                 checkpoint behaviour
└── aws-aidlc-rule-details/
    β”œβ”€β”€ common/                 ← detailed stage procedures referenced
    β”œβ”€β”€ inception/                 conditionally by core-workflow.md
    β”œβ”€β”€ construction/
    β”œβ”€β”€ operations/
    └── extensions/             ← opt-in rule packs: security, testing, resiliency

Each tool installs these in its own rules or steering location:

ToolInstalled as
Kiro.kiro/steering/aws-aidlc-rules/
Amazon Q Developer.amazonq/rules/aws-aidlc-rules/
Cursor.cursor/rules/ai-dlc-workflow.mdc (alwaysApply: true)
Claude CodeCLAUDE.md
GitHub Copilot.github/copilot-instructions.md
OpenAI CodexAGENTS.md

Amazon Q Developer, Cursor and Cline all name their version rules; Kiro coined steering files; Claude Code, GitHub Copilot and OpenAI Codex express the same idea through their own instruction conventions (CLAUDE.md, copilot-instructions.md, AGENTS.md). The capabilities differ only in scoping detail: Kiro steering offers inclusion modes (always, auto or manual plus glob patterns such as fileMatchPattern), Cursor rules support alwaysApply or description-based smart matching and Q rules stay deliberately plain workspace markdown. Same category everywhere β€” resident instructions loaded every session.

Example one β€” the AI-DLC extension rule convention. The official AWS implementation imposes a fixed shape on its rules. Extension rules (security, resiliency, compliance, or your own) are defined as sequential headings with a Rule section stating the requirement and a Verification section with the concrete checks the model evaluates:

## Rule SECURITY-01: Input validation on all API boundaries

**Rule**: Reject malformed or unexpected input at every public entry point
before any processing occurs.

**Verification**:

- Every public endpoint validates its request body against a schema
- Unsupported content types return 4xx, not a stack trace
- No raw user input is interpolated into logs or error messages

The rule ID (<PREFIX-NN>, here SECURITY-01) must be unique across all loaded extensions, because it is referenced in audit logs and compliance summaries β€” the rule file is not just prose, it produces traceable evidence. Each extension pairs its rules file with an *.opt-in.md partner that the workflow scans for and presents as a multiple-choice prompt during requirements analysis; opting in loads the rules file (derived by stripping .opt-in.md), opting out never loads it, and omitting the opt-in file makes the extension always enforced. Rules are blocking by default: a failing verification stops the stage until resolved.

Example two β€” the path-scoped rule convention. The emerging shape for rules that should fire only when the agent touches certain files is a Markdown file with optional YAML frontmatter carrying scoping metadata, mirroring how Cursor and several other tools express smart matching:

---
description: Backend API conventions β€” loaded when touching API files
trigger: auto
paths:
  - src/api/**
  - src/routes/**
---

- Validate all request bodies with zod schemas before processing
- Return errors as `{ error, code }`, never free-form messages
- Every new endpoint needs an integration test in tests/api/

The frontmatter fields (description, trigger, paths) capture the common subset that already exists scattered across tools β€” Cursor’s alwaysApply and description matching, Kiro’s fileMatchPattern globs, Q’s scoping β€” but each tool names and interprets them differently. That divergence, with no ratifying body, is exactly why it remains a convention rather than a standard.

Spec-Driven Development (SDD)

Spec-driven development (SDD) is a pillar of AI-assisted development (see The Pillars of AI-Assisted Development): a structured specification becomes the source of truth and the agents derive implementation, tests and documentation from it. This section explains what SDD is, the levels it comes in, the tools that implement it and how it fits into AI-DLC. It draws on Birgitta BΓΆckeler’s survey Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl (martinfowler.com, 2025).

What SDD Is

SDD means writing a spec before writing code with AI β€” “documentation first”. The spec becomes the source of truth for both the human and the AI. Two definitions frame it:

  • GitHub’s spec-kit: “In this new world, maintaining software means evolving specifications. […] The lingua franca of development moves to a higher level, and code is the last-mile approach.”
  • Tessl: “A development approach where specs β€” not code β€” are the primary artifact. Specs describe intent in structured, testable language, and agents generate code to match them.”

The term is still semantically diffuse β€” BΓΆckeler notes people sometimes use “spec” loosely, even as a synonym for “a detailed prompt” β€” so it helps to pin down what a spec actually is rather than rely on the label alone.

The Three Levels of SDD

BΓΆckeler observes that what tools call “spec-driven development” sits at several levels of commitment, and they build on each other:

  • Spec-first β€” a well-thought-out spec is written first, then used to guide the AI-assisted workflow for the task at hand. Once the task is done, the spec may be discarded; the next change starts a fresh spec.
  • Spec-anchored β€” the spec is kept after the task completes and continues to be the reference for the feature’s evolution and maintenance. The spec is updated as the feature grows, rather than re-derived each time.
  • Spec-as-source β€” the spec is the main source file over time. Only the spec is edited by the human; the human never touches the code, which is generated from the spec.

All SDD approaches are spec-first, but not all aim to be spec-anchored or spec-as-source β€” and even the spec-anchored tools rarely make their long-term maintenance strategy explicit. The spec-as-source level in particular carries a cautionary history: BΓΆckeler draws the parallel to model-driven development (MDD), where hand-built generators turned structured models or DSLs into code. MDD never took off for business applications because it sat at an awkward abstraction level and created too much overhead and constraint. LLMs remove some of that overhead β€” no predefined parseable language, no elaborate generators β€” but they add non-determinism, so spec-as-source risks the downsides of both worlds: the inflexibility of MDD and the non-determinism of LLMs.

What a Spec Is

There is no general definition of “spec”; the closest consistent description BΓΆckeler found is a comparison to a Product Requirements Document. Her working definition: a spec is a structured, behavior-oriented artifact β€” or a set of related artifacts β€” written in natural language that expresses software functionality and serves as guidance to AI coding agents. Each SDD variant defines its own structure, level of detail and how the artifacts are organised in the project.

The distinction between specs and the general context documents of a codebase (sometimes called a memory bank): rules files, or high-level descriptions of the product and codebase, like AGENTS.md, project.md and architecture.md. Context documents are relevant across all coding sessions in the codebase, whereas specs are only relevant to the task that creates or changes the particular functionality. This distinction maps directly onto the Rules-versus-Spec layering used throughout this post (see Rules files): rules are the cross-session memory bank, and the per-Intent spec is the task-scoped artifact.

The Tools

Three tools label themselves SDD, and they are quite different from each other β€” a reminder that “SDD” is not one thing.

Kiro (the most lightweight) is mostly spec-first. Its workflow is Requirements β†’ Design β†’ Tasks, with each step represented by one markdown document. Requirements are structured as user stories in “As a…” format with acceptance criteria in GIVEN/WHEN/THEN format. The design document holds component architecture, data flow, data models, error handling, testing strategy and implementation approach. Tasks trace back to requirement numbers and carry UI affordances to run and review one task at a time. Kiro’s memory bank is its “steering”, whose default topology is product.md, structure.md and tech.md.

Spec-kit (GitHub’s version, a CLI with slash commands) is the most customisable because it drops artifacts directly into the workspace. Its workflow is Constitution β†’ Specify β†’ Plan β†’ Tasks. The constitution is a powerful, effectively immutable rules file that the workflow applies to every change β€” essentially a memory bank. Each workflow step instantiates a set of files and prompts from templates, and makes heavy use of checklists inside the files to track clarifications, constitution violations and research tasks; the checklists act like a definition of done per step (interpreted by AI, so not guaranteed). One spec is made up of many files β€” spec, plan, tasks, data-model, api, component, research, and templates. GitHub aspires to spec-anchored (“living, executable artifacts that evolve… specs become the shared source of truth”), but spec-kit creates a branch per spec, which suggests it treats a spec as a living artifact for the lifetime of a change request rather than for the lifetime of a feature.

Tessl (CLI plus MCP server) is the only one explicitly aiming at spec-anchored, and it is exploring spec-as-source. Generated code carries a // GENERATED FROM SPEC - DO NOT EDIT marker, with roughly a 1:1 mapping between a spec and a code file. Tags such as @generate and @test tell it what to produce, and the exposed interfaces are put into the spec so the critical public surface stays under maintainer control. The low, per-file abstraction level reduces the number of steps and interpretations the LLM performs, lowering error chances β€” but non-determinism still showed when BΓΆckeler generated the same code multiple times from one spec, forcing her to iterate the spec toward more specificity and repeatability.

Cautions Via the Tools

BΓΆckeler’s hands-on testing surfaced several caveats that any SDD adoption should weigh:

  • One workflow does not fit every size. Both Kiro and spec-kit felt like “a sledgehammer to crack a nut” for small fixes β€” a trivial bug became four user stories with sixteen acceptance criteria in Kiro, and spec-kit’s elaborate, file-heavy review was overkill for a medium feature. An effective SDD tool needs flexibility for different problem sizes and types.
  • Reviewing markdown versus reviewing code. Spec-kit produced a lot of verbose, repetitive markdown for the human to review, some of which already contained code. BΓΆckeler notes she would rather review code than those files; SDD needs a good spec-review experience or it becomes a tax.
  • A false sense of control. Larger context windows do not guarantee the agent picks up everything. In her spec-kit run, the agent ignored research notes describing existing classes and regenerated them as new duplicates. Conversely, it sometimes went overboard following an instruction too eagerly. Small, iterative steps have historically been the reliable way to stay in control, which sits awkwardly with heavy up-front spec design.
  • Separating functional from technical spec is hard. SDD tools want to keep functional requirements apart from technical implementation (to enable switching tech stacks), but in practice BΓΆckeler found it confusing, the tooling inconsistent, and our profession already struggles to separate requirements from implementation in ordinary user stories.
  • Who is the target user? SDD tools push product- and requirements-analysis work onto developers without making that explicit, and it is unclear how far cross-skilling is meant to go.
  • The Verschlimmbesserung risk. Elaborate, file-heavy workflows may amplify existing challenges such as review overload and hallucination β€” making something worse in the attempt to make it better.

The takeaway is not that SDD is worthless β€” the general principle of spec-first is valuable, and how to structure a memory bank and a good spec for AI are among the most-asked practitioner questions. It is that SDD is not a single settled practice, and the more elaborate variants deserve scrutiny.

How SDD Fits Into AI-DLC

In the AI-DLC context, the SDD specification is not a separate artifact stream β€” it lives inside the same on-disk layout described throughout this appendix. The three layers are:

Rules / Steering files   HOW work happens β€” process, all work, once
        β”‚ (consulted every session)
        β–Ό
Spec (per Intent)        WHAT this feature is β€” intent.md, unit-*.md,
                         discovery.md, domain design, completion criteria
        β”‚ (source of truth for this feature's build)
        β–Ό
Implementation / Tests   derived from the spec
  • AI-DLC occupies the spec-first, leaning spec-anchored, part of the spectrum β€” it is not spec-as-source. The per-Intent artifacts (intent.md, unit-*.md, discovery.md, the domain design and the completion criteria) are committed to the repository as “artifacts are memory” (see Persistent Context: Artifacts Are Memory), so they persist beyond the task and feed future evolution, which is spec-anchoring in behaviour. But humans still read and edit the code and validate outcomes, so AI-DLC stops short of spec-as-source.
  • The SDD memory bank maps onto the AI-DLC Rules and Steering files β€” the process layer that is loaded every session and applies across all work (see Rules files and Steering files). The SDD spec maps onto the per-Intent layer.
  • The definition-of-done / checklist role that spec-kit’s checklists play maps onto AI-DLC’s completion criteria β€” precise, verifiable conditions per Unit that gate autonomy (see Core Terminology: Completion Criteria).

Where each piece of the spec lands on disk:

Spec elementWhere it lives
Intent (purpose, frontmatter)aidlc/intents/<id>/ (AWS) or .ai-dlc/{intent}/intent.md (community)
Units and their completion criteriaaidlc/intents/<id>/construction/{unit}/... (AWS) or .ai-dlc/{intent}/unit-*.md
Requirements and domain designaidlc/intents/<id>/inception/ including domain-design/ (AWS); discovery.md (comm.)
Domain knowledge the spec draws onaidlc/spaces/<name>/knowledge/ (AWS) or .ai-dlc/knowledge/ (community)
How the spec is producedThe stage library and heuristics in the Rules, which decide whether requirements analysis runs at all

The relationship holds across both implementations: the Rules and Steering files define the process that produces the spec, the spec is the versioned source of truth for a particular Intent, and the agent iterates against that spec until its completion criteria pass. Rules neither replace nor duplicate the spec β€” the two live at different levels, and the appendix layouts keep them in separate, committed directories.

References

Books:

  • Huyen, C. (2025). AI Engineering. O’Reilly.

Standards and frameworks:

  • OWASP Top 10 for LLM Applications.

Online references:

  • Anthropic (2024). Building Effective Agents. anthropic.com.
  • arXiv:2509.06216 (2025). Agentic Software Engineering: Foundational Pillars and a Research Roadmap.
  • arXiv:2606.04967 (2026). From Prompt to Process: A Taxonomy of Agentic AI-Driven Development Frameworks.
  • arXiv:2605.13357 (2026). AI Harness Engineering: A Runtime Substrate for Foundation-Model Software Agents.
  • BΓΆckeler, B. (2026). Context Engineering for Coding Agents. martinfowler.com.
  • BΓΆckeler, B. (2025). Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl. martinfowler.com.
  • Cloud Security Alliance (2026). Autonomy Levels for Agentic AI. cloudsecurityalliance.org.
  • Google (2025). Introducing Google Antigravity, a New Era in AI-Assisted Software Development. antigravity.google.
  • The Bushido Collective (2026). AI-DLC 2026 Method Definition Paper. ai-dlc.dev/paper.
  • GitHub (2025). Spec Kit: Writing specifications your team will actually use. github.blog.
  • Meppiel, D. (2025). How to build reliable AI workflows with agentic primitives and context engineering. GitHub Blog.
  • SP, R. (2025). AI-Driven Development Life Cycle: Reimagining Software Engineering. AWS DevOps Blog.
  • AWS (2025). Open-Sourcing Adaptive Workflows for AI-Driven Development Life Cycle (AI-DLC). AWS DevOps Blog.
  • AWS (2025). Building with AI-DLC using Amazon Q Developer. AWS DevOps Blog.
  • AWS (2026). AI-Driven Development Lifecycle for Financial Services. AWS Industries Blog.
  • awslabs (2025). aidlc-workflows. GitHub.
Share :
comments powered by Disqus

Related Posts

Agent2Agent Protocol (A2A)

Agent to Agent Protocol (A2A) is an open standard protocol to enable seamless communication and collaboration between AI agents.

Read More

Software Engineering in Fintech: Lifecycle, Personas and AI Practice

The full SDLC, every fintech persona and AI practice mapped across the lifecycle.

Read More

LangChain Deep Agents

Comprehensive reference for building long-running, multi-step AI agents using LangChain’s Deep Agents SDK β€” covering planning, file systems, subagents, memory, skills, sandboxes, backends, context management, human-in-the-loop, and deployment.

Read More