Files
alan 01d5dad9b9 docs: describe the agent-driven workflow, drop the scripted driver model
Rewrite the workflow documentation to describe how the system actually works:
the agent (the session) is the brain and advances the queue by hand through the
`pipelines` CLI. There is no orchestration script, no driver, no polling loop and
no lane machinery, and none may be written.

- references/work.md: rewritten end to end. The queue-driver script
  (drivers/workd.sh), the claim-file ledger with atomic renames, the PAUSED
  marker and the poll loop are gone. State is now the server (authoritative for
  run state), the queue file (authoritative for intent) and the conversation.
  The agent reads the queue, picks the item, creates its worktree/branch and
  launches it with `pipelines run <pipeline> <brief> --json --yes`; progress is
  event-driven via a background `pipelines wait <run-id> [...]` (never polled);
  on completion the agent reconciles with `pipelines inspect <run-id> --json`,
  verifies it landed and starts the next item.
- references/queue.md: the landing gate runs the command directly
  (`git merge-base --is-ancestor <branch> main`, exit 0 = landed) instead of a
  `land-check.sh` helper; the never-delete-branch / never-remove-worktree rules
  are kept, and the waiting section states the agent advances the queue by hand.
- references/orchestration.md: intro and "Running and watching" state the
  agent-driven, event-driven model; "Pipeline choice" names the current set
  (Android, TUI, Server, Generic, Plan and land, UI sweep, Probe) by area and
  records the retired names.
- references/debugging.md: "Duplicated work after a driver restart" became
  "…after a session restart", resuming from the queue file not a cursor file.
- SKILL.md: the routing row no longer says "queue driver".
- AGENTS.md: the maintenance workflow names the current pipeline set instead of
  the retired `Pipelines maintenance - plan implement review`.
- internal/tui/AGENTS.md: the restart line no longer names lanes.
- docs/notes/agent-driven-work-model.md: the docs-fold note recording that
  docs/cli.md needs its "Scripted runs"/`--wait` framing aligned to the
  event-driven model, and that the dated evidence docs stay as they are.

Checked before committing: no packaged template directory exists in this repo, so
none needed updating; internal/author/install.go's managed file inventory needs no
change (no packaged reference was added or removed — the 13 listed files all
match internal/author/skill/references/); no stale `queue driver`/`workd.sh`/
`claim-file` references remain anywhere under internal/author. Genuine device
tooling (android/scripts/capture_png.sh-style) and server-side polling prose were
left alone.

Checks: `go test ./internal/author -count=1` ok; `go build ./...` clean;
`go vet ./...` clean; `gofmt -l .` clean.
2026-10-18 01:50:55 +01:00

2.2 KiB

The TUI — working map

Read this before touching internal/tui/. The generic side — how a Go CLI/TUI project is built, tested and reviewed — belongs to the pipeline that started you.

Build and test

go build ./...
go test ./internal/tui        # fast (~2-4 s); the whole tree is ~1 min
go vet ./...

No device, no capture, no network: a TUI change is verified by unit tests plus a rendered frame.

How the TUI is put together

  • model.go — the Model, the key map (keys), and Update/View dispatch. Key bindings are declared in one place; a new binding goes there, not inline.
  • dashboard.go, pipeline.go, runs.go, run_detail.go — the screens. A run's detail is built from sections, and a section can open as its own pane in the sliding stack.
  • context_footer.go — the footer for the current mode. A modal's footer replaces the page's; never inherit shortcuts that the modal does not honour.
  • theme.go / style.go — colours and text styles. Status colour comes from one vocabulary so a state looks the same in every screen.
  • linetext.go, graph.go — line building and the stage graph rendering.
  • Human decision stages are answered in the TUI: ↑/↓ choose · Tab feedback · Enter decide · Esc cancel.

Reviewing a TUI change without a terminal

The pinned frames in internal/harness/tmp/ui-review/render/ (empty-catalog-*, filter-no-match-*, narrow-long-model-*, plain-nocolor-*, wide-focused-*, in dark and light) are the reference renders. Compare against them when a change alters layout, spacing, colour or the footer, and add a frame when you introduce a new state worth pinning. A change that alters a pinned frame and does not say why is a review finding.

Conventions and traps

  • No polling: state arrives from the server; do not add a ticker to look busy.
  • The footer and the pane stack are shared surfaces — a change there affects every screen, so say what you checked.
  • Terminal width matters: verify at a narrow width as well as a wide one, and never assume colour support (plain-nocolor-* exists for a reason).
  • Do not restart the deployed server or ntfy to test a TUI change: run the binary against a scratch server or use the fixtures.