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

+50 -50
View File
@@ -2,66 +2,66 @@
name: kvb-create-plan
description: >
Turn a request into an objective-oriented plan for the kvb-org-robot skill.
Trigger on /kvb-create-plan or a request for a plan, breakdown or strategy
before work starts.
Trigger on a request for a plan, breakdown or strategy before work starts.
---
Produce a plan whose every item is an outcome with a check, then execute it
autonomously. A plan that lists activities instead of objectives cannot be
verified, and an unverifiable plan cannot be handed to a robot.
autonomously. A plan of activities instead of objectives cannot be verified,
and an unverifiable plan cannot be handed to a robot.
## Procedure
1. **Interview first.** Open every plan with the `kvb-think-listen` skill: ask
until scope, constraints, success criteria, and the operator-only facts are
all pinned, then reflect the understanding back. This is the only point in
the run where questions are allowed, so leave nothing open here.
2. **Pin the objective.** State the end state in one sentence, as a condition
that is either true or false, never as an activity. Name the command or
observation that proves it.
3. **Inspect before decomposing.** Read the code, config, tests, and history the
objective touches. Every plan item must rest on something you have seen, not
on an assumption about how the project works.
4. **Decompose into sub-objectives.** Each item gets: the outcome it reaches,
the verification that proves it, and the items it depends on. Split an item
whenever it needs more than one verification. Order by dependency and mark
the items that are independent, so they can run in parallel.
5. **Resolve the open decisions now.** Any root cause, design choice, or
trade-off the plan rests on gets settled before execution, escalating to the
`kvb-think-dialectic` skill where being wrong is expensive. The robot does not ask, so
an unresolved decision becomes a guess at runtime.
6. **Record the plan in the register.** Enter the objective in the
until scope, constraints, success criteria and the operator-only facts are
pinned, then reflect the understanding back. This is the only point in the
run where questions are allowed, so leave nothing open.
2. **Pin the objective.** The end state in one sentence, as a condition that
is true or false, never an activity, with the command or observation that
proves it.
3. **Inspect before decomposing.** Read the code, config, tests and history
the objective touches; every item rests on something you have seen, not on
an assumption. Explore the code through the codebase-memory-mcp graph
first (`search_graph`, `trace_path`, `get_architecture`, `detect_changes`;
the `kvb-agent-optimize` skill sets it up), grep and read after.
4. **Decompose into sub-objectives.** Each item gets its outcome, the
verification that proves it, and the items it depends on. Split an item
that needs more than one verification. Order by dependency and mark the
independent items, so they can run in parallel.
5. **Resolve the open decisions now.** Every root cause, design choice or
trade-off the plan rests on is settled before execution, through the
`kvb-think-dialectic` skill where being wrong is expensive. The robot does
not ask, so an unresolved decision becomes a guess at runtime.
6. **Record the plan in the register.** The objective goes into the
`kvb-org-rasci` register with each sub-objective's verification as a key
result, and mirror the sub-objectives into the harness's own todo tracking,
one entry per item, phrased as the outcome. Keep a plan file only when the
operator asks for one.
7. **Present it and wait.** Show the objective, the ordered sub-objectives with
their verifications, what is deliberately out of scope, and the assumptions
the plan rests on. Stop here: the plan is the deliverable of this step.
8. **Implement it statically, in full.** On the operator's go, write every code,
config, test, and doc change the plan calls for, across all sub-objectives,
before running anything that needs live infrastructure. Verify statically:
read the diff, run the linters, the unit tests, and whatever dry-run or
syntax check the project offers. This step ends only when the whole plan
exists on disk, with no sub-objective left unwritten.
9. **Then iterate under `kvb-org-robot`.** With the static implementation complete,
invoke the `kvb-org-robot` skill with the objective as its goal for the dynamic part:
run, deploy, observe, fix, repeat until every verification passes. It drives
the loop without check-ins, verifies each outcome instead of assuming it, and
reports the items that fall outside its clearance for the operator to run.
result; mirror the sub-objectives into the harness's todo tracking, one
entry per item, phrased as the outcome. A plan file only when the operator
asks for one.
7. **Present it and wait.** Show the objective, the ordered sub-objectives
with their verifications, what is deliberately out of scope, and the
assumptions the plan rests on. Stop: the plan is this step's deliverable.
8. **Implement it statically, in full.** On the operator's go, write every
code, config, test and doc change the plan calls for, across all
sub-objectives, before running anything that needs live infrastructure.
Verify statically: read the diff, run the linters, the unit tests, and any
dry-run or syntax check the project offers. The step ends only when the
whole plan exists on disk.
9. **Then iterate under `kvb-org-robot`.** Invoke the `kvb-org-robot` skill
with the objective as its goal for the dynamic part: run, deploy, observe,
fix, repeat until every verification passes. It drives the loop without
check-ins, verifies each outcome, and reports the items outside its
clearance for the operator to run.
## Rules
- One objective per item, in outcome form: "endpoint returns 200 for an expired
token", not "fix the auth middleware".
- No item without a verification. If you cannot name what proves it, the item is
still a wish, not a plan.
- One objective per item, in outcome form: "endpoint returns 200 for an
expired token", not "fix the auth middleware".
- No item without a verification; an item nothing proves is a wish.
- Plan only what the request covers. Speculative future-proofing, refactors
nobody asked for, and abstractions with one caller belong in the out-of-scope
list, not in the plan.
- Static before dynamic: never start the robot loop on a half-written plan. A
deploy that fails on code you had not written yet costs a full cycle and
proves nothing.
- Re-plan on contradicted evidence: when execution disproves an assumption the
plan rests on, revise the plan instead of forcing the original steps through.
nobody asked for, and abstractions with one caller go to the out-of-scope
list.
- Static before dynamic: never start the robot loop on a half-written plan; a
deploy failing on code not yet written costs a full cycle and proves
nothing.
- Re-plan on contradicted evidence: when execution disproves an assumption,
revise the plan instead of forcing the original steps through.
- Cite `file:line` for every claim about the current state of the code.