The deep dive · chapter 8 · 8 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

   $ cat .aidlc/guidance/lessons.md
   
   # Lessons
   
   - Two sessions in one folder collide on git, not on state.
     Use a worktree for concurrent work.
   - A follow-up written as prose is not a work item. If a fix
     is understood well enough to write down, capture it.

   where these came from

   Each line was written at the
   end of a piece of work that
   went wrong.
   
   The next piece of work reads
   this file before it starts.

   ← 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. When a piece of work completes, the retrospective captures what was learned and appends it there. 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 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: lock files from crashed sessions, ignore rules that no longer cover what they should, 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. Confirm repairs describe themselves and wait, because anything that could surprise you must be your decision. --dry-run shows both without doing either.

   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. 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, Cursor, Kiro, Codex, Windsurf and GitHub Copilot all 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.

7. 7. 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.

8. 8. 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.

   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.

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