Case Study, Part 1 of 5: Setup & Kickoff

In plain English: This is a real, complete walkthrough — not a made-up toy example. We're going to actually build a small command-line tool from a one-sentence idea, using the real aidlc-workflows engine from the last three pages, and show everything it does along the way: every question it asks us, every file it writes, and every "approve this?" checkpoint.

One real requirement, run start to finish on the actual aidlc-workflows engine — not the simplified story version. Five phases, five pages, nothing skipped:

1. Setup & Kickoff (this page)
2. Ideation Phase
3. Inception Phase
4. Construction Phase
5. Operation Phase

Every prompt we actually type is highlighted like this. Everything else is Claude Code's output, or our own narration.

The Brief

We're building synth-data: a CLI that takes a schema (column names, types, constraints) and generates realistic fake rows in whatever format we ask for — CSV, JSON, Parquet, or SQL INSERT statements — for testing and demos.

Before We Start

Three things need to be true first — full detail on each is in How We Use This Repo:

1. aidlc-workflows is cloned and built: git clone → bun install --frozen-lockfile → bun scripts/package.ts
2. It's installed into a fresh project folder: aidlc config --harness claude (or the manual installer)
3. aidlc doctor reports clean

From here, we assume those three are done.

Who writes vision.md and technical-environment.md?

We do — by hand, before we ever open Claude Code. These are not generated by AI-DLC; nothing has run yet. We open a plain text editor, create two Markdown files in the project root, and write them ourselves. On macOS/Linux:

touch vision.md technical-environment.md

On Windows (PowerShell): New-Item vision.md, technical-environment.md. Or, simplest of all on any OS: just create two new text files in your project folder named exactly vision.md and technical-environment.md using whatever editor you already have open.

This step is optional — skip it, and Claude Code will ask us the same questions one at a time in conversation once the workflow starts. We write them anyway because five minutes of typing here saves several rounds of back-and-forth during Requirements Analysis.

# vision
A CLI that generates synthetic data from a schema. Output as CSV,
JSON, Parquet, or SQL inserts. For testing and demos — not a
production data pipeline.

## MVP Features (IN)
- Define a schema (column name, type, constraints) in YAML
- Generate N rows of realistic fake data matching it
- Export to CSV, JSON, Parquet, or SQL insert statements

## Out of Scope (for now)
- A web UI
- Referential integrity across multiple tables
- Streaming / infinite generation

# technical-environment
- Language: Python 3.12
- CLI framework: click
- Fake data: Faker
- Formats: pandas + pyarrow (CSV/Parquet), stdlib json, stdlib csv for SQL text
- Testing: pytest
- Deployment: published to PyPI, installed locally via pip

Once both files are saved, that's the point setup ends and the actual AI-DLC workflow begins.

The Journey, At a Glance

flowchart LR
    I["Initialization<br/>(automatic)"] --> ID["Ideation"]
    ID --> IN["Inception"]
    IN --> C["Construction"]
    C --> O["Operation"]

We'll run the feature scope: the full 33-stage lifecycle, standard depth — nothing skipped except one stage that never applies to a brand-new project (Reverse Engineering, which only runs when there's existing code to scan). Every phase gets its own page in this case study, in full, including Operation — the part most tutorials wave their hands at.

Kickoff

You: Using AI-DLC, I want to build a synthetic data generator. Please read vision.md and technical-environment.md, then begin the AI-DLC workflow.

Claude Code renders the AI-DLC welcome banner, then starts working.

Behind the scenes: aidlc-session-start fires first — it emits SESSION_STARTED and injects the current workflow context. Every real prompt we type also triggers aidlc-record-human-turn, which appends a HUMAN_TURN event to the audit trail (the permanent, timestamped log of everything that happened). This is the "human-presence gate": a safety rule that says an approval can't go through later unless a real HUMAN_TURN was logged since the last gate — in other words, the AI can't quietly approve its own work while we're not looking.

Phase 0 — Initialization (automatic, under a second)

Three stages run inside one tool call, with no interaction from us:

─── Scope Detection ──────────────────────────────────────────────
Detected scope: feature (Standard depth, Standard test strategy, all 33 stages)
▸ Approve scope? [Yes / Change scope / Change depth / Change test strategy]

The detected scope is exactly what we want — a real product, full lifecycle, practical depth.

You: Yes

Behind the scenes: Three audit events land in order — WORKSPACE_SCAFFOLDED, WORKSPACE_SCANNED, WORKSPACE_INITIALISED — then our confirmation fires SCOPE_DETECTED. aidlc-state.md now lists all 33 stages, with Reverse Engineering alone pre-marked [S] Skipped (scope-excluded reason: no source to reverse-engineer). Everything else starts [ ] Not Started.

Continue to: Part 2 — Ideation Phase