showrunner
Project management in the terminal — a journal-derived plan, rendered to text or HTML.
A project is two plain-text files: a tiny fixed-frame description and an append-only
journal. Every view — the task tree, what's blocked, what's next, whether you'll hit your
dates — is computed by replaying the journal. Nothing stores "current state," so nothing
can drift. Because replay is a pure function of (events, as-of), time-travel is free: ask
what any report looked like on any past date and it replays only the events up to then.
Recording a change is a single appended line that can't corrupt prior history — so a human or an AI operator can drive it equally well.
backyard-studio · status · as of 2026-06-30 (now)
──────────────────────────────────────────────────
1 in progress · 1 blocked · 1 milestone missed
Milestones
! ◆ Permit approved target 2026-06-20 (10 days ago, MISSED)
◆ Ready for framing inspection target 2026-06-30 → projected 2026-07-01 (+1d)
Blocked
⊘ Pour the foundation → waiting on Set the forms jeremy → Ready for framing inspection
In progress (what's actively moving right now)
◐ Set the forms est 2d bob (delegated) → Ready for framing inspection
Next: nothing to start yet
Watch: Permit approved is overdue; Ready for framing inspection projected +1d late
The two files
myproject.toml — the fixed frame: identity, the owner (you — "me"), and the
milestone goals. No tasks, estimates, or dates; those move, so they live in the journal.
[project]
name = "Backyard Studio Build"
owner = "jeremy"
[milestone.permit-approved]
title = "Permit approved"
external = true # a date controlled outside the project
[milestone.framing-done]
title = "Ready for framing inspection"
myproject.journal is the project: an append-only, timestamped event per line, newest
last, always fully qualified. Never edit a past line — correct a mistake with a later event.
2026-05-01T09:01 add-task sitework.excavate "Excavate footings" est 3d owner bob
2026-05-01T09:02 add-task sitework.forms "Set the forms" est 2d owner bob needs sitework.excavate
2026-05-01T09:05 target framing-done 2026-06-30
2026-06-13T16:30 done sitework.excavate
2026-06-14T08:00 started sitework.forms
Task ids are dotted paths (sitework.forms); each segment is unique only among its
siblings. The file stores the full path; the CLI accepts an unambiguous shorthand (forms).
Getting started
init scaffolds a directory with a project.toml (name from the dir, owner from $USER)
plus a Makefile, Nix flake, and agent guidance. The .journal is created on the first write.
showrunner init myproject && cd myproject
# edit project.toml to declare milestones, then record:
showrunner add-task design "Draw up plans" est 1w owner jeremy -p project.toml
showrunner target framing-done 2026-08-30 -p project.toml
showrunner started design -p project.toml
showrunner status project.toml
A bare showrunner project.toml means status; with a single .toml in the directory you
can drop the path entirely.
Reports
Read-only views over the journal:
showrunner tree project.toml # current task tree — the readable "plan"
showrunner status project.toml # triage strip, milestones, in-progress, blocked
showrunner next project.toml # what you can do now (in-progress first)
showrunner waiting project.toml # not-done tasks, grouped by why they're stuck
showrunner missed project.toml # milestones past target with no reached date
showrunner projected project.toml # target vs projected date per milestone
showrunner log project.toml # the journal, newest-first
Each renders to two surfaces from the same result: terminal (default) and a self-contained HTML file (timeline/Gantt — no server). Tasks are labelled by description, never id.
showrunner status project.toml --html > out.html # HTML to stdout
showrunner status project.toml --open # write + open in a browser
showrunner tree project.toml --ascii # ASCII glyphs
showrunner status project.toml --as-of 2026-06-10 # time-travel
Recording changes
Each write verb appends one canonical line, resolves shorthand ids, and validates against
current state first. Point it at a project with -p/--project.
| Verb | What it does |
|---|---|
add-task <id> "<title>" [est <dur>] [owner <name>] [needs <id>,…] [feeds <ms>] [at <date>] |
create a task |
update-task <id> ["<title>"] [est <dur>] [owner <name>] [needs <id>,…] [drops <id>,…] [feeds <ms>] [at <date>] |
amend a task — any subset of its attributes, one line |
drop-task <id> |
remove a task |
re-parent <id> [under] <parent> · re-order <id> before|after <sibling> |
move within the tree |
depend / un-depend <id> [on] <dep> |
add / remove one dependency |
target <milestone> <date> · add-milestone <id> "<title>" [external] |
set target / add a goal |
started <id> (alias start) · done <id> · re-open <id> · reached <milestone> |
progress |
note <subject> "<text>" |
pin free text to a task or milestone |
Durations are calendar spans, not business days: d, w (= 7 days), mo.
update-task changes any attribute, including the milestone a task feeds.
needs adds dependencies and drops removes them; an omitted attribute is
left alone, and a line naming none is refused.
A verb built from a prefix and a root is hyphenated. reorder, reopen and
undepend still parse, so old journals replay unchanged. re-estimate,
reassign, reschedule and retitle are deprecated in favour of
update-task — the command line keeps them as shorthands, each appending an
update-task line.
Building
This project is built with Nix, which pins the toolchain used by the human, agents, and CI:
nix build # build the binary
nix flake check # clippy (deny warnings) + rustfmt --check + tests
nix develop # dev shell + cargo-insta
Design
The pipeline runs one direction, pure in the middle, impure only at the ends:
argv ─▶ CLI ─▶ LOAD ─▶ PARSE ─▶ REPLAY ─▶ ANALYZE ─▶ REPORT ─▶ RENDER ─▶ stdout / .html
(edge) clap fs nom/toml (pure) (pure) (pure) term/html (edge)
The clock and filesystem are touched only at the edges, so identical files + now give
byte-identical output — quotable by an agent, snapshot-testable with insta. The terminal
and HTML renderers are two views over one analyzed model, so they can't drift.
Full design in docs/igor/: the model and report rules
(information-architecture.md), the two formats
(dsl-design.md), and how the pieces fit
(architecture.md).
License
Apache-2.0. See LICENSE.