Skip to content
Agent Fundamentals

The board

The board is a folder: .agent/board/, one markdown file per ticket. The app renders it as three columns — and only three:

Backlog  →  Doing  →  Done

Two invariants keep it honest: only one ticket is in Doing at any time (the agent finishes or splits before starting the next), and stations are never invented — a ticket is in one of these three, or the app shows an error banner.

A ticket is a file

Section titled “A ticket is a file”
---
id: site-scaffold
title: Scaffold the site
station: Backlog
created: 2026-08-26T08:25:00Z
order: 1
plan: agent-fundamentals-website
---
## Scope
What this ticket covers — small enough for one agent run.


## Acceptance criteria
How both sides know it is done.

Two optional flags matter to you as the owner:

  • needs_human: true — a human must act (a manual test, an account, a DNS entry). The app surfaces these so they don’t rot in Backlog.
  • open_question: Q1 — the agent is blocked on a question you haven’t answered yet. See Questions.

Where tickets come from

Section titled “Where tickets come from”

A fresh project has a plan and an empty board. The agent reads the active plan (lifecycle: active — only one plan may be active), slices it into small tickets ordered by order, and then works the board: pick the top Backlog ticket, set it to Doing, do the work, commit, set it to Done. A ticket that turns out too big is split into smaller ones rather than left half-done.

History: the inspector’s memory

Section titled “History: the inspector’s memory”

Each ticket has an append-only log, .agent/board/history/<id>/index.jsonl — one JSON line per meaningful step:

{"actor":"agent","event_type":"station_changed","summary":"Backlog -> Doing","ticket_id":"site-scaffold","timestamp":"2026-08-26T09:05:30Z"}

The app logs what the app changes; the agent logs its own steps — creating and moving tickets, recording answered questions, running a skill. The event types (ticket_created, station_changed, ticket_edited, agent_run) each get an icon in the ticket inspector, so you can reconstruct any ticket’s life without reading a terminal transcript.