refactor(skills): cap every SKILL.md at 600 words and cut agent messages

Every loaded SKILL.md and every listed description is paid on every turn of every session, and every delivered message costs its recipient a full turn. scripts/budget.py gains SKILL_WORDS = 600, enforced by test_lock, and test_naming forbids a skill naming its own slash command; 53 descriptions and 10 body lines drop it. The 18 longest skills move details into 31 side files read only in their situation (organize's capacity, succession, peers, offices, relay and lineage; cleanup's docker, worktrees, execute and ask; code-tune, changelog, triage, dream, split and others), so all SKILL.md files shrink from 33866 to 26291 words without dropping a rule; an independent review of HEAD against the new text found no loss in 60 of 64 skills and three weakenings, now restored (WSJF re-estimates after an objective change, cleanup's volume checklist, essence's absolute dates).

The kvb-org-organize Peer protocol sends status that asks nothing to the news board, answers nothing that asks nothing, keeps messages terse, and lets light runs admit themselves in the operator's wording; the skills follow it (operator reads the register, relax and wakeup reply through the news, evening collects them there, wsjf asks only for missing estimates, cleanup and triage batch their questions). Skills that explore code ask the codebase-memory-mcp graph first, subagent briefs scale with the stakes and cap their answers, and the skills that need the full register or council tables call show --wide or list --long.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-BirkenbachandClaude Opus 5.5 committed 2026-11-04 17:07:23 +01:00
1 parent 34b434a744
commit 3c2f6c44b5
99 files changed
+2110 -2086

No files matched your search

