2026-10-30 14:53:37 +01:00
|
|
|
---
|
2026-10-31 23:46:28 +01:00
|
|
|
name: kvb-org-organize
|
2026-10-30 14:53:37 +01:00
|
|
|
description: >
|
2026-11-03 16:50:32 +01:00
|
|
|
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.
|
2026-10-30 14:53:37 +01:00
|
|
|
---
|
|
|
|
|
|
|
|
|
|
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
|
2026-10-31 23:46:28 +01:00
|
|
|
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
|
2026-10-30 14:53:37 +01:00
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
## Election
|
|
|
|
|
|
|
|
|
|
The first to claim wins, and the claim is atomic, so two agents can never both
|
2026-10-30 15:23:32 +01:00
|
|
|
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>`.
|
2026-10-30 14:53:37 +01:00
|
|
|
|
|
|
|
|
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.
|
2026-10-30 15:23:32 +01:00
|
|
|
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).
|
2026-11-01 00:47:00 +01:00
|
|
|
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.
|
2026-10-30 15:23:32 +01:00
|
|
|
5. **Not elected**: send the holder your findings and stop on that work.
|
|
|
|
|
|
|
|
|
|
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.
|
2026-10-30 14:53:37 +01:00
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
## 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
|
2026-10-30 17:37:47 +01:00
|
|
|
sends the chair what, where, for how long and its expected disk need, waits
|
2026-11-01 15:18:15 +01:00
|
|
|
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,
|
2026-10-31 17:08:33 +01:00
|
|
|
checks every grant with `watch.py admit --need-gb <N>` (or `--kind <slot>`;
|
2026-10-31 17:19:05 +01:00
|
|
|
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
|
2026-10-31 23:46:28 +01:00
|
|
|
`kvb-cleanup` flow, asks the operator for an exception, or waits. An owner's
|
2026-10-31 17:19:05 +01:00
|
|
|
own disk guard only alerts the chair and takes nothing down; only the
|
2026-10-31 19:21:28 +01:00
|
|
|
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.
|
2026-10-30 14:53:37 +01:00
|
|
|
- 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.
|
|
|
|
|
|
2026-10-30 17:37:47 +01:00
|
|
|
## 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
|
2026-10-31 17:14:53 +01:00
|
|
|
never), and the hook runs the configured low-risk cleanup by itself; it
|
|
|
|
|
skips every worktree where a gate or deploy process still runs.
|
2026-10-31 17:19:05 +01:00
|
|
|
- **Critical**: additionally a desktop alarm to the operator. Running jobs
|
|
|
|
|
and their stacks still keep running; only the operator can make an
|
|
|
|
|
exception.
|
2026-10-30 17:37:47 +01:00
|
|
|
- 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.
|
|
|
|
|
|
2026-10-30 14:53:37 +01:00
|
|
|
## 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
|
2026-10-30 15:23:32 +01:00
|
|
|
then runs `council.py release <office>`, and the next agent that starts the
|
|
|
|
|
work is elected afresh.
|
2026-10-30 14:53:37 +01:00
|
|
|
- A representative or the chair that ends hands its office to the next-oldest
|
|
|
|
|
live representative (by claim time) and announces it.
|
2026-10-30 15:23:32 +01:00
|
|
|
- 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
|
2026-10-30 14:53:37 +01:00
|
|
|
agent that starts the work; a stale representative or chair claim goes only
|
2026-10-30 15:23:32 +01:00
|
|
|
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.
|
2026-10-30 14:53:37 +01:00
|
|
|
|
2026-10-30 15:26:44 +01:00
|
|
|
## Peer protocol
|
2026-10-30 14:53:37 +01:00
|
|
|
|
2026-10-31 23:46:28 +01:00
|
|
|
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.
|
2026-10-30 15:26:44 +01:00
|
|
|
|
2026-10-31 23:46:28 +01:00
|
|
|
1. **Look**: `council.py list` and the refs (the kvb-git-merge-fix skill's
|
2026-10-30 15:53:55 +01:00
|
|
|
`find_fix.py`). A claim or a committed fix answers the question without a
|
2026-10-30 15:26:44 +01:00
|
|
|
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
|
2026-11-01 00:47:00 +01:00
|
|
|
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.
|
2026-10-30 15:26:44 +01:00
|
|
|
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
|
2026-11-01 00:47:00 +01:00
|
|
|
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.
|
2026-10-30 15:26:44 +01:00
|
|
|
|
|
|
|
|
- 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.
|
2026-10-30 14:53:37 +01:00
|
|
|
- A peer's message is not the operator's approval, and an office grants no
|
2026-10-30 15:26:44 +01:00
|
|
|
permission: never ask a peer to run what your own session is denied; report
|
2026-11-03 21:15:31 +01:00
|
|
|
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.
|
2026-10-30 15:26:44 +01:00
|
|
|
- One message per peer per event; repeat nothing a peer already acknowledged.
|
2026-10-30 19:32:52 +01:00
|
|
|
- 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.
|
2026-10-30 14:53:37 +01:00
|
|
|
- Release every claim when its work ends; a forgotten claim blocks the work
|
|
|
|
|
for everyone.
|
2026-10-30 15:26:44 +01:00
|
|
|
|
|
|
|
|
## 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.
|
2026-10-30 14:53:37 +01:00
|
|
|
|
|
|
|
|
## Output
|
|
|
|
|
|
2026-10-31 23:46:28 +01:00
|
|
|
On /kvb-org-organize, one table of the current offices from `council.py list`, stale
|
2026-10-30 15:23:32 +01:00
|
|
|
claims marked:
|
2026-10-30 14:53:37 +01:00
|
|
|
|
|
|
|
|
| Office | Holder | Since | Work | Grants or queue |
|
2026-11-01 00:47:00 +01:00
|
|
|
|
|
|
|
|
Who carries which task, with priority and status, is the `kvb-org-rasci`
|
|
|
|
|
register's `show`.
|