From 66f06b96b918570fb234c5b31682babf14793d21 Mon Sep 17 00:00:00 2001 From: istos Date: Fri, 31 Jul 2026 11:09:42 +0200 Subject: [PATCH] docs design: turn 2 of Bench Docs on real bench content MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Turn 1 of the docs design wrapped three good layouts around invented content — a bench.toml, a brew-installed CLI, "lanes", a handoff rule engine, port 7331, PAS-411 cards. None of it exists. Turn 2 holds all three layouts and replaces every word, label and code block with the product AGENTS.md, README.md and manager/core/.env.example describe. 1b Dockside — hero terminal is the real install one-liner, the real first-run questions and the real board.py startup lines on 26071. The six doors are install, the five stages, agents on the board, PRs & review, team mode, the three-layer law. 1a Harbour — the article is "Claiming a card": what each move writes to **Assignee:**, the two local/.env keys that turn it on, and the board: → () commit it makes. 1c Logbook — the CLI reference is now a settings reference, with BOARD_SYNC as the shown key and the board's own activity log (real event strings from sync.py, agents.py and github.py) in the pinned console. The design project's write path needs an interactive permission grant, which a headless run cannot answer, so the finished file lands here as reference/bench-docs-design-turn2.dc.html for a human to upload as "Bench Docs.dc.html". The card scoped itself to the design project with no repo files changed; this one file is the deviation, and a git rm undoes it once the upload has happened. --- reference/bench-docs-design-turn2.dc.html | 437 ++++++++++++++++++++++ 1 file changed, 437 insertions(+) create mode 100644 reference/bench-docs-design-turn2.dc.html diff --git a/reference/bench-docs-design-turn2.dc.html b/reference/bench-docs-design-turn2.dc.html new file mode 100644 index 0000000..f5642e5 --- /dev/null +++ b/reference/bench-docs-design-turn2.dc.html @@ -0,0 +1,437 @@ + + + + + + + + + + + + + + + + + +
+ +
+ bench docs + turn 2 — the same three page types, re-cut on what bench actually is +
+ +
+ + +
+
+ 1a + Harbour — the article page + three columns, dark ink code, marginalia in the gutter +
+ +
+ +
+ 12vectors + / + bench + ▾ + + docs for 0.2-alpha +
+ +
+
+ bench + docs +
+ + +
+ / + Search the docs… + + ⌘K +
+ +
+ +
+ + + +
+
+ Concepts›Claiming a card +
+ +

Claiming a card

+

Claiming is moving. Taking a card out of backlog/ towards work is the commitment, so that is where ownership gets written down — one line in the task file, taken from the identity git history already shows.

+ +
+ TL;DR + A board-made move writes **Assignee:** <git user.name> into the task file. It gates exactly one thing — ▸ start work. Everything else is convention, and git history is the audit. +
+ +

What a move writes

+

The first claim sticks: a card that already names an assignee keeps it when someone else moves it on. Walking it all the way back to backlog clears the line, because nobody holds it again.

+ +
+
+ MoveWhat the board doesAssignee +
+
+ backlog → to-doWrites the line from git config user.nameclaimed +
+
+ to-do → in-progressLeaves whoever claimed it first alonekept +
+
+ anything → backlogRemoves the line — the card is free againcleared +
+
+ mv on diskNarrates the move; writes no assigneeyours to write +
+
+ +

Turning it on

+

Claiming is off by default. It lives in manager/local/.env, the copy of the documented example your first run wrote.

+ +
+
+ + + manager/local/.env + + copy +
+ 
# claim on move, and commit the move
BOARD_COMMIT_MOVES=1
 
# the other half of team mode: origin/main is the truth
BOARD_SYNC=1
BOARD_SYNC_INTERVAL=30  # seconds between pulls
+
+

↑ the first run asks "solo or team?" and writes both keys for you.

+ +
+ !! heads up + Identity is git's, so it collides like git's. Two machines both configured user.name = ronald are one person as far as the board is concerned. Teams that share a git history already share that assumption. +
+ +

What you see when it fires

+
+
+ 1 + The task file grows **Assignee:** ronald beside its **Status:** line, and the card shows the name. +
+
+ 2 + The move commits itself — one commit touching only that file, messaged board: 18 → in-progress (ronald). +
+
+ 3 + Another board refuses ▸ start work on that card, names who holds it, and offers ▸ take over instead. +
+
+ +
+ {{ feedbackAsk }} + + + +
+ +
+ + +
+ +
+ 
  ___________________