+56 -192
View File
@@ -3,214 +3,78 @@ name: kvb-org-organize
description: >
Keep parallel agents from duplicating work: the first claim owns it, a
chair allocates. Run AUTOMATICALLY before work another agent might also
do, and on /kvb-org-organize.
do.
---
Two agents doing the same work waste the second run and then collide in the
merge. The remedy is an election nobody has to hold: whoever starts first owns
the work. The structure is anarcho-syndicalist: councils (soviets) of
delegates with a bound mandate, organised as a matrix, recallable by the
operator at any time.
## Offices
- **President of a piece of work**: the first agent that starts it. It does
the whole piece. Every later agent hands its findings to the president and
moves on to other work; it never builds a second version.
- **Representative of an organisational line**: the first agent that works in
the line. Lines come in as many dimensions as are useful: functional domain
(security, GUI, identity, i18n), repository, branch line, host, cloud
account. An agent belongs to one line per dimension.
- **Organiser of a work cluster**: the first agent that starts a cluster
cutting across lines (a failure cluster from `kvb-ci-triage`, a cost cluster from
`kvb-code-tune`, a feature touching several domains). It works the strand end to end
and informs the representative of every line the strand touches before it
changes that line's files.
- **Chair**: the earliest-elected president still running. It chairs the
council of all representatives and organisers and allocates the resources of
the whole system everyone runs on. There is exactly one allocator at any
time.
Every office is a mandate, not a rank: it coordinates and allocates, it never
takes over or directs the content of another agent's work. The operator
outranks every office and appoints or recalls at will; an operator
appointment outranks the election.
The first claim owns a piece of work; a later agent hands its findings to the
owner and never builds a second version. Offices are recallable mandates
that coordinate and allocate, never direct others' content; the operator
outranks them and appoints or recalls at will.
## Election
The first to claim wins, and the claim is atomic, so two agents can never both
be first. `${CLAUDE_SKILL_DIR}/scripts/council.py` keeps the claims in
`/tmp/agents-council`; other runtimes call the same script from their skills
directory with `--session <id>`.
`${CLAUDE_SKILL_DIR}/scripts/council.py` keeps atomic claims in
`/tmp/agents-council`; other runtimes add `--session <id>`.
1. **Name the office**: `work/<slug>`, `cluster/<slug>`,
`<dimension>/<line>` for a representative, or `chair`. The slug names the
work concretely: the issue number, the failing line, the cost's log line.
2. **Look first**: `council.py list`. A claim for the same work under another
slug counts as first.
3. **Claim**: `council.py claim <office> --work "<what, evidence, branch or
worktree>"`. Exit 0: elected, or already yours. Exit 3: a live agent holds
it, and its claim is printed. Exit 4: the holder's session is dead (see
Succession).
4. **Elected**: the claim entered the task in the `kvb-org-rasci` register,
the organisation's single point of truth; complete it there (objective,
description, priority, roles), then continue with the Peer protocol; its
message is the announcement.
5. **Not elected**: send the holder your findings and stop on that work.
1. Name the office: `work/<slug>` (a piece of work), `cluster/<slug>` (a
strand across lines), `<dimension>/<line>` (a line) or `chair`, the slug
concrete (issue number, failing line, log line). The first agent elected
while `chair` is vacant also claims it. Read `offices.md` next to this
file before claiming a cluster, a line or the chair.
2. `council.py list`; the same work claimed under another slug counts.
3. `council.py claim <office> --work "<what, evidence, branch or worktree>"`.
Exit 0: yours; 3: a live holder (printed); 4: the holder's session is dead.
4. Elected: complete the task the claim entered in the `kvb-org-rasci`
register (objective, description, priority, roles); the listed claim is
the announcement.
5. Not elected: post your findings to the holder via the news and stop.
A Claude Code session cannot edit a file in a git worktree before it holds a
claim: a PreToolUse hook (`council.py gate`) blocks the edit.
A hook (`council.py gate`) blocks worktree edits before a claim. Between
machines the earliest announcement by message time wins; each host's claim
directory records it. Read `succession.md` next to this file when a claim
ends or goes stale, or after a restart.
Peers on other machines cannot see this host's claims. Between machines the
earliest announcement by message time wins, and each host's claim directory
records the result.
## Capacity
## Chair and resource allocation
- The first agent elected on the system while `chair` is vacant also claims
`chair`, in the same way.
- An operator-appointed allocator holds the chair: its claim says
`appointed: operator`, and no election replaces it while its session runs and
the operator has not ended the appointment.
- Before starting anything that consumes shared capacity (gates, deploys,
iteration loops, swarm or cloud resources, cleanup of shared data), an agent
sends the chair what, where, for how long and its expected disk need, waits
for the grant, and reports the release. The chair keeps one queue: a
hotfix gate (a branch from the default branch that fixes it) takes the next
free gate or test slot before every other line, the rest follows the WSJF
rank of the `kvb-org-wsjf` skill (it asks its subordinates for the Fibonacci
estimates); a running gate is never cut short for a hotfix. It answers
every request with its position, enforces the limits the operator set,
checks every grant with `watch.py admit --need-gb <N>` (or `--kind <slot>`;
test kinds also need CPU and RAM below the configured limits).
- A running job (deploy, gate, test, swarm run, build) is never cut short to
free capacity. The chair neither asks nor orders its owner to stop, take
down or kill it, not for an operator-prioritised slot and not for a
projected disk stop. It grants nothing new, frees idle items through the
`kvb-cleanup` flow, asks the operator for an exception, or waits. An owner's
own disk guard only alerts the chair and takes nothing down; only the
operator can order a running job down. The one exception is a hang: an
agent may end its own job, a stuck step inside it, or a process its own
ended session left behind, once at least 60 minutes passed without log
progress and a probe shows standstill (no fresh child process, no network
traffic, CPU time not moving). It secures the live state first and then
reports the timestamp, the step, the probe and the command. A peer's hung
job goes to its owner, and to the operator when the owner does not answer.
- Handover is explicit: the outgoing chair sends every peer the new holder,
the queue and the running grants, and keeps allocating until the incoming
chair confirms. Two allocators never run at once.
## Resource watch
The chair keeps the system from running out instead of reacting once it has.
`${CLAUDE_SKILL_DIR}/scripts/watch.py` does the measuring as hooks in every
session, so no agent probes the disk by hand; it reads its thresholds, job
patterns, cleanup commands and cache directories from
`~/.config/agents-council/config.json` (keys in the script's docstring) and
stays silent below the thresholds.
- **Warn**: the chair and every session get the biggest consumers; the chair
plans a cleanup and grants no large slot.
- **Stop**: new heavy jobs are blocked in every session (teardown commands
never), and the hook runs the configured low-risk cleanup by itself; it
skips every worktree where a gate or deploy process still runs.
- **Critical**: additionally a desktop alarm to the operator. Running jobs
and their stacks still keep running; only the operator can make an
exception.
- A measured fall that would reach the critical threshold within the
projection window raises the stage by one at once.
- Caches together stay under their budget; the least recently used go first.
`watch.py status` shows the last measurement. A `RESOURCE` line in a hook's
context is addressed to the chair; any other session only adjusts its own
plans to it.
## Succession
- A piece of work or a cluster ends with its result, a proposal, or an
abandoned attempt, reported to the peers who heard the claim. The holder
then runs `council.py release <office>`, and the next agent that starts the
work is elected afresh.
- A representative or the chair that ends hands its office to the next-oldest
live representative (by claim time) and announces it.
- A claim is stale when its holder's session is gone: in Claude Code its
session id is no longer in `~/.claude/sessions`; other runtimes run
`council.py beat` at least hourly and go stale after 60 minutes without
one. `claim` then exits 4. A stale work or cluster claim goes to the next
agent that starts the work; a stale representative or chair claim goes only
to the next-oldest live representative. The successor runs
`council.py takeover <office> --work "..."` and announces the succession;
everyone else leaves it alone.
- After a restart or reboot, run `council.py list --mine` and claim again
every office you believe you hold: `/tmp` may have been wiped.
- Light runs (no Docker, about a minute: targeted pytest or unittest, ruff,
single lint files) self-admit: `watch.py admit --kind test-nostack`, start
on `grant`.
- `make test`, `make test-lint`, quality gates, deploys, iteration loops,
swarm, image builds, cloud, shared-data cleanup, anything with Docker or
over a few minutes: ask the chair (what, where, how long, disk), wait for
the grant, post the release to the news.
- No running job is cut short for capacity; only the operator orders one
down. `RESOURCE` hook lines address the chair; others adjust plans.
- Read `capacity.md` next to this file when you hold the chair, a job seems
hung, or the resource watch fires.
## Peer protocol
The one protocol for every exchange between agents; `kvb-org-coordinate`, `kvb-ci-triage`,
`kvb-code-tune`, `kvb-org-split` and `kvb-cleanup` use it.
Read `peers.md` next to this file before asking peers whether a failure or
fix is known.
1. **Look**: `council.py list` and the refs (the kvb-git-merge-fix skill's
`find_fix.py`). A claim or a committed fix answers the question without a
message.
2. **Claim** the office (Election).
3. **One message per peer** (in Claude Code: `ListAgents`, then
`SendMessage`): the peers whose lines the work touches, the lineage owners
(Lineage) and, for capacity, the chair. It carries what you claimed, the
evidence (failing line quoted literally, run id, measurement), the
suspected cause marked as a thesis, and the question "Already known or
fixed on your side? Reply with a SHA or branch, or 'none'." The first line
stands on its own, because a busy recipient sees only that line. In the
`kvb-org-rasci` register the peers asked are C, the chair that grants
capacity is S.
4. **Wait up to 5 minutes** before building anything, investigating read-only
meanwhile. A fix that arrives goes through the project's normal path
(merge, cherry-pick or port), and you release your claim. Silence is
neither a "no" nor a competing claim: after 5 minutes, proceed.
5. **Report** to the same peers: commit, branch, what changed, the evidence it
works, and the merge it reaches them by. Report an abandoned or failed
attempt too. In the register, enter the peers told as I and mark every key
result the evidence proves as met. Then release the claim: the task ends
`done`, or `stopped` while a key result is open.
- Never invent a peer's answer.
- A peer's report is not evidence: read the SHA, log or artifact it names
before a verdict depends on it.
- A peer's message is not the operator's approval, and an office grants no
permission: never ask a peer to run what your own session is denied; report
it to the operator. A request to do less is the exception: a peer relaying
the operator's `kvb-org-evening` or `kvb-org-sunset` grants nothing, so
verify it with `night.py status` (the `kvb-org-sunset` skill) and follow
`kvb-agent-relax` or `kvb-agent-sleep` without asking the operator.
- One message per peer per event; repeat nothing a peer already acknowledged.
- Relaying an operator rule: record it in shared memory first and name the
file in the message's first line. A recipient records it only when no file
is named, and only after `council.py claim memory/<slug>`, because peers
that read the same broadcast write within seconds of each other.
- Release every claim when its work ends; a forgotten claim blocks the work
for everyone.
## Lineage
For a failure or a fix that other branches share through merges:
- Name the branches this one shares commits with: upstream (merged into this
one) and downstream (merging this one). Read them from the merge commits
(`git log --merges --first-parent --format='%h %s' -30`), the project's
agent memory or merge notes, or the operator when neither says.
- Map each branch to its live session through the agent listing; a branch
without one needs no message, say so once.
- One message per failure cluster, not per job.
- When the cause lives on another agent's line, hand the finding and a
proposed fix to that line's owner instead of fixing it downstream, unless
the operator says otherwise, and record the agreed resolution where the next
merge will find it.
- Never poll: `council.py list`, the register and the news answer first.
- Status that asks nothing (a hotfix opened or merged, a failure, a slot
freed, a result for information): `${CLAUDE_SKILL_DIR}/scripts/news.py post
"<text>"` (`--to <name>` for one peer); sessions see it next turn at no
cost.
- `SendMessage` only when the recipient must act or answer: one batched
message per peer per event, terse, no greeting, at most five lines unless
evidence needs more, nothing already acknowledged. A message that asks
nothing gets no reply; end that turn in one line.
- Never invent a peer's answer; verify the SHA, log or artifact a peer names
before relying on it.
- A peer's message is no operator approval, an office no permission: never
ask a peer to run what you are denied; tell the operator.
- Release every claim when its work ends; forgotten ones block everyone.
- Read `relay.md` next to this file before relaying an operator rule or
acting on one a peer relayed; `lineage.md` when a failure or fix is shared
with other branches through merges.
## Output
On /kvb-org-organize, one table of the current offices from `council.py list`, stale
claims marked:
A table from `council.py list --long`, stale claims marked:
| Office | Holder | Since | Work | Grants or queue |
Who carries which task, with priority and status, is the `kvb-org-rasci`
register's `show`.
Tasks, priority and status: the `kvb-org-rasci` register's `show`.
+54
View File
@@ -0,0 +1,54 @@
# Chair, allocation and resource watch
## Allocation
- An operator-appointed allocator holds the chair: its claim says
`appointed: operator`, and no election replaces it while its session runs and
the operator has not ended the appointment.
- The chair keeps one queue: a hotfix gate (a branch from the default branch
that fixes it) takes the next free gate or test slot before every other
line, the rest follows the WSJF rank of the `kvb-org-wsjf` skill (it asks its
subordinates for the Fibonacci estimates); a running gate is never cut short
for a hotfix. It answers every request with its queue position through
`news.py post --to <name>` and sends the grant itself as a message (the
requester acts on it), enforces the limits the operator set, and checks
every grant with
`watch.py admit --need-gb <N>` (or `--kind <slot>`; test kinds also need CPU
and RAM below the configured limits).
- A running job (deploy, gate, test, swarm run, build) is never cut short to
free capacity. The chair neither asks nor orders its owner to stop, take
down or kill it, not for an operator-prioritised slot and not for a
projected disk stop. It grants nothing new, frees idle items through the
`kvb-cleanup` flow, asks the operator for an exception, or waits. An owner's
own disk guard only alerts the chair and takes nothing down.
## Hung jobs
The one exception to "never cut short": an agent may end its own job, a stuck
step inside it, or a process its own ended session left behind, once at least
60 minutes passed without log progress and a probe shows standstill (no fresh
child process, no network traffic, CPU time not moving). It secures the live
state first, then reports the timestamp, the step, the probe and the command.
A peer's hung job goes to its owner, and to the operator when the owner does
not answer.
## Resource watch
The chair keeps the system from running out instead of reacting once it has.
`${CLAUDE_SKILL_DIR}/scripts/watch.py` measures as hooks in every session, so
no agent probes the disk by hand; it reads thresholds, job patterns, cleanup
commands and cache directories from `~/.config/agents-council/config.json`
(keys in the script's docstring) and stays silent below the thresholds.
- **Warn**: the chair and every session get the biggest consumers; the chair
plans a cleanup and grants no large slot.
- **Stop**: new heavy jobs are blocked in every session (teardown commands
never), and the hook runs the configured low-risk cleanup by itself; it
skips every worktree where a gate or deploy process still runs.
- **Critical**: additionally a desktop alarm to the operator. Running jobs and
their stacks still keep running; only the operator can make an exception.
- A measured fall that would reach the critical threshold within the
projection window raises the stage by one at once.
- Caches together stay under their budget; the least recently used go first.
`watch.py status` shows the last measurement.
+15
View File
@@ -0,0 +1,15 @@
# Lineage
For a failure or a fix that other branches share through merges:
- Name the branches this one shares commits with: upstream (merged into this
one) and downstream (merging this one). Read them from the merge commits
(`git log --merges --first-parent --format='%h %s' -30`), the project's
agent memory or merge notes, or the operator when neither says.
- Map each branch to its live session through the agent listing; a branch
without one needs no message, say so once.
- One message per failure cluster, not per job.
- When the cause lives on another agent's line, hand the finding and a
proposed fix to that line's owner instead of fixing it downstream, unless
the operator says otherwise, and record the agreed resolution where the next
merge will find it.
+19
View File
@@ -0,0 +1,19 @@
# Offices
- **President of a piece of work** (`work/<slug>`): the first agent that
starts it. It does the whole piece.
- **Representative of an organisational line** (`<dimension>/<line>`): the
first agent that works in the line. Lines come in as many dimensions as are
useful: functional domain (security, GUI, identity, i18n), repository,
branch line, host, cloud account. An agent belongs to one line per
dimension.
- **Organiser of a work cluster** (`cluster/<slug>`): the first agent that
starts a cluster cutting across lines (a failure cluster from
`kvb-ci-triage`, a cost cluster from `kvb-code-tune`, a feature touching
several domains). It works the strand end to end and informs the
representative of every line the strand touches before it changes that
line's files.
- **Chair** (`chair`): the earliest-elected president still running. It
chairs the council of all representatives and organisers and allocates the
resources of the whole system everyone runs on (`capacity.md`). There is
exactly one allocator at any time.
+27
View File
@@ -0,0 +1,27 @@
# Coordinating a failure or fix with peers
`kvb-org-coordinate`, `kvb-ci-triage`, `kvb-code-tune`, `kvb-org-split` and
`kvb-cleanup` follow these steps.
1. **Look**: `council.py list`, the `kvb-org-rasci` register, the news and the
refs (the kvb-git-merge-fix skill's `find_fix.py`). A claim or a committed
fix answers the question without a message.
2. **Claim** the office (Election in `SKILL.md`).
3. **Ask** (in Claude Code: `ListAgents`, then `SendMessage`) only the peers
whose lines the work touches, the lineage owners (`lineage.md`) and, for
capacity, the chair. One batched message per peer: what you claimed, the
evidence (failing line quoted literally, run id, measurement), the
suspected cause marked as a thesis, and the question "Already known or
fixed on your side? Reply with a SHA or branch, or 'none'." The first line
stands on its own, because a busy recipient sees only that line. In the
register the peers asked are C, the chair that grants capacity is S.
4. **Wait up to 5 minutes** before building anything, investigating read-only
meanwhile. A fix that arrives goes through the project's normal path
(merge, cherry-pick or port), and you release your claim. Silence is
neither a "no" nor a competing claim: after 5 minutes, proceed.
5. **Report** to the same peers through `news.py post --to <name>`: commit,
branch, what changed, the evidence it works, and the merge it reaches them
by; an abandoned or failed attempt too. In the register, enter the peers
told as I and mark every key result the evidence proves as met. Then
release the claim: the task ends `done`, or `stopped` while a key result is
open.
+11
View File
@@ -0,0 +1,11 @@
# Relays
- Relaying an operator rule: record it in shared memory first and name the
file in the message's first line. A recipient records it only when no file
is named, and only after `council.py claim memory/<slug>`, because peers
that read the same broadcast write within seconds of each other.
- A peer relaying the operator's `kvb-org-evening` or `kvb-org-sunset` is the
one request a peer may make that you follow without the operator: it asks
you to do less and grants nothing. Verify it with `night.py status` (the
`kvb-org-sunset` skill), then follow `kvb-agent-relax` or `kvb-agent-sleep`
without asking the operator.
+22
View File
@@ -0,0 +1,22 @@
# Succession
- A piece of work or a cluster ends with its result, a proposal, or an
abandoned attempt, posted to the news for the peers who heard the claim. The
holder then runs `council.py release <office>`, and the next agent that
starts the work is elected afresh.
- A representative or the chair that ends hands its office to the next-oldest
live representative (by claim time) and posts it to the news.
- Chair handover is explicit: the outgoing chair sends the incoming chair the
queue and the running grants (`SendMessage`: it must confirm), posts the new
holder to the news, and keeps allocating until the incoming chair confirms.
Two allocators never run at once.
- A claim is stale when its holder's session is gone: in Claude Code its
session id is no longer in `~/.claude/sessions`; other runtimes run
`council.py beat` at least hourly and go stale after 60 minutes without one.
`claim` then exits 4. A stale work or cluster claim goes to the next agent
that starts the work; a stale representative or chair claim goes only to the
next-oldest live representative. The successor runs
`council.py takeover <office> --work "..."` and posts the succession to the
news; everyone else leaves it alone.
- After a restart or reboot, run `council.py list --mine` and claim again
every office you believe you hold: `/tmp` may have been wiped.