aidlc-workflow

# AI-DLC workflow A lightweight, tool-free version of the AI-DLC used by the reference sample. There is no engine: the **state file, stage artifacts, and gate approvals are plain markdown** that the team and AI keep up to date. Every stage has an owner, an input, an output, a review, and an explicit human approval before the next stage starts. Project record: `aidlc/spaces/default/intents/261107-robopath/` (called `<intent>/` below). Baseline decisions: `docs/seed-spec.md`. All artifacts, code, comments, and commit messages are written in **English**. Only chat with the user may be in another language. ## Principles 1. **AI proposes, human approves.** The accountable role owns every decision; AI output is a draft until the role signs it in the state file. 2. **Plan before generating.** Each stage starts with a short plan and open questions. Ask only questions that change behavior, scope, contract, or acceptance criteria; otherwise record an assumption (`A-xx`) and proceed. 3. **Small, reviewable stages with gates.** No stage starts until the previous gate is approved. Fix defects in the stage that owns them, then re-approve. 4. **Traceability by ID.** `FR/NFR -> AC -> design element -> code -> TC`. A gap is visible, never silent. 5. **Context is a deliverable.** Decisions, assumptions, and corrections are written to the stage artifact or memory, not left in chat. ## Stage set | # | Phase | Stage | Owner | Output (in `<intent>/`) | Gate | |---|---|---|---|---|---| | 1 | Ideation | intent-capture | BA | `ideation/intent-capture/intent-statement.md` | - | | 2 | Ideation | scope-definition | BA | `ideation/scope-definition/scope-document.md` | - | | 3 | Inception | requirements-analysis | BA | `inception/requirements-analysis/requirements.md` | **G1** Product approved | | 4 | Inception | domain-design | TechLead | `inception/domain-design/architecture.md` (+ ADRs) | - | | 5 | Inception | contract-design | TechLead | `inception/contract-design/contract.md` | **G2** Design approved | | 6 | Construction | code-generation (backend) | Senior Engineer | `backend/src/maze_game/*`, `backend/migrations/`, `backend/tests/` | - | | 7 | Construction | code-generation (UI) | Engineer | `frontend/src/*`, `frontend/tests/` | **G3** Integration review (TechLead) | | 8 | Construction | build-and-test | QC | `construction/build-and-test/{test-plan,test-results}.md` | **G4** Release readiness | Skipped on purpose (recorded in the state file): `units-generation` (two fixed units: backend and UI), `functional-design` (covered by `docs/seed-spec.md` and the architecture), Operation phase (local Docker only). QC starts test design right after G1 and runs in parallel with design and construction. ## Stage protocol 1. **Start:** read `<intent>/aidlc-state.md`, memory (`aidlc/spaces/default/memory/org.md`, `team.md`, `project.md`, `phases/<phase>.md`) and the previous stage's approved artifact. Mark the stage `in progress`. 2. **Plan:** write a short plan (what, inputs, output, done criteria) at the top of the artifact under `## Stage plan`. List open questions with an `[Answer]:` slot. 3. **Generate:** produce the artifact with the role skill and its templates. Link IDs to upstream IDs. 4. **Self-review:** run the role checklist; list remaining gaps under `## Review`. 5. **Gate:** present a summary (changes, decisions, assumptions, open risks) and ask for approval. Record result, approver, date, and note in the state file. If rejected, record the change request and rework. 6. **Handoff:** fill `./assets/handoff.template.md` in the state file's handoff log. Never mark a gate approved without a recorded human approval. Never begin code generation before **G2**. ## State file `<intent>/aidlc-state.md` is the single place that answers: what stage are we in, what was approved, what is next. Update it at every stage start, gate, and handoff. Template: `./assets/aidlc-state.template.md`. ## Traceability and IDs | Prefix | Meaning | Created by | |---|---|---| | `D-xx` | Baseline decision (see `docs/seed-spec.md`) | BA/TechLead | | `A-xx` | Assumption awaiting confirmation | any role | | `FR{n}`, `NFR{n}` | Requirements | BA | | `AC{n}.{m}` | Acceptance criterion for `FR{n}` | BA | | `ADR-{nnn}` | Architecture decision | TechLead | | `C-{nn}` | Contract element (endpoint, error code) | TechLead | | `TC-{nnn}` | Test case | QC | | `BUG-{nnn}` | Defect | QC | Rules: every FR has at least one AC; every AC has at least one TC; every test and code module cites the IDs it covers. QC maintains the matrix in `test-plan.md` with status `OK / GAP / ORPHAN / Deferred / N/A`. Gate checklists: `./references/stage-gates.md`. ## Engineering standards Coding standards, performance, SQL performance, and security rules live in the `dev-standards` skill and apply to every gate that touches code or design (G2, G3, G4). ## AI usage log (optional) Keep `<intent>/ai-usage-log.md`: role, stage, task, what AI got right or wrong, and how the human corrected it. ## Anti-patterns - Generating code before the contract is approved. - Asking many questions that a stated assumption could resolve. - Updating requirements to match the code without a change request. - Letting QC discover scope the BA never wrote down. - Claiming a gate or a test passed without the recorded approval or command output. ## References and assets - [Gate checklists and rework rules](./references/stage-gates.md) - [State file template](./assets/aidlc-state.template.md) - [Handoff note template](./assets/handoff.template.md)