Kodo Flow

What is Kodo Flow?

Kodo Flow is a lightweight, file-based task management methodology. Every task is a plain Markdown file sitting inside your repository, right alongside the code it describes. There is no external service to authenticate against, no database to back up, and no proprietary format to migrate away from someday. Your task history is your Git history.

Because tasks are ordinary files, they work with every editor, every CI system, and every AI coding tool. You can grep them, git log them, review them in a pull request, and auto-generate them from a script. Nothing about the methodology requires a specific IDE, plugin, or operating system.

The core idea is simple: a task moves through your workflow by moving its file between folders — backlog/, doing/, done/. The folder is the status. Git records who moved it and when. That is the entire system.

Core Principles

1. Tasks are documents. Every task is a self-contained Markdown file with YAML frontmatter and free-form prose sections. It carries its own context — why the work exists, what done looks like, which files are affected — so a developer (or an AI assistant) can understand it without hunting through a separate ticketing system.
2. The filesystem is the board. Status is encoded by folder location, not by a field value in a database. Moving a file is the status change. No API calls, no synchronization lag, no merge conflicts on a central store.
3. Git is the system of record. Every status transition, every edit to acceptance criteria, every note added mid-task — all of it flows through a normal git commit. You get a full audit trail, branching, code review, and blame for free.
4. Convention over configuration. The folder layout, frontmatter fields, and file naming scheme are defined once. Everyone on the team (and every tool) shares a single mental model. There is nothing to configure per-project.
5. Human-readable first, tool-friendly second. Task files read naturally as prose. Structured fields (frontmatter) are kept minimal so they stay easy to edit by hand. Tooling — editors, scripts, AI — can parse and manipulate them, but a developer with nothing but a terminal can always read, move, and update a task without any tooling at all.

Repository Structure

Kodo Flow uses three artifact types, each in its own folder. Where this root lives in your repository is up to you — docs/, a top-level folder, or anywhere else that fits your project.

your-root/
├── epics/                         # Broad initiatives (flat folder, no sub-states)
│   └── EPIC-1-platform-hardening.md
├── specs/                         # Requirements and design documents (flat folder)
│   └── SPEC-3-auth-requirements.md
└── tasks/                         # Kanban board — the only folder with sub-states
    ├── backlog/                   # Planned work not yet started
    │   └── TASK-1-add-login-page.md
    ├── doing/                     # Work currently in progress
    │   └── TASK-42-api-rate-limiting.md
    └── done/                      # Completed work (never deleted)
        └── TASK-7-initial-setup.md

Only tasks/ has the backlog/, doing/, done/ sub-states that form the Kanban board. Epics and specs are flat folders — they don't have a workflow status because they describe intent and requirements, not deliverable units of work.

File names always embed the stable ID: PREFIX-N-short-slug.md. The prefix and number are permanent; the slug is a human-readable hint that can be updated as the work evolves. See IDs and Cross-references for how artifacts reference each other.

The done/ folder accumulates completed tasks indefinitely. Do not delete them — they are a searchable record of decisions made and work delivered.

IDs and Cross-references

The three artifact types form a simple hierarchy. References only point upward — a child declares its parent, never the other way around:

Upward, child-declared membership

An epic is not responsible for knowing which specs belong to it, and a spec is not responsible for knowing which tasks implement it. Membership is always declared by the child. To find all specs under an epic, grep for epic: EPIC-N across the specs folder — the parent file itself never needs updating when a child is added or removed.

Stable IDs, not paths

Every artifact declares its ID in frontmatter and the ID is embedded in the file name. Cross-references always use just the ID — never a file path — so a file can be renamed without breaking any reference elsewhere in the system.

A spec referencing its parent epic can do so in several ways:

# Plain ID in frontmatter — canonical form, always accepted by tooling
epic: EPIC-1

# Markdown link in frontmatter — also accepted; tooling strips the path and reads the ID
epic: [EPIC-1](../epics/EPIC-1-platform-hardening.md)

