One requirement, one Spring Boot repo, every step spelled out.

This page runs AWS AI-DLC on a small Java API with the express profile (10 of the 33 stages). For each of the 17 steps you see exactly what you type, what Claude returns, and what appears on disk, with every folder explained. The code, the tests, their output and the API's JSON are real. You start from the public starter repo varasrinivas/aidlc-priorauth-api (the API at v1.0.2, before the change); the finished workspace, record included, is the java-workspace/ folder next to this page.

17steps, 4 of them a one-character answer

10 / 33stages (express profile)

1 h 25 min09:30 to 10:55, 4 gates

12files: 6 new, 6 changed

9tests, 6 from this run

0new dependencies (pom.xml: version only)

You typeThe exact text. A copy button is under it. Most steps are one character.

Claude returnsAbridged: the lines that matter, in the documented shape. Your wording will differ a little.

On disk nowWhat the step created or changed. Green is new.

GateA question Claude will not pass on its own. A named person answers it; the answer is kept in audit/.

What you are going to change, before any AI is involved

The requirement in one sentence: every request in the pending list should say how many working days it has been waiting, and get a flag once it has waited more than 5.

Nurses review prior-authorization requests (a doctor asking the insurer "may we do this MRI?"). Their screen gets the list from GET /requests/pending. Today that list says when each request arrived, but not how long it has waited, so nobody sees the old ones. The rule for "how long", in four lines:

