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 +
+
+
+
+
+ + +
+
+ +
+
+ + + + +