1 Approve or 2 <why> Request ChangesWhatThe outcome you want, in your words; in the tool also one tracked run with its own folder (the record).
WhyStart from the ask, not an interpretation of it; the AI interprets out loud as numbered requirements and open questions.
Analogy One renovation project with its own folder in the cabinet.
/aidlc express Build what ./docs-in/request.md describes → intents/<id>/
WhatFive chapters, each handing the next richer context. AWS names Inception, Construction, Operations; the tool adds Initialization and Ideation.
WhyIdeation stops the wrong thing; Inception stops building it badly or all at once; Construction stops unreviewable change; Operation feeds evidence back.
Analogy Deciding, planning, building, living in it.
artifacts in <record>/<phase>/; checks in verification/
What33 numbered steps, each with inputs, outputs, a lead persona (product, architect, developer, quality…) and a gate. Conditional ones skip themselves.
WhySmall named steps make the run repeatable and traceable; few broad agents instead of many narrow ones avoids waterfall handoffs.
Analogy One meeting or one job with a named deliverable, run by the right specialist.
2.3 → requirements.md · 2.7 → unit-of-work.md · 3.5 → code
WhatEvery stage outside Initialization ends with (1) Approve (2) Request Changes; your reply, in your words, becomes an audit shard.
WhyThe AI plans and asks; a person decides; only then it implements. Responsibility gets a name.
Analogy The owner signs each page; “move the sink” is written on the drawing and it comes back redrawn.
1 · 2 <what to change> · 1.7 Reject · 3.5 I'll edit · 4.7 New cycle
WhatThe whole team validates the AI's proposals together: in Inception (requirements, stories) and in Construction (design choices).
WhyOne sitting over the same proposal instead of serial handoffs; objections surface once, decisions are made where the context is.
Analogy Everyone round the kitchen table with the plans, one round of objections.
bounded rounds; 2.4 is the mob stage; /aidlc --collaborators on
WhatAn independently buildable, testable, reviewable piece of the solution (2.7), with boundaries and a place in a dependency DAG.
WhyReplaces the epic: cut by what can be built and approved alone, so the AI gets a bounded job and a reviewer a bounded review.
Analogy One room's job a crew can finish alone; plumbing before tiling is the DAG.
unit-of-work.md, dependency DAG · OURS: one unit = one branch = one PR
WhatA delivery slice of dependency-linked units with a definition of done and a demo, measured in hours or days.
WhyReplaces the sprint: when the AI builds, the limit is human review, so the cycle shrinks to one sitting with a visible result.
Analogy A crew's block with “done by Friday” on it, not the office's two-week calendar.
2.9 → bolt-plan.md; a kept sprint is only a reporting calendar
WhatThe smallest working integrated slice, built first; it must pass a real end-to-end check and be approved before other units start.
WhyIntegration risk is the expensive risk: prove the wiring while there is little to throw away.
Analogy Frame, roof, one pipe and one wire so water comes out of one tap.
marked in bolt-plan.md; “Verified with <cmd> (exit 0)” first
WhatOne approved command run after every unit; the checkpoint carries its exit code; 3.6 writes the verification matrix; phase checks between phases.
Why“Done” must be something the AI cannot assert: an exit code, a matrix row per requirement, a traceability check.
Analogy The agreed pressure test after every room; the inspector between chapters.
verification-command.txt · test-results.md · phase-check-*.md
WhatPlans, requirements, decisions, state and audit are files next to the code, reused by every stage and every later run.
WhyChat scrolls away and is compacted; files survive sessions, travel through git, and are read by the next person or run.
Analogy The folder in the cabinet, the survey, the deeds, the house rules. The notebook can be lost; the cabinet cannot.
aidlc/spaces/<space>/: memory · knowledge · codekb · intents/<id>
WhatScope = which stages run (express 10, bugfix 9, poc 8, mvp 23, feature 33). Depth = how long the artifacts. Test strategy = how many tests.
WhyThe same method shrinks to a two-hour fix or grows to an audited feature: same gates, same record, fewer or more stages.
Analogy Fixing a tap, a new kitchen, or an extension with permits: same architect, different paperwork.
/aidlc <profile> …: naming the profile is the choice; express asks no scope question
WhatDeploy, observe, learn: 4.1 pipeline + rollback, 4.3 deployment log, 4.4 alarms, 4.7 feedback that can start a new intent. People own every gate, the mob, the pipeline buttons, branches and PRs.
WhyProduction evidence, not opinion, drives the next intent; judgment, not typing, becomes the scarce resource.
Analogy Putting the dish on the menu, the smoke alarm you install, and the monthly look at what to change.
conditional: skipped when there is no pipeline to work on · OURS: push and PR
| PRD | → | intent + requirements.md |
| Epic | → | unit of work |
| Sprint | → | bolt |
| Refinement meeting | → | mob elaboration |
| Design review | → | mob construction + 3.5 plan approval |
| Definition of done | → | command exits 0 + named approval |
| Status board | → | aidlc-state.md + audit/ |
| Retrospective | → | learning loop + 4.7 feedback |
slice of time with a demo · calendar (OURS) · piece of the solution
a person answers · automatic between phases · per-unit gate with exit code · automatic on file writes
documents you gave · rules the team taught · what the tool read in the code
the work and its folder · one run through the stages · one conversation
“It opens PRs.” No: there is no PR stage. Claude branches and commits when your CLAUDE.md asks; pushing and PRs are yours.
“Express skips testing.” No: one test per requirement, run before the Code Generation gate.
“Approve is a formality.” No: recorded with your name and words; 2 is normal.
“The chat is the record.” No: the record is aidlc/, committed and shared.
1 Approve · 2 <what to change> · 3.5 plan: 1 Approve Plan / 3 I'll edit · Construction entry: Continue automatically or Review each checkpoint · 4.7: Start New Ideation Cycle