The deep dive · chapter 8 · 9 steps

Making it yours

How a lesson from one job reaches the next one, turning a repeatable chore into a skill instead of a project, keeping the repository healthy, and running the same setup on six different assistants.

1. 1. The problem — learning the same thing twice

   You finished something last month, and it went wrong in a way you understood completely by the end. This month it went wrong the same way.

   The knowledge existed. It was in somebody's head, or in a note at the bottom of a document nobody opens at the start of a job. Whatever mechanism was supposed to carry it forward, it didn't.

   Same shape for chores. There's a fiddly six-step thing you do every release — the steps are known, the order matters, and you get one wrong roughly every third time.

2. 2. Lessons in, chores out

   Lessons in, chores out

   aidlc — zsh

   $ ls .aidlc/guidance/
   
   accessibility.md
   api-conventions.md
   index.yaml
   lessons-digest.md
   secure-defaults.md

   .aidlc/guidance/lessons.md (after the first retrospective)

   - Two sessions in one folder
     collide on git, not on state.
     Use a worktree.
   - A follow-up written as prose
     is not a work item.
   
   A fresh setup has only the
   digest. lessons.md appears
   when the first retrospective
   runs. Each line is read at the
   start of the next job.

   ← backstep 1 of 3next →

   Three separate mechanisms in one transcript. Take them one at a time.

3. 3. Guidance — read at the start, not the end

   .aidlc/guidance/ holds files that get read at the start of a job. That single detail is the whole mechanism.

   lessons.md is the one fed by finishing work. It doesn't exist in a fresh setup — the first frame shows only lessons-digest.md, the short distillation that ships with it. When your first piece of work completes, the retrospective captures what was learned and creates lessons.md with it. Next job, before anything else happens, those lines get read.

   Contrast with the failure mode: writing the same lesson into the completed job's own write-up. That file is read by nobody, ever again. The distinction between guidance (read at the start of every job) and record (read when investigating that particular job) is the entire difference between a lesson that carries forward and one that doesn't.

   Alongside lessons sit the layers you write yourself — secure-defaults, accessibility, api-conventions — active when listed in index.yaml. Those are yours to edit; the framework won't overwrite them.

   Two disciplines keep the file usable. A cap — around three lessons per completed job, or the file becomes something nobody reads, at which point it's decorative. And consolidation: when it gets long, the run of near-duplicates about the same mistake collapses into one entry that says it better.

4. 4. Skills — for the chore, not the change

   The rule is one line: the lifecycle for changes to the system, a skill for repeatable operations of the system.

   Adding a feature so posts can belong to a series changes what the system can do — that's a piece of work with steps and documents. Publishing a post is a chore the system already supports, done the same way every time — wrapping each one in seven steps is ceremony, and it's the fastest way to make everybody route around all of this.

   aidlc add skill publish-release-notes --description "Publish notes for a tagged release"
   

   The skill is written to .aidlc/operational-skills/publish-release-notes.md, with a small file for your assistant beside it. It always asks before writing, because a skill is instructions an agent will run later.

   The important part is what gets scaffolded with it: the verification lives inside the skill. Facts checked, links resolved, build run — as steps of the skill itself, not as a review wrapped around each invocation. A skill carrying its own checks produces checked output every time it runs. A skill relying on somebody remembering to review it produces checked output sometimes.

   There's an escape hatch worth knowing. Sometimes running a chore reveals a missing capability — you go to publish and find there's no way to mark something a draft. At that point the chore stops being the work, and the missing capability becomes an ordinary piece of work. What you must not do is quietly grow the skill into building the feature.

   aidlc add action is the smaller sibling: run something automatically on a lifecycle event. This project uses one to cut a branch whenever work starts, and one to move an idea to done when the work it became completes.

5. 5. Doctor — repairing the repository

   Repositories accumulate rubbish: ignore rules that no longer cover what they should, layouts left over from an older version, generated files that got committed by accident.

   aidlc doctor --dry-run
   

   Two tiers, and the split is the interesting bit. Safe repairs apply on their own — adding a missing ignore rule harms nobody. The rest describe themselves and wait for your yes, because anything that could surprise you must be your decision. --dry-run shows both without doing either, and --yes confirms them all. In the frame, doctor would add five missing .gitattributes entries. The lines that start skipped are checks that found nothing to do here.

   The same pass runs during aidlc update, with one difference that's a deliberate design choice: doctor exits non-zero when confirmable work is pending, and update never fails for it. A command you run to check health should be able to fail; a command you run to get the latest version should not fail because of unrelated tidying.

