How to Keep Massive AI-Assisted Side Projects on Track

A repo-native coordination layer for AI-assisted projects

Most of my side projects die in a week.

After the excitement of the first sprint fades, life gets in the way. A full-time job. A family. Weekends with the thousand small obligations. By the following Saturday, the grand vision I had on Sunday is mostly gone, and what’s left is a folder of half-finished files.

AI changes the shape of this, but doesn’t solve it. The first sprint goes further than it used to, as an evening of work now produces what used to take a few weeks. But the rest of the project still takes weeks of real effort. The bugs, the integrations, the edge cases. AI sessions routinely tell me a feature is a six-month project when I know from experience it’s three to four hours with AI.

So AI puts more things within reach. But only if I can hold the work together across sessions and through the gaps where life takes over. Every new session starts cold. The chat history dies; whatever the model figured out on Saturday is gone on Wednesday. The project lives in my head between sessions, and my head, already full, turns out to be a bad place to put it.

What I’ve been doing for the last few weeks is putting that state inside the repo, in a form that an AI session can pick up cold, and that is what I’ll share in this post.

“What are we building today?”

If you build with AI coding tools, you know that writing code is easy. It’s preserving direction across context loss that troubles me.

Every conversation starts from scratch. Prior decisions have to be re-derived. The model doesn’t know what you tried last week, what you decided not to do, or what surprised you the first time you went near a part of the codebase. You can hold all of that in your head for a while, but the longer the project runs, the more it slips. Eventually, you sit down on a Saturday, and the project is a folder of files you only half-recognize.

The fix has to live somewhere the model can read. Something durable, version-controlled, and close to the code. Something a session can open on a Wednesday night and tell you what shape the project was in when you walked away.

That’s what changed for me. I sit down, open Claude Code, and ask: *what are we building?*The session reads the repo, checks the plan, and answers. Sometimes it’s the slice I queued last week. Sometimes it’s something I’d forgotten existed. Either way, the answer is there before me, ready to be executed. n

The project I couldn’t quit

Flow-State aggregates Colorado river data from five public agencies and tells you whether your favorite section is running. I’m a former river guide and avid private boater, and I hate pulling data from government websites built in 1998. I built it for myself. I shipped a working v1 on a livestream in about two hours, as a non-developer building in public.

When the livestream ended, I wanted to keep going. That’s the part that doesn’t usually happen for me. Flow-State just happens to be the project that finally forced me to figure out how to not lose it.

I work on it in short bursts. Usually 30-90 minutes as I watch a show after my dad duties are done for the day.

My design for the coordination layer

Before the system, a quick note on what it isn’t.

There are real memory systems out there that solve a version of this problem. Cortex, an open-source memory layer, gives agents a shared brain with vector search and real-time sync. Mem0 does something similar with a different shape and a paid subscription. Claude Code now has memory features. Any of them might be able to do this, but that needs setup, maintenance, and layers of work I don’t want to do.

They are not wrong; it’s just that tools are changing fast enough that I might be coding in a completely different way a month from now. I wanted something I could open in any repo, on any machine, with any AI tool in front of me, without setup or special knowledge. Something that would survive me switching from Claude Code to whatever’s next, and a format I can scaffold into any project with a single prompt.

So here’s the structure.

I asked Claude Code, in a single prompt, to scaffold a product vision, a roadmap, and a component-tracking system inside the repo. The output was a directory called .plans/ with four things in it:

• A vision folder. Short markdown files answering the why questions: what is this project for, who is it for, what counts as success, and what it’s explicitly not. These rarely change.
• A roadmap. A single ordered queue of work, each item with its own folder and a frontmatter block recording value, effort, dependencies, and status.
• A slices directory. The queue itself is one folder per unit of work. The current slice has a full plan with file paths and acceptance criteria. The next few have lighter sketches. Far-out slices get a paragraph called what success looks like.
• A lessons directory. Things the project has learned the hard way. Each lesson follows a fixed template: what I assumed, how it broke, what’s actually true, and how to recognize the pattern next time.

The whole thing is markdown in a folder. No database, no embeddings, no semantic index. I kept most of what the model generated, edited a few of the conventions, and started using it that evening. The bootstrap was 20 minutes.

A note on why this matters: the value of building it this way wasn’t that I designed the perfect system. It was that I got something in place fast enough to actually use it. The first iteration was crude. Several weeks of real use have refined it. None of that refinement would have happened if I’d spent two weekends designing the perfect tracker before starting.

How I actually use it

Most sessions start the same way. I open Claude Code against the repo and ask: what’s next to build?

The session reads .plans/, pulls in any lessons that look relevant, checks the current state of the codebase, and tells me where the project is. Usually, it points to a slice I queued a week ago. Sometimes it’s a slice I’d forgotten existed. Once in a while, it’s something that wasn’t queued at all, and the session notices that the code and the plan have drifted apart and flags it.

