Kjell Tore Guttormsen 9dd24c3446 feat(brief): render the nightly cross-repo briefing without a model

The operator has more repos than they can hold in their head, and the
question that actually costs them is "who is waiting on me, and what does
answering cost". board.sh already scans for it; nothing rendered it in a
form an unattended job could leave behind.

--brief is a second RENDERING of that scan, never a second scan. It prints
NESTE uncut, because the 38-character cut is the table column's property
and not the record's - the value used to be truncated at record-build time,
which left the cut string as the only copy. Each startup command is derived
by CALLING route.sh with that repo's own four traits; next-cost alone
cannot produce it, since the advisor flag is a property of the ROW and two
rows can share a model/effort pair while differing on it. A repo with no
route line is told so rather than handed a guess.

It cross-checks itself against coord-count.sh, and that is the substance of
the change rather than a nicety. The repo scan and the mailbox are two
different populations: a mailbox can carry a name no scan will ever produce
- a declared non-git surface (CLAUDE_COORD_REPO, e.g. ~/repos) or a
checkout outside the roots. Measured on the real mailbox: 11 repos / 21
messages in the briefing against coord-count's 12 / 22, the missing one
being the declared surface `repos`. A briefing that only walked the scan
would answer "who is waiting on you" with a number it quietly knew was
short.

Zero model calls, which was the deciding property. Measured against 2.1.220
under subscription auth: --max-budget-usd DOES bite (terminal_reason
budget_exhausted, exit 1), but it aborts AFTER turn one - floor ~0.25
USD-equivalent per turn on claude-opus-5[1m]. It is a runaway brake, not a
pre-flight gate, so a nightly claude -p job would draw on the same quota
pool as interactive work every night. Determinism removes the question.

board.sh stays read-only: the file write lives in brief-nightly.sh, which
renders to a temp file and renames it into place, and treats an EMPTY
render as a FAILED one - board prints nothing when its scan roots do not
exist, which is what a mistyped path or a moved home looks like, and a
plain `> file` redirect would destroy yesterday's briefing on a bad launchd
environment.

The launchd template carries placeholders, not absolute paths: this repo is
mirrored publicly and a plist is the one file here that would need a home
directory in it. It points at a checkout rather than the plugin cache,
which is version-pinned and would break silently on the next bump.

board-selftest 36 -> 49. One check pins a defect caught only by eye against
the real tree: fold copies its input's missing trailing newline, which ran
the command onto the tail of the NESTE prose and produced a briefing whose
commands could not be copied.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017orCFDkmp88fLnqDR3chdJ

2026-08-01 22:38:46 +02:00

9.2 KiB

Raw Blame History

name	description	version
board	Answer "which repository deserves the next session" across every repo at once, using the local cross-repo attention board (`board.sh`) as the evidence. Use whenever the user asks what to work on next, who is waiting on them, what unblocks the most other work, what is cheapest to move under quota pressure, or for a cross-repo status read: "what should I work on", "who is waiting on me", "what unblocks the most", "show the board", "what is cheapest to move", "cross-repo status", "where is the leverage", "which repo is blocked". Also triggers on Norwegian phrasings: "hva skal jeg jobbe med", "hvem venter på meg", "hva løsner mest", "vis tavlen", "hva er billigst å flytte", "hvor bør jeg begynne", "status på tvers av repo", "hva er blokkert". Trigger even when the user names no repo and no tool — choosing between repos is this skill. Not for "where were we" inside the current repo: that is this repo's own STATE.md, already injected at session start.	0.15.0

board — which repo deserves the next session

This skill turns "what should I work on" into a decision backed by measurement. board.sh is the engine; this skill is the ranking and the answer. The script is read-only by construction — it never writes to a repo, a STATE.md, or the mailbox — so running it is always safe and needs no confirmation.

The failure mode this skill exists to prevent is dumping the table. The board prints one line per repo across every repo on the machine; pasting that back is not an answer, it is the question again in table form. Run it, read it, name one repo.

The engine

BOARD="${CLAUDE_PLUGIN_ROOT}/scripts/board.sh"

There is no deployed copy anywhere else and no fallback path. One entry point is the whole point: two entries pointed at two copies and made it impossible to know which one actually ran. If this fails to resolve, the fix is this expression — never restoring a copy under ~/.claude/scripts/.

"$BOARD"                          # every repo under the default roots
"$BOARD" --roots <dir>[,<dir>...] # scan somewhere else

BOARD_ROOTS overrides the default scan roots and CLAUDE_COORD_DIR the mailbox root. Exit 0 is normal (0 discovered repos also exits 0, silently); exit 2 means a malformed argument — read stderr and fix it rather than retrying.

Re-run it every single invocation. Never answer from a board you ran earlier in the session, from a number quoted in a document, or from memory. Inbox counts, uncommitted files and board lines all change between turns, and a recommendation built on a stale count is the exact defect the operator's premise-verification rule exists to stop. The run costs about three seconds.

What the columns mean

