Task Tracking That Works for Humans and AI Agents

Sun 23 November 2025

AI agents are brilliant at writing code, but they have a habit that'll drive you nuts: they create new documents for everything. Status updates? New file. Planning notes? Another file. Task breakdown? Yet another markdown file sitting in your repo.

The problem isn't the files themselves—it's that you now have multiple sources of truth scattered everywhere, each one slightly out of sync with the code and with each other. You spend more time hunting down which STATUS.md is the real one than actually building features.

The Real Problem

When you're working with AI agents, you need a task tracking system that:

  • Works for both humans and AI—no special agent-only formats
  • Stays in sync with your code changes
  • Enforces a single source of truth by design
  • Doesn't require Jira or heavyweight project management tools

Most tools fail on at least one of these. Jira is too heavy. GitHub Issues live separate from your code. And letting agents create their own tracking files? That's a recipe for chaos.

A Different Approach

What if your task board was just a STATUS.md file that lives with your code? Not a special format that needs parsing, not a hidden database—just markdown that both you and your agents can read and update.

That's what MarkDeck does. It's a Kanban board that visualizes your STATUS.md file and keeps everything in sync. When you drag a card, it updates the file. When an agent updates the file, you see it on the board.

Two Formats, One Source of Truth

MarkDeck supports two modes depending on your needs:

Simple checkbox mode for quick task lists:

- [ ] Fix login bug
- [x] Update dependencies
- [ ] Write tests

This creates a two-column board (TODO → DONE). Perfect for straightforward checklists.

Full emoji mode for project tracking with status:

- 🔵 TODO: Implement user authentication
- 🟡 IN PROGRESS: Refactor database layer
- 🔴 BLOCKED: Need API keys from ops team
- 🟢 DONE: Set up CI pipeline

The RYGBO system (Red, Yellow, Green, Blue, Orange) maps to three columns: TODO (blue), IN PROGRESS (yellow), and DONE (green). Red and orange are blocked modifiers—they keep tasks in TODO or IN PROGRESS but flag them visually. No separate "blocked" column needed.

Why This Actually Works

The key insight is round-trip safety. When MarkDeck saves your STATUS.md, it preserves everything that isn't a card—your notes, code blocks, architecture diagrams, whatever. The file format is the source of truth, not the tool.

This means:

  • AI agents can update STATUS.md directly in code commits
  • You can edit it in any text editor
  • The Kanban view is just a nice visualization layer
  • Everything stays in sync with your code

No more hunting through five different tracking.md files to figure out what the agent was thinking. No more merge conflicts because the agent created its own version. One file, one truth.

GitHub Integration

MarkDeck syncs with GitHub using personal access tokens, so your STATUS.md stays current across your team. There's also a terminal viewer for quick status checks without opening the web UI:

npm run markdeck-tui

See your board right in the terminal—useful for those times when you're deep in the command line and just want a quick status check.

The Bigger Picture

The problem with agents creating documentation everywhere isn't just clutter. It's that they optimize for immediate task completion, not long-term maintainability. Each new file makes sense in the moment but becomes technical debt later.

By forcing everything through a single STATUS.md file, you're not restricting the agent—you're giving it clear boundaries. The agent knows exactly where to record progress, and you know exactly where to look. That's not a limitation; it's good design.

Try It Yourself

Check out the live demo or grab the code from GitHub. The README has the full format spec and examples.

The real win here isn't the Kanban view—plenty of tools do that. It's the recognition that when you're working with AI agents, you need systems that enforce single sources of truth by design. Otherwise, you'll spend more time managing documentation than shipping code.

Give it a go, you're probably already doing something similar with checklists.