The day it arrived is day 0. Counting starts the next day.
Count up to and including today, or the date you pass as ?asOf=YYYY-MM-DD (that makes the answer testable: it doesn't change tomorrow).
Skip Saturdays, Sundays and the tenant's holidays. Tenant TX-01 has a holiday on Mon 12 Oct 2026.
More than 5 working days means over the limit. Exactly 5 is still fine; 6 is flagged. The 5 comes from configuration, not from the code.

Worked example. Request PA-10231 arrived Thu 1 Oct; we ask on Tue 13 Oct:

Thu1day 0

Fri21

Sat3off

Sun4off

Mon52

Tue63

Wed74

Thu85

Fri96

Sat10off

Sun11off

Mon12hol.

Tue137 >5

Grey = not counted (weekend, or hol. = TX-01 holiday). 7 working days, more than 5, so it is flagged. The API should say so in three new fields on every row: ageBusinessDays, overLimit, ageLabel.

Actual today v1.0.2 · real

$ curl "localhost:8080/requests/pending?asOf=2026-10-13"
[
  {
    "id": "PA-10231",
    "tenantId": "TX-01",
    "service": "MRI lumbar spine",
    "status": "PENDED",
    "receivedAt": "2026-10-01"
  },
  { "id": "PA-10244", ... "receivedAt": "2026-10-06" },
  { "id": "PA-10263", ... "receivedAt": "2026-10-09" }
]
# ?asOf is ignored; nothing says how long anything has waited

What it should be v1.1.0 · real

$ curl "localhost:8080/requests/pending?asOf=2026-10-13"
[
  {
    "id": "PA-10231",
    "tenantId": "TX-01",
    "service": "MRI lumbar spine",
    "status": "PENDED",
    "receivedAt": "2026-10-01",
    "ageBusinessDays": 7,
    "overLimit": true,
    "ageLabel": "7 bd OVER 5"
  },
  { "id": "PA-10244", ... "ageBusinessDays": 4, "overLimit": false, ... },
  { "id": "PA-10263", ... "ageBusinessDays": 1, "overLimit": false, ... }
]

Done meansEvery row carries the three new fields; ?asOf works; mvn test runs 10 tests (3 old + 7 new), 0 failures.

Doesn't changeThe endpoint, its existing fields, how requests are stored, and the libraries: pom.xml changes only its version.

See "actual" yourselfAfter step 1: cd priorauth-api; mvn spring-boot:runcd priorauth-api && mvn spring-boot:run, then the curl above in a second window. Stop it with Ctrl+C before step 2.

Answer key. The starter repo carries tag v1.1.0, the code as this run left it. git -C priorauth-api diff v1.0.2 v1.1.0 --stat lists the twelve files; use it to check your own run, not to skip it. Claude may find the tag too, before it writes code: step 12 says what to answer.

Before you start: three things on your laptop, once

New to AI-DLC workspaces? Set up an AI-DLC workspace explains every command used in steps 1–2 below and every file they create.

AI-DLC is a set of workflow files that Claude Code runs; the aidlc command installs and configures them. Java and Maven are for the repo, not for AI-DLC.

A JDK 21 and Maven 3.9 on the path (any JDK 21 build; Maven from maven.apache.org or your package manager)

You type PowerShellTerminal (macOS)

java -version
mvn -version

You see your shell, not Claude

openjdk version "21.0.x" 2026-xx-xx LTS
Apache Maven 3.9.x
Java version: 21.0.x # the JDK Maven uses: this is the line that must say 21

AI-DLC Workflows (the aidlc command; v2.11 at the time of writing)

You type PowerShellTerminal (macOS)

irm https://github.com/awslabs/aidlc-workflows/releases/latest/download/install.ps1 | iex
aidlc --version

curl -fsSL https://github.com/awslabs/aidlc-workflows/releases/latest/download/install.sh | sh
aidlc --version

You see

aidlc installed
aidlc 2.11.x

Claude Code signed in and working: claude opens, /help answers. Install it from docs.claude.com.

In plain words. Installing AI-DLC is like giving a new colleague a badge: once per laptop. After that, every project is "open the folder, start Claude, type /aidlc".

The two folders you will be looking at

AI-DLC never runs inside the code repo. It runs from a folder around it, the workspace, and writes its own notes next to the code, never into it. Below, both folders before anything happens.

The workspace (yours)

java-workspace/ before the run

java-workspace/             the folder you start Claude in
  CLAUDE.md                 house rules Claude reads first (ours)
  repos.json                which repos belong here (ours)
  scripts/verify.sh         the one test command (ours)
  scripts/verify.cmd        same, for Windows (ours)
  docs-in/request.md        the Slack message, saved as a file
  priorauth-api/            the code repo: a git clone

Entry	What it is for
`CLAUDE.md`	Two paragraphs Claude Code loads automatically: which repo owns what, how to test, how to name branches. Your team writes it once.
`repos.json`	The list of code repos that belong to this workspace, so a teammate can clone them all with `aidlc system workspace-sync`. Each `name` is the folder; `url` overrides the default clone source (`git@github.com:<org>/<name>.git`), and here points at the public starter repo. "Disk wins": a repo that is listed but not cloned is not part of the run.
`scripts/`	Your own scripts. `verify.sh` runs `mvn -q test` in the repo; CLAUDE.md tells Claude to test only through it.
`docs-in/`	Inputs you hand to the run: the request, a brief, an exported page. Anything Claude should read rather than hear.
`priorauth-api/`	The repo, cloned from GitHub. AI-DLC finds it because it has a `.git` folder.

The Java repo (Maven layout)

priorauth-api/ at tag v1.0.2 (before)

priorauth-api/
  pom.xml                                     Maven's recipe: name, Java 21, two Spring starters
  README.md
  .gitignore                                  target/ is never committed
  src/main/java/com/acmehealth/priorauth/     code that ships
    PriorAuthApiApplication.java              the main() Spring Boot starts from
    api/PendingRequestsController.java        GET /requests/pending
    api/PendingRequestResponse.java           one JSON row
    model/PriorAuthRequest.java               the domain record
    store/RequestStore.java                   loads the export, oldest first
  src/main/resources/                         config and data packed into the jar
    application.yml                           name, port 8080
    data/requests.sample.json                 4 requests, 3 pending
  src/test/java/com/acmehealth/priorauth/     tests; never shipped
    store/RequestStoreTest.java               2 tests
    api/PendingRequestsControllerTest.java    1 test, starts the app in-process
  target/                                     appears when you build; generated, ignored

Folder	What goes there
`pom.xml`	The build file. Every Maven command reads it: which Java, which libraries (here only two "starters"), how to package. Version numbers live here.
`src/main/java`	The application. The folder path mirrors the package name: `com.acmehealth.priorauth` → `com/acmehealth/priorauth`.
`src/main/resources`	Non-code files the app reads at runtime: `application.yml` settings, data files. They end up inside the jar.
`src/test/java`	JUnit tests, same package layout. `mvn test` compiles and runs them; they are not shipped.
`target/`	Maven's scratch space: compiled classes, test reports, the jar. Delete it any time; never commit it.

In plain words. The repo is the kitchen. The workspace is the restaurant around it, and the folder AI-DLC is about to create, aidlc/, is the order book: every order, every question asked, every decision, and who signed it. The kitchen never keeps the order book.

What express skips. express runs the stages in colour; the rest are for work whose requirements are not yet understood. If Ravi's message had been vague, you would start the run with feature instead of express at step 5. In this run the three Operation stages were skipped too: they run only when the workspace has a pipeline to work against (step 15).

0.1 0.2 0.3 Initialization1.1 Intent Capture1.2 Market Research1.3 Feasibility1.4 Scope1.5 Team Formation1.6 Rough Mockups1.7 Approval & Handoff 2.1 Reverse Engineering2.2 Practices Discovery2.3 Requirements Analysis2.4 User Stories2.5 Refined Mockups2.6 Domain Design2.7 Units Generation2.8 Contract Design2.9 Delivery Planning 3.1 Functional Design3.2 NFR Requirements3.3 NFR Design3.4 Infrastructure Design3.5 Code Generation3.6 Build and Test3.7 CI Pipeline 4.1 Deployment Pipeline4.2 Environment Provisioning4.3 Deployment Execution4.4 Observability Setup4.5 Incident Response4.6 Performance Validation4.7 Feedback & Optimization

Set upsteps 1–4 · your shell, then Claude Code · about 10 minutes

yours, not the tool

Make the workspace folder and put the repo in it

AI-DLC runs from the folder around the repo, so its record and your code never mix.

Kiran · 09:20

You type PowerShellTerminal (macOS)

mkdir C:\work\java-workspace
cd C:\work\java-workspace
git init -b main
git clone https://github.com/varasrinivas/aidlc-priorauth-api.git priorauth-api
# the team's files (CLAUDE.md, repos.json, scripts\), written from scratch:
mkdir scripts | Out-Null
[IO.File]::WriteAllText("$PWD\CLAUDE.md", (@'
# java-workspace

Run AI-DLC from this folder. One code repo, `priorauth-api/`, a Spring Boot 4.1 REST API on Java 21, built with Maven.

| Repo          | Owns                                   | Verify with      | Branch pattern       |
|---------------|----------------------------------------|------------------|----------------------|
| priorauth-api | the API the reviewer screen reads      | `mvn -q test`    | request-age/<slug>   |

Rules: the record in `aidlc/` is the source of truth for requirements and decisions; commit it after every gate.
One unit = one branch = one PR. Tests through `./scripts/verify.sh` (`scripts\verify.cmd` on Windows), never ad hoc.
Never add a dependency to pom.xml inside a unit without saying so in the plan.
'@ -replace "`r", "") + "`n")
[IO.File]::WriteAllText("$PWD\repos.json", (@'
{
  "org": "acme-health",
  "repos": [
    { "name": "priorauth-api", "branch": "main", "url": "https://github.com/varasrinivas/aidlc-priorauth-api.git" }
  ]
}
'@ -replace "`r", "") + "`n")
[IO.File]::WriteAllText("$PWD\scripts\verify.sh", (@'
#!/usr/bin/env bash
# The one verification command for this workspace (approved at Code Generation, run after every unit).
set -uo pipefail
cd "$(dirname "$0")/../priorauth-api"
mvn -q test
'@ -replace "`r", "") + "`n")
[IO.File]::WriteAllText("$PWD\scripts\verify.cmd", (@'
@echo off
rem The one verification command for this workspace (Windows twin of verify.sh).
cd /d "%~dp0..\priorauth-api" && mvn -q test
'@ -replace "`r", "") + "`n")

mkdir -p ~/work/java-workspace
cd ~/work/java-workspace
git init -b main
git clone https://github.com/varasrinivas/aidlc-priorauth-api.git priorauth-api
# the team's files (CLAUDE.md, repos.json, scripts/), written from scratch:
mkdir -p scripts
cat > CLAUDE.md <<'EOF'
# java-workspace

Run AI-DLC from this folder. One code repo, `priorauth-api/`, a Spring Boot 4.1 REST API on Java 21, built with Maven.

| Repo          | Owns                                   | Verify with      | Branch pattern       |
|---------------|----------------------------------------|------------------|----------------------|
| priorauth-api | the API the reviewer screen reads      | `mvn -q test`    | request-age/<slug>   |

Rules: the record in `aidlc/` is the source of truth for requirements and decisions; commit it after every gate.
One unit = one branch = one PR. Tests through `./scripts/verify.sh` (`scripts\verify.cmd` on Windows), never ad hoc.
Never add a dependency to pom.xml inside a unit without saying so in the plan.
EOF
cat > repos.json <<'EOF'
{
  "org": "acme-health",
  "repos": [
    { "name": "priorauth-api", "branch": "main", "url": "https://github.com/varasrinivas/aidlc-priorauth-api.git" }
  ]
}
EOF
cat > scripts/verify.sh <<'EOF'
#!/usr/bin/env bash
# The one verification command for this workspace (approved at Code Generation, run after every unit).
set -uo pipefail
cd "$(dirname "$0")/../priorauth-api"
mvn -q test
EOF
cat > scripts/verify.cmd <<'EOF'
@echo off
rem The one verification command for this workspace (Windows twin of verify.sh).
cd /d "%~dp0..\priorauth-api" && mvn -q test
EOF
chmod +x scripts/verify.sh

You see your shell; Claude is not running yet

Initialized empty Git repository in C:/work/java-workspace/.git//Users/you/work/java-workspace/.git/
Cloning into 'priorauth-api'...
Receiving objects: 100% (64/64), 11.97 KiB | 2.99 MiB/s, done.
Resolving deltas: 100% (7/7), done.

On disk now

java-workspace/
  .git/                     the workspace's own repo (git init): Claude commits the record here after the gates; you add the rest at step 17
  priorauth-api/            the clone, branch main = tag v1.0.2 (before) · its .git folder is how AI-DLC finds it
  CLAUDE.md                 written by the commands above: house rules (repo map, test command, branch pattern)
  repos.json                written by the commands above: the repos that belong here (one entry)
  scripts/verify.sh         written by the commands above: runs mvn -q test inside priorauth-api
  scripts/verify.cmd        the Windows twin

java-workspace/CLAUDE.mdClaude Code reads this at start, every time

java-workspace/repos.jsonwho belongs here

java-workspace/scripts/verify.shthe one test command

In plain words. You are setting a table before the guest arrives: the kitchen (repo) is there, the rulebook (CLAUDE.md) is on the table, and the test command is the one knife everybody agrees to use.

aidlc command

Tell AI-DLC that your assistant is Claude Code, then let it check the folder

The aidlc command writes the files Claude Code needs (the /aidlc slash command and its agents) into a .claude/ folder. doctor confirms the folder is usable.

Kiran · 09:22

You type PowerShellTerminal (macOS), inside java-workspace

aidlc config --harness claude
aidlc system workspace-sync
aidlc doctor

You see abridged

configured ...\java-workspace for Claude Code 2.11.0; next: open Claude Code in this project ...
aidlc workspace-sync: reconciling ...\java-workspace against repos.json (1 repo(s))
  ✓ priorauth-api already on disk - leaving untouched
  ✓ .gitignore managed block → 1 child dir(s)
  ✓ aidlc.code-workspace → 1 child root(s)
✓ workspace in sync
AI-DLC doctor
Machine                            ok    11 checks passed
Project (.claude, Claude Code)     ok    47 checks passed
Framework integrity                ok    all 12 checks passed
0 problems, 3 warnings. # expected now: no update cache yet, hooks not run yet, aidlc/ not committed yet

On disk now

java-workspace/
  .claude/                  generated: the /aidlc command, agents, hooks. Never edit; re-run `aidlc config` after `aidlc update`
  aidlc/                    the record's folder, started: spaces/default/memory/ (team and project memory files)
  .gitignore                two managed blocks: runtime scratch (from config) and /priorauth-api/ (from workspace-sync: the repo has its own history)
  aidlc.code-workspace      from workspace-sync: a VS Code multi-root file, workspace + repo

Once per laptop, per workspace. workspace-sync reads repos.json: it clones any listed repo that is missing and writes the .gitignore line that keeps the repo out of the workspace's git. A teammate who clones the workspace runs the same three commands on their machine. The tool's files are generated; your team's files (CLAUDE.md, repos.json, scripts/) are not.

yours, not the tool

Save the requirement as a file

Claude should read the request, not be told it in a chat that scrolls away. The record will quote this file.

Kiran · 09:25

You type nothing in a terminal

In your editor, create docs-in/request.md and paste Ravi's message into it, with who sent it and when. That is the whole step.

Claude returns —

(Claude is not involved yet)

On disk now

java-workspace/
  docs-in/request.md        the input of the run. One file, five lines.

java-workspace/docs-in/request.mdthe whole file

Claude Code

Start Claude Code in the workspace folder

Start it here, not inside priorauth-api/: the /aidlc command and the record belong to the workspace.

Kiran · 09:29

You type PowerShellTerminal (macOS), inside java-workspace

claude

Claude returns abridged

╭──────────────────────────────────────────────╮
│ Welcome to Claude Code                       │
│ cwd: C:\work\java-workspace ~/work/java-workspace                  │
│ CLAUDE.md loaded · /aidlc available          │
╰──────────────────────────────────────────────╯
> _

From here on, everything you type goes into this prompt. Lines that start with / are slash commands (/aidlc is one). Lines that start with ! run in your shell and show the output (you will use that for git). Everything else is a message to Claude, including the one-character answers at the gates.

Initializationstages 0.1 – 0.3 · automatic, inside one command

0.1 Workspace Scaffold0.2 Workspace Detection0.3 State Initialization

Start the run: one command creates the record and goes straight on to the first real stage

express names the scope; "Build what ./docs-in/request.md describes" is the request. Naming the scope in the command is the decision: express asks no scope question. Claude creates the record folder, looks at the repo, writes the state file, and starts Reverse Engineering in the same turn.

Kiran · 09:30

You type in Claude Code

/aidlc express Build what ./docs-in/request.md describes

Claude returns abridged · wording from a real 2.11.0 run

Setting up an express workflow for this: 7 stages, 7 approval gates; no reviewers, sensors,
learnings ritual, summary confirmation, or plan approval; lead agent only.
Intent created: 261013-request-age-api (space: default)
State initialized: express scope, 10 stages, Minimal depth
Project type: Brownfield
Languages: Java
Frameworks: Spring Boot
Build System: maven (pom.xml)
First post-init stage: reverse-engineering (INCEPTION)
Choose Yes when Claude Code asks to change this project's settings, then answer the question below.
▸ Claude Code asks to create .claude/settings.local.json

On disk now

java-workspace/
  aidlc/                                    the order book. Everything AI-DLC writes lives under here.
    spaces/default/                         a "space" groups runs; one is enough for a team
      intents/intents.json                  the registry of runs in this space: one row, status in-flight
      intents/261013-request-age-api/       this run. The id is the date (26-10-13) plus a label Claude picked
        aidlc-state.md                      where the run is: scope, stages to run, a checkbox per stage. Read it to resume.
        project-description.json            your request, verbatim, kept exactly as you typed it
        audit/                              who answered what, when. This course keeps one small file per answer:
          0001-scope.md                     the scope you named in the command, with time and name

aidlc/spaces/default/intents/intents.jsonthe registry, at this moment

aidlc/spaces/default/intents/261013-request-age-api/project-description.jsonthe request, as one JSON string

intents/261013-request-age-api/audit/0001-scope.mdan audit shard: who decided what, when

Your folder name will differ. The intent id is the day you run it plus a two-to-three-word label Claude picks from your request: run on 14 Oct 2026 it is 261014-request-age-api, and the label may differ too. Everything else on this page still applies; read 261013-request-age-api as "your intent folder".

Where the tool's understanding goes. project-description.json keeps only your words. What the tool detected (brownfield, Java, Spring Boot, Maven) and decided (scope express, the 10 stages to run, the 23 to skip) is written into aidlc-state.md; you can see the finished file at step 16. "request" in the registry row (and Question Id in the state file) points to your request as the engine saved it. When the run completes, the row's status becomes complete.

Choosing the scope. Express is right when the requirement is already understood, the repo is small and one team owns it. All three are true here, so the command names it. If Ravi's message had said "and make it configurable per tenant somehow", you would start with /aidlc feature … instead, and the tool would add the design and units stages. "7 approval gates" counts the stages that end with a question to you: 2.1, 2.3, 3.5, 3.6, 4.1, 4.3, 4.4. In this run you answer four of them; the three Operation stages are skipped at step 15.

In plain words. The first command opens a new page in the order book, writes the customer's words on it, notes that this is a small job because you said so, glances into the kitchen, and starts writing down what is in the cupboards.

Inceptionstages 2.1 and 2.3 · understand the repo, write the requirements · 09:31 – 09:50

2.1 Reverse Engineering

Choose Yes if Claude Code asks to change the project's settings. Claude reads the repo and writes nine short files about it

Before anything is designed, the tool writes down what exists: the layers, the endpoint, the libraries, the tests, the rules it can see. Those nine files are reused by every later run in this workspace. This is the same turn as step 5; the one thing you may have to do is allow a settings change.

Kiran · 09:31 → 09:39

You choose in Claude Code's permission prompt · no prompt, nothing to do

Yes

Claude returns abridged · wording from a real 2.11.0 run · 8 minutes

Bringing in the developer to work on Reverse Engineering.
codekb priorauth-api: NO_STORE, first scan → full scan of ./ at commit 976ab66
The developer takes a look at the API code and writes up what it finds.

Reverse Engineering complete
I've finished reading through priorauth-api. It's small: 2 test classes and 3 tests. I read every file in full.
  business-overview.md     Serves the pending prior-auth list that the reviewer screen reads
  api-documentation.md     GET /requests/pending returns id, tenantId, service, status, receivedAt
  technology-stack.md      Java 21, Spring Boot 4.1, Maven, JUnit 5, AssertJ, MockMvc
  …six more
What matters for this change: no business-day or holiday logic exists in this repo. Requirements will
need to settle whether the received day counts, whether "over 5" means more than 5, and where the
holidays come from.
Review: aidlc/spaces/default/codekb/priorauth-api/
▸ Reverse Engineering is done. How would you like to proceed?
  1. Approve: continue to Requirements Analysis   2. Request Changes   3. Other

On disk now

java-workspace/aidlc/spaces/default/
  codekb/priorauth-api/                     what the tool knows about the repo; reused by the next run
    business-overview.md                    what the service is for, in two sentences
    architecture.md                         layers: api, store, model; no database in this cut
    code-structure.md                       the folder map with one line per file
    api-documentation.md                    the one endpoint and its JSON
    component-inventory.md                  each class and what it does
    technology-stack.md                     Java 21, Spring Boot 4.1, Maven; the dependency policy
    dependencies.md                         the two starters, nothing else
    code-quality-assessment.md              what is clean; "date arithmetic belongs in its own package"
    reverse-engineering-timestamp.md        when, which commit, and a fingerprint of what was scanned
  and in java-workspace/.claude/
  settings.local.json                       your "Yes" wrote "disableAllHooks": false here (this machine only)

codekb/priorauth-api/code-structure.mdreal file from java-workspace/

codekb/priorauth-api/technology-stack.md

codekb/priorauth-api/component-inventory.md

codekb/priorauth-api/code-quality-assessment.md

Why the settings prompt. AI-DLC's checks run as Claude Code hooks. On the first run in a new workspace the tool checks they are firing; when it can't see them yet, it asks Claude to set "disableAllHooks": false in .claude/settings.local.json (your machine's settings, not the team's), and Claude Code asks you first. Choose Yes. If Claude Code shows no prompt, the hooks were already seen and there is nothing to do. Your codekb wording will differ from the files below; the nine names and the fingerprint will not.

Gate 1 of 4: is the scan right?

Meena skimmed the nine files in three minutes. The one that matters later is technology-stack.md: "no dependency without a reason" becomes requirement NFR1 without anyone typing it. code-quality-assessment.md's last line decides where the new code goes.

Approved at step 7 by Meena Iyer (tech lead) · 09:41

In plain words. Before cooking in someone else's kitchen you open the cupboards and write down what is where. Next time, you read the note instead of opening every cupboard again.

2.3 Requirements Analysis

Approve the scan. Before writing any requirement, Claude writes down what the message did not say, as four questions with lettered answers

A test can check "FR1.1: Saturday and Sunday are not business days". It cannot check "weekends should not count". This stage makes that translation, and it starts by asking instead of guessing: the questions go into a file, each with options A, B, C and "X. Other".

Kiran · 09:41

You type

Claude returns abridged · wording from a real 2.11.0 run

Before I write the requirements, I need four things pinned down. The nightly report that already
computes AGE isn't in this workspace, so I can't copy its exact rule from the code. The four questions
are in aidlc/spaces/default/intents/261013-request-age-api/inception/requirements-analysis/requirements-analysis-questions.md:
  - how the age is counted: whether the day a request arrived counts
  - whether "over-5" means more than 5, or 5 and over
  - where the holiday list comes from
  - which time zone decides what "today" is
▸ How would you like to answer them?
  1. Guide me: I'll walk you through each question here
  2. I'll edit the file: you fill in the answers in the file yourself
  3. Chat: we talk it through and I pull the decisions out of the conversation
  4. Other

On disk now

java-workspace/aidlc/spaces/default/intents/261013-request-age-api/
  inception/                                the Inception phase's folder; one sub-folder per stage that ran
    reverse-engineering/developer-scan-priorauth-api.md   the scan's notes for this run (the codekb is the reusable part)
    requirements-analysis/
      requirements-analysis-questions.md    four questions, lettered options, an empty [Answer]: line under each
  audit/0002-2-1-reverse-engineering.md      your "1"
java-workspace/.git                          a commit of aidlc/, if you allowed it (see below)

If Claude Code asks to run git add aidlc/ && git commit …, choose Yes. Your CLAUDE.md says "commit it after every gate", so Claude commits the record in the workspace repo after approvals; the first time, Claude Code asks you. Some commits wait: while a code plan waits for approval (steps 11–12), AI-DLC blocks commands that change files outside the record, git included, so that commit lands once the plan is approved. If you say No, Claude tells you and carries on; step 17 commits whatever is left.

The AI askedDoes the arrival day count? Is "over 5" more than 5, or 5 and over? Where do holidays come from? Which time zone is "today"?

Who decidedRavi Menon (day 0 and more than 5, same as the report; a flag, no alerting). Meena Iyer (holiday file in the API for now; the server's zone).

Kiran didWalked to Ravi's desk with the file open, then typed the answers with their names at step 8.

inception/requirements-analysis/requirements-analysis-questions.mdshown with the answers filled in at steps 8 and 9

# Requirements Analysis — Questions

Context: the request (Ravi Menon, 13 Oct) asks the pending list from `GET /requests/pending` to carry "the same business-day age and the over-5 flag" as the nightly report, where weekends and the org's holidays don't count. The nightly report's code is not in this workspace, so its exact rule can't be read off. These questions pin it down so the API matches the report.

## Question 1
How should the business-day age be counted? It depends on whether the day the request arrived counts. For example, a request received on Thursday 8 Oct 2026, viewed on Tuesday 13 Oct 2026 (Monday 12 Oct is a weekday):

A. Count business days after the received date, up to and including today (received day does not count). A request received today has age 0.
B. Count business days including both the received date and today. A request received today has age 1.
C. Count business days after the received date, up to but not including today (whole business days elapsed before today).
X. Other (please specify)

[Answer]: A — the received day is day 0, same as the report. (Ravi Menon, 09:47) **Mode:** chat

## Question 2
When should the "over-5" flag be true?

A. When the age is strictly greater than 5 business days (6 or more)
B. When the age is 5 business days or more
X. Other (please specify)

[Answer]: A — over means more than 5; the threshold is 5, from configuration. (Ravi Menon, 09:47) **Mode:** chat

## Question 3
Where should the list of org holidays come from? Nothing in the API knows about holidays today, and the nightly report's holiday list lives elsewhere.

A. A list of dates in the API's configuration (`application.yml`), which the team updates each year
B. A list of dates in a data file bundled with the API (like the existing sample data), updated each year
C. Read from the same source the nightly report uses (please name it), so the two can never disagree
D. Hard-code the 2026 US federal holidays for now
X. Other (please specify)

[Answer]: B — the same TX-01 list the report uses, as a JSON file in the API resources for now. (Meena Iyer, 09:47) **Mode:** chat

## Question 4
Which time zone decides what "today" is? This matters near midnight, and the received date has no time or zone attached.

A. The org's local time zone (please name it)
B. UTC
C. Whatever time zone the server runs in
X. Other (please specify)

[Answer]: C — the server's zone; callers can pass asOf. The API returns a flag and never refuses or alerts. (Ravi Menon, Meena Iyer, 09:47) **Mode:** chat

## Follow-up 1
You chose the TX-01 holiday list the nightly report uses (Question 3), but its dates aren't anywhere in this workspace, so I can't copy them. This matters right away: Monday 12 Oct 2026 falls inside the sample data's date range, and whether it is a TX-01 holiday changes the ages.

A. I'll paste the TX-01 holiday dates here
B. I'll point you to a file in the workspace that holds them
C. Ship the file with no dates for now (weekends only) and add the dates later
X. Other (please specify)

[Answer]: A — the 2026 TX-01 holidays are 2026-01-01, 2026-01-19, 2026-02-16, 2026-05-25, 2026-07-03, 2026-09-07, 2026-10-12, 2026-11-11, 2026-11-26, 2026-11-27, 2026-12-25. (Meena Iyer, 09:49) **Mode:** chat

## Follow-up 2
TX-01 is a tenant id, and every sample request belongs to TX-01. What should happen for a request from any other tenant?

A. Use the TX-01 list for every tenant for now (one org-wide holiday list)
B. Key the holiday file by tenant. Only TX-01 has dates; other tenants count weekends only
X. Other (please specify)

[Answer]: B — one file per tenant; a shared calendar service is a separate intent. (Meena Iyer, 09:49) **Mode:** chat

In plain words. "Make it spicy" becomes "two green chillies, not three", and before cooking the cook writes down the four things the customer forgot to say, with the likely answers ticked off, instead of deciding them alone.

2.3 Requirements Analysis

Pick `3` (Chat), then answer the four questions in one message, with the names of the people who decided

AI-DLC records one reply per question, and "how would you like to answer?" is a question too. Answer it first, on its own, then send all four answers together: one letter per question, plus anything Claude should know.

Kiran · 09:44 → 09:47

You type first message

You type second message, when Claude asks for the answers

1 A: the received day is day 0, same as the report. 2 A: over means more than 5; the threshold is 5, from configuration. 3 B: the same TX-01 list the report uses, as a JSON file in the API resources for now. 4 C: the server's zone; callers can pass asOf. The API returns a flag and never refuses or alerts. (Ravi, Meena)

Claude returns abridged · wording from a real 2.11.0 run

I've written your four answers into the questions file. Two follow-ups came out of them, and you can
answer them in the same reply.

Follow-up 1: the TX-01 holiday dates. You chose the TX-01 list the nightly report uses, but its dates
aren't anywhere in this workspace. This affects the results straight away, because Monday 12 Oct 2026
falls inside the sample data's date range.
  1. I'll paste the TX-01 holiday dates here
  2. I'll point you to a file in the workspace that has them
  3. Ship the file with no dates for now (only weekends are skipped) and add the dates later
  4. Other

Follow-up 2: other tenants. TX-01 is a tenant id, and every sample request belongs to TX-01. What
should happen to a request from any other tenant?
  1. Use the TX-01 list for every tenant for now (one org-wide holiday list)
  2. Key the holiday file by tenant. Only TX-01 has dates, so other tenants skip weekends only
  3. Other
▸ Reply with each question's number and the number of your choice (for example F1: 1, F2: 2), or just tell me.

Why 3 first. In our real run we sent the answers straight away, without picking from the menu. Claude wrote them into the file, but AI-DLC refused to record them, and Claude said "Your answer didn't reach AI-DLC. Please give it once more." That message had already been used up answering the menu. Sending the answers again ("same as before") worked. Picking 3 on its own first avoids the round trip; we took the long way, so Claude's short reply to 3 is not shown. 1 walks you through one question at a time; 2 lets you type after each [Answer]: in the file and then say "done".

Why the follow-ups. Your answers created two new gaps: "the list the report uses" names a list Claude cannot see, and "TX-01" is one tenant of several. Claude asks rather than shipping an empty holiday file or guessing a rule for the other tenants. Expect your follow-ups to differ: they come from what your answers left open.

2.3 Requirements Analysis

Answer the two follow-ups. Claude writes the requirements and lists what it still had to assume

Only now does requirements.md appear. Read the assumptions at the end of Claude's reply first: each is a gap Claude filled on its own, and some of them other people's code will depend on.

Kiran · 09:49

You type one message

F1: 1, the 2026 TX-01 holidays are 2026-01-01, 2026-01-19, 2026-02-16, 2026-05-25, 2026-07-03, 2026-09-07, 2026-10-12, 2026-11-11, 2026-11-26, 2026-11-27, 2026-12-25. F2: 2, one file per tenant; a shared calendar service is a separate intent. (Meena)

Claude returns abridged · wording from a real 2.11.0 run, this story's names and numbers

Requirements Analysis complete
  FR1    business-day age: each pending row gets its age. The day a request was received is day 0.
         Weekends and the tenant's holidays are skipped. Optional asOf; without it, today (server's zone)
  FR2    over-limit flag: true only when the age is more than the threshold. The threshold is 5 by
         default and is set in configuration. The API never refuses or alerts on it.
  FR3    the new values are only added: existing fields and the oldest-first order are unchanged
  NFR1   no new dependencies
Worked check against the sample data as of Tue 2026-10-13:
  PA-10231 is age 7 and flagged. PA-10244 is age 4 and not flagged. Mon 12 Oct is a TX-01 holiday.

I made four assumptions you may want to change now:
  Field names: businessDayAge and overAgeThreshold. The request doesn't name them.
  Config key and files: the threshold is priorauth.age.threshold-business-days, and the files are
    holidays/<tenant>-<year>.json.
  Before the received date: if the as-of date is earlier than the received date, the age is 0.
  Ages that cross a year: each year uses its own holiday file.
Review: aidlc/spaces/default/intents/261013-request-age-api/inception/requirements-analysis/
▸ Requirements Analysis is done. How would you like to proceed?
  1. Approve: continue to Code Generation   2. Request Changes: tell me what to revise   3. Other

On disk now

java-workspace/aidlc/spaces/default/intents/261013-request-age-api/inception/requirements-analysis/
  requirements.md                         FR1…FR3, NFR1, assumptions, out of scope. One page: Minimal depth.
  requirements-analysis-questions.md      every [Answer]: line filled in, with the names you gave

2.3 Requirements Analysis

Request Changes with `2`: the names the screen team already uses, and one rule

2 does not mean "wrong". It means "change the artifact, then ask me again". Everything after the 2 is the correction; Claude rewrites requirements.md and comes back to the same gate. Now, a field name is one line in a markdown file; after step 12 it is a rename across code and tests.

Kiran · 09:53

You type one message

2  The screen team already named the fields: ageBusinessDays (integer), overLimit (boolean) and ageLabel (text such as "7 bd OVER 5"). Config key priorauth.aging.threshold-days. Holiday files at data/holidays-<tenant>-2026.json. An as-of date before the received date is a caller error, not age 0. (Meena)

Claude returns abridged · wording from a real 2.11.0 run, this story's numbers

Requirements Analysis revised
I made these changes in requirements.md:
  Fields: they're now ageBusinessDays (integer), overLimit (boolean) and ageLabel (text) (FR3)
  Config key: priorauth.aging.threshold-days (FR2)
  Holiday files: data/holidays-<tenant>-2026.json, for example data/holidays-TX-01-2026.json (FR1.2)
  As-of date before the received date: this is now a caller error (FR1). Before, I had assumed an age of 0.

I had to assume one thing. You gave the label for an over-limit request ("7 bd OVER 5") but not the
label for one under the limit. I've used "<age> bd" for those, for example "4 bd".
  id (as of 2026-10-13)   ageBusinessDays   overLimit   ageLabel
  PA-10231                7                 true        7 bd OVER 5
  PA-10244                4                 false       4 bd
  PA-10263                1                 false       1 bd
▸ How would you like to proceed?
  1. Approve: continue to Code Generation   2. Request Changes: tell me what to revise   3. Other

inception/requirements-analysis/requirements.mdreal file · the page the tests are named after

# Requirements: request age on the pending list (intent 261013-request-age-api, express, Minimal depth)

## Intent analysis
The reviewer screen reads `GET /requests/pending` from priorauth-api and must show how long each request has waited,
in business days, and which ones are over the tenant's limit, with the same rule the nightly report already uses.
Source: docs-in/request.md (Ravi Menon). The endpoint, its path and its existing fields do not change.

## Functional requirements
- FR1  Each pending row carries its age in business days as of a date. The request may pass `?asOf=YYYY-MM-DD`; without it, today in the server's time zone (Question 4).
  The received day is day 0 (A-01, confirmed: Question 1). An as-of date before the received date is a caller error.
- FR1.1  Saturday and Sunday are not business days.
- FR1.2  The tenant's holidays are not business days. Source: one JSON file per tenant under `src/main/resources/data/`,
  the same list the nightly report uses (Question 3, follow-ups 1 and 2). A tenant without a file has no holidays.
- FR2  A row is over the limit when its age is strictly greater than the threshold (Question 2). Threshold: 5, from configuration
  (`priorauth.aging.threshold-days`), so an environment or tenant can override it without a code change.
- FR3  The new values travel in the existing response: `ageBusinessDays` (integer), `overLimit` (boolean) and
  `ageLabel` (text such as "7 bd OVER 5") on every row. No new endpoint, no new call for the screen.

## Non-functional requirements
- NFR1  No new dependencies: pom.xml changes only its version. (Constraint from codekb/technology-stack.md.)

## Assumptions
- A-01  The received day counts as day 0. Confirmed by Ravi Menon, 09:47.
- A-02  Only the API changes in this intent; the screen shows the new fields in its own change later (out of scope).

## Out of scope
- Changing the screen; changing the report; alerting when something is over the limit (answer to Question 4: that is observability, not the API).

Gate 2 of 4: the requirements, after one Request Changes

Every line in requirements.md now says where it came from: the message, a question, a follow-up or the repo. FR1…FR3 and NFR1 are the names the tests and the traceability file will use. Nothing about how yet.

Approved at step 11 by Ravi Menon and Meena Iyer · 09:56

3.5 Code Generation · plan

Approve the requirements and turn plan approval on. Inception is done; Claude writes the plan and stops for it

Express skips design and unit decomposition, so the plan is the design: which files, created or changed, covering which requirement, and the branch they go on. Reading it is the cheapest moment to change your mind, but express does not stop there by default, so you ask it to.

Kiran · 09:56 → 10:03

You type

1, and turn plan approval on: Meena reads every plan before code is written

Claude returns abridged · wording from a real 2.11.0 run, this story's numbers · 7 minutes

Plan Approval changed: off (from scope express) to on (set by a command)
Each code plan is now shown for approval before it is built.
Progress: 2/7 in-scope stages complete | 2/2 INCEPTION. Next: Code Generation
  … Claude reads the code-generation rules and the repo, then writes the plan …
The code plan is ready for Meena to review.

Approve the code plan?
  Builds: business-day age, over-limit flag and age label on each row of GET /requests/pending,
          with an optional asOf date and a holiday file per tenant
  Touches: priorauth-api/src/main/java/com/acmehealth/priorauth/{api,aging}/, application.yml, new
          data/holidays-TX-01-2026.json, pom.xml (version only), README.md, tests under src/test/java/...
  Tests: 7 new tests (4 for the age rule, 1 for the flag, 2 endpoint tests); the 3 existing tests stay green
Plan: aidlc/spaces/default/intents/261013-request-age-api/construction/code-generation/code-generation-plan.md
Test instructions: aidlc/spaces/default/intents/261013-request-age-api/construction/code-generation/unit-test-instructions.md
  - It adds no new dependencies; pom.xml changes its version only.
  - The work goes on a branch called request-age/u1-age-api, and the last step commits there.
    Pushing and opening the PR are left to the team.
▸ 1. Approve Plan   2. Request Changes   3. I'll edit the files

On disk now

java-workspace/aidlc/spaces/default/intents/261013-request-age-api/
  construction/                             the Construction phase's folder
    code-generation/
      code-generation-plan.md               four steps; the file table below; requirement → step
      unit-test-instructions.md             how the tests run, and how many to expect
      code-generation-questions.md          the same question as a file: answer after [Answer]: and say done
  aidlc-state.md                            Plan Approval: off (from scope express) → on (set by a command)
  audit/0003-2-3-requirements-analysis.md    the menu, the answers, the follow-ups, your "2 …" and your "1", with names

construction/code-generation/code-generation-plan.mdapproved before any file was written

# Code Generation Plan — Request age on the pending list (priorauth-api)

Express scope, zero Units: one stage-level implementation for the whole change. Repo: priorauth-api.
Workspace rules (CLAUDE.md): one unit = one branch = one PR, branch pattern `request-age/<slug>`; tests through
`./scripts/verify.sh` (`scripts\verify.cmd`); a new pom.xml dependency must be declared here (there is none).

## Steps
- [ ] Step 1 — Branch and baseline. In `priorauth-api/`, create `request-age/u1-age-api` from `main`; run `./scripts/verify.sh`
  and record the baseline: 3 existing tests, all passing.
- [ ] Step 2 — Files, in this order:

| # | File | Action | Covers |
|---|---|---|---|
| 1 | src/main/java/com/acmehealth/priorauth/aging/BusinessDays.java | create: `isBusinessDay`, `between` (strictly after start, up to and including end) | FR1, FR1.1, FR1.2 |
| 2 | src/main/java/com/acmehealth/priorauth/aging/AgeBadge.java | create: record `businessDays`, `overLimit`, `thresholdDays`; `of(...)`, `label()` | FR2, FR3 |
| 3 | src/main/java/com/acmehealth/priorauth/aging/HolidayCalendar.java | create: `@Service`, loads `data/holidays-<tenant>-2026.json`, empty set when absent | FR1.2 |
| 4 | src/main/resources/data/holidays-TX-01-2026.json | create: the 11 TX-01 dates (follow-up 1) | FR1.2 |
| 5 | src/main/java/com/acmehealth/priorauth/api/PendingRequestResponse.java | change: add `ageBusinessDays`, `overLimit`, `ageLabel`; `from(request, badge)` | FR3 |
| 6 | src/main/java/com/acmehealth/priorauth/api/PendingRequestsController.java | change: `?asOf` (ISO date, default today; before a received date → 400), inject `HolidayCalendar` and the threshold | FR1, FR2, FR3 |
| 7 | src/main/resources/application.yml | change: `priorauth.aging.threshold-days: 5` | FR2 |
| 8 | src/test/java/com/acmehealth/priorauth/aging/BusinessDaysTest.java | create: day zero, weekend, holiday, as-of before received (4 tests) | FR1, FR1.1, FR1.2 |
| 9 | src/test/java/com/acmehealth/priorauth/aging/AgeBadgeTest.java | create: 5 not flagged, 6 flagged, labels (1 test) | FR2 |
| 10 | src/test/java/com/acmehealth/priorauth/api/PendingRequestsControllerTest.java | change: add two tests, `?asOf=2026-10-13` → PA-10231 7 / true, PA-10244 4 / false; `?asOf=2026-09-30` → 400 | FR1, FR3 |
| 11 | pom.xml | change: version 1.0.2 → 1.1.0, nothing else | NFR1 |
| 12 | README.md | change: usage line | — |

- [ ] Step 3 — Verify. Run `./scripts/verify.sh`. Expected: 10 tests (3 existing + 7 new), 0 failures.
- [ ] Step 4 — Commit on `request-age/u1-age-api`. Pushing and opening the PR are the team's.

Not touched: PriorAuthApiApplication, PriorAuthRequest, RequestStore, RequestStoreTest, the sample export, the endpoint path.

## Requirement → Step Traceability
FR1, FR1.1, FR1.2 → files 1, 3, 4, 6, 8, 10 · FR2 → files 2, 6, 7, 9 · FR3 → files 2, 5, 6, 10 · NFR1 → file 11

Why "turn plan approval on". The express scope ships with plan approval off (aidlc-state.md said Plan Approval: off (from scope express)). Left off, Claude writes the plan, says it is starting code generation, asks whether you want to look at the plan first, and starts building without waiting. Your team reviews every plan (CLAUDE.md: a new dependency must be named in the plan), so you switch it on in plain words. Claude runs aidlc engine config set plan-approval on for you, which is why the state line reads on (set by a command), and the plan stop below exists.

How to read the plan in 60 seconds. Every file row has a requirement in the last column; a row with "—" is housekeeping (README). Nothing in src/main/java/.../store or model is touched, which is what "nothing else changes" meant. The new code gets its own package, aging, because code-quality-assessment.md said date arithmetic does not belong in the controller. Steps 1 and 4 are the git work: Claude makes the branch your CLAUDE.md pattern asks for (request-age/<slug>) and commits on it.

A stop inside 3.5, not a gate: the plan

Meena read the plan on her screen while Kiran waited: four steps, twelve file rows, every one with a requirement, the branch name, no new dependency. She did not have to ask for the plan: turning plan approval on made Claude stop here.

Plan approved at step 12 by Meena Iyer · 10:03

In plain words. The cook shows you the recipe card before touching a pan: these six new things, these six small changes, this is how we will taste it. You can still say "no onions".

Constructionstages 3.5 and 3.6 · the code on its branch, then a second check · 10:03 – 10:55

3.5 Code Generation

Approve the plan. Claude makes the branch, writes the twelve files, runs the team's script, and commits

This is the step where code appears. Claude follows the plan's four steps: a branch from main with one baseline test run, the files, ./scripts/verify.sh, a commit. The gate question only arrives after the script has passed and the commit exists; if a test had failed, Claude would fix and re-run before asking.

Kiran · 10:03 → 10:41

You type

You choose in Claude Code's permission prompts, a few times

Yes   # to run scripts/verify.sh (scripts\verify.cmd on Windows) and git in priorauth-api

Claude returns abridged · 35 minutes incl. the first Maven download

Switched to a new branch 'request-age/u1-age-api' (from main) · baseline: ./scripts/verify.sh, 3 tests, 0 failures
  create  src/main/java/com/acmehealth/priorauth/aging/BusinessDays.java
  create  src/main/java/com/acmehealth/priorauth/aging/AgeBadge.java
  create  src/main/java/com/acmehealth/priorauth/aging/HolidayCalendar.java
  create  src/main/resources/data/holidays-TX-01-2026.json
  modify  src/main/java/com/acmehealth/priorauth/api/PendingRequestResponse.java
  modify  src/main/java/com/acmehealth/priorauth/api/PendingRequestsController.java
  modify  src/main/resources/application.yml
  create  src/test/java/com/acmehealth/priorauth/aging/BusinessDaysTest.java
  create  src/test/java/com/acmehealth/priorauth/aging/AgeBadgeTest.java
  modify  src/test/java/com/acmehealth/priorauth/api/PendingRequestsControllerTest.java
  modify  pom.xml (version 1.0.2 → 1.1.0, nothing else)   modify  README.md
Running ./scripts/verify.sh …  Tests run: 10, Failures: 0, Errors: 0, Skipped: 0 · BUILD SUCCESS  (exit 0)
[request-age/u1-age-api b477c4e] request age and over-limit flag on the pending list (intent 261013-request-age-api, U1)
 12 files changed, 230 insertions(+), 10 deletions(-)
Code Generation complete
The feature is built and committed as b477c4e on request-age/u1-age-api in priorauth-api/. It hasn't been
pushed. The full test run passed 10 of 10: the 3 existing tests and 7 new ones. pom.xml changes its version only.
Review: aidlc/spaces/default/intents/261013-request-age-api/construction/code-generation/ (start with code-summary.md)
▸ How would you like to proceed?
  1. Approve: continue to Build and Test   2. Request Changes: tell me what to revise   3. Other

If Claude says the feature was already built. Your clone of the starter repo carries tag v1.1.0, the answer key. In our real run Claude found it before writing any code, saw that it holds this very change (PR #58, not on main), and asked whether to rebuild from main, build on that code, or stop. Answer 1, rebuild from main: the tag is the course's answer key, not your team's history.

On disk now

java-workspace/priorauth-api/                       on branch request-age/u1-age-api · commit b477c4e · 12 files touched
  pom.xml                                            changed: version only
  README.md                                          changed: usage line
  src/main/java/com/acmehealth/priorauth/
    aging/BusinessDays.java                            new: the arithmetic. 36 lines, no Spring in it
    aging/AgeBadge.java                                new: days + over-limit flag + label, as a record
    aging/HolidayCalendar.java                         new: @Service; reads holidays-<tenant>-2026.json once
    api/PendingRequestResponse.java                    changed: three new JSON fields
    api/PendingRequestsController.java                 changed: ?asOf (400 if too early), holiday calendar, threshold
  src/main/resources/
    application.yml                                    changed: priorauth.aging.threshold-days: 5
    data/holidays-TX-01-2026.json                      new: the 11 dates from follow-up 1
  src/test/java/com/acmehealth/priorauth/
    aging/BusinessDaysTest.java                        new: 4 tests (FR1, FR1.1, FR1.2, the error case)
    aging/AgeBadgeTest.java                            new: 1 test (FR2: 5 is not flagged, 6 is)
    api/PendingRequestsControllerTest.java             changed: 2 new tests (FR3: the JSON carries the fields; FR1: asOf too early → 400)
  target/                                            appeared when Maven ran; ignored by git
java-workspace/aidlc/.../261013-request-age-api/construction/code-generation/
  code-summary.md  traceability.json

New files (the whole file, runs as shown):

src/main/java/com/acmehealth/priorauth/aging/BusinessDays.javanew · pure Java, no Spring

package com.acmehealth.priorauth.aging;

import java.time.DayOfWeek;
import java.time.LocalDate;
import java.util.Set;

/**
 * Business-day arithmetic for request age (intent 261013-request-age-api, FR1).
 * Age counts business days strictly after the received date up to and including the as-of date, so a request
 * received on Monday has age 0 on Monday and age 1 on Tuesday (assumption A-01, confirmed by Ravi Menon).
 * Weekends and the tenant's holidays are not business days (FR1.1, FR1.2).
 */
public final class BusinessDays {

private BusinessDays() {
    }

public static boolean isBusinessDay(LocalDate day, Set<LocalDate> holidays) {
        DayOfWeek dow = day.getDayOfWeek();
        return dow != DayOfWeek.SATURDAY && dow != DayOfWeek.SUNDAY && !holidays.contains(day);
    }

/** Business days strictly after {@code start}, up to and including {@code end}. */
    public static int between(LocalDate start, LocalDate end, Set<LocalDate> holidays) {
        if (end.isBefore(start)) {
            throw new IllegalArgumentException("as-of date " + end + " is before the received date " + start);
        }
        int days = 0;
        for (LocalDate cursor = start.plusDays(1); !cursor.isAfter(end); cursor = cursor.plusDays(1)) {
            if (isBusinessDay(cursor, holidays)) {
                days++;
            }
        }
        return days;
    }
}

src/main/java/com/acmehealth/priorauth/aging/AgeBadge.javanew · a record

src/main/java/com/acmehealth/priorauth/aging/HolidayCalendar.javanew · a Spring @Service

package com.acmehealth.priorauth.aging;

import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Service;
import tools.jackson.databind.JsonNode;
import tools.jackson.databind.json.JsonMapper;

import java.io.IOException;
import java.io.InputStream;
import java.time.LocalDate;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;

/**
 * The tenant's holidays (FR1.2): one JSON file per tenant under resources/data, the same list the nightly report uses.
 * A tenant without a file has no holidays, which is the safe default (the age is then slightly higher, never lower).
 */
@Service
public class HolidayCalendar {

private final JsonMapper mapper;
    private final Map<String, Set<LocalDate>> cache = new ConcurrentHashMap<>();

public HolidayCalendar(JsonMapper mapper) {
        this.mapper = mapper;
    }

public Set<LocalDate> forTenant(String tenantId) {
        return cache.computeIfAbsent(tenantId, this::load);
    }

private Set<LocalDate> load(String tenantId) {
        ClassPathResource file = new ClassPathResource("data/holidays-" + tenantId + "-2026.json");
        if (!file.exists()) {
            return Set.of();
        }
        try (InputStream in = file.getInputStream()) {
            JsonNode root = mapper.readTree(in);
            Set<LocalDate> holidays = new HashSet<>();
            root.get("holidays").forEach(node -> holidays.add(LocalDate.parse(node.asString())));
            return Set.copyOf(holidays);
        } catch (IOException e) {
            throw new IllegalStateException("cannot read holidays for tenant " + tenantId, e);
        }
    }
}

src/main/resources/data/holidays-TX-01-2026.jsonnew

src/test/java/com/acmehealth/priorauth/aging/BusinessDaysTest.javanew · one test per requirement

package com.acmehealth.priorauth.aging;

import org.junit.jupiter.api.Test;

import java.time.LocalDate;
import java.util.Set;

import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;

/** One test per requirement (Minimal test strategy), intent 261013-request-age-api. */
class BusinessDaysTest {

private static final Set<LocalDate> NO_HOLIDAYS = Set.of();
    private static final LocalDate MON_12_OCT = LocalDate.of(2026, 10, 12);

@Test // FR1, A-01: the day a request arrives is day 0
    void receivedTodayHasAgeZero() {
        assertThat(BusinessDays.between(MON_12_OCT, MON_12_OCT, NO_HOLIDAYS)).isZero();
        assertThat(BusinessDays.between(MON_12_OCT, MON_12_OCT.plusDays(1), NO_HOLIDAYS)).isEqualTo(1);
    }

@Test // FR1.1: Saturday and Sunday do not count
    void weekendIsNotCounted() {
        LocalDate fri9 = LocalDate.of(2026, 10, 9);
        assertThat(BusinessDays.between(fri9, MON_12_OCT, NO_HOLIDAYS)).isEqualTo(1);
    }

@Test // FR1.2: a tenant holiday does not count
    void tenantHolidayIsNotCounted() {
        LocalDate fri9 = LocalDate.of(2026, 10, 9);
        assertThat(BusinessDays.between(fri9, MON_12_OCT, Set.of(MON_12_OCT))).isZero();
    }

@Test // FR1: an as-of date before the received date is a caller error, not an age of -1
    void asOfBeforeReceivedIsAnError() {
        assertThatThrownBy(() -> BusinessDays.between(MON_12_OCT, MON_12_OCT.minusDays(1), NO_HOLIDAYS))
                .isInstanceOf(IllegalArgumentException.class);
    }
}

src/test/java/com/acmehealth/priorauth/aging/AgeBadgeTest.javanew · the 5/6 boundary

Changed files (the diff: red lines went away, green lines arrived):

src/main/java/com/acmehealth/priorauth/api/PendingRequestsController.javadiff · ?asOf, the calendar, the threshold, the 400

--- a/src/main/java/com/acmehealth/priorauth/api/PendingRequestsController.java
+++ b/src/main/java/com/acmehealth/priorauth/api/PendingRequestsController.java
@@ -1,23 +1,45 @@
 package com.acmehealth.priorauth.api;
 
+import com.acmehealth.priorauth.aging.AgeBadge;
+import com.acmehealth.priorauth.aging.HolidayCalendar;
 import com.acmehealth.priorauth.store.RequestStore;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.format.annotation.DateTimeFormat;
+import org.springframework.http.HttpStatus;
 import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
 
+import java.time.LocalDate;
 import java.util.List;
 
-/** GET /requests/pending: the list the reviewer screen shows, oldest first. */
+/** GET /requests/pending[?asOf=YYYY-MM-DD]: the list the reviewer screen shows, oldest first, with its age (FR3). */
 @RestController
 public class PendingRequestsController {
 
     private final RequestStore store;
+    private final HolidayCalendar holidays;
+    private final int thresholdDays;
 
-    public PendingRequestsController(RequestStore store) {
+    public PendingRequestsController(RequestStore store, HolidayCalendar holidays,
+                                     @Value("${priorauth.aging.threshold-days:5}") int thresholdDays) {
         this.store = store;
+        this.holidays = holidays;
+        this.thresholdDays = thresholdDays;
     }
 
     @GetMapping("/requests/pending")
-    public List<PendingRequestResponse> pending() {
-        return store.pending().stream().map(PendingRequestResponse::from).toList();
+    public List<PendingRequestResponse> pending(
+            @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate asOf) {
+        LocalDate day = asOf != null ? asOf : LocalDate.now();
+        try {
+            return store.pending().stream()
+                    .map(r -> PendingRequestResponse.from(r,
+                            AgeBadge.of(r.receivedAt(), day, holidays.forTenant(r.tenantId()), thresholdDays)))
+                    .toList();
+        } catch (IllegalArgumentException e) { // FR1: an as-of date before a received date is the caller's error
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, e.getMessage(), e);
+        }
     }
 }

src/main/java/com/acmehealth/priorauth/api/PendingRequestResponse.javadiff · three new fields

--- a/src/main/java/com/acmehealth/priorauth/api/PendingRequestResponse.java
+++ b/src/main/java/com/acmehealth/priorauth/api/PendingRequestResponse.java
@@ -1,5 +1,6 @@
 package com.acmehealth.priorauth.api;
 
+import com.acmehealth.priorauth.aging.AgeBadge;
 import com.acmehealth.priorauth.model.PriorAuthRequest;
 
 import java.time.LocalDate;
@@ -10,10 +11,13 @@ public record PendingRequestResponse(
         String tenantId,
         String service,
         String status,
-        LocalDate receivedAt) {
+        LocalDate receivedAt,
+        int ageBusinessDays,
+        boolean overLimit,
+        String ageLabel) {
 
-    public static PendingRequestResponse from(PriorAuthRequest request) {
+    public static PendingRequestResponse from(PriorAuthRequest request, AgeBadge age) {
         return new PendingRequestResponse(request.id(), request.tenantId(), request.service(), request.status(),
-                request.receivedAt());
+                request.receivedAt(), age.businessDays(), age.overLimit(), age.label());
     }
 }

src/test/java/com/acmehealth/priorauth/api/PendingRequestsControllerTest.javadiff · two new tests

--- a/src/test/java/com/acmehealth/priorauth/api/PendingRequestsControllerTest.java
+++ b/src/test/java/com/acmehealth/priorauth/api/PendingRequestsControllerTest.java
@@ -26,4 +26,23 @@ class PendingRequestsControllerTest {
                 .andExpect(jsonPath("$[0].id").value("PA-10231"))
                 .andExpect(jsonPath("$[0].receivedAt").value("2026-10-01"));
     }
+
+    @Test // FR3: the age and the flag travel with each row; 1 Oct -> 13 Oct is 7 business days (12 Oct is a TX-01 holiday)
+    void eachRowCarriesItsAgeAndFlag() throws Exception {
+        mvc.perform(get("/requests/pending").param("asOf", "2026-10-13"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].id").value("PA-10231"))
+                .andExpect(jsonPath("$[0].ageBusinessDays").value(7))
+                .andExpect(jsonPath("$[0].overLimit").value(true))
+                .andExpect(jsonPath("$[0].ageLabel").value("7 bd OVER 5"))
+                .andExpect(jsonPath("$[1].id").value("PA-10244"))
+                .andExpect(jsonPath("$[1].ageBusinessDays").value(4))
+                .andExpect(jsonPath("$[1].overLimit").value(false));
+    }
+
+    @Test // FR1: PA-10231 arrived on 1 Oct, so an as-of of 30 Sep is the caller's error: 400, not 500
+    void asOfBeforeReceivedIsABadRequest() throws Exception {
+        mvc.perform(get("/requests/pending").param("asOf", "2026-09-30"))
+                .andExpect(status().isBadRequest());
+    }
 }

src/main/resources/application.ymldiff

pom.xmldiff · NFR1: the version and nothing else

The record Claude wrote beside the code:

construction/code-generation/traceability.jsonrequirement → files → tests

construction/code-generation/code-summary.mdunedited, becomes the pull request description at step 14

# Code summary: priorauth-api (3.5)

**Intent** 261013-request-age-api · **Scope** express · **Requirements** FR1–FR3, NFR1 · **Branch** request-age/u1-age-api · **Commit** b477c4e

**What changed.** New package `com.acmehealth.priorauth.aging`: `BusinessDays` (pure business-day arithmetic, received day = day 0,
weekends and tenant holidays excluded), `AgeBadge` (days, over-limit flag, label) and `HolidayCalendar` (one JSON file per tenant
under resources, the same TX-01 list the report uses). `GET /requests/pending` takes an optional `?asOf=YYYY-MM-DD` and every row
now carries `ageBusinessDays`, `overLimit` and `ageLabel`. The threshold comes from `priorauth.aging.threshold-days` (default 5).
An `asOf` before a request's received date answers 400. Version 1.0.2 → 1.1.0.

**What did not change.** The endpoint path, the existing fields, `RequestStore`, the model, the sample export, the dependencies.

**Verification.** `./scripts/verify.sh`: 10 tests, 7 new (one per requirement, the 5/6 boundary and the 400), 0 failures.

**Open.** Holiday data covers TX-01 2026 only; each later year and each other tenant needs its own file (without one, only
weekends are skipped). Pushing the branch and opening the PR are the team's.

construction/code-generation/unit-test-instructions.md

Your code will differ, and that is fine. The plan fixes the files' jobs, not their text. In our real run Claude wrote other class names (BusinessDayAgeCalculator, an injectable Clock) and 14 new tests instead of 7, and its API answered the curl at step 13 with the same numbers. What you check is the same: every requirement has a test, the script passed, the diff matches the plan.

What Claude wroteThe branch, all twelve files, the commit, and two record files. It ran the script twice: before (3 tests) and after (10).

What Kiran checkedOpened BusinessDays.java and the controller diff in the IDE; ran git -C priorauth-api show --stat; read traceability.json against the plan.

What Meena checkedThe diff of b477c4e: no new import from outside the two starters, the loop in between, the default in @Value.

Gate 3 of 4: Code Generation

The question arrived with the proof attached: the script's result and the commit. Approving means "this commit is the change". Request Changes would send Claude back to the files with your comment; it would run the script again and commit again before the next question. Express has no units: Code Generation runs once, for the whole change. "U1" in the branch and the commit is the team's name for it, from CLAUDE.md's "one unit = one branch = one PR".

Approved at step 13 by Meena Iyer, after reading the diff · 10:45

In plain words. The cook follows the approved recipe, tastes the dish with the agreed spoon (the team's test script), plates it, and only then calls you over: "it passed; do you accept it?"

3.6 Build and Test

Approve Code Generation. A separate agent builds and tests the whole repo again and checks that every requirement has a test

With one change this looks like a repeat. It is the stage that would catch two pieces of work disagreeing, and it writes the one table the gate signs: which test proves which requirement.

Kiran · 10:45 → 10:52

You type

Claude returns abridged · wording from a real 2.11.0 run, this story's numbers

Build and Test complete
The build succeeds and the full suite passes 10 of 10 on request-age/u1-age-api at b477c4e: the 3 existing
tests plus 7 new ones.
  test-results.md                  per-class results from the test reports, plus the target check
  cross-unit-traceability.md       PASS: FR1–FR3 and NFR1 are all covered, each mapped to a test
  build-and-test-summary.md        build, test and code-review readiness; known limitations
  build-instructions.md            JDK 21 + Maven, ./scripts/verify.sh, run notes
  integration / performance / security instructions
                                   the Minimal test strategy needs no extra suites; each file says
                                   what already covers that area and what doesn't
Still open:
  - Holiday data covers TX-01 2026 only, so each later year needs its own file.
  - The branch isn't pushed and no PR is open. The team needs to push request-age/u1-age-api and open one PR.
Review: aidlc/spaces/default/intents/261013-request-age-api/construction/build-and-test/
▸ How would you like to proceed?
  1. Approve: continue to Deployment Pipeline   2. Request Changes: tell me what to revise   3. Other

The manual check, in a second terminal. Both outputs below are real: they come from the repo at tag v1.1.0.

You type PowerShellTerminal (macOS), second window

cd ~/work/java-workspace/priorauth-api
mvn test
mvn spring-boot:run

cd C:\work\java-workspace\priorauth-api
mvn test
mvn spring-boot:run

curl "http://localhost:8080/requests/pending?asOf=2026-10-13"Then this, in a third window: spring-boot:run keeps the second one busy until Ctrl+C. In PowerShell, curl.exe if curl is the alias.

You see Maven, then the API's JSON · real output

$ mvn test
...
[INFO]  T E S T S
[INFO] Running com.acmehealth.priorauth.aging.AgeBadgeTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 -- in com.acmehealth.priorauth.aging.AgeBadgeTest
[INFO] Running com.acmehealth.priorauth.aging.BusinessDaysTest
[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0 -- in com.acmehealth.priorauth.aging.BusinessDaysTest
[INFO] Running com.acmehealth.priorauth.api.PendingRequestsControllerTest
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0 -- in com.acmehealth.priorauth.api.PendingRequestsControllerTest
[INFO] Running com.acmehealth.priorauth.store.RequestStoreTest
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0 -- in com.acmehealth.priorauth.store.RequestStoreTest
[INFO] Results:
[INFO] Tests run: 10, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS
[INFO] Total time:  7.4 s
$ echo $?
0

$ curl "http://localhost:8080/requests/pending?asOf=2026-10-13"
[
    {
        "id": "PA-10231",
        "tenantId": "TX-01",
        "service": "MRI lumbar spine",
        "status": "PENDED",
        "receivedAt": "2026-10-01",
        "ageBusinessDays": 7,
        "overLimit": true,
        "ageLabel": "7 bd OVER 5"
    },
    {
        "id": "PA-10244",
        "tenantId": "TX-01",
        "service": "Physical therapy x12",
        "status": "IN_REVIEW",
        "receivedAt": "2026-10-06",
        "ageBusinessDays": 4,
        "overLimit": false,
        "ageLabel": "4 bd"
    },
    {
        "id": "PA-10263",
        "tenantId": "TX-01",
        "service": "CT abdomen",
        "status": "PENDED",
        "receivedAt": "2026-10-09",
        "ageBusinessDays": 1,
        "overLimit": false,
        "ageLabel": "1 bd"
    }
]

Check the number yourself. PA-10231 arrived Thu 1 Oct. Counting business days after it up to Tue 13 Oct: Fri 2 (1), Mon 5 – Fri 9 (6), Mon 12 is a TX-01 holiday (still 6), Tue 13 (7). Over 5, so overLimit is true and the label reads 7 bd OVER 5. PA-10244 arrived Tue 6 Oct: 7, 8, 9, 13 = 4.

On disk now

java-workspace/aidlc/spaces/default/intents/261013-request-age-api/construction/build-and-test/
  test-results.md                         10 tests, which test proves which requirement, the manual check
  cross-unit-traceability.md              PASS: every requirement in traceability.json has a test
  build-and-test-summary.md               readiness, the target matrix, known limitations
  build-instructions.md                   build, run, package
  integration-test-instructions.md        why no extra suite: the endpoint test already covers it
  performance-test-instructions.md        no target set; the one known risk
  security-test-instructions.md           what is covered, what is not (no auth, unchanged)

construction/build-and-test/test-results.mdreal file · the matrix is what the gate signs

# Test results (3.6) · Tue 13 Oct, 10:52

## Build status
| Repo | Command | Pass | Fail | Skipped |
|---|---|---|---|---|
| priorauth-api | mvn -q test | 10 | 0 | 0 |

## Target Verification Matrix (finalised)
| Requirement | Test | Result |
|---|---|---|
| FR1 | BusinessDaysTest.receivedTodayHasAgeZero, BusinessDaysTest.asOfBeforeReceivedIsAnError, PendingRequestsControllerTest.asOfBeforeReceivedIsABadRequest (→ 400) | pass |
| FR1.1 | BusinessDaysTest.weekendIsNotCounted | pass |
| FR1.2 | BusinessDaysTest.tenantHolidayIsNotCounted | pass |
| FR2 | AgeBadgeTest.flagOnlyWhenOverTheThreshold (5 → not flagged, 6 → flagged) | pass |
| FR3 | PendingRequestsControllerTest.eachRowCarriesItsAgeAndFlag | pass |
| NFR1 | pom.xml diff: only `<version>` changed | pass (inspection) |
Existing tests: 3, still passing.

## Manual check
`mvn spring-boot:run`, then `curl "http://localhost:8080/requests/pending?asOf=2026-10-13"`: PA-10231 returns
`"ageBusinessDays": 7, "overLimit": true, "ageLabel": "7 bd OVER 5"` (received 1 Oct; 12 Oct is a TX-01 holiday).

## Loop-Back Log
(none)

construction/build-and-test/cross-unit-traceability.mdthe final coverage check

# Cross-Unit Traceability — Final Coverage Gate

**Verdict: PASS.** Every FR and NFR in `inception/requirements-analysis/requirements.md` is covered with status `OK` (or a justified `N/A`) in `construction/code-generation/traceability.json`, and every target file exists. User Stories did not run (express scope), so there are no story IDs to trace.

| ID | Status | Owning stage | Target file | Test evidence |
|---|---|---|---|---|
| FR1 | OK | code-generation (zero-Unit) | `aging/BusinessDays.java` | `BusinessDaysTest.receivedTodayHasAgeZero`, `asOfBeforeReceivedIsAnError`, `PendingRequestsControllerTest.asOfBeforeReceivedIsABadRequest` |
| FR1.1 | OK | code-generation | `aging/BusinessDays.java` | `BusinessDaysTest.weekendIsNotCounted` |
| FR1.2 | OK | code-generation | `aging/HolidayCalendar.java` | `BusinessDaysTest.tenantHolidayIsNotCounted` |
| FR2 | OK | code-generation | `aging/AgeBadge.java` | `AgeBadgeTest.flagOnlyWhenOverTheThreshold` |
| FR3 | OK | code-generation | `api/PendingRequestResponse.java` | `PendingRequestsControllerTest.eachRowCarriesItsAgeAndFlag` |
| NFR1 | N/A | code-generation | — | `pom.xml` changes its version only |

## Uncovered elements / findings
- No traced ID is uncovered.

Gate 4 of 4: build and test

Every requirement has a passing test or an inspection note, and cross-unit-traceability.md says PASS. This is the last question of the run: Meena approves it at step 15, after the PR is open.

Approved at step 15 by Meena Iyer · 10:55

In plain words. A second tasting, by someone whose only job is tasting, who writes down "dish 3, tasted, fine" in a table the manager signs.

yours, not the tool

Push the branch and open the pull request, with the code summary as its description

Claude committed on the branch at step 12, but pushing and the pull request are the team's: AI-DLC has no PR stage. Your CLAUDE.md applies: one unit, one branch, one PR. The PR body is the file Claude already wrote.

Kiran · 10:52 – 10:54

You type in Claude Code, two ! lines

! git -C priorauth-api push -u origin request-age/u1-age-api
! gh pr create --repo acme-health/priorauth-api --base main --head request-age/u1-age-api --title "Request age and over-limit flag on the pending list (U1)" --body-file aidlc/spaces/default/intents/261013-request-age-api/construction/code-generation/code-summary.md

You see git and gh output

To github.com:acme-health/priorauth-api.git
 * [new branch]      request-age/u1-age-api -> request-age/u1-age-api
Creating pull request for request-age/u1-age-api into main in acme-health/priorauth-api
https://github.com/acme-health/priorauth-api/pull/58

Following along? Skip both lines. acme-health and PR #58 are the story's GitHub: your origin is the public starter repo, which you cannot push to. Claude's commit is already on your branch; ! git -C priorauth-api log --oneline -2 shows it above v1.0.2.

The repo's history, as it is at tag v1.1.0 git log --oneline --graph --decorate

*   49fe266 (HEAD -> main, tag: v1.1.0) Merge pull request #58 from acme-health/request-age/u1-age-api
|\
| * b477c4e (request-age/u1-age-api) request age and over-limit flag on the pending list (intent 261013-request-age-api, U1)
|/
* d9aa178 (tag: v1.0.2) priorauth-api 1.0.2: pending list for the reviewer screen

Who reviews what. Meena reviews PR #58 on GitHub the way she reviews any PR. The difference is the description: it names the intent, the requirements and the verification result, because Claude wrote it at step 12 and nobody retyped it. She merges at 11:02, after the run is complete.

	From plan to merge, in this run	Whose step	Where it is recorded
1	Plan approval (steps 11–12). The plan names the branch, and the engine stops until it is approved.	the engine stops; Meena answers	`code-generation-plan.md`, audit shard 0004
2	Branch, code, `scripts/verify`, commit (step 12).	Claude, because your `CLAUDE.md` says so	`request-age/u1-age-api`, `code-summary.md`
3	The 3.5 and 3.6 gates (steps 13, 15). Express has no units, so no unit checkpoint.	the engine; Meena answers	`aidlc-state.md`, audit shards 0005, 0006
4	Push and open the PR (this step).	Kiran	GitHub
5	Review and merge (11:02).	Meena	`main`, tag `v1.1.0`

In feature scope it repeats per unit. A run with units (/aidlc feature …) goes through rows 1–5 once per unit, and row 3 becomes a unit checkpoint: the engine runs scripts/verify itself, then asks “Approve this completed <unit>?”. Three units, three branches, three PRs: the feature-scope page, step 11 walks through that loop.

In plain words. The dish goes to the pass with the recipe card clipped to it. The head chef reads the card, tastes, and sends it out.

Operationstages 4.1, 4.3, 4.4 · planned by express, skipped in this run: nothing to deploy to · 10:55

4.1 Deployment Pipeline · skipped4.3 Deployment Execution · skipped4.4 Observability Setup · skipped

Approve build and test. Claude skips the three Operation stages, and the run is complete

Express plans three Operation stages, but each one runs only when there is something to work on. This workspace has no pipeline, no container or infrastructure files and no deployment target, so Claude skips them without asking, and the engine records each skip.

Kiran · 10:55

You type

Claude returns abridged · wording from a real 2.11.0 run, this story's numbers

Progress: 4/7 in-scope stages complete (7/33 overall) | 2/2 CONSTRUCTION. Next: Deployment Pipeline
Now working on Deployment Pipeline, wearing the release engineer hat.
Deployment Pipeline doesn't apply here, so I skipped it. The repo has no CI or CD configuration,
no container or infrastructure files, and no deployment target to design against.
Now working on Deployment Execution, wearing the release engineer hat.
Deployment Execution doesn't apply here either, so I skipped it. There's no environment in the
workspace to deploy to.
Now working on Observability Setup, wearing the operations engineer hat.
Observability Setup does not apply here, so I skipped it.

The work is finished. The reviewer screen's API now returns a business-day age and an over-5 flag on
every pending request. I skipped the last three stages (Deployment Pipeline, Deployment Execution,
Observability Setup) because priorauth-api has no pipeline, environment or deployment setup in this
workspace to work against.
  Code: priorauth-api/ on branch request-age/u1-age-api, commit b477c4e. All 10 tests pass.
  Record: aidlc/spaces/default/intents/261013-request-age-api/, committed in the workspace repo.

On disk now

java-workspace/aidlc/spaces/default/intents/261013-request-age-api/
  aidlc-state.md                            Status: Completed · the three Operation stages marked [S], skipped
  audit/0006-3-6-build-and-test.md          your "1"
  audit/0007-4-operation-skipped.md         the three skips and why; no prompt, nobody asked
  (no operation/ folder: a skipped stage writes nothing)

Why no question. Each Operation stage has a condition in its definition. Deployment Pipeline: "Execute when CD pipeline needs creation or significant modification". Deployment Execution: "Execute after deployment pipeline and environment are ready". Observability Setup: "Execute when monitoring, dashboards, alarms, or tracing need configuration". Claude looked for a pipeline, a Dockerfile, infrastructure code and deploy manifests, found none, and reported each stage as skipped with that reason; the engine accepts a skip without a gate. The "7 approval gates" express announced at step 5 included these three; you answered four.

How a team gets the Operation gates. Give Claude something to work against: the pipeline's config, a Dockerfile, or a deploy runbook in the workspace, or a line in CLAUDE.md that says where they live and how a release goes out. Then 4.1 writes a deployment strategy and stops at a gate, 4.3 lists the pipeline steps for you to run and keeps the log, and 4.4 proposes alarms. We have not run that path; the conditions above are what decides it. Here, shipping is the team's: Meena merges PR #58 and the existing release process tags v1.1.0.

In plain words. The menu has a "send it to the delivery van" step, but this restaurant has no van. The cook says so, crosses the step off, and writes down why, instead of inventing a van.

Afterwhat you have, what you keep, and how to come back tomorrow

workflow complete

Check the status: 7 of 10 stages, 3 skipped. This is what you have on disk, every file explained

aidlc engine status reads the state file the run wrote. The intent is complete: /aidlc tomorrow would start from a clean slate.

Kiran · 10:57

You type in Claude Code

! aidlc engine status

You see real output, from java-workspace/

AI-DLC Workflow Status
==============================
Project:        Build what ./docs-in/request.md describes
Scope:          express
Project Type:   existing code
Depth:          Minimal (from scope express)
Phase:          OPERATION
Current Stage:  Observability Setup (4.4)
Status:         Completed
Active Agent:   Operations Agent
Guard Policy:   off (from scope express)
Sensors: off (from scope express)
Learnings: off (from scope express)
Summary Confirmation: off (from scope express)
Plan Approval: on (set by a command)
Collaborators: off (from scope express)
Completion:     7/10 stages (70%) - 3 skipped

Phase Progress:
  INITIALIZATION   ███ 3/3
  INCEPTION        ██ 2/2
  CONSTRUCTION     ██ 2/2
  OPERATION        SSS 0/3

Last Completed: Build and Test

Everything on disk at 10:57, every file explained matches java-workspace/

java-workspace/                                               the folder you start Claude Code in
├─ aidlc/                                                     the order book: everything AI-DLC writes
│  └─ spaces/                                                 spaces group runs
│     └─ default/                                             the one space this team uses
│        ├─ codekb/                                           code knowledge base, one folder per repo
│        │  └─ priorauth-api/                                 what 2.1 learned about the repo; reused by every run
│        │     ├─ api-documentation.md                        the endpoint and its JSON
│        │     ├─ architecture.md                             layers and what is absent (no database)
│        │     ├─ business-overview.md                        what the service is for
│        │     ├─ code-quality-assessment.md                  what is clean; where new code should go
│        │     ├─ code-structure.md                           folder map, one line per file
│        │     ├─ component-inventory.md                      each class and its job
│        │     ├─ dependencies.md                             the two starters
│        │     ├─ reverse-engineering-timestamp.md            when, which commit, and the fingerprint the next run compares
│        │     └─ technology-stack.md                         Java 21, Spring Boot 4.1, Maven; dependency policy
│        ├─ intents/                                          one folder per run
│        │  ├─ intents.json                                   the registry: one row per run, status complete
│        │  └─ 261013-request-age-api/                        this run: 13 Oct 2026, label request-age-api
│        │     ├─ audit/                                      one shard per gate answer: who, when, prompt, answer
│        │     │  ├─ 0001-scope.md                            express, named in the command
│        │     │  ├─ 0002-2-1-reverse-engineering.md          1
│        │     │  ├─ 0003-2-3-requirements-analysis.md        3, the answers, the follow-ups, 2 with names, then 1
│        │     │  ├─ 0004-3-5-code-generation-plan-approval.md 1 (Approve Plan)
│        │     │  ├─ 0005-3-5-code-generation.md              1, after the script passed and the commit
│        │     │  ├─ 0006-3-6-build-and-test.md               1
│        │     │  └─ 0007-4-operation-skipped.md              4.1, 4.3, 4.4 skipped; no prompt
│        │     ├─ construction/                               phase 3 artifacts
│        │     │  ├─ build-and-test/                          stage 3.6
│        │     │  │  ├─ build-and-test-summary.md             readiness, target matrix, known limitations
│        │     │  │  ├─ build-instructions.md                 build, run, package
│        │     │  │  ├─ cross-unit-traceability.md            PASS: every requirement has a test
│        │     │  │  ├─ integration-test-instructions.md      why no extra suite
│        │     │  │  ├─ performance-test-instructions.md      no target; the one known risk
│        │     │  │  ├─ security-test-instructions.md         what is covered, what is not
│        │     │  │  └─ test-results.md                       which test proves which requirement
│        │     │  └─ code-generation/                         stage 3.5
│        │     │     ├─ code-generation-plan.md               four steps, 12 files; approved first
│        │     │     ├─ code-generation-questions.md          the plan question as a file, answered A
│        │     │     ├─ code-summary.md                       what changed; became the PR description
│        │     │     ├─ traceability.json                     requirement -> file
│        │     │     └─ unit-test-instructions.md             how to run the tests
│        │     ├─ inception/                                  phase 2 artifacts
│        │     │  ├─ requirements-analysis/                   stage 2.3
│        │     │  │  ├─ requirements-analysis-questions.md    4 questions, 2 follow-ups, answers and names
│        │     │  │  └─ requirements.md                       FR1-FR3, NFR1, assumptions, out of scope
│        │     │  └─ reverse-engineering/                     stage 2.1, this run's part
│        │     │     └─ developer-scan-priorauth-api.md       the scan's notes; the codekb is the reusable part
│        │     ├─ aidlc-state.md                              Status: Completed, 7/10 stages, 3 skipped
│        │     └─ project-description.json                    the request, verbatim, as one JSON string
│        ├─ knowledge/                                        onboarded documents (none in this run)
│        │  └─ .gitkeep                                       keeps the empty folder in git
│        └─ memory/                                           rules the tool reads at every stage; written by aidlc config
│           ├─ org.md                                         AI-DLC's defaults: trunk-based, squash-merge, test posture per scope
│           ├─ project.md                                     this project's rules and corrections (empty sections)
│           ├─ team.md                                        the team's affirmed practices (empty until practices-discovery)
│           ├─ phases/                                        guardrails per phase, AI-DLC's defaults
│           │  ├─ construction.md                             complete files, error handling, test and security floors
│           │  ├─ ideation.md                                 problem before solution (not run by express)
│           │  ├─ inception.md                                testable requirements, traceability
│           │  └─ operation.md                                rollback steps, smoke checks, quantified alarms
│           └─ templates/                                     artifact-format overrides a team may add (none)
│              └─ .gitkeep                                    keeps the empty folder in git
├─ docs-in/                                                   inputs you hand to a run
│  └─ request.md                                              the Slack message, saved as a file
├─ priorauth-api/                                             the code repo: main at v1.1.0, history in .git
│  ├─ .git/                                                   v1.0.2 (before), the branch, the merge, v1.1.0
│  ├─ src/                                                    Maven layout
│  │  ├─ main/                                                what ships
│  │  │  ├─ java/com/acmehealth/priorauth/                    the package; folders mirror the dots
│  │  │  │  ├─ aging/                                         the new package
│  │  │  │  │  ├─ AgeBadge.java  new                          days, flag, label
│  │  │  │  │  ├─ BusinessDays.java  new                      the arithmetic
│  │  │  │  │  └─ HolidayCalendar.java  new                   reads the tenant's holiday file
│  │  │  │  ├─ api/                                           the REST layer
│  │  │  │  │  ├─ PendingRequestResponse.java  changed        + ageBusinessDays, overLimit, ageLabel
│  │  │  │  │  └─ PendingRequestsController.java  changed     + ?asOf (400 if too early), calendar, threshold
│  │  │  │  ├─ model/                                         domain
│  │  │  │  │  └─ PriorAuthRequest.java                       the record; untouched
│  │  │  │  ├─ store/                                         data access
│  │  │  │  │  └─ RequestStore.java                           loads the export; untouched
│  │  │  │  └─ PriorAuthApiApplication.java                   main(); untouched
│  │  │  └─ resources/                                        config and data packed into the jar
│  │  │     ├─ data/                                          data files
│  │  │     │  ├─ holidays-TX-01-2026.json  new               the tenant's holidays
│  │  │     │  └─ requests.sample.json                        4 requests, 3 pending; untouched
│  │  │     └─ application.yml  changed                       + priorauth.aging.threshold-days: 5
│  │  └─ test/                                                tests, never shipped
│  │     └─ java/com/acmehealth/priorauth/                    same package layout as main
│  │        ├─ aging/                                         tests for the new package
│  │        │  ├─ AgeBadgeTest.java  new                      1 test: FR2 boundary
│  │        │  └─ BusinessDaysTest.java  new                  4 tests: FR1, FR1.1, FR1.2, error case
│  │        ├─ api/                                           endpoint tests
│  │        │  └─ PendingRequestsControllerTest.java  changed  + 2 tests: FR3, FR1 (400)
│  │        └─ store/                                         store tests
│  │           └─ RequestStoreTest.java                       2 tests; untouched
│  ├─ .gitignore                                              target/ and IDE files
│  ├─ pom.xml  changed                                        Maven: parent 4.1.1, two starters; version 1.1.0
│  └─ README.md  changed                                      how to run; usage line updated
├─ scripts/                                                   your scripts
│  ├─ verify.cmd                                              the Windows twin
│  └─ verify.sh                                               the verification command: mvn -q test in the repo
├─ .gitignore                                                 AI-DLC's two managed blocks: runtime scratch, and /priorauth-api/
├─ aidlc.code-workspace                                       VS Code multi-root file: workspace + repo (from workspace-sync)
├─ CLAUDE.md                                                  house rules Claude Code reads first (ours)
├─ README.md                                                  how to run and replay this workspace
├─ repos.json                                                 which repos belong here (ours)
└─ WALKTHROUGH.md                                             the 17 steps as text: you type / Claude returns

intents/261013-request-age-api/aidlc-state.mdreal 2.11 format: aidlc engine status reads it as Completed, 7/10, 3 skipped

# AI-DLC State Tracking

## Project Information
- **Project**: Build what ./docs-in/request.md describes
- **Project Description Source**: project-description.json
- **Project Type**: Brownfield
- **Project Type Source**: workspace scan
- **Scope**: express
- **Start Date**: 2026-10-13T04:00:00Z
- **Question Id**: 5b0e7d21
- **State Version**: 8
- **Active Agent**: aidlc-operations-agent
- **Worktree Path**:
- **Bolt Refs**:
- **Practices Affirmed Timestamp**:

## Scope Configuration
- **Stages to Execute**: 0.1, 0.2, 0.3, 2.1, 2.3, 3.5, 3.6, 4.1, 4.3, 4.4
- **Stages to Skip**: 1.1 (intent-capture), 1.2 (market-research), 1.3 (feasibility), 1.4 (scope-definition), 1.5 (team-formation), 1.6 (rough-mockups), 1.7 (approval-handoff), 2.2 (practices-discovery), 2.4 (user-stories), 2.5 (refined-mockups), 2.6 (domain-design), 2.7 (units-generation), 2.8 (contract-design), 2.9 (delivery-planning), 3.1 (functional-design), 3.2 (nfr-requirements), 3.3 (nfr-design), 3.4 (infrastructure-design), 3.7 (ci-pipeline), 4.2 (environment-provisioning), 4.5 (incident-response), 4.6 (performance-validation), 4.7 (feedback-optimization)
- **Depth**: Minimal
- **Test Strategy**: Minimal
- **Review Override**: 
- **Guard Policy**: off (from scope express)
- **Sensors**: off (from scope express)
- **Learnings**: off (from scope express)
- **Summary Confirmation**: off (from scope express)
- **Plan Approval**: on (set by a command)
- **Collaborators**: off (from scope express)

## Workspace State
- **Project Root**: .
- **Languages**: Java
- **Frameworks**: Spring Boot
- **Build System**: maven (pom.xml)

## Execution Plan Summary
- **Total Stages**: 10
- **Completed**: 7
- **In Progress**: none

## Runtime State
- **Revision Count**: 1

## Phase Progress

- **Initialization**: Verified
- **Ideation**: Skipped
- **Inception**: Verified
- **Construction**: Verified
- **Operation**: Verified

## Stage Progress

### INITIALIZATION PHASE
- [x] workspace-scaffold — EXECUTE
- [x] workspace-detection — EXECUTE
- [x] state-init — EXECUTE

### IDEATION PHASE
- [ ] intent-capture — SKIP
- [ ] market-research — SKIP
- [ ] feasibility — SKIP
- [ ] scope-definition — SKIP
- [ ] team-formation — SKIP
- [ ] rough-mockups — SKIP
- [ ] approval-handoff — SKIP

### INCEPTION PHASE
- [x] reverse-engineering — EXECUTE
- [ ] practices-discovery — SKIP
- [x] requirements-analysis — EXECUTE
- [ ] user-stories — SKIP
- [ ] refined-mockups — SKIP
- [ ] domain-design — SKIP
- [ ] units-generation — SKIP
- [ ] contract-design — SKIP
- [ ] delivery-planning — SKIP

### CONSTRUCTION PHASE
Per unit: [TBD]
- [ ] functional-design — SKIP
- [ ] nfr-requirements — SKIP
- [ ] nfr-design — SKIP
- [ ] infrastructure-design — SKIP
- [x] code-generation — EXECUTE
- [x] build-and-test — EXECUTE
- [ ] ci-pipeline — SKIP

### OPERATION PHASE
- [S] deployment-pipeline — EXECUTE
- [ ] environment-provisioning — SKIP
- [S] deployment-execution — EXECUTE
- [S] observability-setup — EXECUTE
- [ ] incident-response — SKIP
- [ ] performance-validation — SKIP
- [ ] feedback-optimization — SKIP

## Current Status
- **Lifecycle Phase**: OPERATION
- **Current Stage**: observability-setup
- **Next Stage**: none
- **Status**: Completed
- **Last Updated**: 2026-10-13T05:25:00Z

## Session Resume Point
- **Last Completed Stage**: build-and-test
- **Next Action**: Workflow complete
- **Pending Artifacts**: none

## Notes
Owner Kiran Rao. Express named in the command 09:30; reverse engineering approved by Meena Iyer 09:41; questions answered
09:44-09:49 (Ravi Menon, Meena Iyer); requirements approved by Ravi Menon and Meena Iyer 09:56 after one Request Changes, with
plan approval turned on; plan approved 10:03 (Meena Iyer); code committed b477c4e on request-age/u1-age-api 10:41 and code
generation approved 10:45 (Meena Iyer); build and test approved 10:55 (Meena Iyer). Deployment Pipeline, Deployment Execution
and Observability Setup skipped 10:55: no pipeline or deployment config in the workspace. PR #58 merged 11:02, tag v1.1.0.
Times are IST (UTC+05:30).

intents/261013-request-age-api/audit/0003-2-3-requirements-analysis.mdthe busiest gate: five messages

shard: 0003
stage: 2.3 Requirements Analysis
at: 2026-10-13T09:56:00+05:30
by: Ravi Menon, Meena Iyer
prompt: Requirements Analysis is done. How would you like to proceed? 1. Approve 2. Request Changes 3. Other
answer: 1, with: turn plan approval on, Meena reads every plan before code is written.
before the gate:
  09:44 How would you like to answer the questions? 1. Guide me 2. I'll edit the file 3. Chat 4. Other -> 3 (Kiran Rao)
  09:47 Questions 1-4 -> A, A, B, C: received day is day 0, same as the report; over means more than 5, threshold 5 from
        configuration; the TX-01 list the report uses, as a JSON file in the API resources; the server's zone, callers can
        pass asOf. The API returns a flag and never refuses or alerts. (Ravi Menon, Meena Iyer)
  09:49 Follow-up 1 (the TX-01 dates) -> A, the 11 dates pasted; Follow-up 2 (other tenants) -> B, one file per tenant;
        a shared calendar service is a separate intent. (Meena Iyer)
  09:53 Request Changes: the screen team's names ageBusinessDays, overLimit, ageLabel; config key
        priorauth.aging.threshold-days; files data/holidays-<tenant>-<year>.json; an as-of date before the received date
        is a caller error (400). (Meena Iyer)
setting: Plan Approval off (from scope express) -> on (set by a command), 09:56

intents/261013-request-age-api/audit/0007-4-operation-skipped.mdthe last shard

Follow one thread, end to end. "weekends and our holidays do not count" (Slack) → question 3 and follow-ups 1–2 → FR1.1 and FR1.2 in requirements.md → plan rows 1, 3, 4 → BusinessDays.isBusinessDay and HolidayCalendar → weekendIsNotCounted, tenantHolidayIsNotCounted → traceability.json → cross-unit-traceability.md: PASS → PR #58 → "ageBusinessDays": 7 in the JSON the screen will read. Every hop is a file you can open.

In plain words. The order book explains the dish, and the dish explains the order book. Either one alone would be a story; together they are a record.

yours, not the tool

Commit the team's own files, so the team has the whole workspace tomorrow

Claude committed the record after each gate, because your CLAUDE.md says to. The files you added yourself (the request, CLAUDE.md, repos.json, the scripts) and the two that aidlc generated (.gitignore, the VS Code file) are not part of the record: you commit them once. The code repo stays ignored because it has its own history. .claude/ is left out on purpose: every machine regenerates it with aidlc config.

Kiran · 11:05

You type in Claude Code

! git log --oneline
! git add aidlc docs-in CLAUDE.md repos.json scripts .gitignore aidlc.code-workspace
! git commit -m "intent 261013-request-age-api: complete (PR #58, v1.1.0)"

You see your hashes and messages will differ

$ git log --oneline   Claude's commits, one per approval
429671d aidlc: request-age-api workflow complete (operation stages skipped: no deploy target)
7d6aa46 aidlc: request-age-api build and test approved
fb77798 aidlc: request-age-api code generation approved
a80d256 aidlc: request-age-api record through code plan approval
…
[main 5c2e0b9] intent 261013-request-age-api: complete (PR #58, v1.1.0)
 7 files changed, 76 insertions(+)
 create mode 100644 CLAUDE.md
 create mode 100644 docs-in/request.md
 ...

Fewer commits in your log? Claude commits when Claude Code lets it. If you said No to the git prompt at step 7, or a commit was blocked while a plan waited for approval, the record is not committed yet; the git add aidlc above picks it up, and the counts are larger.

Tomorrow, same runclaude then /aidlc with nothing after it resumes the active intent from aidlc-state.md. /aidlc park pauses one.

Tomorrow, a new run/aidlc express Build what ./docs-in/next.md describes creates a second folder under intents/; the codekb is reused, not rescanned.

A teammateClones the workspace, runs aidlc config --harness claude, then aidlc system workspace-sync (clones the repos from repos.json). aidlc doctor warns when aidlc/ has uncommitted changes.

Run it yourself

The course's java-workspace/ folder is the workspace exactly as the page shows it after the run, with the repo's git history (tag v1.0.2 before, branch request-age/u1-age-api, tag v1.1.0 after). The starter repo carries the same two tags, so git -C priorauth-api switch --detach v1.1.0 in your own run shows the answer. JDK 21 and Maven 3.9 on the path; the first mvn downloads the libraries, about a minute.

cd java-workspace\priorauth-api; mvn test10 tests, 7 from this run (Windows PowerShell).

cd java-workspace/priorauth-api && mvn test10 tests, 7 from this run (macOS Terminal).

mvn spring-boot:runStarts the API on port 8080. Leave it running and open a second window.

curl "http://localhost:8080/requests/pending?asOf=2026-10-13"The JSON above, with "ageBusinessDays": 7, "overLimit": true on PA-10231. In PowerShell, curl.exe if curl is the alias.

git -C priorauth-api diff v1.0.2 v1.1.0 --statThe twelve files the run touched, from the workspace folder.

Replay the run with the tool

git clone https://github.com/varasrinivas/aidlc-priorauth-api.git priorauth-apiReplay in a new, empty workspace folder: steps 1 to 5 of this page (this clone is step 1). Don't replay inside the course's java-workspace/: its repo already has the branch request-age/u1-age-api, which Claude creates at step 12.

/aidlc express Build what ./docs-in/request.md describesAnswer the gates as the page shows. Your artifacts will differ in wording; the shape, the stage list and the questions will not.

Eleven words, in the order you met them

workspace: The folder around the repo(s) that you start Claude Code in. Holds the record, the team files and the clones.
intent: One run of AI-DLC for one request. Its folder is intents/<date>-<label>/; the id here is 261013-request-age-api.
space: A group of intents that share a codekb, knowledge and memory. default is enough until you have teams that must not see each other's runs.
profile / scope: Which of the 33 stages run. express runs 10; bugfix 9, poc 8, mvp 23, feature all 33. Named in the command at step 5.
depth, test strategy: How long the artifacts are (Minimal: one or two pages, key decisions only) and how many tests (Minimal: one per requirement). Express sets both to Minimal.
gate: A question at the end of a stage that a person must answer: Approve, or Request Changes with a comment. The answer becomes an audit shard.
audit shard: One small file per gate answer under audit/, numbered: who, when, which prompt, what answer.
codekb: The nine files reverse engineering writes about a repo. Lives under the space, not the intent, so every run reuses it.
unit: A piece of the change that one branch and one PR can carry. Express does not split the work ("zero Units"): Code Generation runs once for the whole change; the team calls it U1.
verification command: The command that proves the code works: here the team's ./scripts/verify.sh, named in CLAUDE.md. Claude runs it before asking the Code Generation question. "Done" means it exited 0.
traceability: The file that maps each requirement to the files that implement it and the tests that prove it. Build and Test checks it is complete (cross-unit-traceability.md).

What is real here, and what is not

The code, the tests, Maven's output and the API's JSON are real (the repo at tag v1.1.0, and java-workspace/); the repo's git history is real, including the commit Claude makes at step 12. Steps 5 to 16 were checked against a real AI-DLC 2.11.0 run on Claude Code (14–15 Oct 2026, same starter repo, same request): the order of the questions, their options, the follow-ups, the plan stop, the commits and the three skipped Operation stages happened as shown, and Claude's lines are quoted from that run with this story's names, dates and numbers put back in. That run's code was not the code at v1.1.0 (other class names, 14 new tests instead of 7); its API answered the step 13 curl with the same numbers. The record files under aidlc/ follow that run's file set and formats, filled with this story; the files the tool reads pass its own checks: aidlc-state.md and intents/intents.json (aidlc engine status: Completed, 7/10 stages, 3 skipped), project-description.json, the codekb's scope block (codekb-scope-diff --check: VALID) and memory/, which aidlc config generated. The audit shards are the course's, one per gate: 2.11 writes one audit log per machine. The people, the clock, the acme-health GitHub organization and PR #58 are a story. Pushing and the pull request are the team's own steps: the tool has no pull-request stage.

Companion pages: the Python run of the same rule on the nightly report ("AI-DLC in One Morning"), the full 33-stage run across five repos ("Gold Card"), and the sharing model for the workspace folder ("The Workspace Repo").

One requirement, one Spring Boot repo, every step spelled out.

What you are going to change, before any AI is involved

Before you start: three things on your laptop, once

The two folders you will be looking at

The workspace (yours)

The Java repo (Maven layout)

Make the workspace folder and put the repo in it

Tell AI-DLC that your assistant is Claude Code, then let it check the folder

Save the requirement as a file

Start Claude Code in the workspace folder

Start the run: one command creates the record and goes straight on to the first real stage

Choose Yes if Claude Code asks to change the project's settings. Claude reads the repo and writes nine short files about it

Approve the scan. Before writing any requirement, Claude writes down what the message did not say, as four questions with lettered answers

Pick 3 (Chat), then answer the four questions in one message, with the names of the people who decided

Answer the two follow-ups. Claude writes the requirements and lists what it still had to assume

Request Changes with 2: the names the screen team already uses, and one rule

Approve the requirements and turn plan approval on. Inception is done; Claude writes the plan and stops for it

Approve the plan. Claude makes the branch, writes the twelve files, runs the team's script, and commits

Approve Code Generation. A separate agent builds and tests the whole repo again and checks that every requirement has a test

Push the branch and open the pull request, with the code summary as its description

Approve build and test. Claude skips the three Operation stages, and the run is complete

Check the status: 7 of 10 stages, 3 skipped. This is what you have on disk, every file explained

Commit the team's own files, so the team has the whole workspace tomorrow

Run it yourself

Replay the run with the tool

Eleven words, in the order you met them

What is real here, and what is not

Pick `3` (Chat), then answer the four questions in one message, with the names of the people who decided

Request Changes with `2`: the names the screen team already uses, and one rule