Phases are the release, so AGENTS.md stops burying them. The six sections
that were `###`s inside "Task file format" — where they had split that
section's own prose in half, header table above and Assignee below —
become a `## Phases` section of their own, between "Pull requests" and
"Stages" because that is the order they are learned in. Nothing in them
changed: the diff is a move plus the section's opening paragraph.
Which gives the site three pages to cut rather than a tail nobody would
find at the bottom of "Task files": /concepts/phases/ (the model),
/concepts/running-a-phase/ (the branch, the beat, the halt, the ending)
and /concepts/phases-on-the-board/ (what the Board stops drawing, and the
Phases view that draws it instead). They sit after "PRs and review" in
the Concepts flow, which is the order AGENTS.md now reads in — the
manifest and the source cannot disagree about that without the build
saying so.
The landing page's third reason says it too, since "parallel work, zero
collisions" was only half of what the board now does, and the README's
opening paragraph gains the sentence it was missing.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A link to bench.12vectors.com under the opening paragraph, and the board
screenshot beneath it — the fastest way to say what this is.
The image is an absolute raw.githubusercontent URL rather than a repo
path, for two reasons. README.md ships in the release artifact and
site/ deliberately does not, so a relative link would break in every
vendored install. And the site's own copy is served under an immutable
year-long cache, so linking that would pin readers to whatever
screenshot was current when they first loaded the page.
The three-layer-law paragraph gains a clause and loses one. That section
is sliced into /concepts/three-layer-law/, so "or read them at
bench.12vectors.com" rendered as a page on that site telling you to go
to that site. It now says AGENTS.md is the file the docs site is cut
from, which is true in both places — the rule this repo sets for its own
prose.
The third setup question wanted an answer about a repo the person may
have just cloned, thirty seconds in, before anything had explained why
the board needed one. The file that names a project's ecosystem usually
names its runner too, so it is read off the project: package.json → npm
test, Cargo.toml → cargo test, go.mod → go test ./..., a
pyproject/setup.py/tests/ → python3 -m unittest.
Nothing recognisable writes BOARD_AGENT_COMMANDS empty rather than the
example's Python default, which would be quietly wrong in most repos —
and a wrong prefix denies an agent exactly the way an empty one does, so
absent beats wrong here.
Two details the first attempt got wrong, both now covered:
- Detection runs *before* the questions. Placed after them, a Ctrl-D
part-way through skipped it and left the example's default.
- "Keep what the project already said" reads the existing .env, not the
example-seeded defaults dict — which already carries the example's
answer, so every first run looked like it had one and detection never
ran.
The landing page's terminal, README.md and AGENTS.md follow: two
questions now, and AGENTS.md documents the detection table.
The site's page bodies are heading slices of these two files, so a
sentence that only makes sense to an agent inside an installed project
becomes a sentence on bench.12vectors.com. Fixed at the source rather
than forked into the site:
- "The flow is linear" and its diagram sat at the end of "Pull requests",
which put the whole stage flow on the PR page and left "Stages" with no
opening. Moved under "## Stages", where it introduces what follows.
- "Agents working the board" ended in a stray sentence about worktrees
and one-agent-per-task; folded into the start-work paragraph it
belongs to.
- Start work no longer claims to launch `claude -p`: it launches through
the configured adapter, which is the whole point of adapters.
- "see below" and "the PR guard above" name their sections instead,
since above and below are other pages on the site.
- The tool-chips sentence had grown into the middle of the verdict it
interrupted ("The card wears it in the design system's colours", with
no nearby "it"). Split into two paragraphs.
- "Task file format" gains a table of every header field, what it may
contain and who writes it — including PR, which the board writes and
nothing documented until now.
- Paths are written from the repo root, the reference-directory example
no longer names another project's regulator, and README's three-layer
law links the two documents it points at rather than naming them.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A project could run bench for months without a manager/local/.env:
everything fell back to core/.env.example, so the two settings that
change what bench is — claim-on-move and syncing through origin/main —
were invisible to anyone who had not read that file.
install.py now writes it on a first run. It asks three questions no
default can be right about (solo or team, which agent adapter, the
project's test command) and writes core/.env.example with the answers
substituted into their lines, comments and all keys intact — so the
written file is where the project reads what else it can change.
- Runs after first_boot_clean: .env is one of the two things the
first-boot guard reads, so writing it earlier would skip the clean.
- Never asks without a terminal on stdin. install.py sits on the path
of start.sh, update.sh and every hook, so no TTY prints one line and
carries on rather than blocking a board start on an invisible prompt.
--dry-run reports the questions and writes nothing.
- An existing .env is never touched; --setup is the only way back to
the questions, pre-filling from the current file and rewriting it in
place, so start.sh's fallback BOARD_PORT line survives.
- Bare Enter takes every default (the result is the example verbatim,
i.e. today's behaviour exactly); Ctrl-D skips the rest.
start.sh needed no change — it already calls install.py before the port
dance, which is the right order. Tests drive the interactive runs over a
real pty and the non-interactive ones with /dev/null on stdin.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
AGENTS.md gets the "Syncing boards" section — what pushes, what pulls,
what a lost race looks like, and the two disciplines that make it safe:
local main advances only through the board and origin, and sync never
merges. The module map gains sync.py, the settings paragraph and the
Board view's description gain the sync chip and the author attribution,
and .env.example documents BOARD_SYNC / BOARD_SYNC_INTERVAL, including
the fetch-rate line for rate-limited remotes.
Resolutions honouring both sides:
- CLAUDE.md: main's pointer form wins; this branch's release-era wording
(tree diagram line, Updating section) ported into AGENTS.md where the
brief now lives.
- update.sh: this branch's release-based rewrite wins; main's additions
to the old file list (AGENTS.md from task 13, LICENSE) are carried by
the release-manifest instead: added copy AGENTS.md and copy LICENSE.
- Starter local/: manifest and release.sh now seed the split pair
(AGENTS.md notes + pointer CLAUDE.md) mirroring task 13's layout;
artifact test updated to match.
- tests/test_update_round_trip.py (main's, aimed at the removed
git-clone mechanism) retired; its two 13-specific intents ported into
test_update_from_release.py as
test_agents_brief_replaces_an_old_vendor_named_copy, its third already
covered there. 147 tests green.
- release.sh's lost executable bit restored.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
README's first instruction becomes the tokenless curl | tar against
the stable latest-release URL; the clone path moves to a "working on
bench itself" note. CLAUDE.md's Updating section and .env.example's
BENCH_SOURCE comment describe release-based updates: the source is
stamped at build time, BENCH_SOURCE is an override rather than a
prerequisite.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Ships with the distribution: update.sh's core-owned file list carries
LICENSE so installed projects receive it, and the release manifest
(task 15) inherits the list.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
AGENTS.md is the cross-vendor name (opencode, Codex, Gemini CLI read it
natively; so does current Claude Code), and the brief goes to every
vendor's agents — an opencode work agent previously launched with no
project brief at all. The content moves verbatim to AGENTS.md at the
root and in manager/local/; each CLAUDE.md becomes a load-bearing
compatibility pointer (@AGENTS.md import) for older Claude Code CLIs.
update.sh's core-owned file list now carries both names, so updating an
old-layout install lands AGENTS.md and replaces the full CLAUDE.md with
the pointer instead of resurrecting it. All four core prompts, README,
the board.py/taskfiles.py docstrings, the task template and the adapter
contract docs now name AGENTS.md; adapters/README.md notes that vendors
reading AGENTS.md from the working tree need no adapter work.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A vendored clone of bench arrives carrying bench's own task cards, plans
and reference documents, so a new user's first board opened pre-loaded
with our backlog. install.py now detects first boot — a vendored install
(project root != manager root) whose manager/local/ has never been
populated (no .env, no state/) — and only then clears the stage
directories, tasks/archive/, plans/ and reference/, keeping
task-template.md and the .gitkeep files and printing every removal.
--dry-run lists instead of removing. After cleaning it stamps
manager/local/state/, so the guard is permanently false on every later
run even if the adapter wire fails, and a host's own cards are never
touched. Self-hosted repos (bench itself, including fresh dev clones)
are never cleaned: their tasks/ is the repo's history.
Covered end-to-end in tests/test_install_first_boot.py by running
install.py as a subprocess against scratch host layouts; README notes
the first-boot behaviour under "Install into a repo".
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Everything core from cicero-pas's .task-manager, with instance data
reduced to skeleton: empty stage directories, the task template, empty
local/ scaffolding, and a README covering install (clone into
.task-manager/, vendored on purpose) and update (update.sh replaces core
wholesale; local/ and tasks/ survive).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
