how-we-build / chapter 1

Step 1 of the loop

Tasks that live with the code

Most teams track work in a tool that lives somewhere else — a browser tab that slowly stops matching reality. We do the opposite: every project carries its own task database inside the repo. Clone the code, get the backlog.

The problem it solves

AI agents forget. A human engineer holds a plan in their head between sessions; an agent starts every session cold. If the plan lives in a chat transcript or a markdown TODO, it's gone or stale by tomorrow. And if it lives in an external tracker, nothing forces it to stay in sync with the code it describes.

The fix is structural: put the task graph in the repo, next to the code it changes. Version-controlled, branch-aware, merged like everything else. When work and code travel together, staying in sync is the default — and what still drifts gets caught, which is chapter 2's whole job.

How it works

The task layer runs on beads (bd) — an open-source, dependency-aware issue tracker built for AI agents, with 25k+ GitHub stars. Each project keeps a small database in a .beads/ directory, exported to a plain JSONL file that git tracks. Key properties:

  • A graph, not a list. Tasks declare dependencies; bd ready shows only work with no open blockers, so an agent never picks up something it can't finish.
  • Built for many hands. Several agents can create tasks at the same time, on different branches, without colliding — the IDs are hash-based, so they never clash.
  • Epics with children. Big goals decompose into small claims, and progress rolls up.
  • Close with evidence. A task doesn't just get checked off — it closes with a reason that says what shipped.

One repo, one loop

THE REPO

Code + a tracked task file. The backlog clones with the project.

THE AGENT

Runs bd ready, claims a task, does the work.

THE CLOSE

Task closes with evidence; the update commits with the code.

↺ the updated task file is part of the same push — work and record never separate

What an agent sees

A session starts with one command and gets back the live state of the project — what's ready, what's claimed, what's blocked: 

$ bd ready
# tasks with no open blockers, ready to claim
$ bd update <id> --claim
# atomically assigns the task and marks it in progress
$ bd close <id> --reason "shipped: retry logic + test, all green"
# closed with evidence — the audit trail is the point

Illustration — invented examples, not real tasks

Add retry logic to the nightly export

task · ready · no blockers · parent: harden the data pipeline

Write the onboarding doc for new agents

task · in progress · claimed this session

Our house rules on top

The tool is upstream open source; the discipline is ours:

  • Plain-English titles. Every task is a full sentence a stranger could act on. IDs are command handles, never conversation.
  • Every task has a parent epic whose title describes the cluster — no orphan work.
  • No task, no code. Work gets a tracked task before the first line is written, and nothing is "done" until it's closed with evidence.

Multiply this by every project on the estate and you get the input to the next chapter: dozens of little databases, each honest about its own project — and no single place to see them all. That's what mission control is for.