+ |___________________|
+   ||             ||
+   ||             ||
+
+ bench + a 12vectors product · built in the open +
+ + github.com/12vectors/bench +
+
+
+ + +
+
+ 1b + Dockside — the docs home + a landing that's mostly a terminal and a set of doors +
+ +
+ +
+ 12vectors + / + bench + ▾ + + docs · guides · concepts · github +
+ +
+
+ bench + docs +
+ + + +
+ +
+
+ Documentation +

Put the agents
on the bench.

+

Task files in stage directories are the only source of truth. A stdlib-only board narrates what happens to them — agents working in git worktrees, PRs opening on review, CI on the cards — and never merges anything itself.

+
+ + +
+ no account, no service, no database. it is python 3 on your own machine. +
+ +
+
+ + + ~/your-repo +
+ 
$ mkdir .task-manager && curl -L \
    https://github.com/12vectors/bench/releases/latest/download/bench.tar.gz \
    | tar -xz -C .task-manager
$ ./.task-manager/start.sh
 
  No .task-manager/manager/local/.env yet — a few questions and bench writes one.
    solo or team? [solo]:
    which agent adapter? [claude]:
    what command runs this project's tests? [python3 -m unittest]:
 
  Task board for ~/your-repo/.task-manager/tasks
    http://127.0.0.1:26071/
    Ctrl-C to stop▊
+
+
+ +
+
+ 01 + Install + Untar it into .task-manager/, run start.sh, answer three questions. Port 26071, pinned. +
+
+ 02 + The five stages + backlog → to-do → in-progress → review → done. The directory a file sits in is its status. +
+
+ 03 + Agents on the board + ▸ start work makes a worktree and a branch, runs the agent headless, and moves the card when it exits. +
+
+ 04 + PRs & review + A card entering review gets a PR opened for it. Then ◔ review PR, ⚑ copilot, ↻ act on PR — until it settles. +
+
+ 05 + Team mode + BOARD_SYNC=1 makes origin/main the truth. Moves commit and push themselves; boards pull on a beat. +
+
+ 06 + The three-layer law + Core knows tasks, worktrees, PRs and events. Drivers know apps, adapters know vendors, local/ knows your project. +
+
+ +
+ Most opened this week +
+ local/.env settings + a run that died + the adapter contract + archive & undo +
+
+
+
+ + +
+
+ 1c + Logbook — the settings reference + prose left, the board's own activity pinned right +
+ +
+ +
+ 12vectors + / + bench + ▾ + + 0.2-alpha +
+ +
+ + +
+
+
+ team mode + off by default +
+

BOARD_SYNC

+

Makes origin/main the truth and every board a converging replica. Off, none of it runs — no fetch, no push, no thread, no behaviour change at all.

+ +
BOARD_SYNC=<empty>  ·  empty / 0 / false / no / off = off, anything else = on
+ + Keys it pulls in +
+
+ BOARD_COMMIT_MOVES + Implied by this one. A move that never commits has nothing to publish. +
+
+ BOARD_SYNC_INTERVAL + Default 30. Seconds between fetch-and-fast-forward beats. Raise it on a metered remote. +
+
+ BOARD_WATCH_INTERVAL + Default 2. The disk poll that narrates what a pull just applied. +
+
+ +
+ ~ tip + Answering team at the first run writes this key and BOARD_COMMIT_MOVES together. install.py --setup is the way back to the question. +
+
+ +
+
+
+ + activity · 12vectors/bench + + live +
+ 
09:14:02 move  26-forge-adapters.md moved
                to-do → in-progress (you)
09:14:03 sync  pushed 1 board commit to origin/main
09:14:33 sync  pulled 2 commits from origin/main
                (elena)
09:31:22 agent Wren finished 26-forge-adapters.md
                — review branch task/26-forge-adapters
09:31:24 move  26-forge-adapters.md moved
                in-progress → review (agent)
09:31:26 agent PR opened for 26-forge-adapters.md:
                https://github.com/12vectors/bench/pull/31
09:32:31 agent CI on 26-forge-adapters.md's PR:
                all checks pass
▊
+
+ the browser gets these over SSE · no refresh +
+
+
+
+
+ +
+ bench + a 12vectors product + + edit this page on GitHub ↗ +
+
+
+ +
+
+ + + + +