For years, the hardest part of software development was turning ideas into working code. Planning was simple. You sketched out a feature, estimated the effort, and then spent weeks writing, debugging, and testing. Artificial intelligence turned that workflow upside down. Now I can design a feature in twenty minutes and have a functional prototype by the afternoon. The bottleneck didn’t disappear—it shifted. The new challenge is keeping track of everything I have in motion. Without a reliable method for tracking ai projects, I ended up with a dozen half-built plans and no clear picture of what was alive, stalled, or dead. This article explains the problem, why conventional tools fail, and a plain-text convention I built to solve it.
The New Bottleneck: Knowing What You Are Actually Building
For most of my career, writing code was the slowest step. Planning took an hour; implementation took days or weeks. AI assistants like Claude Code, Cursor, and Windsurf changed that equation. I can now scope a feature conversationally and generate a working prototype in a single afternoon. That shift is genuinely transformative. But the constraint did not vanish—it relocated.
The new bottleneck is awareness. Instead of struggling to write code, I struggle to remember what I am working on. At any given moment, I have two or three active builds, a couple of stalled experiments, and several more ideas that never advanced past the planning stage. Dependencies between these plans linger in my memory for a day or two and then fade. When someone asks me for a status update, I cannot answer without reading through scattered files and re-discovering my own intentions. This is the real productivity problem that AI introduced, and it is the one no existing tool has solved for solo developers or small teams.
Effective tracking ai projects requires a method that matches the pace and volatility of AI-assisted work. Traditional project management software assumes stable, team-driven workflows. The reality of AI-assisted development is different: many small, parallel, frequently shifting tasks with unclear states and rapid context switches.
The Mess: Half-Built Projects Everywhere
Concretely, here is what the chaos looked like for me. In any given month, my workspace contained:
- Two or three active plans I was currently implementing
- One or two stalled plans I had started enthusiastically and abandoned around the sixty-percent mark
- A handful of ideas I had asked AI to outline but never moved past the design document
- Several “I should pick this up again” thoughts about half-finished features from two months prior
- Invisible dependencies between these pieces—knowledge I had when creating them and later forgot
Every one of these generated a FEATURE_X_PLAN.md file somewhere in the repository. At one point, I counted thirty-eight plan files at the root of a single repo. None of them could be quickly classified as active or abandoned without re-reading the entire document. The result was painful: when a stakeholder—or future-me opening the repository after a few weeks away—asked about the current state, I could not answer. Not a vague answer; I genuinely could not produce a clear summary without an hour of archaeological work.
This experience underscores why tracking ai projects demands a different approach. The volume of generated ideas is high, but the visibility is low. The cost of starting a new project has plummeted; the cost of keeping tabs on all of them has skyrocketed.
Why Existing Tools Fail for AI-Assisted Solo Work
Jira
I tried Jira first. It worked for about a week. Opening a browser tab, navigating through boards, clicking dropdowns, and filling custom fields became significantly higher friction than writing one more markdown file in the editor. The overhead of leaving the development environment to update a ticket killed the habit.
Linear
Linear offered a cleaner user experience. The same friction point remained: any interaction outside the code editor felt like a context switch too many. After a few days, the tool sat unused. A better interface does not solve the problem of requiring a different place to log information.
Notion
Notion lasted the longest because it felt closer to writing. I created a workspace with linked databases and status properties. For three weeks, I dutifully updated it. Then I stopped. The tool became a third source of state rather than the single source of truth. I had plan files in the repository, notes in Notion, and mental notes—all diverging. Instead of simplifying, it added complexity.
These tools share a common design assumption: they are built for teams shipping a small number of larger items in a coordinated way. That model does not fit AI-assisted solo development, which generates many small, parallel, frequently changing pieces of work. Forcing high-velocity AI output into team-throughput tools creates friction. That friction is the symptom of a mismatch.
The Pattern: Tracking AI Projects in Plain Text
I needed a solution that lived inside the repository, required no external service, and could be read natively by AI coding assistants. I wrote a markdown convention. It is not a tool or a SaaS subscription. It is a structure of directories, a frontmatter schema, and a single HTML dashboard. The entire system is about three hundred lines of code.
The core insight: tracking ai projects works best when the tracking mechanism is as lightweight as the project creation process. If recording a plan takes longer than generating the plan, no one will keep records. The convention I built takes seconds to apply and integrates directly into the workflow.
The Three-Directory Structure
The entire convention rests on three directories inside the repository:
- plans/active – what you are actively building right now
- plans/shipped – what you completed (keep these as records)
- plans/superseded – what you abandoned (keep these to understand why)
The do not delete rule matters. Old plans are evidence of how a project evolved. Deleting them removes the history of decisions and false starts. When you revisit a project months later, those superseded plans explain why you went in a different direction. They become a log of reasoning, not just a graveyard of dead ideas.
The Seven-Field Frontmatter
Each plan file starts with YAML frontmatter containing exactly seven fields:
You may also enjoy reading: 3 Advanced JavaScript Array Methods: Map, Filter, Reduce.
- status – active, stalled, shipped, or superseded
- priority – high, medium, low, or none
- owner – who is responsible (even in solo work, naming yourself helps)
- type – feature, bug, experiment, refactor, research
- depends_on – list of other plan files this one requires
- blocks – list of other plan files that depend on this one
- last_updated – ISO date of last change
The depends_on and blocks fields perform the heaviest lifting. They create a dependency graph that is invisible in a standard file list but explicit in the frontmatter. When I mark a plan as stalled, I can immediately see which other plans are blocked by it. When I complete a plan, I know which downstream plans can move forward. This visibility prevents the silent accumulation of blocked work that I have forgotten about.
The STATUS.md File and Dashboard
At plans/STATUS.md, I maintain a one-page summary of every plan’s current state. It is a simple markdown table regenerated from the frontmatter of all plan files. A quick glance tells me exactly how many plans are active, stalled, shipped, or superseded.
Beyond the markdown summary, I built a small HTML dashboard. It reads a plans.json file (generated from the frontmatter) and renders an interactive Gantt chart plus a dependency graph. The entire dashboard is a single file, about three hundred lines of HTML and JavaScript. It runs in any browser with no server required. When I open it, I see the full landscape of my work: which tasks overlap, where dependencies create bottlenecks, and how priorities distribute across time.
This combination—plain text files plus a lightweight visual layer—gives me both the simplicity of markdown and the clarity of a project timeline. It fits perfectly into the workflow of tracking ai projects because the source data is exactly what AI assistants can read, and the dashboard provides the human overview.
Why This Convention Works for AI-Assisted Work
Three properties make this approach effective for the pace and volatility of AI-driven development:
Zero friction. Creating a new plan file requires no tool switch. I stay inside my editor. The frontmatter template reduces to a few keystrokes. If generating a plan takes less effort to write a plan than to open a browser tab and log into a project management system.
Native AI readability. AI coding assistants like Claude Code, Cursor, and Windsurf read plain text files natively. When I ask an assistant to “update the status of the authentication plan to shipped,” it can parse the frontmatter, modify the YAML, and even regenerate the STATUS.md file. The convention becomes a data source that AI can interact with, not a human-only artifact.
Single source of truth. The plan files live in the repository alongside the code. There is no external system to synchronize. When I clone a repository on a new machine, the entire state of my project management travels with it. No export, no login, no schema mismatch.
How to Implement This Yourself
To adopt this convention for your own work, follow these steps:
- Create the directory structure. Inside your repository root, create plans/active, plans/shipped, and plans/superseded.
- Define a frontmatter template. Write a YAML snippet with the seven fields: status, priority, owner, type, depends_on, blocks, last_updated. Save it as a template you can copy for each new plan.
- Adopt the habit. Every time you start a new feature or experiment with AI, create a plan file in plans/active. Fill in the frontmatter honestly. It takes thirty seconds and pays back exponentially when you later need to recall what you were doing.
- Move files when state changes. When a plan ships, move it from active to shipped. When you abandon it, move it to superseded. Do not delete the file—just move it. The file remains as a record.
- Create a STATUS.md generator. Write a small script (bash, Python, or Node.js) that reads all plan files, parses the frontmatter, and outputs a summary table. Run it periodically or after each major change.
- Optionally, build a dashboard. If you want a visual overview, write a script that exports the frontmatter to JSON, then create a lightweight HTML page that renders a Gantt chart and dependency graph using a library like D3.js or a simple canvas.
- Integrate with AI assistants. Tell your AI coding assistant that plan files are authoritative. Ask it to update frontmatter or generate reports. Because the files are plain text, the assistant can manipulate them directly.
The whole setup takes about an hour to create and minutes to maintain. It scales from one project to many because the file count grows linearly but the overhead stays flat. For tracking ai projects, this pattern provides the necessary transparency without the overhead of traditional project management tools.
The shift AI brought to development is irreversible. Building is easy; knowing what you built is the new challenge. A lightweight, repository-native convention bridges that gap. It keeps you honest about what is in progress, what is blocked, and what is abandoned. More importantly, it preserves the reasoning behind every decision, so future-you never has to guess why something was left half-done.