# In prose — for human navigation in rendered Markdown
See [EPIC-1](../epics/EPIC-1-platform-hardening.md) for the initiative context.

The plain ID form is preferred in frontmatter fields. The Markdown link form is also accepted — useful when copying a reference from rendered prose — and tooling will resolve both identically. The ID prefix is always the authoritative key; the path component of the link is ignored.

Resolving an ID

Any ID can be resolved without tooling by grepping frontmatter across the repository:

grep -r "^id: SPEC-3" .

Renaming SPEC-3-auth-requirements.md to SPEC-3-authentication-and-authorization.md is a safe refactor: every reference says spec: SPEC-3, not a path. The only thing that must never change is the prefix and number.

No leading zeros

IDs use plain integers: TASK-1, TASK-42, EPIC-3, SPEC-12. Do not pad with zeros. Leading zeros create an artificial ceiling (pad to three digits and you imply a limit of 999) and make lexicographic sorting misleading once you exceed the padding width.

Task File Format

Each task file begins with YAML frontmatter, followed by free-form Markdown sections. Below is a complete example:

---
id: TASK-42
title: Add rate limiting to the public API
type: feature
priority: high
readiness: ready
epic: EPIC-1
spec: SPEC-3
labels:
  - backend
depends_on:
  - TASK-38
estimate: m
risk: low
created_at: 2026-03-01
---

## Goal

Prevent API abuse by enforcing per-client request limits without
degrading response times for well-behaved clients.

## Acceptance Criteria

- [ ] Requests exceeding the limit receive HTTP 429 with a `Retry-After` header
- [ ] Limits are configurable per API key tier (free / pro / enterprise)
- [ ] P99 latency for requests under the limit does not increase by more than 5 ms
- [ ] Limit counters reset on a rolling 60-second window

## Notes

Using an in-process token-bucket per worker. Redis is not available in
the current infra — revisit if we go multi-region.

## Code Paths

- `src/api/middleware/rate_limit.py`
- `src/api/config/tiers.yaml`

Frontmatter field reference

Markdown sections

The sections below the frontmatter are free-form prose. The names shown above (Goal, Acceptance Criteria, Notes, Code Paths) are recommended but not enforced. Add, rename, or omit sections to fit your team's needs. The only convention is that a task should always contain enough context that a developer — or an AI assistant — can pick it up cold and understand what needs to be done and why.

Getting Started

No installation required. Set up the folder structure, write a task file, and start working.

1. Create the folder structure inside your existing repository. Choose a root path that fits your project — a top-level folder, under docs/, or anywhere else:

   mkdir -p epics specs tasks/backlog tasks/doing tasks/done

   Commit this empty structure with a .gitkeep in each folder so the directories are tracked.
2. Write your first task. Create a file like tasks/backlog/TASK-1-your-first-task.md with at minimum a frontmatter block and a Goal section. Use the example above as a starting point.
3. Commit it to Git:

   git add tasks/
   git commit -m "chore: initialize Kodo Flow task structure"

   From this point on, every task change is a commit.
4. Start a task by moving it from backlog/ to doing/ and committing:

   git mv tasks/backlog/TASK-1-your-first-task.md \
           tasks/doing/TASK-1-your-first-task.md
   git commit -m "Start TASK-1"

   The folder move is the status change — no frontmatter edit required.
5. Complete a task by moving it to done/ and committing. The file stays in the repository forever as a record of delivered work.
6. Share the convention with your team. Add a brief note to your CONTRIBUTING.md explaining the task folder layout and frontmatter fields. That is the only "setup" other developers need.

Using the KodoFlow Extension

The methodology is designed to work with any editor and any toolchain. If you use Visual Studio Code, the KodoFlow extension gives you a visual Kanban board over this same file structure — drag cards between columns to move tasks, click a card to open its Markdown file, and create new tasks through a guided prompt.