The deep dive · chapter 1 · 6 steps

Why the work lives in files

Where AIDLC keeps track of a piece of work, why it uses plain files next to your code, and what happens the first time you point it at a codebase that already exists.

1. 1. The problem — Monday morning

   Every session with an AI assistant starts by explaining the project again. You spent Friday afternoon getting it up to speed on how your billing code fits together, what you'd decided about retries, and which half of the change was finished. On Monday it knows none of it.

   You can paste in a summary. Then you're maintaining a summary. And the summary drifts from the code, quietly, until one day the assistant confidently builds on something that stopped being true a week ago.

   The usual answer is a longer memory. That doesn't work either, because the thing you need to survive isn't the conversation — it's the decisions. Which step you're on. What you agreed the feature should do. What the review found. Those need to be readable by you, by a colleague, by your build pipeline, and by whichever assistant you happen to open tomorrow.

   So AIDLC writes them down as files, in your repository, next to the code they describe.

2. 2. What one command creates

   Start a piece of work and watch what appears on disk. Step through it:

   One command, and the work has a place to live

   aidlc — zsh

   $ aidlc start full-feature --name price-alerts
   
   Lifecycle instance created:
     Name:     price-alerts
     Template: full-feature
     Scope:    full
     Phase:    ideation
     Path:     .aidlc/state/price-alerts/
     Action:   create-branch-on-instance-start ✓

   .aidlc/state/price-alerts/instance.yaml

   name: price-alerts
   template: full-feature
   scope: full
   current_phase: ideation
   claim: null

   ← backstep 1 of 3next →

   Three things worth noticing.

   The folder is the memory. Nothing in there depends on a conversation having happened. aidlc status read those files cold.

   Each step of the work owes documents. phase-ideation.yaml doesn't contain the thinking — it says which document that step is expected to produce and whether it exists yet. The thinking goes in idea.md, a normal markdown file you can read, edit, and argue with in a pull request.

   One folder per piece of work. AIDLC calls that folder an instance — a word worth taking care with, because in most of software it means something else entirely. Here it just means one unit of work with its own folder: a feature, a fix, a spike.

3. 3. Why a file and not chat history

   Four things become possible once a decision lives in a file, and none of them are possible otherwise.

   You can review it. requirements.md shows up in a pull request as a diff. Somebody can disagree with a line of it before any code exists.

   A machine can check it. Your build pipeline can run aidlc gate my-feature testing and get an exit code. You cannot pipeline a conversation.

   It survives the tool. These are markdown and YAML files in your git history. If you stop using AIDLC tomorrow, you still have the record of what was decided and why.

   Two people see the same thing. Not two summaries of the same thing.

   The documents a step is required to produce have a name — artifacts — and they're the unit everything else is built on. The gates check them. Reviews target them. The whole framework is a set of rules about which files must exist before the work moves on.

4. 4. Pointing it at code that already exists

   Most codebases aren't new, and the first honest question is what any of this knows about yours.

   On first activation, AIDLC reads your project and writes down what it found:

   aidlc discover
   

   That produces context documents under .aidlc/context/ — a description of the architecture as it actually stands, and a style guide derived from your real code rather than from a preference. It also seeds a set of notes about your modules and how they depend on each other, which the next chapter but two is about.

   These are files like any other, so the useful move is to read them and fix what's wrong. A generated description of your architecture that you've corrected by hand is worth considerably more than one nobody has looked at.

5. 5. Checkpoint

   checkpoint

   You stop halfway through a feature on Friday and open a completely fresh session on Monday. How does the assistant find out which step you were on?

   • It reads back the earlier conversation.
   • It reads the small files under .aidlc/state/.
   • It asks you where you left off.
   • It syncs from a hosted service.

   This checkpoint needs JavaScript.

6. 6. What you can do now

   You can open any .aidlc/state/<name>/ folder and read, without running anything, what a piece of work is, which step it reached, and which documents it still owes. That's the foundation for everything in the rest of the series — every capability from here on is something that reads or writes those files.

   Next: how much process a given piece of work should actually get, and how to stop a typo fix from being treated like a new subsystem.