A markdown convention I wrote to track 5-10 half-built projects without losing my mind, and without another SaaS subscription.
TL;DR. AI made it cheap to generate ideas, draft plans, and start projects. It did not make it cheap to track them. I ended up with 5-10 half-built projects, plan files everywhere, no idea which were stalled vs. blocked vs. abandoned, and no way to explain status to stakeholders or even to future-me. I tried Jira, Linear, Notion, none stuck. I wrote a markdown convention for myself instead: 3 directories, 7-field frontmatter, one HTML dashboard. AI coding assistants (Claude Code, Cursor, Antigravity, Windsurf) read it natively as a side effect. Repo at the bottom.
The new bottleneck
For most of my career, the bottleneck was writing the code. Planning was the easy part. You'd think a feature through, scope it, then spend the next two weeks actually building it.
AI inverted this. I can now scope a feature with Claude in 20 minutes and have a working prototype in an afternoon. That's genuinely transformative. But the bottleneck didn't disappear, it moved.
The new bottleneck is knowing what I'm actually working on.
I have 5-10 half-built projects right now. Some I started with AI and never finished. Some I planned with AI and never started. Some are blocked on something I forgot. Some are stalled because I lost interest two weeks in. Some have dependencies on other half-built things, and the dependencies aren't visible anywhere.
If you asked me "what are you actively building this week?", I genuinely couldn't tell you without opening five repos and reading scattered markdown files. That's the real productivity problem AI introduced, and it's the one no tool I tried actually solves.
What the mess looks like in practice
Concretely, in any given month, I'll have:
- 2-3 active plans I'm working on right now
- 1-2 stalled plans I started enthusiastically and quietly abandoned around the 60% mark
- 2-3 ideas I asked AI to plan out that never moved past the planning doc
- A few "I should pick this up again" thoughts about half-built things from 2 months ago
- Dependencies between some of these that I knew when I wrote them and have since forgotten
Every one of those generates a FEATURE_X_PLAN.md somewhere. At one point I had 38 plan files at the root of one repo, none of which I could quickly classify as "alive" or "dead" without re-reading them.
The result: when someone (a stakeholder, or future-me opening the repo cold after weeks away) asked me what state things were in, I couldn't answer. Not "I gave a vague answer", I genuinely could not produce a clear answer without an hour of archaeological work.
What I'd tried
Jira. Worked for a week. Opening a browser tab and clicking through fields became higher friction than writing one more markdown file in the editor.
Linear. Same outcome, faster. Better UX doesn't matter if the friction is "leave my editor".
Notion. Lasted longer because it felt closer to writing. Sat unused after three weeks anyway. Became a third source of state, not a single source.
Pattern I missed for too long: these tools are built for teams shipping a small number of larger things in a coordinated way. That's not what AI-assisted solo work looks like. AI-assisted work generates a larger number of smaller, parallel, shifting things with unclear states and frequent context switches. Different shape of work needs a different shape of tracking.
Forcing AI-velocity work into team-throughput tools is the wrong fit, and the friction is the symptom.
What I built instead
A convention, not a tool. Lives entirely in the repo as plain text.
Three directories:
plans/
active/ <- what's being built right now
shipped/ <- what's done (don't delete, keep the receipts)
superseded/ <- what got abandoned (don't delete, keep the why)
The "don't delete" part matters. Old plans are evidence of how a project actually evolved. Deleting them erases the history of decisions.
One file per feature, with 7 fields of frontmatter:
---
status: active
priority: P1
owner: yasiru
type: feature
depends_on: []
blocks: []
last_updated: 2026-05-17
---
The depends_on and blocks fields are the ones that quietly do the most work. Plans aren't independent; they have a dependency graph, and the graph is what lets me see "I can't start B until A ships."
One STATUS.md at plans/STATUS.md that answers "where are we right now" in one place. In flight, up next, recently shipped, backlog. I open this in the morning instead of trying to remember.
One HTML dashboard (roadmap.html) that reads the auto-generated plans.json and renders an interactive Gantt + dependency graph + filterable cards. Static file, no server, no account, no login. This is the thing I send to stakeholders. They open a URL, they see what's happening. No tool training, no permissions, no monthly seat cost. Just a webpage.
The whole convention is about 300 lines of code and lives in your repo. No service, no build step.
The AI part wasn't the goal, but it ended up mattering
I built this for me. The primary audience is the human (often future-me) trying to remember what state 8 different projects are in.
But because the format is plain markdown with predictable structure, AI coding assistants read it natively. No integration, no MCP server, no plugin. Claude Code, Cursor, Antigravity, Windsurf, all of them just open the files and know what's in flight.
When I start a Claude session now, it reads STATUS.md and the relevant plan files. It already knows the state. We start working in two messages instead of fifteen.
That wasn't the goal. It's a consequence of writing things down clearly.
The insight that made it click: AI didn't fix my planning problem. AI made my planning problem urgent. The fix was structure I should have had all along.
What actually changed
Three things, in order of unexpected impact.
One: I can answer "what are you building this week" in 10 seconds. I open STATUS.md. The answer is there. I didn't realise how much cognitive load I was carrying around not being able to answer that question instantly.
Two: stakeholders and future-me can see the dashboard. When someone asks about a project's status, I send the roadmap.html link. When future-me opens a side project I haven't touched in two months, the dashboard tells me where I left off without an archaeological dig. The dashboard is a static page, no login, works on phone. Status updates went from "I owe you a write-up" to "here's the link, click around."
Three: AI sessions stopped opening with 15 minutes of context. Side effect, but a big one. The AI now knows what I shipped last week without me re-explaining.
The 5-10 half-built projects didn't go away. I still have them. But now I can see them, classify them, and consciously decide what to do with each one. Some moved to superseded/ (honest "I'm not finishing this"). Some moved to a "later" status with a reason. Some got picked up again because seeing them on the dashboard reminded me I cared.
The mess didn't vanish; it became legible.
Where this fits in the wider trend
AI-assisted development is shifting toward spec-driven workflows. The spec, the plan, the structured intent becomes a first-class artifact that your AI assistant reads and writes against, not just a doc you wrote once and forgot.
GitHub's Spec Kit (released late 2025) handles the per-feature spec workflow really well: define one feature, generate its spec, generate the plan, generate the tasks, execute. It's good.
Plans is the portfolio layer for the same shift. Spec Kit answers "how do I build this one feature well". Plans answers "what are the 8 features I'm juggling, which are alive, which are dead, which are blocked, and what's the next thing I should pick up". Different layer of the same trend.
If you're already doing spec-driven work with Spec Kit (or anything similar), Plans is the thing that keeps the multi-feature view legible. If you're not yet doing spec-driven work, Plans is a low-cost way to start, because the convention itself nudges you in that direction.
Why I'm sharing this now
Two reasons.
One: I'm genuinely curious whether this is a me-problem or a universal one. If you're a solo dev or small team using AI coding assistants, do you also have 5-10 half-built things you can't track? How are you managing it? I want to know if I built something useful only to me, or if this is a real shared pain that nobody's solved.
Two: the convention is MIT and the repo is public. If it sounds useful, the install is one curl one-liner. If it doesn't fit your workflow, that's also useful signal for me.
Where to find it
Repo, docs, live dashboard demo, and install instructions: github.com/yrangana/Plans
If you try it, I'd love to know what works and what breaks. If you don't try it but the problem resonates, I'd love to know how you've solved it yourself. Either way, drop a comment, that's the signal I'm actually trying to gather.
Built this as a personal tool, sharing it as a convention. No business model, no roadmap pressure, just markdown files and one HTML dashboard. If a bigger player (GitHub, Anthropic, etc.) ships something better in 6 months, I'll happily migrate. Until then, this is what I use.
Top comments (0)