6. 6. Hooks, and a short statement of what the repo is for

   Two more things you set up once. Both are opt-in or one command.

   A session that knows where it is. When an assistant session starts, is cleared or is compacted, it forgets which piece of work it had a claim on. The session-start hook tells it which instance is claimed. aidlc init installs it by default for Claude Code. In an older project, add it yourself:

   aidlc hook install
   

   From then on a new session is told the claimed instance (with its template and scope), its phase and the next step, in three lines at most. If you run the hook by hand in a project with a claim, it prints this:

   AIDLC: instance price-alerts is claimed in this checkout (full-feature template, full scope).
   Phase: ideation. Phase instructions: .aidlc/skills/aidlc-ideation.md
   Next step: produce idea.md. Resume with the aidlc-continue skill.
   

   A guard you choose. Planning phases are for documents. The phase guard asks before a project file outside .aidlc/ is edited during ideation, requirements or design:

   aidlc hook install --guard
   

   It only asks. It never blocks on its own, and it can't see files written through the shell, so it is a guardrail, not a wall. It is for Claude Code. To take it away again:

   aidlc hook remove --guard
   

   aidlc hook remove on its own removes both hooks.

   The constitution is the other thing every phase reads first. It says what this repo is for and what it must never become. You don't write it from nothing. You start from your product vision document:

   aidlc constitution import docs/vision.md
   

   That reads a .docx, .md, .markdown or .txt file into a snapshot and lists the statements it found:

   Imported docs/vision.md → .aidlc/context/vision-source.md
     extractor: text, statements: 4
   

   Then the aidlc-constitution skill turns those statements into .aidlc/context/constitution.md. Every phase reads that file at the start, the way it reads guidance. It is also what makes "no, not for us" a reason someone can read when you triage an idea.

   Visions change. To see whether yours did:

   aidlc constitution check
   

   It reports statements added or removed since the last import, and says whether the constitution cites any that were removed. It is advice only. It never stops a phase.

7. 7. The same setup on six assistants

   The lifecycle instructions live once, in .aidlc/skills/, as plain markdown. Setup packages that same text into whatever native format each assistant expects — Claude Code and Codex each get files in their own convention, generated from one canonical body.

   npx @rasensio/aidlc init --platform claude-code
   

   Which means switching assistants, or having two people on different ones, doesn't fork your process. The rules are in your repository; the packaging is per-tool. And when the framework updates, aidlc update refreshes the generated files and leaves everything you wrote — your guidance layers, your context documents, your ideas — alone.

   One caution learned the hard way here: npx <tool> will happily prefer a globally installed copy over your local one. If a command reports that nothing changed while you're looking at changed files on disk, that's usually why.

8. 8. Checkpoint

   checkpoint

   At the end of a piece of work you write down something that went wrong. What has to happen for the next piece of work to benefit?

   • Nothing — the note is read at the start of the next job.
   • Somebody has to remember it and repeat it.
   • It has to be turned into a check that blocks the work.
   • It needs to become a task somebody is assigned.

   This checkpoint needs JavaScript.

9. 9. What you can do now

   You've been through the whole surface. Concretely, you can now: read a piece of work's state off the disk; pick the right amount of process for it; read a blocked check and fix it; ask what the project already knows instead of re-reading code; find out what something cost, including the bugs it caused; keep an idea list that doesn't rot; run alongside somebody else without losing work; and turn a repeated lesson or a repeated chore into something that carries itself forward; and tell a new session where it is, ask before code changes during planning, and keep a short statement of what the repo is for.

   The one thing worth carrying out of all of it: every check you add is paid for by every future job, forever. This project shipped eleven features in nine days and then spent five days almost entirely on fixes, because most of what it had shipped were features that watch the process rather than serve a user. Guidance somebody reads costs nothing to anyone who doesn't need it. A gate costs everybody, every time. Prefer the former, and hold the latter to a much higher bar.

   When you want to know why something works the way it does, aidlc explain is where to ask.

   Reference for everything mentioned here: the command reference, the skills, the workflows, and the glossary for any word that's been used carefully.