Skip to content

Concepts ​

Items ​

An item is one Markdown file: YAML frontmatter, then a title heading and text. There are seven types, each in its own folder under the content root.

TypeIDFolderWhat it is
goalGOAL-00001goals/something you want to reach; may belong to an area
projectPRJ-00001projects/work towards one or more goals
taskTASK-00001tasks/a unit of work in a project, with a checklist and a state
adrADR-00001adr/a decision: proposed, accepted, deprecated or superseded
docDOC-00001docs/a guide that can list the code it covers
contextCTX-00001context/text for agents, synced into CLAUDE.md and AGENTS.md
runbookRUN-00001runbooks/steps for an operation, may cover code

The hierarchy is area → goal → project → task. The app shows it as columns of goals per area, a page per goal listing its projects, and a board per project.

IDs ​

An ID is a prefix and a number, padded to id_padding digits (5 by default). A new item gets the next number after the highest one in use, and IDs are what links point at. A file name is <ID>-<slug>.md: the slug follows the title, but the ID is what counts, so changing a title does not break links. (Because the next number is the highest plus one, deleting the newest item frees its number; netherite lint reports it if a deleted item's ID is still linked.) aliases in the frontmatter repeats the ID so other tools can resolve [[TASK-00042]] (see Obsidian).

Two kinds, and both end up in the graph:

  • Relations in frontmatter, which carry meaning: project, goals, decisions, depends_on, related, supersedes, superseded_by, explains.
  • Wikilinks in text: [[ID]], [[ID|label]], [[ID#Heading]]. Links in code spans and code blocks are not links.
FieldOnMeans
projecttask, ADRbelongs to that project
goalsprojectbelongs to those goals
decisionstask, projectimplements those ADRs
depends_ontaskcannot finish before these tasks; shown as "Waiting on"
relatedtasksee also
supersedes / superseded_byADRthe chain of replaced decisions
explainsdoc, runbookdescribes these items

Backlinks are computed, not stored: an item never needs editing because something links to it. An item that no other item links to is an orphan, unless it is a doc or runbook that sets explains, project or covers: those say what it belongs to themselves. Knowledge can filter to orphans, and the Inbox lists the orphaned decisions; a doc or runbook is raised there only when it goes stale.

States ​

A task's state is one of the names in your states config; each name has a category (todo, active, blocked, done) that decides its colour, whether a task counts as done in progress bars, and whether it shows in the Inbox as blocked. An ADR has a status instead. Progress for a project is tasks in a done state over all its tasks; for a goal, the same across its projects.

Dates and horizons ​

Start dates are never written: when work began comes from the git history (when a task first left the backlog, when a project got its first task). What you can write is where it should end. A goal or project takes due: YYYY-MM-DD; a project can also name a milestone that the date stands for. A goal takes a horizon, how far ahead it looks: forever, or a length such as 10 years, 6 months, 90d. Lint warns about a due before the item existed, a milestone without a due, and a horizon it cannot read.

Order ​

Goals inside an area, projects and tasks in a column are arranged by dragging them in the app. A move writes one optional position number to the moved item's file, so it is a one-line diff. An item without position sorts by the number in its ID, which is creation order. Areas are alphabetical, with goals that have no area last.

Freshness ​

A doc or runbook (or context item) with covers globs is fresh, drifting or stale, depending on how many commits since it was last reviewed touched the files it covers (thresholds in freshness). "Reviewed" is reviewed_at, or the doc's own last commit if there is none. Items without covers are not tracked, and neither are superseded or deprecated ADRs. Freshness needs git history; in a shallow clone the counts are minimums.

Context ​

Context items with include_in_context: true are rendered, highest priority first, into the files named in context.targets, until the token budget is used; what does not fit is reported by netherite context sync. They are also served to agents as the netherite://context resource.

Who writes the files ​

Every write, from the app, the CLI or an agent, goes through the same core operations: the new text is validated against the item schema, formatting and comments in the frontmatter are kept, and only the lines that must change are touched. If the file changed since it was read, the write is refused rather than overwriting someone's edit. Nothing is ever committed for you.

MIT licensed. Nothing is sent anywhere: it runs on your machine.