Then I redirect. Often.

A typical conversation: No, hold on, I just got back from a Browns Canyon trip, and I want to log it. Let’s build the river-log feature, ignore the queue. Or: I’m ready to start on the forecast model, but I just realized it needs at least thirteen months of historical data to be useful, and we don’t have it. Let’s queue a backfill slice before any of the forecast work. The session reshuffles the queue, updates the affected frontmatter, regenerates the roadmap, and we go. The work I was about to do gets moved, and the thing that actually needed to happen first takes its place.

The git log is full of these. Queue river log slices ahead of forecast work. That commit moved seven slices in front of the work I’d told myself was the actual reason for the project. Insert a thirteen-month backfill between two existing slices. That one wedged a data-backfill slice into the middle of a dependency chain because no forecaster would produce real numbers without history. Queue a new snowpack audit slice that didn’t exist before. That slice was a tangent I noticed on a Saturday and queued in ten minutes.

Each of those reorderings was a short conversation. In a previous life, each could have derailed the project, since my brain can’t juggle that many changes to the plan over several weeks.

In some ways, this setup gives my mild ADHD tendencies an anchor to hold on to without taking the project down with them.

What I’ve learned after a few weeks

The first thing is that the roadmap isn’t really a plan. It’s a record of what the project thinks it’s doing, that I can argue with.

It’s wrong almost every week, since my mind changes frequently. I show up on a Saturday, look at the queue, and immediately want to change something. For a while, I thought that meant the planning system was broken. The opposite turned out to be true. The pivoting is the work. The roadmap’s job isn’t to be right; its job is to absorb the corrections without losing the through-line. If I move three slices around on Monday, the system on Saturday still tells me what I was building and why.

The second thing is that the near-term slices aren’t more reliable than the far ones. The first version of the system was built around what I called a depth gradient: vague far out, detailed near in. That part is still true. But even the detailed near-in slices get rewritten before they get built. Everything is provisional until I’m actually doing it. n

The third thing is the one I didn’t expect. The point of any of this isn’t to follow the plan. The point is that the project has somewhere to be between Tuesday night and Saturday morning. When I come back, the queue is there. The lessons are there. The active slice is half-written. I don’t have to remember where I was. Claude continuously tracks it for me, without fail, across context windows.

That last part is what makes Flow-State feel like a sustainable side project for the first time in years. The 20 minutes I used to spend reconstructing what I’d been thinking is gone. I ask the system. It tells me. I either build or argue. Either way, we move forward.

A tax worth paying

This isn’t free, and I want to name the costs.

A meaningful share of my AI time goes into managing the project rather than writing code. Every “what’s next?” conversation reads the active slice, the next few queued, the relevant lessons, the roadmap, and a vision doc or two. A pivot doubles that, because the session also has to load whatever I’m pulling forward and update dependencies in several places. Tokens spent on project management add up.

In fact, I had a 30-minute session the other day where we didn’t write any code at all. I moved three slices around, wrote a new intent, killed a slice that turned out not to matter, and called it done. That can feel strange, a whole Saturday morning spent reorganizing a project instead of building it. The work was real, but it wasn’t the work I sat down to do.

There’s also a softer cost on my attention. The system asks me good questions, like does this slice still make sense? Is the order right? What should we defer? Those questions are a different mode than building, and they accumulate. Some weeks, I’m running a small planning meeting against myself before any code gets written.

If you’re considering doing this, go in knowing those costs exist. The system isn’t a free wrapper around what you were already doing. It adds to the work, but if I’m honest, it’s also the only thing that keeps my project alive, so it’s well worth it.

As I’m writing this, I’m realizing that I don’t even remember the vision I gave Flow-State. It has escaped my working memory. But that’s the point. It no longer has to be in my working memory; the repo itself is keeping the project together.

The system means I don’t have to hold project state in my head. The vision is in vision/. The roadmap is in ROADMAP.md. The decisions are recorded in the slice folders themselves. The mistakes are in lessons/. When I come back, all of it is still there. I argue with the AI about what’s next, redirect when I disagree, and start building inside of ten minutes.

The trade is tokens and attention for resumability. After a few weeks, I’d make it again. n

Why this might matter for you

If you’re building with AI tools across more than one session, and especially if your project is a side project that has to survive long gaps, you might hit the same wall I did. It’s not a code problem and it isn’t going to be fixed by a better model. The model can be perfect and the project will still die between sessions if the project state doesn’t live somewhere durable.

You don’t need anything sophisticated to start. You need a coordination layer the AI can read every time. Mine is markdown in a folder. Yours can be whatever fits. The pieces that matter are: a short statement of what you’re building and why, an ordered queue of work, per-item plans that grade from detailed (now) to vague (later), and a record of what the project has learned the hard way. The rest is decoration.