Column	Meaning
`STATUS`	`planned` / `in-progress` / `blocked` / `deferred` / `done`, or `blocked>X` naming the repo it waits on. `?` means the STATE.md has no board line.
`KOST`	Model/effort for the next step, from the rubric row table in `route.sh` (the `route` skill writes it; this one only reads it).
`INN`	Unhandled inbox: other repos are waiting on THIS one. An obligation it owes outward.
`DRT`	Uncommitted files.
`ALDER`	Days since STATE.md last changed — the age of the plan. `-` where the repo has none.
`SISTE`	Days since the last commit — the age of the work. `-` where the repo has no commits yet.
`NESTE`	First line of the STATE.md next-step block, truncated.

INN never means "this repo is waiting on someone." It means the opposite: messages arrived and were not handled. The mailbox format carries no reply-to or thread field, so outbound waiting is not derivable from it at all — blocked>X is the only source for who a repo waits on. Conflating the two axes is a known defect class here; keep them apart in every sentence you write.

How to rank

Apply in order and stop at the first that discriminates. Always say which rule fired — the rule is the justification, and it is what lets the operator disagree.

Unblocks the most. A repo that others are blocked> on. Moving it converts several blocked repos to active: the highest leverage per token spent. Follow the chain — if A is blocked on B and B is blocked on C, the answer is C.
Cheap and blocking. Among unblockers, prefer the lowest KOST. This is the standing rule under quota pressure: take the cheap blocking one first.
Owes the most outward. High INN means other sessions are stalled waiting for a reply. Answering is procedurally mandatory anyway, so this work is owed regardless of what else is on the board.
Uncommitted risk. High DRT is not urgent work, but it is exposure worth naming: the config backup mirrors commits, not working trees, so uncommitted files exist in exactly one place.

Neither ALDER nor SISTE is a ranking input. An old STATE.md often means a finished repo, not a neglected one, and an old last commit can mean the same. Report either only if the user asks about staleness directly — the four rules above stay four.

Read them as a pair, though: they answer different questions, and the gap between them is the reading neither gives alone. A fresh ALDER beside a long SISTE is a repo that keeps being re-planned without anything landing, which no other column on the board reports.

deferred is a deliberate choice, not neglect — do not surface a deferred repo as a candidate unless nothing else qualifies, and say that it was deferred if you do.

Read the winner's STATE.md before answering

The NESTE column is truncated to fit the table, so it is a pointer, not the action. Once ranking picks a repo, open that repo's STATE.md and read the actual next-step block. Report the real first action from that block. A truncated fragment quoted as if it were the next step is a wrong answer that looks right.

The answer

Short prose, roughly five to ten lines. No table, no per-repo rundown, no top-five list — "top five with their columns" is still a dump.

The repo, named once.
Why it won, as the rule that fired.
The concrete first action, from that repo's STATE.md next-step block.
What it costs — the KOST value, so the operator can set model and effort before starting.
Runner-up in one clause, only if it is genuinely close.

If the user asked a narrower question ("who is waiting on me", "what is cheapest"), answer that question directly from the same run instead of forcing the full ranking onto them.

Coverage gaps you must name

A ranking is only as honest as its inputs, and two gaps are invisible in the answer unless you state them:

Repos with no board line render ? in status and cost, so they drop out of exactly the sort the board exists for. The script counts them in its closing note. Pass that count through as one clause ("N repos have no board line and are outside this ranking"), and never let it grow into a side quest — adding board lines to other repos is that repo's work, not this session's.
MALFORMED status tokens mean a board line outside the closed vocabulary. The script warns; repeat the warning and name the repo, because a malformed line silently misplaces a repo in the wrong bucket.

Repos with no STATE.md at all appear in their own group. They are not candidates — there is no next step to read — but a large uncommitted count in one is worth a sentence under rule 4.

Boundaries

Read-only, both ways. The script writes nothing, and neither should the skill. Do not fix a missing board line, edit another repo's STATE.md, or send a coord message as a side effect of ranking. Recommend; the operator decides.
Not a session-start hook. Injecting the board into every session costs real context about repos the session is not in. It runs when asked, never on a timer.
Coordination metadata is private. Repo names, blocking chains and inbox counts are local operational data and never belong on a public surface.

Examples

Placeholder names throughout — resolve real ones from the run, never from a document.

Example 1 — the ordinary ask Input: "hva skal jeg jobbe med nå?" Action: run the board. repo-a is blocked>repo-b, and repo-b is active at a low cost. Answer: repo-b, rule 1 + 2 (cheap and unblocks repo-a), the first action read from repo-b/STATE.md, and its KOST.

Example 2 — quota pressure Input: "jeg har lite kvote igjen, hva er billigst å flytte?" Action: run the board, restrict to candidates whose KOST is at the low end of the rubric, and prefer one that also unblocks something. Name the cost explicitly.

Example 3 — the obligation question Input: "hvem venter på meg?" Action: read INN only. List the repos with unhandled mail and say that this is mail owed outward, not repos this one is waiting on. Do not rank; the question was narrower than the ranking.

Example 4 — chain following Input: "what unblocks the most?" Action: build the blocked> chain from the run, and name the repo at its root, plus how many repos come free when it moves.

Example 5 — nothing qualifies Input: "vis tavlen" Action: if every repo is done or deferred, say so plainly and name the largest uncommitted exposure instead of inventing a candidate. An empty board is a real answer.

9.2 KiB Raw Blame History