The interesting open question is whether something heavier would do better. A real memory system, with embeddings on the lessons, semantic search across slices, and retrieval that knows what you’ve worked on before, would probably have better recall than what I have now. It would also be a system to maintain. The bar I cared about was not best possible context retrieval. It was good enough that I keep coming back. Markdown in a folder cleared that bar on the first night and is still clearing it.

If I were starting a new side project today, the first thing I’d do, before any feature work, is ask the model to scaffold a coordination layer like this in the repo. It takes 20 minutes. It changes the shape of every session after.

Flow-State is still small. 80% of the features are still in the queue, and it will probably look different next week. But it’s still alive, and I’m still building it out because all it takes is a question: “What are we building today?”

So here’s the question for you: what’s the next project you’d actually finish if you spent 20 minutes setting up a repo to capture your vision and plan? n

Try it yourself

If you want to set this up in your own project, here’s roughly how I’d start.

Step 1: Capture your vision before you prompt anything

Before you ask the AI to scaffold a planning system, you need a vision for it to plan around. A vague vision produces a vague queue, and a vague queue won’t survive the gaps.

The trick I used was dictation. I opened ChatGPT on my phone, hit the voice button, and rambled for close to ten minutes about Flow-State: who it was for, what it should feel like, what I wanted it to do at v1 versus v3, what it explicitly wasn’t, what I’d already learned from the livestream build, what I was worried about. Stream of consciousness, no editing. Then I asked ChatGPT to summarize it back into a clean vision document, with one specific instruction: do not write any code, do not propose a file structure, do not suggest an architecture. Just organize what I said into a clear product vision.

ChatGPT’s dictation handles long sessions well, which is why I went there instead of typing. Ten minutes of talking turned into about a page of structured vision that I could actually read back and edit. That document is what I handed to Claude Code in the next step.

You can use any tool for this part. The only thing that matters is that you get your real vision out of your head and onto a page before you let an AI start structuring it. The structure is the easy part. The vision is the part only you can write. n

Step 2: Scaffold the coordination layer

Open Claude Code (or whatever AI coding agent you use) inside your repo and paste the prompt below. It will produce a .plans/ directory with vision, roadmap, slices, and lessons, all wired up and ready to use.

I want to scaffold a coordination layer inside this repo that survives long gaps between
sessions and lets any AI coding agent pick up cold and tell me what to build next.

Create a directory called `.plans/` at the root of the repo, containing:
1. `vision/` — markdown files capturing what this project is for, who it's for, what
   counts as success, and what it's explicitly not. These should rarely change. Use the
   vision document I'm providing as the starting content (see below).
2. `ROADMAP.md` — a single ordered queue of work. Each entry references a slice folder
   and includes value, effort, dependencies, and status in a frontmatter block.
3. `slices/` — one folder per unit of work. Use a depth gradient: the current slice gets
   a full plan with file paths and acceptance criteria; the next two or three get lighter
   sketches; far-out slices get a single paragraph called "what success looks like."
   Each slice folder has a frontmatter block with value, effort, dependencies, and status.
4. `lessons/` — markdown files capturing things the project has learned the hard way.
   Each lesson follows this template: what I assumed, how it broke, what's actually true,
   how to recognize the pattern next time. Start this folder empty; lessons accumulate
   as the project teaches them to me.
5. A short `.plans/README.md` explaining how the directory works, so any future session
   (or future me, or a different AI tool) can read it cold and know what to do.

Rules:
- Markdown only. No databases, no embeddings, no semantic indexes.
- Frontmatter blocks should be YAML and consistent across all slices.
- The roadmap should be regenerable from the slice frontmatter so I can ask you to
  rebuild it after a reshuffle without losing state.
- When I ask "what's next to build?" you should read .plans/ in full, check the current
  state of the codebase, and recommend the active slice (or flag if the code and the
  plan have drifted).
- When I redirect (move a slice, insert a new one, kill one), update ROADMAP.md and the
  affected slice folders together so they stay in sync.

Here is my vision document to seed `vision/`:
[PASTE YOUR VISION DOCUMENT HERE]

Before you start, ask me any clarifying questions about the vision or the structure.

Once we're aligned, scaffold the full directory.

Tweak the prompt if you want to. The shape is what matters: vision, roadmap, slices with a depth gradient, and lessons. Those are the four pieces that have earned their keep for me. Everything else is decoration. n

Step 3: Use it on your next session

Close the terminal. Come back next Saturday. Open Claude Code in the repo and ask: what are we building today?

If the system works the way mine works, you’ll get an answer before you’ve finished your coffee.

Good luck. Build the thing.