Compare commits
No files matched your search
@@ -17,6 +17,8 @@ npm-debug.log*
|
||||
.claude/
|
||||
.mcp.json
|
||||
|
||||
.state/
|
||||
|
||||
# Editor / OS
|
||||
.DS_Store
|
||||
*.swp
|
||||
@@ -1,5 +1,50 @@
|
||||
# Changelog
|
||||
|
||||
## [0.3.0] - 2026-11-03
|
||||
|
||||
Breaking:
|
||||
|
||||
- Skills: every skill is now *kvb-category-name*; the old names are gone
|
||||
- Skills: the category *skills* is now *skill*, e.g. *kvb-skill-tune*
|
||||
- Skills: *kvb-create-feature* is now *kvb-think-gaps*
|
||||
- Skills: *kvb-skill-dream* is now *kvb-dream*
|
||||
- Skills: *kvb-skills-shortcuts* and tokens such as *sobu* are gone
|
||||
|
||||
Added:
|
||||
|
||||
- Org: *kvb-org-rasci* keeps one RASCI/OKR register of every agent task
|
||||
- Org: *kvb-org-artefacts* tracks images, volumes and worktrees per task
|
||||
- Org: *kvb-org-wsjf* ranks the register by WSJF from Fibonacci estimates
|
||||
- Org: *kvb-org-operator* lists every command only the operator can run
|
||||
- Commit: commit skills show worktree, branch, confidence and risk first
|
||||
- Transcend: *kvb-transcend* carries session scripts and tests into repos
|
||||
- Requirements: *kvb-create-requirement* with user story, Mermaid and tests
|
||||
- Think: *kvb-think-brainstorm* scores options from seven fixed lenses
|
||||
- Skills: *kvb-skill-compile* turns deterministic steps into scripts
|
||||
- Skills: *kvb-skill-cleanup* deletes legacy skills that renames left behind
|
||||
- Dream: *kvb-optimize* runs all nine optimization skills in one pass
|
||||
- Dream: a GNOME notification recommends */kvb-dream* daily at 17:00
|
||||
- Coach: *kvb-coach* suggests the next step for mind, body, food and tasks
|
||||
- Coach: *kvb-coach-meditation* plays alpha-wave music with fractals
|
||||
- Coach: a short coach note at the first prompt of every full hour
|
||||
|
||||
Changed:
|
||||
|
||||
- Dream: covers every repository and session, then optimizes and cleans up
|
||||
- Dream: one hint per agent every 12 h replaces the tune and dream hints
|
||||
- Tune: *kvb-code-tune* always checks language, framework and recursion
|
||||
- Cleanup: worktrees are listed by size and integration line
|
||||
- Coordination: hotfix gates take the next free test slot
|
||||
- Coordination: an agent may end its own job after 60 min without progress
|
||||
|
||||
Upgrade notes:
|
||||
|
||||
- Install: run *make install* and restart the agent to load the new names
|
||||
- Install: run *make install-skills* in each project to drop old copies
|
||||
- Install: */kvb-skill-cleanup* lists any legacy skill left behind
|
||||
- Install: the global install enables the *kvb-dream-notify.timer* unit
|
||||
- Settings: remove *autotune* and *dream* hooks from *~/.claude/settings.json*
|
||||
|
||||
## [0.2.0] - 2026-10-31
|
||||
|
||||
Added:
|
||||
|
||||
@@ -7,9 +7,83 @@ Every skill is pinned in `skills-lock.json` for reproducible installs.
|
||||
First-party skills live under `skills/` and are layered on top of the locked ones at install time.
|
||||
Compatible with Claude Code, Codex, Gemini CLI, Cursor, Copilot, Windsurf, Cline, and other agents.
|
||||
|
||||
## Naming 🏷️
|
||||
|
||||
Every first-party skill is named `kvb-<category>-<name>` with one of these categories: `think`, `create`, `code`, `ci`, `git`, `check`, `org`, `skill`, `coach`. Only `kvb-cleanup`, `kvb-coach`, `kvb-help` and the collectors `kvb-dream`, `kvb-optimize` and `kvb-transcend` stand without a category. Names use `a-z`, `0-9` and single hyphens, at most 64 characters, and equal their directory name. `tests/test_naming.py` enforces all of it, including that the organigram below lists every skill under its category.
|
||||
|
||||
## Organigram 🏛️
|
||||
|
||||
Every first-party skill under its category.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
kvb((kvb))
|
||||
kvb --> think[think]
|
||||
kvb --> create[create]
|
||||
kvb --> code[code]
|
||||
kvb --> ci[ci]
|
||||
kvb --> git[git]
|
||||
kvb --> check[check]
|
||||
kvb --> org[org]
|
||||
kvb --> skill[skill]
|
||||
kvb --> coach[coach]
|
||||
kvb --> none[no category]
|
||||
think --> think_listen[kvb-think-listen]
|
||||
think --> think_explain[kvb-think-explain]
|
||||
think --> think_dialectic[kvb-think-dialectic]
|
||||
think --> think_criticize[kvb-think-criticize]
|
||||
think --> think_brainstorm[kvb-think-brainstorm]
|
||||
think --> think_gaps[kvb-think-gaps]
|
||||
create --> create_plan[kvb-create-plan]
|
||||
create --> create_requirement[kvb-create-requirement]
|
||||
code --> code_scope_guard[kvb-code-scope-guard]
|
||||
code --> code_no_defaults[kvb-code-no-defaults]
|
||||
code --> code_no_comments[kvb-code-no-comments]
|
||||
code --> code_refactor[kvb-code-refactor]
|
||||
code --> code_test[kvb-code-test]
|
||||
code --> code_tune[kvb-code-tune]
|
||||
code --> code_transcend[kvb-code-transcend]
|
||||
ci --> ci_triage[kvb-ci-triage]
|
||||
ci --> ci_artifacts[kvb-ci-artifacts]
|
||||
ci --> ci_observe[kvb-ci-observe]
|
||||
git --> git_commit_next[kvb-git-commit-next]
|
||||
git --> git_commit_no_verify[kvb-git-commit-no-verify]
|
||||
git --> git_merge_fix[kvb-git-merge-fix]
|
||||
git --> git_branch_gc[kvb-git-branch-gc]
|
||||
git --> git_changelog[kvb-git-changelog]
|
||||
check --> check_legal[kvb-check-legal]
|
||||
check --> check_security[kvb-check-security]
|
||||
check --> check_principles[kvb-check-principles]
|
||||
check --> check_confidence[kvb-check-confidence]
|
||||
check --> check_break_risk[kvb-check-break-risk]
|
||||
org --> org_organize[kvb-org-organize]
|
||||
org --> org_split[kvb-org-split]
|
||||
org --> org_coordinate[kvb-org-coordinate]
|
||||
org --> org_perform[kvb-org-perform]
|
||||
org --> org_matrix[kvb-org-matrix]
|
||||
org --> org_rasci[kvb-org-rasci]
|
||||
org --> org_artefacts[kvb-org-artefacts]
|
||||
org --> org_wsjf[kvb-org-wsjf]
|
||||
org --> org_robot[kvb-org-robot]
|
||||
org --> org_operator[kvb-org-operator]
|
||||
skill --> skill_tune[kvb-skill-tune]
|
||||
skill --> skill_auto[kvb-skill-auto]
|
||||
skill --> skill_essence[kvb-skill-essence]
|
||||
skill --> skill_transcend[kvb-skill-transcend]
|
||||
skill --> skill_compile[kvb-skill-compile]
|
||||
skill --> skill_cleanup[kvb-skill-cleanup]
|
||||
none --> cleanup[kvb-cleanup]
|
||||
none --> help[kvb-help]
|
||||
none --> transcend_all[kvb-transcend]
|
||||
none --> dream_all[kvb-dream]
|
||||
none --> optimize_all[kvb-optimize]
|
||||
none --> coach_all[kvb-coach]
|
||||
coach --> coach_meditation[kvb-coach-meditation]
|
||||
```
|
||||
|
||||
## Skill map 🗺️
|
||||
|
||||
How the first-party skills work together. A solid arrow means the skill invokes or relies on the other one; a dotted arrow means it fires automatically. Every skill that reports a result closes with the `confidence` block; those arrows are left out. The locked third-party skills (caveman, ponytail, archify) are not drawn.
|
||||
How the first-party skills work together. A solid arrow means the skill invokes or relies on the other one; a dotted arrow means it fires automatically. Every skill that reports a result closes with the `kvb-check-confidence` block; those arrows are left out. The locked third-party skills (caveman, ponytail, archify) are not drawn.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@@ -17,63 +91,81 @@ flowchart LR
|
||||
commit_req([commit request])
|
||||
stage_req([staging or fix ready])
|
||||
edit_hook([edit in a git worktree])
|
||||
reminders([reminder hooks])
|
||||
reminders([12 h agent hint, 17:00 GNOME popup])
|
||||
full_hour([full hour])
|
||||
code_task([code task])
|
||||
spawn([subagent spawn])
|
||||
end
|
||||
subgraph commit [Commit]
|
||||
commit_next[commit-next]
|
||||
commit_no_verify[commit-no-verify]
|
||||
comments_clean[comments-clean]
|
||||
advocate[advocate]
|
||||
confidence[confidence]
|
||||
break_risk[break-risk]
|
||||
explain[explain]
|
||||
subgraph cat_think [think]
|
||||
active_listening[kvb-think-listen]
|
||||
explain[kvb-think-explain]
|
||||
dialectic[kvb-think-dialectic]
|
||||
criticize[kvb-think-criticize]
|
||||
brainstorm[kvb-think-brainstorm]
|
||||
gaps[kvb-think-gaps]
|
||||
end
|
||||
subgraph coordination [Coordination]
|
||||
democracy[democracy]
|
||||
coordinate[coordinate]
|
||||
funnel[funnel]
|
||||
cleanup[cleanup]
|
||||
branch_gc[branch-gc]
|
||||
subagent_model[subagent-model]
|
||||
subgraph cat_create [create]
|
||||
plan[kvb-create-plan]
|
||||
requirement[kvb-create-requirement]
|
||||
end
|
||||
subgraph ci [CI]
|
||||
observe[observe]
|
||||
triage[triage]
|
||||
ci_artifacts[ci-artifacts]
|
||||
tune[tune]
|
||||
merge_fix[merge-fix]
|
||||
subgraph cat_code [code]
|
||||
scope_guard[kvb-code-scope-guard]
|
||||
no_defaults[kvb-code-no-defaults]
|
||||
refactor[kvb-code-refactor]
|
||||
test[kvb-code-test]
|
||||
tune[kvb-code-tune]
|
||||
comments_clean[kvb-code-no-comments]
|
||||
code_transcend[kvb-code-transcend]
|
||||
end
|
||||
subgraph reasoning [Reasoning]
|
||||
active_listening[active-listening]
|
||||
dialectic[dialectic]
|
||||
criticize[criticize]
|
||||
sceptic[sceptic]
|
||||
auto_feature[auto-feature]
|
||||
subgraph cat_ci [ci]
|
||||
triage[kvb-ci-triage]
|
||||
ci_artifacts[kvb-ci-artifacts]
|
||||
observe[kvb-ci-observe]
|
||||
end
|
||||
subgraph autonomy [Autonomy]
|
||||
plan[plan]
|
||||
robot[robot]
|
||||
subgraph cat_git [git]
|
||||
commit_next[kvb-git-commit-next]
|
||||
commit_no_verify[kvb-git-commit-no-verify]
|
||||
merge_fix[kvb-git-merge-fix]
|
||||
branch_gc[kvb-git-branch-gc]
|
||||
changelog[kvb-git-changelog]
|
||||
end
|
||||
subgraph self_improvement [Self-improvement]
|
||||
dream[dream]
|
||||
autotune[autotune]
|
||||
autoskill[autoskill]
|
||||
essence[essence]
|
||||
shortcuts[shortcuts]
|
||||
subgraph cat_check [check]
|
||||
advocate[kvb-check-legal]
|
||||
medusa[kvb-check-security]
|
||||
sceptic[kvb-check-principles]
|
||||
confidence[kvb-check-confidence]
|
||||
break_risk[kvb-check-break-risk]
|
||||
end
|
||||
subgraph quality [Quality]
|
||||
test[test]
|
||||
refactor[refactor]
|
||||
no_defaults[no-defaults]
|
||||
scope_guard[scope-guard]
|
||||
subgraph cat_org [org]
|
||||
democracy[kvb-org-organize]
|
||||
funnel[kvb-org-split]
|
||||
coordinate[kvb-org-coordinate]
|
||||
subagent_model[kvb-org-perform]
|
||||
status_matrix[kvb-org-matrix]
|
||||
rasci[kvb-org-rasci]
|
||||
artefacts[kvb-org-artefacts]
|
||||
wsjf[kvb-org-wsjf]
|
||||
robot[kvb-org-robot]
|
||||
operator[kvb-org-operator]
|
||||
end
|
||||
subgraph standalone [Standalone]
|
||||
changelog[changelog]
|
||||
help_skills[help-skills]
|
||||
status_matrix[status-matrix]
|
||||
medusa[medusa]
|
||||
subgraph cat_skill [skill]
|
||||
autotune[kvb-skill-tune]
|
||||
autoskill[kvb-skill-auto]
|
||||
essence[kvb-skill-essence]
|
||||
skill_transcend[kvb-skill-transcend]
|
||||
compile[kvb-skill-compile]
|
||||
skill_cleanup[kvb-skill-cleanup]
|
||||
end
|
||||
subgraph cat_none [no category]
|
||||
cleanup[kvb-cleanup]
|
||||
help_skills[kvb-help]
|
||||
transcend[kvb-transcend]
|
||||
dream[kvb-dream]
|
||||
optimize[kvb-optimize]
|
||||
coach[kvb-coach]
|
||||
end
|
||||
subgraph cat_coach [coach]
|
||||
meditation[kvb-coach-meditation]
|
||||
end
|
||||
|
||||
commit_req -.-> commit_next
|
||||
@@ -81,7 +173,7 @@ flowchart LR
|
||||
stage_req -.-> confidence
|
||||
edit_hook -. council gate .-> democracy
|
||||
reminders -.-> dream
|
||||
reminders -.-> autotune
|
||||
full_hour -.-> coach
|
||||
code_task -.-> no_defaults
|
||||
code_task -.-> scope_guard
|
||||
spawn -.-> subagent_model
|
||||
@@ -105,6 +197,15 @@ flowchart LR
|
||||
funnel --> subagent_model
|
||||
dialectic --> subagent_model
|
||||
democracy --> merge_fix
|
||||
democracy -. claim and release .-> rasci
|
||||
funnel --> rasci
|
||||
status_matrix --> rasci
|
||||
cleanup --> artefacts
|
||||
artefacts --> rasci
|
||||
democracy --> wsjf
|
||||
wsjf --> rasci
|
||||
operator --> rasci
|
||||
dream --> rasci
|
||||
|
||||
observe --> triage
|
||||
observe --> ci_artifacts
|
||||
@@ -123,19 +224,52 @@ flowchart LR
|
||||
criticize --> active_listening
|
||||
sceptic --> dialectic
|
||||
sceptic --> no_defaults
|
||||
auto_feature --> sceptic
|
||||
auto_feature --> active_listening
|
||||
gaps --> sceptic
|
||||
gaps --> active_listening
|
||||
gaps --> requirement
|
||||
requirement --> active_listening
|
||||
requirement --> brainstorm
|
||||
requirement -. offer .-> plan
|
||||
brainstorm --> dialectic
|
||||
|
||||
plan --> robot
|
||||
plan --> active_listening
|
||||
robot --> dialectic
|
||||
|
||||
dream --> dialectic
|
||||
dream --> autotune
|
||||
dream --> autoskill
|
||||
dream --> optimize
|
||||
dream --> cleanup
|
||||
dream --> branch_gc
|
||||
optimize --> skill_cleanup
|
||||
optimize --> transcend
|
||||
optimize --> autoskill
|
||||
optimize --> autotune
|
||||
optimize --> compile
|
||||
optimize --> essence
|
||||
optimize --> refactor
|
||||
optimize --> tune
|
||||
optimize --> gaps
|
||||
coach --> active_listening
|
||||
coach --> operator
|
||||
coach --> rasci
|
||||
coach --> meditation
|
||||
meditation --> active_listening
|
||||
autoskill --> autotune
|
||||
autoskill --> shortcuts
|
||||
autotune --> essence
|
||||
transcend --> skill_transcend
|
||||
transcend --> code_transcend
|
||||
skill_transcend --> active_listening
|
||||
skill_transcend --> autotune
|
||||
code_transcend --> active_listening
|
||||
autotune -. own scripts .-> skill_transcend
|
||||
autotune -. deterministic prose .-> compile
|
||||
autoskill -. deterministic steps .-> compile
|
||||
skill_transcend -. deterministic moves .-> compile
|
||||
essence -. procedures .-> compile
|
||||
compile --> active_listening
|
||||
skill_cleanup --> operator
|
||||
skill_cleanup -. unknown skills .-> transcend
|
||||
tune -. measurements .-> code_transcend
|
||||
|
||||
test --> triage
|
||||
test --> dialectic
|
||||
@@ -163,7 +297,7 @@ Copy the skills into a specific project (`<repo>/.agents/skills` and `<repo>/.cl
|
||||
make project TARGET=/path/to/repo
|
||||
```
|
||||
|
||||
Both commands also patch the target's `.claude/settings.local.json` — the machine-local, untracked file, so a project's reviewed `.claude/settings.json` is never rewritten by an install: the caveman and ponytail plugins are enabled so their modes auto-activate on session start, and two reminder hooks are registered — `autotune` points you at `/autotune` at most once an hour, `dream` points you at `/dream` at most once every twelve hours per repository (stamped in that repository's git dir). A PreToolUse gate from the `democracy` skill blocks edits to files in a git worktree until the session holds a claim (`skills/democracy/scripts/council.py`), and its resource watch (`skills/democracy/scripts/watch.py`) measures disk, Docker and caches, cleans up low-risk data and blocks new heavy jobs before the disk runs out; it stays inactive until `~/.config/agents-council/config.json` exists. Two hooks of the `subagent-model` skill (`skills/subagent-model/scripts/log.py`) log every Agent spawn with its task class, model and effort, and store the quality feedback a sandboxed session prints, in `~/.local/state/agents-council/subagent-model.jsonl`. Existing settings are preserved.
|
||||
Both commands also patch the target's `.claude/settings.local.json` — the machine-local, untracked file, so a project's reviewed `.claude/settings.json` is never rewritten by an install: the caveman and ponytail plugins are enabled so their modes auto-activate on session start, and two reminder hooks are registered — `kvb-dream` points each agent at `/kvb-dream` at most once every twelve hours (stamped per session in `~/.claude/.dream-stamps/`), and `kvb-coach` runs its short form at the first prompt of every full hour, once across all agents (stamped in `~/.claude/.coach-hours/`); the global install also enables the `kvb-dream-notify.timer` systemd user timer, which recommends `/kvb-dream` in a GNOME notification daily at 17:00 local time and catches up once after a missed run. A PreToolUse gate from the `kvb-org-organize` skill blocks edits to files in a git worktree until the session holds a claim (`skills/kvb-org-organize/scripts/council.py`), and its resource watch (`skills/kvb-org-organize/scripts/watch.py`) measures disk, Docker and caches, cleans up low-risk data and blocks new heavy jobs before the disk runs out; it stays inactive until `~/.config/agents-council/config.json` exists. Two hooks of the `kvb-org-perform` skill (`skills/kvb-org-perform/scripts/log.py`) log every Agent spawn with its task class, model and effort, and store the quality feedback a sandboxed session prints, in `~/.local/state/agents-council/subagent-model.jsonl`. Existing settings are preserved.
|
||||
|
||||
Restart your agent afterwards so it loads the new skills.
|
||||
|
||||
|
||||
+42
-13
@@ -1,8 +1,4 @@
|
||||
#!/usr/bin/env node
|
||||
// Enable the caveman and ponytail plugins in a Claude Code settings.json so
|
||||
// their SessionStart hooks auto-activate both modes, register the autotune
|
||||
// and dream reminder hooks, the democracy claim gate, the resource watch and the subagent-model log. Merges non-destructively: existing marketplaces,
|
||||
// plugins and hooks are preserved, unparseable files are left untouched.
|
||||
"use strict";
|
||||
|
||||
const fs = require("fs");
|
||||
@@ -19,7 +15,20 @@ const MARKETPLACES = {
|
||||
ponytail: { source: { source: "github", repo: "DietrichGebert/ponytail" } },
|
||||
};
|
||||
const PLUGINS = { "caveman@caveman": true, "ponytail@ponytail": true };
|
||||
const REMINDERS = ["autotune", "dream"];
|
||||
const REMINDERS = ["kvb-dream", "kvb-coach"];
|
||||
const RETIRED = [
|
||||
"autotune/hooks/reminder.sh",
|
||||
"kvb-skills-tune/hooks/reminder.sh",
|
||||
"kvb-skill-tune/hooks/reminder.sh",
|
||||
];
|
||||
const RENAMED = {
|
||||
"dream/hooks/reminder.sh": "kvb-dream/hooks/reminder.sh",
|
||||
"kvb-skills-dream/hooks/reminder.sh": "kvb-dream/hooks/reminder.sh",
|
||||
"kvb-skill-dream/hooks/reminder.sh": "kvb-dream/hooks/reminder.sh",
|
||||
"democracy/scripts/council.py": "kvb-org-organize/scripts/council.py",
|
||||
"democracy/scripts/watch.py": "kvb-org-organize/scripts/watch.py",
|
||||
"subagent-model/scripts/log.py": "kvb-org-perform/scripts/log.py",
|
||||
};
|
||||
|
||||
let data = {};
|
||||
if (fs.existsSync(settingsPath)) {
|
||||
@@ -41,6 +50,26 @@ for (const [name, entry] of Object.entries(MARKETPLACES)) {
|
||||
data.enabledPlugins = Object.assign(data.enabledPlugins || {}, PLUGINS);
|
||||
|
||||
data.hooks = data.hooks || {};
|
||||
const retired = (hook) =>
|
||||
typeof hook.command === "string" && RETIRED.some((r) => hook.command.includes(`/skills/${r}`));
|
||||
for (const [event, entries] of Object.entries(data.hooks)) {
|
||||
if (!Array.isArray(entries)) continue;
|
||||
data.hooks[event] = entries
|
||||
.map((entry) =>
|
||||
Array.isArray(entry.hooks) ? { ...entry, hooks: entry.hooks.filter((h) => !retired(h)) } : entry)
|
||||
.filter((entry) => !Array.isArray(entry.hooks) || entry.hooks.length > 0);
|
||||
}
|
||||
for (const entries of Object.values(data.hooks)) {
|
||||
if (!Array.isArray(entries)) continue;
|
||||
for (const entry of entries) {
|
||||
for (const hook of entry.hooks || []) {
|
||||
if (typeof hook.command !== "string") continue;
|
||||
for (const [from, to] of Object.entries(RENAMED)) {
|
||||
hook.command = hook.command.replace(`/skills/${from}`, `/skills/${to}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
data.hooks.UserPromptSubmit = data.hooks.UserPromptSubmit || [];
|
||||
const alreadyRegistered = JSON.stringify(data.hooks.UserPromptSubmit);
|
||||
for (const skill of REMINDERS) {
|
||||
@@ -52,8 +81,8 @@ for (const skill of REMINDERS) {
|
||||
}
|
||||
|
||||
data.hooks.PreToolUse = data.hooks.PreToolUse || [];
|
||||
if (!JSON.stringify(data.hooks.PreToolUse).includes("democracy/scripts/council.py")) {
|
||||
const council = path.join(path.dirname(settingsPath), "skills", "democracy", "scripts", "council.py");
|
||||
if (!JSON.stringify(data.hooks.PreToolUse).includes("kvb-org-organize/scripts/council.py")) {
|
||||
const council = path.join(path.dirname(settingsPath), "skills", "kvb-org-organize", "scripts", "council.py");
|
||||
data.hooks.PreToolUse.push({
|
||||
matcher: "Edit|Write|MultiEdit|NotebookEdit",
|
||||
hooks: [{ type: "command", command: `python3 ${JSON.stringify(council)} gate` }],
|
||||
@@ -61,11 +90,11 @@ if (!JSON.stringify(data.hooks.PreToolUse).includes("democracy/scripts/council.p
|
||||
}
|
||||
|
||||
const SCRIPT_HOOKS = [
|
||||
["democracy/scripts/watch.py", "UserPromptSubmit", null, "watch"],
|
||||
["democracy/scripts/watch.py", "PostToolUse", "Bash", "watch"],
|
||||
["democracy/scripts/watch.py", "PreToolUse", "Bash", "block"],
|
||||
["subagent-model/scripts/log.py", "PreToolUse", "Agent|Task", "spawn"],
|
||||
["subagent-model/scripts/log.py", "PostToolUse", "Bash", "persist"],
|
||||
["kvb-org-organize/scripts/watch.py", "UserPromptSubmit", null, "watch"],
|
||||
["kvb-org-organize/scripts/watch.py", "PostToolUse", "Bash", "watch"],
|
||||
["kvb-org-organize/scripts/watch.py", "PreToolUse", "Bash", "block"],
|
||||
["kvb-org-perform/scripts/log.py", "PreToolUse", "Agent|Task", "spawn"],
|
||||
["kvb-org-perform/scripts/log.py", "PostToolUse", "Bash", "persist"],
|
||||
];
|
||||
for (const [script, event, matcher, sub] of SCRIPT_HOOKS) {
|
||||
data.hooks[event] = data.hooks[event] || [];
|
||||
@@ -79,4 +108,4 @@ for (const [script, event, matcher, sub] of SCRIPT_HOOKS) {
|
||||
}
|
||||
|
||||
fs.writeFileSync(settingsPath, JSON.stringify(data, null, 2) + "\n");
|
||||
console.log(`skills: enabled caveman + ponytail plugins, the ${REMINDERS.join(" + ")} reminders, the democracy claim gate, the resource watch and the subagent-model log in ${settingsPath}`);
|
||||
console.log(`skills: enabled caveman + ponytail plugins, the ${REMINDERS.join(" + ")} reminders, the kvb-org-organize claim gate, the resource watch and the kvb-org-perform log in ${settingsPath}`);
|
||||
@@ -53,4 +53,17 @@ else
|
||||
warn "skills: node not found; skipped auto-enabling caveman/ponytail plugins."
|
||||
fi
|
||||
|
||||
if [[ "${TARGET}" == "${HOME}" ]]; then
|
||||
if command -v systemctl &>/dev/null && systemctl --user show-environment &>/dev/null; then
|
||||
log "skills: enabling the daily kvb-dream notification timer"
|
||||
units="${HOME}/.config/systemd/user"
|
||||
mkdir -p "${units}"
|
||||
cp -f "${REPO_ROOT}/skills/kvb-dream/systemd/kvb-dream-notify.service" "${REPO_ROOT}/skills/kvb-dream/systemd/kvb-dream-notify.timer" "${units}/"
|
||||
systemctl --user daemon-reload
|
||||
systemctl --user enable --now kvb-dream-notify.timer
|
||||
else
|
||||
warn "skills: no systemd user session; skipped the kvb-dream notification timer."
|
||||
fi
|
||||
fi
|
||||
|
||||
log "skills: done. Restart your agent to load the skills."
|
||||
@@ -1,32 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# UserPromptSubmit hook: emit the autotune hint at most once per interval.
|
||||
# Stdout lands in the agent's context, which is why the payload tells the agent
|
||||
# to show the hint and keep going instead of running autotune by itself.
|
||||
set -euo pipefail
|
||||
|
||||
interval="${AUTOTUNE_INTERVAL_SECONDS:-3600}"
|
||||
stamp="${AUTOTUNE_STAMP:-${HOME}/.claude/.autotune-stamp}"
|
||||
|
||||
now="$(date +%s)"
|
||||
last=0
|
||||
if [[ -f "${stamp}" ]]; then
|
||||
read -r last <"${stamp}" || true
|
||||
[[ "${last}" =~ ^[0-9]+$ ]] || last=0
|
||||
fi
|
||||
|
||||
if ((now - last < interval)); then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
mkdir -p "$(dirname "${stamp}")"
|
||||
printf '%s\n' "${now}" >"${stamp}"
|
||||
|
||||
cat <<'HINT'
|
||||
AUTOTUNE HINT: over an hour since the last hint. Show the operator this notice
|
||||
verbatim as a short block, then continue with their request. Do NOT run
|
||||
autotune, do not propose skills, do not ask questions about it.
|
||||
|
||||
💡 /autotune - generate a new skill or optimize an existing one
|
||||
(fewer tokens, fewer errors, more focus, learnings that persist).
|
||||
Runs only when you trigger it.
|
||||
HINT
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
name: commit-no-verify
|
||||
description: >
|
||||
Commit the staged changes with --no-verify. Trigger on /commit-no-verify or
|
||||
any request for a no-verify commit; invoking it IS the per-commit
|
||||
authorization --no-verify requires, never carried over to later commits.
|
||||
---
|
||||
|
||||
1. Run the comments-clean audit over the staged and unstaged changes first,
|
||||
then the advocate check over the staging index. An advocate blocker stops
|
||||
here.
|
||||
2. Commit exactly the staging index with `git commit --no-verify` and a
|
||||
Conventional-Commits message derived from the staged diff; never add
|
||||
unstaged files, never push.
|
||||
3. Report the created commit hash and what remains uncommitted.
|
||||
@@ -1,11 +0,0 @@
|
||||
---
|
||||
name: coordinate
|
||||
description: >
|
||||
Coordinate a failure or fix with the agents on related branches through
|
||||
merges: claim, ask, report. Trigger on /coordinate and when a fix touches
|
||||
code other branches share.
|
||||
---
|
||||
|
||||
Run the `democracy` skill's **Lineage** and **Peer protocol** sections for the
|
||||
failure or fix at hand. They hold the whole procedure; this skill only keeps
|
||||
`/coordinate` working.
|
||||
@@ -1,40 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# UserPromptSubmit hook: emit the dream hint at most once per interval and per
|
||||
# repository. The stamp lives in the repository's git dir, so every repository
|
||||
# keeps its own cadence; outside a git repository the hook stays silent.
|
||||
# Stdout lands in the agent's context, which is why the payload tells the agent
|
||||
# to show the hint and keep going instead of running dream by itself.
|
||||
set -euo pipefail
|
||||
|
||||
interval="${DREAM_INTERVAL_SECONDS:-43200}"
|
||||
if [[ -n "${DREAM_STAMP:-}" ]]; then
|
||||
stamp="${DREAM_STAMP}"
|
||||
else
|
||||
git_dir="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)" || exit 0
|
||||
stamp="${git_dir}/.dream-stamp"
|
||||
fi
|
||||
|
||||
now="$(date +%s)"
|
||||
last=0
|
||||
if [[ -f "${stamp}" ]]; then
|
||||
read -r last <"${stamp}" || true
|
||||
[[ "${last}" =~ ^[0-9]+$ ]] || last=0
|
||||
fi
|
||||
|
||||
if ((now - last < interval)); then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
mkdir -p "$(dirname "${stamp}")"
|
||||
printf '%s\n' "${now}" >"${stamp}"
|
||||
|
||||
cat <<'HINT'
|
||||
DREAM HINT: over twelve hours since the last hint for this repository. Show the
|
||||
operator this notice verbatim as a short block, then continue with their
|
||||
request. Do NOT run dream, do not start replaying the history, do not ask
|
||||
questions about it.
|
||||
|
||||
💤 /dream - consolidate the last 24h in this repository: what held, what
|
||||
broke, which hypotheses follow, into memory and improvement proposals.
|
||||
Runs only when you trigger it.
|
||||
HINT
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: break-risk
|
||||
name: kvb-check-break-risk
|
||||
description: >
|
||||
Derive the break-risk percentage from measurement, not feel. Called by
|
||||
`confidence` on every report; also when the operator asks "what could this
|
||||
`kvb-check-confidence` on every report; also when the operator asks "what could this
|
||||
break?" or names a break-risk threshold.
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Break risk: the method in detail
|
||||
|
||||
Each step of the `break-risk` skill, with the trap it defeats.
|
||||
Each step of the `kvb-check-break-risk` skill, with the trap it defeats.
|
||||
|
||||
## The consumer question, first and always
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
name: confidence
|
||||
name: kvb-check-confidence
|
||||
description: >
|
||||
Report calibrated fix confidence and break risk unprompted whenever you
|
||||
stage changes, declare a fix or bundle ready, or summarize work the operator
|
||||
@@ -9,12 +9,12 @@ description: >
|
||||
Every stage summary, fix report, or ready-to-commit bundle ends with a
|
||||
confidence block.
|
||||
|
||||
Invoke the `break-risk` skill every time, before writing the block; this skill
|
||||
Invoke the `kvb-check-break-risk` skill every time, before writing the block; this skill
|
||||
reports the number it derives and never estimates one itself.
|
||||
|
||||
1. **Fix confidence** (percent): probability the change does what it
|
||||
claims. **Break risk** (percent): probability it breaks anything else,
|
||||
derived via the `break-risk` skill. Two separate numbers, never one
|
||||
derived via the `kvb-check-break-risk` skill. Two separate numbers, never one
|
||||
blended figure.
|
||||
2. **Evidence**: the strongest proof lines only — what was executed,
|
||||
reproduced, enumerated, or read from authoritative source. Distinguish
|
||||
@@ -33,8 +33,8 @@ Calibration rules:
|
||||
(test, reproduction, live probe) justifies more.
|
||||
|
||||
A threshold the operator named ("95% confidence, break risk ≤5%") is a gate on
|
||||
the work, handled as the `break-risk` skill's last section says, for both
|
||||
the work, handled as the `kvb-check-break-risk` skill's last section says, for both
|
||||
numbers.
|
||||
|
||||
Objective: the `autotune` skill's **Objective** section. Two figures with their residuals replace a
|
||||
Objective: the `kvb-skill-tune` skill's **Objective** section. Two figures with their residuals replace a
|
||||
hedging paragraph and save the operator a verification round trip.
|
||||
@@ -1,24 +1,23 @@
|
||||
---
|
||||
name: advocate
|
||||
name: kvb-check-legal
|
||||
description: >
|
||||
Check a commit for legal soundness: licence compatibility of added code and
|
||||
dependencies, attribution, copied snippets, GDPR, trademarks. Run
|
||||
AUTOMATICALLY before every commit the operator requests; also on /advocate
|
||||
[ref|range], "rechtlich prüfen", "lizenz prüfen".
|
||||
Check a commit's licences, attribution, copied snippets, GDPR and
|
||||
trademarks. Run AUTOMATICALLY before every commit the operator requests;
|
||||
also on /kvb-check-legal [ref|range], "rechtlich prüfen", "lizenz prüfen".
|
||||
---
|
||||
|
||||
The stance is the project's counsel: find what would make the change unlawful
|
||||
to distribute before it is distributed. This is not legal advice but a reading
|
||||
of the licence texts, with German and EU law where jurisdiction matters; every
|
||||
report says so in one line. Leaked secrets belong to `medusa`, engineering
|
||||
principles to `sceptic`.
|
||||
report says so in one line. Leaked secrets belong to `kvb-check-security`, engineering
|
||||
principles to `kvb-check-principles`.
|
||||
|
||||
## Target
|
||||
|
||||
- Before a commit: the staging index (`git diff --cached`, plus every added or
|
||||
changed file in full where origin or licence is in question).
|
||||
- `/advocate <ref>` or `/advocate <a>..<b>`: that commit or range.
|
||||
- `/advocate` alone: the index if it is non-empty, else `HEAD`.
|
||||
- `/kvb-check-legal <ref>` or `/kvb-check-legal <a>..<b>`: that commit or range.
|
||||
- `/kvb-check-legal` alone: the index if it is non-empty, else `HEAD`.
|
||||
|
||||
## Fast exit
|
||||
|
||||
@@ -56,7 +55,7 @@ attribution, copied snippets, data protection, trademarks).
|
||||
|
||||
## Blockers stop the commit
|
||||
|
||||
Harden every blocker with the `dialectic` skill before reporting it. The
|
||||
Harden every blocker with the `kvb-think-dialectic` skill before reporting it. The
|
||||
antithesis tries: the code is trivial or the operator's own; the dependency is
|
||||
build- or test-only and never distributed; an exception applies (linking or
|
||||
Classpath exception, dual licensing, a licence grant in the issue or commit
|
||||
@@ -75,7 +74,7 @@ the operator's language). Then one table, blockers first:
|
||||
|
||||
`Evidence` is `proven` (licence text, metadata, or file read; cite path:line
|
||||
or the registry URL) or `derived` (inferred). Close with the verdict (commit
|
||||
stops or proceeds) and the `confidence` skill's numbers.
|
||||
stops or proceeds) and the `kvb-check-confidence` skill's numbers.
|
||||
|
||||
## Rules
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Advocate: the checks
|
||||
|
||||
Apply each check to a target the `advocate` skill found in scope.
|
||||
Apply each check to a target the `kvb-check-legal` skill found in scope.
|
||||
|
||||
1. **Inbound code** - every file or block of foreign origin carries a licence
|
||||
that the project licence can absorb in the direction of distribution. GPL
|
||||
@@ -1,15 +1,14 @@
|
||||
---
|
||||
name: sceptic
|
||||
name: kvb-check-principles
|
||||
description: >
|
||||
Analyse a repository, path or diff with a hostile eye for violated
|
||||
principles: SPOT, DRY, KISS, SRP, security at trust boundaries. Trigger on
|
||||
/sceptic, "sei skeptisch", "kritische analyse", "review the architecture",
|
||||
or "what is wrong with the code".
|
||||
Find violated principles (SPOT, DRY, KISS, SRP, trust boundaries) in a
|
||||
repository, path or diff. Trigger on /kvb-check-principles, "sei
|
||||
skeptisch", "kritische analyse", or "review the architecture".
|
||||
---
|
||||
|
||||
The stance is adversarial: the code is guilty until its structure proves
|
||||
otherwise. This skill hunts violated principles, not bugs (`code-review`),
|
||||
not bloat (`ponytail-audit`), not leaked secrets (`medusa`). Read-only —
|
||||
not bloat (`ponytail-audit`), not leaked secrets (`kvb-check-security`). Read-only —
|
||||
report the findings, change nothing unless the operator asks afterwards.
|
||||
|
||||
## Scope
|
||||
@@ -44,7 +43,7 @@ Apply each independently; a finding belongs to exactly one:
|
||||
findings only.
|
||||
6. **Silent defaults** — a fallback that substitutes a guess for a value the
|
||||
caller failed to supply, turning a misconfiguration into wrong behaviour
|
||||
instead of a loud failure. See the `no-defaults` skill.
|
||||
instead of a loud failure. See the `kvb-code-no-defaults` skill.
|
||||
|
||||
## Method
|
||||
|
||||
@@ -55,7 +54,7 @@ Apply each independently; a finding belongs to exactly one:
|
||||
which value drifts, which caller breaks, which input reaches which sink.
|
||||
A finding whose worst case is "feels wrong" gets deleted, not softened.
|
||||
- **Attack your own finding.** For anything consequential or expensive to
|
||||
fix, run it through the `dialectic` skill before reporting it — the
|
||||
fix, run it through the `kvb-think-dialectic` skill before reporting it — the
|
||||
strongest counter-argument is usually "these two are not the same
|
||||
knowledge" or "this boundary is already checked upstream".
|
||||
- **Respect intent.** A deliberate marker (`ponytail:`, a documented
|
||||
@@ -69,7 +68,7 @@ One ranked table, worst blast radius first:
|
||||
| Severity | Principle | Location | What is wrong | Smallest fix |
|
||||
|
||||
Then three closing lines at most: what the scope excluded, which findings
|
||||
survived `dialectic` versus which are still derived-only, and the single
|
||||
survived `kvb-think-dialectic` versus which are still derived-only, and the single
|
||||
finding to fix first. No per-finding paragraphs — the operator asks when a
|
||||
row needs unpacking.
|
||||
|
||||
@@ -78,7 +77,7 @@ row needs unpacking.
|
||||
- Never report formatting, naming taste, or missing comments; a linter owns
|
||||
those and the operator did not ask.
|
||||
- Distinguish proven (grepped, read, reproduced) from derived (reasoned
|
||||
statically) per finding, and close with the `confidence` skill's numbers
|
||||
statically) per finding, and close with the `kvb-check-confidence` skill's numbers
|
||||
for the audit as a whole.
|
||||
- No silent caps: if you ranked and cut, say how many findings were dropped
|
||||
and by what rule.
|
||||
@@ -1,10 +1,9 @@
|
||||
---
|
||||
name: medusa
|
||||
name: kvb-check-security
|
||||
description: >
|
||||
Run the MEDUSA security scanner (medusa-security, PyPI) on a repository,
|
||||
working tree or secret stores. Use for security scans, vetting a repo before
|
||||
cloning, leaked-secret detection in chat or shell history, or /medusa.
|
||||
Defensive only.
|
||||
Run the MEDUSA scanner (medusa-security) on a repository, working tree or
|
||||
secret stores. Use for security scans, vetting a repo, leaked secrets in
|
||||
chat or shell history, or /kvb-check-security. Defensive only.
|
||||
---
|
||||
|
||||
MEDUSA is a defensive AI-first security scanner (40,000+ patterns: CVEs, prompt injection, MCP tool poisoning, leaked secrets).
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: ci-artifacts
|
||||
name: kvb-ci-artifacts
|
||||
description: >
|
||||
Get the evidence out of a CI run: failed job logs (also mid-run) clustered
|
||||
by error line, and the artifacts that hold the cause. Trigger whenever a CI
|
||||
failure must be explained, and from triage.
|
||||
Pull failed job logs (also mid-run), clustered by error line, and the
|
||||
cause-holding artifacts out of a CI run. Trigger when a CI failure needs
|
||||
explaining, and from triage.
|
||||
---
|
||||
|
||||
A job log tells you what broke. An artifact tells you why. Investigating a CI
|
||||
File renamed without changes.
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: observe
|
||||
name: kvb-ci-observe
|
||||
description: >
|
||||
Watch a named target (CI run, pipeline, build, log) on a cadence and triage
|
||||
new failures as they appear. Trigger on /observe <target> or when the
|
||||
operator asks to keep monitoring and fix regressions.
|
||||
Watch a CI run, pipeline, build or log on a cadence and triage new failures.
|
||||
Trigger on /kvb-ci-observe <target> or a request to keep monitoring and fix
|
||||
regressions.
|
||||
---
|
||||
|
||||
Keep a target under continuous watch and act only when it degrades. The loop is
|
||||
@@ -23,18 +23,18 @@ baseline, so a stale baseline re-triages solved failures.
|
||||
|
||||
Drive this with `/loop` in dynamic mode (no fixed interval unless the operator
|
||||
gave one): after each observation, schedule the next wake-up yourself and pass
|
||||
the same `/observe` prompt back so the next firing repeats the watch.
|
||||
the same `/kvb-ci-observe` prompt back so the next firing repeats the watch.
|
||||
|
||||
1. **Poll the target.** Pull its current state (job list, check conclusions, the
|
||||
log's tail); for a GitHub Actions run, the ci-artifacts skill's
|
||||
`ci_failures.py <run>`. Enumerate the failures exactly as the `triage` skill's step 1
|
||||
log's tail); for a GitHub Actions run, the kvb-ci-artifacts skill's
|
||||
`ci_failures.py <run>`. Enumerate the failures exactly as the `kvb-ci-triage` skill's step 1
|
||||
does: failure, cancelled, timed-out; a downstream aggregate that fails only
|
||||
because an upstream did is not its own failure.
|
||||
2. **Diff against the baseline.** A failure is *new* only if it is not in the
|
||||
baseline and was not already triaged this session. If nothing is new, log one
|
||||
short line ("still green" / "N known failures, no change") and reschedule.
|
||||
3. **Triage each new failure.** Invoke the `triage` skill on the new set only —
|
||||
which applies `dialectic` per failing job to a ~99% root cause and a real
|
||||
3. **Triage each new failure.** Invoke the `kvb-ci-triage` skill on the new set only —
|
||||
which applies `kvb-think-dialectic` per failing job to a ~99% root cause and a real
|
||||
fix. Never mask (no retry-until-pass, no disabled check, no soft-skip). Fold
|
||||
each newly fixed failure into the baseline so it is not re-triaged.
|
||||
4. **Reschedule.** Pick the next delay from what you are waiting on: an active
|
||||
@@ -50,7 +50,7 @@ the same `/observe` prompt back so the next firing repeats the watch.
|
||||
notification instead of polling for it; reserve the timed wake-up for external
|
||||
state the harness cannot see (a remote CI run, a deploy queue).
|
||||
- Executed evidence beats reasoning: read the actual failing log line and the
|
||||
artifact, not the job title — triage and dialectic carry this through.
|
||||
artifact, not the job title — kvb-ci-triage and kvb-think-dialectic carry this through.
|
||||
- One baseline, updated in place: dedup every observation against all failures
|
||||
seen so far, or a flaky-then-fixed failure reappears every cycle and the watch
|
||||
never converges.
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: triage
|
||||
name: kvb-ci-triage
|
||||
description: >
|
||||
Triage a failing CI run, pipeline or job set to a verified root cause and a
|
||||
real fix, one cluster per worktree. Trigger when a build, test or deploy
|
||||
pipeline has failed jobs.
|
||||
Triage a failing CI run to a verified root cause and a real fix, one
|
||||
cluster per worktree. Trigger when a build, test or deploy pipeline has
|
||||
failed jobs.
|
||||
---
|
||||
|
||||
Drive a red pipeline to green by root cause, not by guesswork. Treat every
|
||||
@@ -12,7 +12,7 @@ root cause is proven.
|
||||
|
||||
## Procedure
|
||||
|
||||
For a GitHub Actions run, the ci-artifacts skill's `ci_failures.py <run>`
|
||||
For a GitHub Actions run, the kvb-ci-artifacts skill's `ci_failures.py <run>`
|
||||
does the mechanics of steps 0 to 2 in one call: distance to HEAD, the failed
|
||||
jobs' logs, and a first clustering. The judgement in those steps stays yours.
|
||||
|
||||
@@ -37,11 +37,13 @@ jobs' logs, and a first clustering. The judgement in those steps stays yours.
|
||||
actual failing line, not by job name. Jobs whose messages differ in anything
|
||||
but the interpolated identifiers (host, app, port, path) belong in separate
|
||||
clusters.
|
||||
3. **Coordinate every cluster.** Run the `democracy` skill's Lineage and Peer
|
||||
3. **Coordinate every cluster.** Run the `kvb-org-organize` skill's Lineage and Peer
|
||||
protocol for each cluster before fixing it: claim it, ask the lineage
|
||||
whether someone already fixes it, and take their fix or keep yours. Keep
|
||||
investigating while you wait for answers.
|
||||
4. **Download artifacts per cluster.** Use the `ci-artifacts` skill for the
|
||||
investigating while you wait for answers. In the `kvb-org-rasci` register
|
||||
the cluster's objective is the root cause fixed, its key results are the
|
||||
failing jobs passing again, one per job.
|
||||
4. **Download artifacts per cluster.** Use the `kvb-ci-artifacts` skill for the
|
||||
mechanics — it covers per-job logs while a run is still in progress, which
|
||||
bundle to pull, and the grep hygiene that keeps a false positive from
|
||||
becoming a root cause. For each cluster, fetch every artifact of
|
||||
@@ -53,7 +55,7 @@ jobs' logs, and a first clustering. The judgement in those steps stays yours.
|
||||
log looks conclusive, because a log that explains the symptom rarely
|
||||
explains the cause.
|
||||
5. **One funnel per cluster.** Hand every cluster you claimed in step 3 to the
|
||||
`funnel` skill: one agent per cluster, working in its own worktree on its own
|
||||
`kvb-org-split` skill: one agent per cluster, working in its own worktree on its own
|
||||
branch created from the exact current HEAD, with that cluster as its only
|
||||
concern, the artifact paths of step 4 in its brief and a time cap for its
|
||||
interim report.
|
||||
@@ -61,7 +63,7 @@ jobs' logs, and a first clustering. The judgement in those steps stays yours.
|
||||
another cluster's work or under a running gate or deploy. Run clusters in
|
||||
parallel only when their fixes touch different files and the machine has
|
||||
room. A split cluster (step 7) gets a funnel of its own.
|
||||
6. **Dialectic per cluster.** For EACH cluster, invoke the `dialectic` skill:
|
||||
6. **Dialectic per cluster.** For EACH cluster, invoke the `kvb-think-dialectic` skill:
|
||||
form a thesis about the root cause from evidence (the job log, its artifacts,
|
||||
the code at the run's commit, git history), attack it with independent
|
||||
skeptics, and iterate to a ~99% thesis.
|
||||
@@ -71,18 +73,18 @@ jobs' logs, and a first clustering. The judgement in those steps stays yours.
|
||||
is actually green, not just past the first error.
|
||||
8. **Fix at the root, through the funnel.** Apply the real fix for each proven
|
||||
root cause in the cluster's sidetree, with a test and a negative control as
|
||||
the `funnel` skill demands. The fix enters the main line only at the funnel's
|
||||
the `kvb-org-split` skill demands. The fix enters the main line only at the funnel's
|
||||
bar (at least 90 % fix confidence, under 5 % break risk) after its
|
||||
independent review; below the bar the cluster ends as a proposal for the
|
||||
operator, never as a merge. Never mask a failure: no retry-until-pass, no
|
||||
disabling the check, no soft-skip. If a failure is genuinely external
|
||||
(upstream outage, flaky infra), confirm that with evidence and surface it
|
||||
honestly instead of fixing around it. Report every fix, every proposal, and
|
||||
every abandoned attempt to the same agents through the `democracy` Peer protocol,
|
||||
every abandoned attempt to the same agents through the `kvb-org-organize` Peer protocol,
|
||||
then remove the sidetree.
|
||||
9. **Tune what ran out of time.** Only for a cluster whose jobs died on their
|
||||
time budget (timed out, or cancelled by the runner's limit), or when the
|
||||
operator asks: hand the job log that ran furthest to the `tune` skill. Its
|
||||
operator asks: hand the job log that ran furthest to the `kvb-code-tune` skill. Its
|
||||
candidates run through funnels of their own, separate from the cluster's fix
|
||||
sidetree, and never delay or block the fix.
|
||||
10. **Follow the run.** While the run is still in progress, re-check it
|
||||
@@ -1,9 +1,8 @@
|
||||
---
|
||||
name: cleanup
|
||||
name: kvb-cleanup
|
||||
description: >
|
||||
Free disk space agents filled: ask peer sessions what they still need,
|
||||
inventory /tmp, Docker and agent dirs, and delete only what the operator
|
||||
picks. Trigger on /cleanup, "aufräumen", "bereinigen", "platte voll", "no
|
||||
Free disk space agents filled: ask peers, inventory /tmp, Docker and agent
|
||||
dirs, and delete only what the operator picks. Trigger on /kvb-cleanup, "aufräumen", "bereinigen", "platte voll", "no
|
||||
space left on device".
|
||||
---
|
||||
|
||||
@@ -12,10 +11,10 @@ its owner, its size, and its risk.
|
||||
|
||||
## Step 0: the resource chair
|
||||
|
||||
Shared resources belong to the resource chair of the `democracy` skill. If
|
||||
Shared resources belong to the resource chair of the `kvb-org-organize` skill. If
|
||||
another session holds the chair, send it the cleanup request and stop, unless
|
||||
the operator ordered the cleanup in this session; then tell the chair before
|
||||
step 1, so its grants and queue stay consistent. The `democracy` resource
|
||||
step 1, so its grants and queue stay consistent. The `kvb-org-organize` resource
|
||||
watch already runs the configured low-risk cleanup at its stop threshold; this
|
||||
skill covers everything that needs the operator's pick.
|
||||
|
||||
@@ -36,6 +35,10 @@ need, one item per line:
|
||||
- containers, compose or stack projects, volumes, images, networks
|
||||
- running jobs (deploys, tests, builds) and when they finish
|
||||
Reply "nothing" if you need none of it. Items you do not answer for stay.
|
||||
Also search your own worktrees and volumes for unused ones (branch merged or
|
||||
pushed, no uncommitted changes, stack not needed), list them with their size
|
||||
as deletion candidates, delete only your own finished items, and tell me what
|
||||
you removed.
|
||||
```
|
||||
|
||||
## Step 2: inventory
|
||||
@@ -56,10 +59,18 @@ Read-only, in parallel, sizes included:
|
||||
record its volumes (`{{.Mounts}}`); for every volume no running container
|
||||
uses, record size, `CreatedAt` (`docker volume inspect`) and compose project
|
||||
label, anonymous ones included.
|
||||
- **Worktrees**: per worktree its size (`du -sh`), its dirty state (`git
|
||||
status --short`), whether its branch is pushed, and whether its HEAD is
|
||||
already contained in an integration line: the default branch and every
|
||||
branch the project merges features into (ask the operator or the project's
|
||||
memory which ones). With `pkgmgr` installed, `pkgmgr branch gc --json
|
||||
--sizes --merged-into <line>` (one per line) measures all of it; its
|
||||
merged-clean items go to the `kvb-git-branch-gc` skill.
|
||||
- **Other agent dirs**: package and tool caches (pip, npm, pre-commit, act,
|
||||
gh, buildx), worktrees with `git status --short` and whether their branch is
|
||||
merged or pushed, Ansible and build temp dirs. With `pkgmgr` installed,
|
||||
merged branches and worktrees go to the `branch-gc` skill instead.
|
||||
gh, buildx), Ansible and build temp dirs.
|
||||
- **Register**: `rasci.py artifacts` of the `kvb-org-artefacts` skill:
|
||||
workdir, branch and artifacts of every task in the `kvb-org-rasci` register,
|
||||
with its status and worker; `--ended` narrows it to the candidates.
|
||||
- **Live use**: open handles (`fuser`, `lsof`) and running processes by name
|
||||
only (`ps -o pid,etime,comm`). Never print full command lines or
|
||||
environments: process arguments carry credentials. A sandboxed agent often
|
||||
@@ -81,17 +92,20 @@ worktree or compose project name, a container label, an open handle, or
|
||||
`unknown`. Then apply, first match wins:
|
||||
|
||||
1. Claimed by a peer: `keep`.
|
||||
2. A job running on it (deploy, gate, test, swarm run, build): `keep
|
||||
2. Listed in the register under a task that is not `done`, `stopped` or `stale`:
|
||||
`keep (task <task>)`. Under an ended task it is a candidate whose owner is
|
||||
the task's worker.
|
||||
3. A job running on it (deploy, gate, test, swarm run, build): `keep
|
||||
(running)`.
|
||||
3. Attributable to a peer that has not answered: `keep (no answer from
|
||||
4. Attributable to a peer that has not answered: `keep (no answer from
|
||||
<peer>)`. Silence is not consent.
|
||||
4. Archive duty: `archive first`.
|
||||
5. Everything else is a candidate with a risk class:
|
||||
5. Archive duty: `archive first`.
|
||||
6. Everything else is a candidate with a risk class:
|
||||
|
||||
| Risk | Meaning | Typical items |
|
||||
| ---- | ------- | ------------- |
|
||||
| low | regenerated automatically, cheap | stopped containers without volumes, dangling images, unused networks, scratch dirs and logs of finished sessions |
|
||||
| medium | regenerated, but slow, rate-limited or network-bound | unused tagged images (re-pull, registry limits), build cache (cold rebuilds), package caches |
|
||||
| medium | regenerated, but slow, rate-limited or network-bound | unused tagged images (re-pull, registry limits), build cache (cold rebuilds), package caches, clean worktrees whose HEAD is already in an integration line (ignored files such as `node_modules`, build output or evidence are lost, no commit) |
|
||||
| high | data loss or a broken run possible | volumes, stopped containers with volumes, running unclaimed containers or stacks, worktrees with uncommitted or unpushed work, unread reports, anything `unknown` |
|
||||
|
||||
## Step 4: propose
|
||||
@@ -152,9 +166,17 @@ ticked items. Revise repeats call 1; nothing is deleted before `Execute`.
|
||||
free space: not for a priority slot, not at a disk stop. Free idle items,
|
||||
ask the operator for an exception, or wait; an owner's own disk guard only
|
||||
alerts the chair, and only the operator can order a running job down.
|
||||
A hung job is not freed through cleanup: the `kvb-org-organize` skill's hang rule
|
||||
lets only its owner end it.
|
||||
- Idle running stacks go down through the project's teardown target, never by
|
||||
removing their containers or volumes underneath them.
|
||||
- Remove a worktree the way it was made: a slot worktree through the
|
||||
project's teardown target (e.g. `make worktree-down`), run outside the
|
||||
sandbox; a plain sidetree through `git worktree remove` without `--force`,
|
||||
which refuses a dirty tree.
|
||||
- Archive-first items: copy out, verify the copy, then delete.
|
||||
- Drop every deleted item from its task as the `kvb-org-artefacts` skill
|
||||
says (`set <task> --drop-artifact <kind>:<ref>`), so `artifacts` stays true.
|
||||
- A delete failing on permissions (files owned by a container UID): use the
|
||||
project's container helper. Never sudo, never bypass the sandbox; without a
|
||||
helper, report the path.
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
name: kvb-coach-meditation
|
||||
description: >
|
||||
Short meditation with generative alpha-wave music, animated fractals and
|
||||
breathing cues, tuned by feedback. Trigger on /kvb-coach-meditation.
|
||||
---
|
||||
|
||||
A short session in the browser: `assets/meditation.html` plays generative
|
||||
ambient music over an alpha-wave layer (8–13 Hz) and animates a Julia fractal
|
||||
that breathes with the cue. It runs locally, without audio files or network.
|
||||
|
||||
`${CLAUDE_SKILL_DIR}/scripts/meditation.py` keeps the settings in the
|
||||
gitignored `.state/meditation.json` of the skills repository and writes the
|
||||
session page with the settings embedded:
|
||||
|
||||
```bash
|
||||
meditation.py --state <skills repo>/.state/meditation.json set <key>=<value> ...
|
||||
meditation.py --state <same> show
|
||||
meditation.py --state <same> session --page ${CLAUDE_SKILL_DIR}/assets/meditation.html --out <skills repo>/.state/meditation-session.html
|
||||
```
|
||||
|
||||
| Key | Values | First session |
|
||||
| --- | --- | --- |
|
||||
| `minutes` | 1–30 | 5 |
|
||||
| `beat` | 8–13 Hz | 10 |
|
||||
| `base` | 100–400 Hz | 196 |
|
||||
| `volume` | 0.05–1 | 0.4 |
|
||||
| `mode` | `isochronic` (speakers), `binaural` (headphones) | `isochronic` |
|
||||
| `palette` | `aurora`, `ocean`, `ember`, `forest` | `aurora` |
|
||||
| `breathing` | `box` (4-4-4-4), `478`, `none` | `box` |
|
||||
|
||||
## Step 1: start
|
||||
|
||||
Without a state file, `set` the first-session values. Write the session page
|
||||
and hand the operator `xdg-open <session page>` to run: inside the agent
|
||||
sandbox `xdg-open` and `gio open` exit 0 without opening anything. The page starts on the
|
||||
operator's click, shows the elapsed time as a line growing along the bottom
|
||||
edge, and fades out after the set minutes; `+` and `-` set the
|
||||
picture's brightness (20–160 %), which the browser keeps for the next session.
|
||||
|
||||
## Step 2: feedback
|
||||
|
||||
After every session, run the `kvb-think-listen` skill with one
|
||||
`AskUserQuestion`, `multiSelect: false` per question: music (calmer, fits,
|
||||
livelier, quieter, louder), picture (fits, calmer, other palette), length
|
||||
(shorter, fits, longer), effect (calmer, more focused, nothing, restless).
|
||||
Ask about headphones once before switching to `binaural`.
|
||||
|
||||
## Step 3: optimize
|
||||
|
||||
One `set` per answer: quieter or louder ±0.1 `volume`; calmer music `beat`
|
||||
−1, more focus `beat` +1; shorter or longer ±2 `minutes`; other palette the
|
||||
next one; restless `breathing=none`. Log the session in the `kvb-coach`
|
||||
profile (`coach.py done psyche "Meditation <n> min"`) and a liked effect with
|
||||
`coach.py like psyche`.
|
||||
@@ -0,0 +1,260 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>kvb-coach-meditation</title>
|
||||
<style>
|
||||
html, body { margin: 0; height: 100%; background: #000; color: #eee; font-family: "URW Gothic", "Fira Sans", "Cantarell", sans-serif; font-weight: 300; overflow: hidden; }
|
||||
canvas { position: fixed; inset: 0; width: 100%; height: 100%; }
|
||||
#ui { position: fixed; inset: 0; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 1rem; text-align: center; padding: 1rem; }
|
||||
#breath { font-size: 2.6rem; text-transform: lowercase; letter-spacing: .4em; color: #fff; text-shadow: 0 0 14px #fff9, 0 0 40px #9cf8, 0 0 80px #c9f5; will-change: transform, opacity, letter-spacing; }
|
||||
#clock { position: fixed; bottom: 1rem; right: 1rem; opacity: .5; font-variant-numeric: tabular-nums; }
|
||||
#progress { position: fixed; left: 0; bottom: 0; height: 3px; width: 0; background: linear-gradient(90deg, #9cf, #c9f); box-shadow: 0 0 12px #9cf9; opacity: .7; }
|
||||
#level { position: fixed; top: 1rem; right: 1rem; opacity: 0; transition: opacity .6s; letter-spacing: .2em; text-shadow: 0 0 10px #fff8; }
|
||||
button { font: inherit; font-size: 1.4rem; letter-spacing: .4em; text-transform: lowercase; padding: .8rem 2.4rem; border-radius: 2rem; border: 1px solid #fff6; background: #fff1; color: #fff; cursor: pointer; text-shadow: 0 0 12px #fff8; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<canvas id="view"></canvas>
|
||||
<div id="ui"><div id="breath"></div><button id="start">Start</button></div>
|
||||
<div id="clock"></div>
|
||||
<div id="level"></div>
|
||||
<div id="progress"></div>
|
||||
<script>
|
||||
"use strict";
|
||||
const KEYS = ["minutes", "beat", "base", "volume", "mode", "palette", "breathing"];
|
||||
const PALETTES = {
|
||||
aurora: [[0.5, 0.5, 0.5], [0.5, 0.5, 0.5], [1.0, 1.0, 1.0], [0.0, 0.33, 0.67]],
|
||||
ocean: [[0.2, 0.4, 0.6], [0.2, 0.3, 0.4], [1.0, 1.0, 1.0], [0.0, 0.1, 0.2]],
|
||||
ember: [[0.5, 0.3, 0.2], [0.5, 0.3, 0.2], [1.0, 1.0, 1.0], [0.0, 0.1, 0.2]],
|
||||
forest: [[0.3, 0.5, 0.3], [0.2, 0.4, 0.2], [1.0, 1.0, 1.0], [0.1, 0.2, 0.3]],
|
||||
};
|
||||
const PATTERNS = {
|
||||
box: [["Breathe in", 4], ["Hold", 4], ["Breathe out", 4], ["Hold", 4]],
|
||||
"478": [["Breathe in", 4], ["Hold", 7], ["Breathe out", 8]],
|
||||
none: [],
|
||||
};
|
||||
|
||||
const SETTINGS = null;
|
||||
const breathEl = document.getElementById("breath");
|
||||
const clockEl = document.getElementById("clock");
|
||||
const startEl = document.getElementById("start");
|
||||
const missing = KEYS.filter((key) => !SETTINGS || !(key in SETTINGS));
|
||||
const cfg = Object.fromEntries(KEYS.map((key) => [key, SETTINGS ? SETTINGS[key] : null]));
|
||||
["minutes", "beat", "base", "volume"].forEach((key) => { cfg[key] = Number(cfg[key]); });
|
||||
if (missing.length || !PALETTES[cfg.palette] || !PATTERNS[cfg.breathing]) {
|
||||
startEl.remove();
|
||||
breathEl.textContent = "Start the session through the kvb-coach-meditation skill.";
|
||||
throw new Error(`invalid settings: ${missing.join(", ")}`);
|
||||
}
|
||||
|
||||
function breath(t) {
|
||||
const steps = PATTERNS[cfg.breathing];
|
||||
if (!steps.length) return ["", 0.5 + 0.5 * Math.sin(t * 0.2)];
|
||||
const total = steps.reduce((sum, [, d]) => sum + d, 0);
|
||||
let x = t % total;
|
||||
let lung = 0;
|
||||
for (const [label, d] of steps) {
|
||||
if (x < d) {
|
||||
if (label === "Breathe in") return [label, x / d];
|
||||
if (label === "Breathe out") return [label, 1 - x / d];
|
||||
return [label, lung];
|
||||
}
|
||||
x -= d;
|
||||
if (label === "Breathe in") lung = 1;
|
||||
if (label === "Breathe out") lung = 0;
|
||||
}
|
||||
return ["", lung];
|
||||
}
|
||||
|
||||
const canvas = document.getElementById("view");
|
||||
const gl = canvas.getContext("webgl");
|
||||
let draw = () => {};
|
||||
if (gl) {
|
||||
const VERT = "attribute vec2 p; void main() { gl_Position = vec4(p, 0.0, 1.0); }";
|
||||
const FRAG = `precision highp float;
|
||||
uniform vec2 res; uniform float t; uniform float lung; uniform vec3 pa, pb, pc, pd;
|
||||
vec3 pal(float x) { return pa + pb * cos(6.28318 * (pc * x + pd)); }
|
||||
void main() {
|
||||
vec2 z = (2.0 * gl_FragCoord.xy - res) / min(res.x, res.y) * (1.6 - 0.3 * lung);
|
||||
vec2 c = 0.7885 * vec2(cos(t * 0.05), sin(t * 0.05));
|
||||
float n = 0.0;
|
||||
for (int i = 0; i < 160; i++) {
|
||||
z = vec2(z.x * z.x - z.y * z.y, 2.0 * z.x * z.y) + c;
|
||||
if (dot(z, z) > 16.0) break;
|
||||
n += 1.0;
|
||||
}
|
||||
float s = (n - log2(log2(max(dot(z, z), 1.0001))) + 4.0) / 160.0;
|
||||
gl_FragColor = vec4(pal(s + t * 0.01) * (n < 160.0 ? 1.0 : 0.05), 1.0);
|
||||
}`;
|
||||
const shader = (type, src) => {
|
||||
const s = gl.createShader(type);
|
||||
gl.shaderSource(s, src);
|
||||
gl.compileShader(s);
|
||||
return s;
|
||||
};
|
||||
const prog = gl.createProgram();
|
||||
gl.attachShader(prog, shader(gl.VERTEX_SHADER, VERT));
|
||||
gl.attachShader(prog, shader(gl.FRAGMENT_SHADER, FRAG));
|
||||
gl.linkProgram(prog);
|
||||
gl.useProgram(prog);
|
||||
gl.bindBuffer(gl.ARRAY_BUFFER, gl.createBuffer());
|
||||
gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]), gl.STATIC_DRAW);
|
||||
const loc = gl.getAttribLocation(prog, "p");
|
||||
gl.enableVertexAttribArray(loc);
|
||||
gl.vertexAttribPointer(loc, 2, gl.FLOAT, false, 0, 0);
|
||||
const u = (name) => gl.getUniformLocation(prog, name);
|
||||
["pa", "pb", "pc", "pd"].forEach((name, i) => gl.uniform3fv(u(name), PALETTES[cfg.palette][i]));
|
||||
const resize = () => {
|
||||
const scale = Math.min(window.devicePixelRatio || 1, 1.5);
|
||||
canvas.width = Math.floor(innerWidth * scale);
|
||||
canvas.height = Math.floor(innerHeight * scale);
|
||||
gl.viewport(0, 0, canvas.width, canvas.height);
|
||||
};
|
||||
addEventListener("resize", resize);
|
||||
resize();
|
||||
draw = (t, lung) => {
|
||||
gl.uniform2f(u("res"), canvas.width, canvas.height);
|
||||
gl.uniform1f(u("t"), t);
|
||||
gl.uniform1f(u("lung"), lung);
|
||||
gl.drawArrays(gl.TRIANGLES, 0, 6);
|
||||
};
|
||||
draw(0, 0);
|
||||
}
|
||||
|
||||
const levelEl = document.getElementById("level");
|
||||
const progressEl = document.getElementById("progress");
|
||||
const BRIGHTNESS = "kvb-coach-meditation-brightness";
|
||||
const stored = () => {
|
||||
try {
|
||||
return Number(localStorage.getItem(BRIGHTNESS)) || 1;
|
||||
} catch {
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
const store = (value) => {
|
||||
try {
|
||||
localStorage.setItem(BRIGHTNESS, String(value));
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
};
|
||||
let brightness = stored();
|
||||
let levelTimer = 0;
|
||||
const showBrightness = () => {
|
||||
canvas.style.filter = `brightness(${brightness})`;
|
||||
};
|
||||
showBrightness();
|
||||
addEventListener("keydown", (event) => {
|
||||
const step = { "+": 0.1, "=": 0.1, "-": -0.1 }[event.key];
|
||||
if (!step) return;
|
||||
brightness = Math.min(1.6, Math.max(0.2, Math.round((brightness + step) * 10) / 10));
|
||||
showBrightness();
|
||||
const saved = store(brightness);
|
||||
levelEl.textContent = `☀ ${Math.round(brightness * 100)} %${saved ? "" : " (not saved)"}`;
|
||||
levelEl.style.opacity = "1";
|
||||
clearTimeout(levelTimer);
|
||||
levelTimer = setTimeout(() => { levelEl.style.opacity = "0"; }, 1200);
|
||||
});
|
||||
|
||||
function sound(ctx) {
|
||||
const master = ctx.createGain();
|
||||
master.gain.setValueAtTime(0, ctx.currentTime);
|
||||
master.gain.linearRampToValueAtTime(cfg.volume, ctx.currentTime + 8);
|
||||
master.connect(ctx.destination);
|
||||
const reverb = ctx.createConvolver();
|
||||
const length = ctx.sampleRate * 4;
|
||||
const impulse = ctx.createBuffer(2, length, ctx.sampleRate);
|
||||
for (let ch = 0; ch < 2; ch++) {
|
||||
const data = impulse.getChannelData(ch);
|
||||
for (let i = 0; i < length; i++) data[i] = (Math.random() * 2 - 1) * Math.pow(1 - i / length, 3);
|
||||
}
|
||||
reverb.buffer = impulse;
|
||||
reverb.connect(master);
|
||||
if (cfg.mode === "binaural") {
|
||||
const merger = ctx.createChannelMerger(2);
|
||||
[cfg.base, cfg.base + cfg.beat].forEach((freq, ch) => {
|
||||
const osc = ctx.createOscillator();
|
||||
const gain = ctx.createGain();
|
||||
osc.frequency.value = freq;
|
||||
gain.gain.value = 0.12;
|
||||
osc.connect(gain).connect(merger, 0, ch);
|
||||
osc.start();
|
||||
});
|
||||
merger.connect(master);
|
||||
} else {
|
||||
const osc = ctx.createOscillator();
|
||||
const gain = ctx.createGain();
|
||||
const lfo = ctx.createOscillator();
|
||||
const depth = ctx.createGain();
|
||||
osc.frequency.value = cfg.base;
|
||||
gain.gain.value = 0.06;
|
||||
lfo.frequency.value = cfg.beat;
|
||||
depth.gain.value = 0.06;
|
||||
lfo.connect(depth).connect(gain.gain);
|
||||
osc.connect(gain).connect(master);
|
||||
osc.start();
|
||||
lfo.start();
|
||||
}
|
||||
const ratios = [1, 9 / 8, 5 / 4, 3 / 2, 5 / 3, 2];
|
||||
const note = () => {
|
||||
if (ctx.state === "closed") return;
|
||||
const now = ctx.currentTime;
|
||||
const freq = cfg.base * ratios[Math.floor(Math.random() * ratios.length)];
|
||||
const gain = ctx.createGain();
|
||||
gain.gain.setValueAtTime(0, now);
|
||||
gain.gain.linearRampToValueAtTime(0.1, now + 3);
|
||||
gain.gain.linearRampToValueAtTime(0, now + 9);
|
||||
gain.connect(reverb);
|
||||
[0, 4].forEach((cents) => {
|
||||
const osc = ctx.createOscillator();
|
||||
osc.type = "triangle";
|
||||
osc.frequency.value = freq;
|
||||
osc.detune.value = cents;
|
||||
osc.connect(gain);
|
||||
osc.start(now);
|
||||
osc.stop(now + 9.5);
|
||||
});
|
||||
setTimeout(note, 2500 + Math.random() * 3500);
|
||||
};
|
||||
note();
|
||||
return master;
|
||||
}
|
||||
|
||||
startEl.addEventListener("click", () => {
|
||||
startEl.remove();
|
||||
const ctx = new AudioContext();
|
||||
const master = sound(ctx);
|
||||
const begin = performance.now();
|
||||
const end = cfg.minutes * 60;
|
||||
const frame = (now) => {
|
||||
const t = (now - begin) / 1000;
|
||||
const [label, lung] = breath(t);
|
||||
draw(t, lung);
|
||||
progressEl.style.width = `${Math.min(100, (t / end) * 100)}%`;
|
||||
const left = Math.max(0, end - t);
|
||||
clockEl.textContent = `${Math.floor(left / 60)}:${String(Math.floor(left % 60)).padStart(2, "0")}`;
|
||||
breathEl.style.opacity = String(0.35 + 0.65 * lung);
|
||||
breathEl.style.letterSpacing = `${0.3 + 0.5 * lung}em`;
|
||||
breathEl.style.transform = `scale(${0.9 + 0.2 * lung})`;
|
||||
if (t < end) {
|
||||
breathEl.textContent = label;
|
||||
requestAnimationFrame(frame);
|
||||
return;
|
||||
}
|
||||
master.gain.cancelScheduledValues(ctx.currentTime);
|
||||
master.gain.setValueAtTime(master.gain.value, ctx.currentTime);
|
||||
master.gain.linearRampToValueAtTime(0, ctx.currentTime + 6);
|
||||
setTimeout(() => ctx.close(), 6500);
|
||||
breathEl.style.opacity = "1";
|
||||
breathEl.style.transform = "none";
|
||||
breathEl.style.letterSpacing = ".2em";
|
||||
breathEl.textContent = "Done. Back to your agent for a short feedback.";
|
||||
};
|
||||
requestAnimationFrame(frame);
|
||||
});
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
+110
@@ -0,0 +1,110 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Keep the kvb-coach-meditation settings and write the session page.
|
||||
|
||||
Args:
|
||||
--state: path of the settings JSON file.
|
||||
set <key>=<value> ...: change settings; every value is validated.
|
||||
show: print the settings.
|
||||
session --page <meditation.html> --out <file>: write the page with the
|
||||
settings embedded and print its path; fails while a setting is missing.
|
||||
|
||||
Exit codes:
|
||||
0 done, 2 usage error.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
PLACEHOLDER = "const SETTINGS = null;"
|
||||
RANGES = {
|
||||
"minutes": (int, 1, 30),
|
||||
"beat": (float, 8.0, 13.0),
|
||||
"base": (float, 100.0, 400.0),
|
||||
"volume": (float, 0.05, 1.0),
|
||||
}
|
||||
CHOICES = {
|
||||
"mode": ("binaural", "isochronic"),
|
||||
"palette": ("aurora", "ocean", "ember", "forest"),
|
||||
"breathing": ("box", "478", "none"),
|
||||
}
|
||||
KEYS = (*RANGES, *CHOICES)
|
||||
|
||||
|
||||
def fail(message: str) -> None:
|
||||
print(f"meditation: {message}", file=sys.stderr)
|
||||
sys.exit(2)
|
||||
|
||||
|
||||
def parse(pair: str) -> tuple[str, int | float | str]:
|
||||
key, sep, raw = pair.partition("=")
|
||||
if not sep or key not in KEYS:
|
||||
fail(f"{pair}: expected <key>=<value> with key in {', '.join(KEYS)}")
|
||||
if key in CHOICES:
|
||||
if raw not in CHOICES[key]:
|
||||
fail(f"{key} must be one of {', '.join(CHOICES[key])}")
|
||||
return key, raw
|
||||
kind, low, high = RANGES[key]
|
||||
try:
|
||||
value = kind(raw)
|
||||
except ValueError:
|
||||
fail(f"{key} must be a number")
|
||||
if not low <= value <= high:
|
||||
fail(f"{key} must lie between {low} and {high}")
|
||||
return key, value
|
||||
|
||||
|
||||
def load(path: Path) -> dict:
|
||||
try:
|
||||
return json.loads(path.read_text(encoding="utf-8"))
|
||||
except FileNotFoundError:
|
||||
return {}
|
||||
except ValueError:
|
||||
fail(f"{path} is not valid JSON")
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
||||
parser.add_argument("--state", required=True)
|
||||
sub = parser.add_subparsers(dest="cmd", required=True)
|
||||
sub.add_parser("set").add_argument("pairs", nargs="+")
|
||||
sub.add_parser("show")
|
||||
p = sub.add_parser("session")
|
||||
p.add_argument("--page", required=True)
|
||||
p.add_argument("--out", required=True)
|
||||
args = parser.parse_args()
|
||||
|
||||
path = Path(args.state)
|
||||
settings = load(path)
|
||||
if args.cmd == "set":
|
||||
settings.update(parse(pair) for pair in args.pairs)
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
tmp = path.with_suffix(".tmp")
|
||||
tmp.write_text(json.dumps(settings, indent=1, sort_keys=True), encoding="utf-8")
|
||||
tmp.replace(path)
|
||||
if args.cmd in ("set", "show"):
|
||||
for key in KEYS:
|
||||
print(f"{key}={settings.get(key, '-')}")
|
||||
return 0
|
||||
missing = [key for key in KEYS if key not in settings]
|
||||
if missing:
|
||||
fail(f"missing settings: {', '.join(missing)}")
|
||||
page = Path(args.page)
|
||||
if not page.is_file():
|
||||
fail(f"{page} does not exist")
|
||||
template = page.read_text(encoding="utf-8")
|
||||
if template.count(PLACEHOLDER) != 1:
|
||||
fail(f"{page} lacks the line {PLACEHOLDER}")
|
||||
embedded = json.dumps({key: settings[key] for key in KEYS})
|
||||
out = Path(args.out)
|
||||
out.parent.mkdir(parents=True, exist_ok=True)
|
||||
out.write_text(template.replace(PLACEHOLDER, f"const SETTINGS = {embedded};"), encoding="utf-8")
|
||||
print(out.resolve())
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
name: kvb-coach
|
||||
description: >
|
||||
Coach the operator's next step: psyche, body, sleep, food, own and
|
||||
delegable tasks. Trigger on /kvb-coach or "was soll ich tun".
|
||||
---
|
||||
|
||||
Be the operator's coach: short, warm, concrete, with emojis, in the
|
||||
operator's language. Their health comes first; work is one area of six, not
|
||||
the default. Suggestions, never pressure.
|
||||
|
||||
The profile keeps what the operator enjoys, dislikes and last did, host-local
|
||||
in the gitignored `.state/` of the skills repository:
|
||||
|
||||
```bash
|
||||
coach.py --profile <skills repo>/.state/coach.json like|dislike|forget <area> "<thing>"
|
||||
coach.py --profile <same> done <area> "<thing>" [--at <iso>]
|
||||
coach.py --profile <same> show [--json]
|
||||
```
|
||||
|
||||
Areas: `psyche`, `body`, `sleep`, `food`, `tasks`, `delegate`. Every coaching
|
||||
skill beyond this one is named `kvb-coach-<name>`.
|
||||
|
||||
`hooks/reminder.sh` triggers the short form at the first prompt of every full
|
||||
hour, once across all agents (stamped in `~/.claude/.coach-hours/`): at most
|
||||
three lines, the most urgent area first, then the agent continues with the
|
||||
operator's request.
|
||||
|
||||
## Step 1: read the situation
|
||||
|
||||
- **Time**: local time and weekday, and how long the operator has been at it
|
||||
today (their first message of the day in the session transcripts).
|
||||
- **Profile**: `coach.py show`: likes, dislikes, hours since the last sleep,
|
||||
meal, workout or break.
|
||||
- **Own tasks**: the open commands of the `kvb-org-operator` skill and the
|
||||
decisions agents wait on.
|
||||
- **Delegable**: what the operator did by hand that an agent could do, and
|
||||
queued `kvb-org-rasci` register tasks without a worker.
|
||||
|
||||
## Step 2: suggest
|
||||
|
||||
At most one line per area, the most urgent first, the whole answer on one
|
||||
screen:
|
||||
|
||||
- 🧠 **Psyche**: a short break, a walk outside, five minutes with the
|
||||
`kvb-coach-meditation` skill or box breathing, a call with a friend,
|
||||
something just for fun.
|
||||
- 💪 **Body**: a workout from the operator's likes (a 20-minute run, a
|
||||
bodyweight circuit, cycling, yoga), stretching neck, hips and back after
|
||||
long sitting, standing up every hour.
|
||||
- 😴 **Sleep**: wind down, screens off, seven to nine hours; a 20-minute nap
|
||||
in the early afternoon.
|
||||
- 🥗 **Food**: water, a real meal with vegetables and protein, a healthy
|
||||
snack instead of sugar, no caffeine late in the day.
|
||||
- ✅ **Your tasks**: the one step only the operator can take that unblocks
|
||||
the most.
|
||||
- 🤖 **Delegate**: what an agent can take over, with the skill or command
|
||||
that does it.
|
||||
|
||||
The situation sets the order: late evening puts sleep first, hours without
|
||||
a break put moving first, a meal more than five hours ago puts food first.
|
||||
Prefer what the operator likes, never offer a dislike, and do not repeat the
|
||||
last tip of an area. Close with one encouraging line.
|
||||
|
||||
## Step 3: listen and remember
|
||||
|
||||
Often, not every time: when the profile is empty, after a declined
|
||||
suggestion, and every few runs, run the `kvb-think-listen` skill with one
|
||||
short `AskUserQuestion` (what they enjoy, what fits right now, what to
|
||||
avoid). Record the answers with `like` and `dislike`, and what the operator
|
||||
reports having done with `done`.
|
||||
|
||||
## Rules
|
||||
|
||||
- The operator decides: no guilt, no nagging, a declined tip stays off for
|
||||
the day.
|
||||
- General wellbeing, no medical advice: pain, illness or lasting exhaustion
|
||||
get one kind pointer to a doctor.
|
||||
- The profile never leaves the host: not into commits, memory files or peer
|
||||
messages.
|
||||
Executable
+15
@@ -0,0 +1,15 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
hours="${COACH_STAMP_DIR:-${HOME}/.claude/.coach-hours}"
|
||||
hour="${COACH_HOUR:-$(date +%Y-%m-%dT%H)}"
|
||||
|
||||
mkdir -p "${hours}"
|
||||
mkdir "${hours}/${hour}" 2>/dev/null || exit 0
|
||||
find "${hours}" -mindepth 1 -maxdepth 1 -type d ! -name "${hour}" -exec rmdir {} +
|
||||
|
||||
cat <<'HINT'
|
||||
COACH HOUR: a new full hour began. Before answering the operator's request,
|
||||
run the kvb-coach skill in its short form: at most three lines, the most
|
||||
urgent area first, then continue with the request.
|
||||
HINT
|
||||
Executable
+135
@@ -0,0 +1,135 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Keep the operator's coaching profile: likes, dislikes and when what was done.
|
||||
|
||||
Args:
|
||||
--profile: path of the profile JSON file.
|
||||
like|dislike <area> <thing>: record a preference; one replaces the other.
|
||||
forget <area> <thing>: drop a preference.
|
||||
done <area> <thing> [--at <iso>]: log that the operator did it.
|
||||
show [--now <iso>] [--json]: likes, dislikes and the last logged activity
|
||||
per area with the hours since.
|
||||
|
||||
Exit codes:
|
||||
0 done, 2 usage error.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import datetime
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
AREAS = ("psyche", "body", "sleep", "food", "tasks", "delegate")
|
||||
LOG_LIMIT = 500
|
||||
|
||||
|
||||
def fail(message: str) -> None:
|
||||
print(f"coach: {message}", file=sys.stderr)
|
||||
sys.exit(2)
|
||||
|
||||
|
||||
def moment(value: str | None) -> datetime.datetime:
|
||||
if value is None:
|
||||
return datetime.datetime.now(datetime.UTC)
|
||||
try:
|
||||
parsed = datetime.datetime.fromisoformat(value)
|
||||
except ValueError:
|
||||
fail(f"{value} is not an ISO timestamp")
|
||||
return parsed if parsed.tzinfo else parsed.replace(tzinfo=datetime.UTC)
|
||||
|
||||
|
||||
def load(path: Path) -> dict:
|
||||
try:
|
||||
data = json.loads(path.read_text(encoding="utf-8"))
|
||||
except FileNotFoundError:
|
||||
return {"likes": {}, "dislikes": {}, "log": []}
|
||||
except ValueError:
|
||||
fail(f"{path} is not valid JSON")
|
||||
return data
|
||||
|
||||
|
||||
def save(path: Path, data: dict) -> None:
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
tmp = path.with_suffix(".tmp")
|
||||
tmp.write_text(
|
||||
json.dumps(data, indent=1, sort_keys=True, ensure_ascii=False), encoding="utf-8"
|
||||
)
|
||||
tmp.replace(path)
|
||||
|
||||
|
||||
def prefer(data: dict, keep: str, area: str, thing: str) -> None:
|
||||
for key in ("likes", "dislikes"):
|
||||
items = data[key].setdefault(area, [])
|
||||
if thing in items:
|
||||
items.remove(thing)
|
||||
if keep:
|
||||
data[keep][area].append(thing)
|
||||
|
||||
|
||||
def summary(data: dict, now: datetime.datetime) -> list[dict]:
|
||||
rows = []
|
||||
for area in AREAS:
|
||||
last = next((e for e in reversed(data["log"]) if e["area"] == area), None)
|
||||
hours = None
|
||||
if last:
|
||||
hours = round((now - moment(last["at"])).total_seconds() / 3600, 1)
|
||||
rows.append(
|
||||
{
|
||||
"area": area,
|
||||
"likes": data["likes"].get(area, []),
|
||||
"dislikes": data["dislikes"].get(area, []),
|
||||
"last": last["thing"] if last else None,
|
||||
"hours_ago": hours,
|
||||
}
|
||||
)
|
||||
return rows
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
||||
parser.add_argument("--profile", required=True)
|
||||
sub = parser.add_subparsers(dest="cmd", required=True)
|
||||
for name in ("like", "dislike", "forget"):
|
||||
p = sub.add_parser(name)
|
||||
p.add_argument("area", choices=AREAS)
|
||||
p.add_argument("thing")
|
||||
p = sub.add_parser("done")
|
||||
p.add_argument("area", choices=AREAS)
|
||||
p.add_argument("thing")
|
||||
p.add_argument("--at")
|
||||
p = sub.add_parser("show")
|
||||
p.add_argument("--now")
|
||||
p.add_argument("--json", action="store_true")
|
||||
args = parser.parse_args()
|
||||
|
||||
path = Path(args.profile)
|
||||
data = load(path)
|
||||
if args.cmd == "show":
|
||||
rows = summary(data, moment(args.now))
|
||||
if args.json:
|
||||
print(json.dumps(rows, indent=1, ensure_ascii=False))
|
||||
return 0
|
||||
for row in rows:
|
||||
last = f"{row['last']} {row['hours_ago']}h ago" if row["last"] else "-"
|
||||
print(
|
||||
f"{row['area']}\tlast: {last}\tlikes: {', '.join(row['likes']) or '-'}"
|
||||
f"\tdislikes: {', '.join(row['dislikes']) or '-'}"
|
||||
)
|
||||
return 0
|
||||
if args.cmd == "done":
|
||||
data["log"].append(
|
||||
{"area": args.area, "thing": args.thing, "at": moment(args.at).isoformat()}
|
||||
)
|
||||
data["log"] = data["log"][-LOG_LIMIT:]
|
||||
else:
|
||||
keep = {"like": "likes", "dislike": "dislikes"}.get(args.cmd, "")
|
||||
prefer(data, keep, args.area, args.thing)
|
||||
save(path, data)
|
||||
print(f"{args.cmd} {args.area} {args.thing}")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -1,10 +1,10 @@
|
||||
---
|
||||
name: comments-clean
|
||||
name: kvb-code-no-comments
|
||||
description: >
|
||||
Purge explanatory comments from staged and unstaged changes. Run
|
||||
AUTOMATICALLY before every commit or stage request (commit, commit
|
||||
no-verify, stage next, socon, sobu, socobu, "commite ..."); also on
|
||||
/comments-clean or comment complaints.
|
||||
no-verify, stage next, "commite ..."); also on /kvb-code-no-comments or
|
||||
comment complaints.
|
||||
---
|
||||
|
||||
When the operator asks to commit or stage, run this audit first and only
|
||||
@@ -32,7 +32,7 @@ added lines only) and delete every explanatory comment:
|
||||
both the lint and the language parser can pass over code that no longer
|
||||
executes. Diff against the pre-edit revision (`git show HEAD:<path>`) and
|
||||
confirm that only comment lines left.
|
||||
5. Do not stage in order to run a check (the `commit-next` skill's step 4
|
||||
5. Do not stage in order to run a check (the `kvb-git-commit-next` skill's step 4
|
||||
says why). Re-stage after the audit exactly the files that were staged
|
||||
before it.
|
||||
6. Penalty: if this audit finds anything you wrote yourself, admit it in
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
name: no-defaults
|
||||
name: kvb-code-no-defaults
|
||||
description: >
|
||||
Forbid default values for parameters, settings and environment lookups;
|
||||
demand explicit values and fail loudly. Apply AUTOMATICALLY on every task
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: refactor
|
||||
name: kvb-code-refactor
|
||||
description: >
|
||||
Refactor every uncommitted file (staged, unstaged, untracked) up to the
|
||||
project's standards without changing behaviour. Trigger on /refactor or when
|
||||
project's standards without changing behaviour. Trigger on /kvb-code-refactor or when
|
||||
the operator asks to clean up, tidy or polish the current changes.
|
||||
---
|
||||
|
||||
@@ -80,7 +80,7 @@ Concretely:
|
||||
returning early; replace magic values with a named constant at its use site.
|
||||
- **Errors**: never widen a caught exception, never swallow one, never remove a
|
||||
validation or a security check to make the code shorter.
|
||||
- **Comments**: invoke the `comments-clean` skill rather than reimplementing its
|
||||
- **Comments**: invoke the `kvb-code-no-comments` skill rather than reimplementing its
|
||||
rules here.
|
||||
|
||||
Do not reformat regions you have no substantive fix for - cosmetic churn buries
|
||||
@@ -1,10 +1,9 @@
|
||||
---
|
||||
name: scope-guard
|
||||
name: kvb-code-scope-guard
|
||||
description: >
|
||||
Deliver exactly what was asked and nothing more. Trigger on every task that
|
||||
creates files, commands or commits, on unreviewed autonomous runs, on
|
||||
hand-over requests, and when the operator asks why something unrequested
|
||||
exists.
|
||||
creates files, commands or commits, on autonomous runs and hand-overs, and
|
||||
when asked why something unrequested exists.
|
||||
---
|
||||
|
||||
The requested scope is the deliverable. A problem you noticed behind the
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: test
|
||||
name: kvb-code-test
|
||||
description: >
|
||||
Discover the Makefile's test targets, let the operator pick, run and report;
|
||||
fix mode loops until green. Trigger on /test, /test --fix, or when the
|
||||
operator asks to run the tests, make them pass, or get the suite green.
|
||||
Run the Makefile test targets the operator picks and report; fix mode loops
|
||||
until green. Trigger on /kvb-code-test [--fix] or asked to run or fix the
|
||||
tests.
|
||||
---
|
||||
|
||||
The Makefile is the source of truth for how this project runs tests. Never
|
||||
@@ -73,7 +73,7 @@ quoted verbatim. Never paraphrase a failure. Then one line with the exact
|
||||
command to reproduce the failure alone.
|
||||
|
||||
Do not fix what failed unless the operator asks - report first. A request to
|
||||
make the tests pass, fix them, or get the suite green (`/test --fix`) switches
|
||||
make the tests pass, fix them, or get the suite green (`/kvb-code-test --fix`) switches
|
||||
to fix mode.
|
||||
|
||||
## Fix mode
|
||||
@@ -87,8 +87,8 @@ after three simultaneous changes proves nothing about which one mattered.
|
||||
- **Run** the failing target alone, the fastest command that reproduces the
|
||||
failure. Widen back to the full selection only when that target is green.
|
||||
- **Diagnose** from the actual error output before touching a file. Apply the
|
||||
`triage` skill to reach a verified root cause; for a cause still unclear
|
||||
after one look, apply `dialectic` rather than guessing twice. Say in one line
|
||||
`kvb-ci-triage` skill to reach a verified root cause; for a cause still unclear
|
||||
after one look, apply `kvb-think-dialectic` rather than guessing twice. Say in one line
|
||||
which side is wrong:
|
||||
- **Code**: the test states the intended behaviour. Fix the code.
|
||||
- **Test**: it encodes an outdated or incorrect expectation. Fix it only with
|
||||
@@ -98,7 +98,7 @@ after three simultaneous changes proves nothing about which one mattered.
|
||||
unbuilt artefact. Fix the environment or report it; do not patch code
|
||||
around it.
|
||||
- **Fix** with the smallest change that addresses the root cause, in the
|
||||
project's idioms and under the `no-defaults` and `comments-clean` rules.
|
||||
project's idioms and under the `kvb-code-no-defaults` and `kvb-code-no-comments` rules.
|
||||
Forbidden without explicit operator approval: deleting, skipping, `xfail`-ing
|
||||
or commenting out a failing test; loosening an assertion to what the code
|
||||
produces; swallowing the exception the test surfaces; retries, sleeps or
|
||||
@@ -126,5 +126,5 @@ Emit one line per iteration: target, failure, hypothesis, change. The final
|
||||
report gives per iteration what failed, the root cause, the fix and the
|
||||
result; the final state of every selected target with the verbatim output of
|
||||
anything still failing; everything deliberately not done; and the command
|
||||
reproducing the final state. State confidence per the `confidence` skill. Do
|
||||
reproducing the final state. State confidence per the `kvb-check-confidence` skill. Do
|
||||
not commit unless the operator asked for a commit.
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
name: kvb-code-transcend
|
||||
description: >
|
||||
Carry the session's ad-hoc tests and scripts into the current repo.
|
||||
Trigger on /kvb-code-transcend.
|
||||
---
|
||||
|
||||
The test the agent ran from its scratchpad, the probe that proved a cause, the
|
||||
benchmark behind an optimization: they protected this session's work and
|
||||
nothing after it. This skill moves them into the repository the agent works
|
||||
in (`git rev-parse --show-toplevel`), in that repository's own form. It
|
||||
changes nothing before the operator confirms.
|
||||
|
||||
## Step 1: inventory
|
||||
|
||||
Read-only:
|
||||
|
||||
- **Tests and scripts outside the repo**: `transcend.py scan` of the
|
||||
`kvb-transcend` skill lists them in the own and peers' scratchpads and
|
||||
skips what was already decided and has not changed; peer candidates follow
|
||||
that skill's consent step. Add the `python -c` checks and negative controls
|
||||
this session ran inline.
|
||||
- **Probes and reproductions** that proved a root cause or a fix.
|
||||
- **Measurements**: prototypes and before/after harnesses of the
|
||||
`kvb-code-tune` skill.
|
||||
- **Repeated commands** a make target or script of the repository could own.
|
||||
- **Untracked helpers** the agent left inside the repository.
|
||||
|
||||
One line each: `candidate -> source -> what it guards`.
|
||||
|
||||
## Step 2: classify
|
||||
|
||||
Read the repository's rules first (AGENTS.md, CONTRIBUTING, the Makefile, the
|
||||
test layout). Per candidate one target in that repository's form: a test in
|
||||
its test tree and framework, a make target, a script under its scripts
|
||||
directory, a CI step, or drop. No new framework, dependency or language
|
||||
without the operator. A kept optimization keeps its measurement as a
|
||||
benchmark or regression test.
|
||||
|
||||
## Step 3: listen and confirm
|
||||
|
||||
Run the `kvb-think-listen` skill on the open points: target path, framework,
|
||||
which repository line owns the file. Then `AskUserQuestion`: one
|
||||
`multiSelect` with the candidates, nothing preselected, and per pick a
|
||||
single-select `Write it` / `Revise it` / `Discard` with the drafted diff.
|
||||
|
||||
## Step 4: write
|
||||
|
||||
- Write only the confirmed files, path-scoped; a peer's line goes to its
|
||||
owner through the `kvb-org-coordinate` skill.
|
||||
- Every carried test fails without the code it guards: show the negative
|
||||
control once.
|
||||
- Run the repository's tests only on the resource chair's grant (the
|
||||
`kvb-org-organize` skill); leave the result uncommitted for the
|
||||
`kvb-git-commit-next` skill.
|
||||
- `transcend.py mark` every offered candidate with its verdict.
|
||||
|
||||
## Output
|
||||
|
||||
| Candidate | Source | Target in the repo | Verdict |
|
||||
|
||||
Dropped candidates stay with their reason.
|
||||
@@ -1,10 +1,9 @@
|
||||
---
|
||||
name: tune
|
||||
name: kvb-code-tune
|
||||
description: >
|
||||
Find and apply performance optimizations (CI, deploy, build, gate, hot
|
||||
paths) without reducing logic, coverage or correctness. Trigger on /tune,
|
||||
when a job dies on its time budget, when a pipeline or deploy grows slower,
|
||||
or asked where time goes.
|
||||
Speed up CI, deploys, builds and hot paths without losing logic or
|
||||
coverage. Trigger on /kvb-code-tune, a job hitting its time budget, or
|
||||
asked where time goes.
|
||||
---
|
||||
|
||||
# Tune
|
||||
@@ -14,7 +13,7 @@ correctness counts as a speed-up.**
|
||||
|
||||
## Once per session: listen first
|
||||
|
||||
The first time this skill runs in a session, invoke the `active-listening`
|
||||
The first time this skill runs in a session, invoke the `kvb-think-listen`
|
||||
skill before measuring anything, and ask three questions through the host's
|
||||
structured question mechanism. Offer each as a checklist (multi-select) with
|
||||
suggestions, and allow free text:
|
||||
@@ -22,8 +21,8 @@ suggestions, and allow free text:
|
||||
1. **What to examine.** Suggestions: CI wall-clock, deploy duration, gate and
|
||||
test runtime, image pulls and build caches, per-item loops and process
|
||||
spawns, idempotency (work repeated on a second run), network round trips,
|
||||
resource use (CPU, memory, disk, I/O), and language or runtime choice for
|
||||
hot paths.
|
||||
and resource use (CPU, memory, disk, I/O). Language, framework and
|
||||
recursion are checked on every run anyway (see Always check).
|
||||
2. **Which performance boundaries to keep.** Suggestions: time budgets per job,
|
||||
deploy or gate; resource caps (memory, CPU, disk headroom); a minimum saving
|
||||
per change (default 10 s per run); the measurement source that counts as
|
||||
@@ -31,13 +30,14 @@ suggestions, and allow free text:
|
||||
3. **Which limits apply to optimizations.** Suggestions: the scope that may be
|
||||
changed (files, roles, services); whether new dependencies, toolchains or
|
||||
languages may be introduced; whether infrastructure or CI configuration may
|
||||
change; the merge bar (default: the `funnel` skill's 90 % confidence and
|
||||
change; the merge bar (default: the `kvb-org-split` skill's 90 % confidence and
|
||||
under 5 % break risk); a time cap per delegated agent (default 60 minutes).
|
||||
|
||||
Keep the answers for the rest of the session and do not ask again. Work only
|
||||
inside them; a candidate outside them becomes a proposal.
|
||||
|
||||
When another skill (triage, observe) or an autonomous run invoked tune, skip
|
||||
When another skill (kvb-ci-triage, kvb-ci-observe) or an autonomous run invoked
|
||||
this skill, skip
|
||||
the questions: examine the handed-over log, apply the defaults above, and ask
|
||||
only when an operator-only fact blocks.
|
||||
|
||||
@@ -92,7 +92,7 @@ Discard a before/after pair, not just its noise, when:
|
||||
|
||||
## Before you optimize
|
||||
|
||||
- **Search every branch** (the merge-fix skill's `find_fix.py -S <symbol> --path <path>`) for a change
|
||||
- **Search every branch** (the kvb-git-merge-fix skill's `find_fix.py -S <symbol> --path <path>`) for a change
|
||||
that already removes or reshapes the step. A fix on a sibling branch can make
|
||||
the whole candidate worth zero.
|
||||
- A step that is long by design (a backup and restore drill, an end-to-end
|
||||
@@ -106,19 +106,38 @@ Discard a before/after pair, not just its noise, when:
|
||||
|
||||
A cost cluster is one place the time goes: one step, one hot path, one
|
||||
repeated call, named by its log line and its number. Before investigating or
|
||||
implementing a cluster, run the `democracy` skill's Peer protocol for it with
|
||||
implementing a cluster, run the `kvb-org-organize` skill's Peer protocol for it with
|
||||
every agent session on this machine, not only the branch lineage.
|
||||
|
||||
- **The first to identify a cluster works it.** "First" is the `democracy`
|
||||
- **The first to identify a cluster works it.** "First" is the `kvb-org-organize`
|
||||
claim `cluster/<slug>`, whose `--work` names the cluster's log line and
|
||||
number; between machines, the earliest announcement by message time. A
|
||||
claim without a measurement does not count.
|
||||
claim without a measurement does not count. In the `kvb-org-rasci` register
|
||||
the cluster's key result is the measured target (`<step> from <before> to
|
||||
under <after>`), met only by the re-measurement.
|
||||
- **Someone was earlier:** send them your measurements and findings, then move
|
||||
on to the next cluster. Never build a second optimization of the same
|
||||
cluster.
|
||||
- **A claim ends** when its holder reports the result, a proposal or an
|
||||
abandoned attempt and releases it, or when the operator reassigns it.
|
||||
|
||||
## Always check
|
||||
|
||||
Every run examines these two on each measured hot path, whatever the operator
|
||||
picked in the first question, and lists the result in the output table, a
|
||||
clean result included:
|
||||
|
||||
- **Language and framework**: whether the hot path's language and framework
|
||||
are the most efficient fit for its work (see Language and framework).
|
||||
- **Unnecessary recursion**: a recursive function that recomputes the same
|
||||
subproblem (memoize it or turn it into a loop), recursion that only walks a
|
||||
list or a fixed depth (a loop), a tree walk that visits or reads the same
|
||||
node more than once, depth that grows with the input (stack limits, Python's
|
||||
1000 frames), and recursive tool calls: a make target calling make, a role
|
||||
or playbook including itself, a script re-invoking itself per item. Count
|
||||
the calls first (a profiler's call graph, cProfile's `ncalls`, log lines);
|
||||
recursion that is bounded, rare and cheap stays.
|
||||
|
||||
## Levers that usually pay
|
||||
|
||||
- **Batch per-item process spawns**: N calls that each boot an interpreter or
|
||||
@@ -133,16 +152,22 @@ every agent session on this machine, not only the branch lineage.
|
||||
- **Overlap waits with work** only where concurrent execution is proven safe.
|
||||
Schema migrations and lock-holding steps are usually not.
|
||||
|
||||
## Language and runtime
|
||||
## Language and framework
|
||||
|
||||
Look for language optimizations where they make sense, for example replacing a
|
||||
Python hot path with Rust:
|
||||
Check the language and the framework of every measured hot path, for example
|
||||
replacing a Python hot path with Rust, or a heavy framework layer with a
|
||||
lighter one or the standard library:
|
||||
|
||||
- **Only for measured CPU-bound work.** When the profile shows the time in
|
||||
computation inside the process (parsing, hashing, rendering, tight loops),
|
||||
a compiled language can win by an order of magnitude. When the time goes to
|
||||
process start-up, network round trips or waiting, batching in the current
|
||||
language wins first, and a rewrite changes nothing.
|
||||
- **Framework overhead**: when the profile puts the time inside the framework
|
||||
(import and start-up, middleware, ORM query building, serialization),
|
||||
compare a lighter framework or the standard library on the same input. An
|
||||
ORM issuing one query per item is fixed by batching the query, not by
|
||||
swapping the framework.
|
||||
- **Prefer the narrowest cut**: rewrite the hot function as an extension
|
||||
module (for Python and Rust: PyO3 and maturin) or a small binary behind the
|
||||
same interface, before rewriting a whole tool.
|
||||
@@ -151,20 +176,20 @@ Python hot path with Rust:
|
||||
and test parity with the old implementation.
|
||||
- **Prove it on a prototype**: the same input, the same machine state, a before
|
||||
and an after number, and the old test suite passing against the new code.
|
||||
- A language change is applied only when the session's limits allow new
|
||||
languages or toolchains; otherwise it is submitted as a proposal with the
|
||||
prototype's numbers.
|
||||
- A language or framework change is applied only when the session's limits
|
||||
allow new languages, frameworks or toolchains; otherwise it is submitted as
|
||||
a proposal with the prototype's numbers.
|
||||
|
||||
## Delegating an optimization
|
||||
|
||||
Hand every optimization to an agent through the `funnel` skill: one sidetree
|
||||
Hand every optimization to an agent through the `kvb-org-split` skill: one sidetree
|
||||
per candidate, branched from an exact commit, with a time cap and "measure
|
||||
first, report the time split before implementing". The agent probes live
|
||||
systems read-only and never starts gates or deploys. A broad brief without a
|
||||
cap can run for hours without a word; at its cap, collect the agent's interim
|
||||
findings and let it run on.
|
||||
|
||||
Before merging, run independent skeptics through the `dialectic` skill. The
|
||||
Before merging, run independent skeptics through the `kvb-think-dialectic` skill. The
|
||||
antithesis must try to show that the candidate removes coverage, hides a
|
||||
failure, or only moves the cost somewhere the measurement does not look.
|
||||
|
||||
@@ -174,11 +199,14 @@ failure, or only moves the cost somewhere the measurement does not look.
|
||||
2. Coordinate the cluster with the other agents; work it only when you
|
||||
identified it first, otherwise hand over your findings and take the next.
|
||||
Then form one candidate for it, after the branch search and the floor check.
|
||||
3. Harden it with the `dialectic` skill.
|
||||
3. Harden it with the `kvb-think-dialectic` skill.
|
||||
4. Funnel it through a sidetree; merge what reaches the bar, submit the rest as
|
||||
proposals. Re-measure from the same source under the same conditions and
|
||||
report a before and an after number.
|
||||
5. Repeat until the next candidate is worth less than the run that measures it.
|
||||
6. Hand the prototypes and before/after harnesses of every kept candidate to
|
||||
the `kvb-code-transcend` skill, so the measurement stays in the repository
|
||||
as a benchmark or regression test.
|
||||
|
||||
## Output
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: plan
|
||||
name: kvb-create-plan
|
||||
description: >
|
||||
Turn a request into an objective-oriented plan and hand it to the robot
|
||||
skill. Trigger on /plan or when the operator asks for a plan, breakdown or
|
||||
Turn a request into an objective-oriented plan and hand it to the kvb-org-robot
|
||||
skill. Trigger on /kvb-create-plan or when the operator asks for a plan, breakdown or
|
||||
strategy before work starts.
|
||||
---
|
||||
|
||||
@@ -12,7 +12,7 @@ verified, and an unverifiable plan cannot be handed to a robot.
|
||||
|
||||
## Procedure
|
||||
|
||||
1. **Interview first.** Open every plan with the `active-listening` skill: ask
|
||||
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.
|
||||
@@ -28,11 +28,13 @@ verified, and an unverifiable plan cannot be handed to a robot.
|
||||
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
|
||||
`dialectic` skill where being wrong is expensive. The robot does not ask, so
|
||||
`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 as a todo list.** Write 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.
|
||||
6. **Record the plan in the register.** Enter the objective in 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.
|
||||
@@ -42,8 +44,8 @@ verified, and an unverifiable plan cannot be handed to a robot.
|
||||
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 `robot`.** With the static implementation complete,
|
||||
invoke the `robot` skill with the objective as its goal for the dynamic part:
|
||||
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.
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
name: kvb-create-requirement
|
||||
description: >
|
||||
Write a requirement: user story, decisions, Mermaid approach, acceptance
|
||||
criteria, tests. Trigger on /kvb-create-requirement, "requirement
|
||||
schreiben", or a kvb-think-gaps pick.
|
||||
---
|
||||
|
||||
Writes requirements, never implementations. Nothing touches disk before the
|
||||
operator picks `Write it`.
|
||||
|
||||
## Step 1: context
|
||||
|
||||
Ask the operator for the context first, in one open question: what should
|
||||
change, for whom, and why now. A candidate handed over by the
|
||||
`kvb-think-gaps` skill already carries it. Read what the answer points to
|
||||
(code, issues, logs, existing requirements) before the next step.
|
||||
|
||||
## Step 2: listen
|
||||
|
||||
Run the `kvb-think-listen` skill until scope, constraints, the definition of
|
||||
done and every operator-only decision are fixed. Its answers become the
|
||||
Decisions section.
|
||||
|
||||
## Step 3: brainstorm
|
||||
|
||||
Run the `kvb-think-brainstorm` skill on the approach. The operator's pick
|
||||
becomes a decision; each rejected option stays there with its reason.
|
||||
|
||||
## Step 4: draft
|
||||
|
||||
Location, filename and numbering follow the project's existing requirement
|
||||
documents; read them first, and ask when there are none. One feature per
|
||||
document: a title that needs "and" is two requirements. Sections in this
|
||||
order:
|
||||
|
||||
1. `# <number> - <title>`
|
||||
2. `## User Story`: "As a <role>, I want <capability>, so that <benefit>."
|
||||
3. `## Decisions (operator-confirmed <YYYY-MM-DD>; do not re-litigate)`:
|
||||
numbered, a bold keyword first, rejected alternatives with their reason.
|
||||
4. `## Approach`: one Mermaid `flowchart TD` over the whole procedure, one
|
||||
`subgraph` per phase with an emoji title and an emoji in every node:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph P["🧭 0 · Preparation"]
|
||||
P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
|
||||
P2 -- "✏️ corrections" --> P1
|
||||
end
|
||||
P2 -- "🤖 yes" --> A1
|
||||
subgraph A["🛠️ A · Implementation"]
|
||||
A1["🧩 Change"] --> A2{"🧪 Tests green?"}
|
||||
A2 -- "🔴 no: fix" --> A1
|
||||
A2 -- "🟢 yes" --> AF{"💬 Operator feedback?"}
|
||||
AF -- "✏️ changes" --> A1
|
||||
end
|
||||
AF -- "👍 fits" --> D1["🏁 Review, commit with operator OK, hand-over"]
|
||||
```
|
||||
|
||||
Every verifiable stage gets its test loop and an operator feedback
|
||||
checkpoint; a user-visible change shows screenshots at that checkpoint.
|
||||
5. `## Acceptance Criteria`: grouped under `###` per area. Each item is a
|
||||
`- [ ]` that one check proves or disproves on its own: a command, a
|
||||
`file:line`, a test name, an observable state. No "should", no "works
|
||||
well".
|
||||
6. `### Tests`, the last group: `Unit`, `Integration` and `E2E`, each with
|
||||
its criteria. A level that cannot apply stays with `n/a: <reason>`.
|
||||
|
||||
## Step 5: confirm and write
|
||||
|
||||
Show the full draft, then `AskUserQuestion`: `Write it` / `Revise it` /
|
||||
`Discard`. Revise loops back to the step the correction touches. Write only
|
||||
on `Write it`; lint the file with the project's markdown linter on the
|
||||
resource chair's grant (the `kvb-org-organize` skill).
|
||||
|
||||
## Step 6: hand over
|
||||
|
||||
Stop after writing. Offer in one line to run the `kvb-create-plan` skill,
|
||||
which hands the plan to the `kvb-org-robot` skill; never start the
|
||||
implementation without the operator's yes.
|
||||
@@ -1,21 +1,20 @@
|
||||
---
|
||||
name: dream
|
||||
name: kvb-dream
|
||||
description: >
|
||||
Consolidate the last 24 hours of work in this repository: what held, what
|
||||
broke, which hypotheses follow, into memory and improvement proposals.
|
||||
Trigger on /dream or when the operator asks to reflect on or learn from
|
||||
recent work.
|
||||
Process the last 24 hours of every repository and session: memory,
|
||||
improvements, kvb-optimize, cleanups. Trigger on /kvb-dream or a request
|
||||
to learn from recent work.
|
||||
---
|
||||
|
||||
Sleep on the work: replay what happened in this repository, separate what held
|
||||
from what broke, and keep only the conclusions that survive an attack. A dream
|
||||
that flatters the dreamer is worthless — an unverified success counts as
|
||||
unknown, not as a win.
|
||||
Sleep on the work: replay what happened, separate what held from what broke,
|
||||
keep only the conclusions that survive an attack, then optimize and clean up.
|
||||
Dreaming processes everything. A dream that flatters the dreamer is worthless —
|
||||
an unverified success counts as unknown, not as a win.
|
||||
|
||||
## Objective
|
||||
|
||||
The dream exists to raise the confidence of every future run in this repository
|
||||
until the mistakes it found cannot happen again. Judge every finding, memory
|
||||
The dream exists to raise the confidence of every future run until the
|
||||
mistakes it found cannot happen again. Judge every finding, memory
|
||||
entry, and proposal by one question: does it make the next run measurably less
|
||||
likely to repeat this failure? What changes nothing about future behaviour is
|
||||
not worth recording.
|
||||
@@ -24,22 +23,27 @@ A class of error counts as closed only when something structural prevents it —
|
||||
a test, a lint rule, a CI check, a hook, a written rule in the agent
|
||||
instructions, or a skill. "Be more careful next time" closes nothing. Report the
|
||||
confidence the next run can now hold on each closed class, calibrated as the
|
||||
`confidence` skill requires, and name what is still open.
|
||||
`kvb-check-confidence` skill requires, and name what is still open.
|
||||
|
||||
## Scope
|
||||
|
||||
Everything is read from the repository the skill runs in (`git rev-parse
|
||||
--show-toplevel`); never mix in another project's history or memory. The default
|
||||
window is the last 24 hours — the operator may widen it (`/dream 7d`). State the
|
||||
repository and the window in one line before you start.
|
||||
Every repository and session this agent touched in the window: the
|
||||
repositories named by its session transcripts (working directories and
|
||||
worktrees), by the workdirs of its `kvb-org-rasci` register tasks, and the
|
||||
current one. The default window is the last 24 hours — the operator may widen
|
||||
it (`/kvb-dream 7d`). State the repositories and the window in one table before
|
||||
you start. Each repository is recalled and scored on its own; a finding goes
|
||||
into the memory of the project it concerns, never mixed with another's.
|
||||
|
||||
Run only when the operator asks. The 12-hour reminder hook
|
||||
(`hooks/reminder.sh`, stamped per repository in its git dir) is a hint for the
|
||||
operator, not a trigger: print it and continue with their actual request.
|
||||
Run only when the operator asks. Two hints point at it, neither is a trigger:
|
||||
`hooks/reminder.sh` tells each agent at most once every twelve hours (stamped
|
||||
per session in `~/.claude/.dream-stamps/`), and the `kvb-dream-notify.timer`
|
||||
user timer shows a GNOME notification daily at 17:00 local time, catching up
|
||||
once after a missed run. Print the hint and continue with the actual request.
|
||||
|
||||
## Step 1: recall
|
||||
|
||||
Gather the window's actual record, not your recollection of it:
|
||||
Gather the window's actual record per repository, not your recollection of it:
|
||||
|
||||
- **History**: `git log --since` across all branches plus `--reflog`, with
|
||||
`--stat`; the reflog carries the resets, rebases, and amends the log hides.
|
||||
@@ -48,7 +52,10 @@ Gather the window's actual record, not your recollection of it:
|
||||
logs of the red ones — the failing log line, not the job title.
|
||||
- **Reviews**: pull requests and issues touched in the window, and the review
|
||||
comments on them.
|
||||
- **Memory**: this project's memory directory and its `MEMORY.md` index — the
|
||||
- **Register**: the `kvb-org-rasci` register: `rasci.py tools` ranks the
|
||||
scripts and tools the window's tasks ran, the refactoring candidates;
|
||||
`get <task>` shows a task's objective, roles, workdir and artifacts.
|
||||
- **Memory**: each project's memory directory and its `MEMORY.md` index — the
|
||||
findings already recorded, so the dream extends them instead of repeating them.
|
||||
- **Instructions**: `CLAUDE.md`, `AGENTS.md`, and the project's own skills, to
|
||||
see which rule a mistake actually violated.
|
||||
@@ -77,14 +84,14 @@ that nothing could disprove is not a hypothesis — cut it.
|
||||
|
||||
## Step 4: dialectic
|
||||
|
||||
Put every surviving hypothesis through the `dialectic` skill: thesis,
|
||||
Put every surviving hypothesis through the `kvb-think-dialectic` skill: thesis,
|
||||
independent skeptics, synthesis, iterated to ~99%. What survives becomes a
|
||||
finding. What gets refuted is recorded as discarded **with the refutation**, so
|
||||
the next dream does not re-derive it.
|
||||
|
||||
## Step 5: write memory
|
||||
|
||||
Persist the findings in this project's memory directory: one file per fact, one
|
||||
Persist the findings in the memory directory of the project they concern: one file per fact, one
|
||||
pointer line in `MEMORY.md`. Update the file that already covers a fact instead
|
||||
of adding a duplicate, and delete the memories this run disproved. Absolute
|
||||
dates, never "yesterday". Nothing that the repository already records — code
|
||||
@@ -94,7 +101,7 @@ structure, git history, `CLAUDE.md` — belongs in memory.
|
||||
|
||||
Two kinds come out of the findings:
|
||||
|
||||
- **Code** — the change to this repository's source, tests, config, or CI that
|
||||
- **Code** — the change to the affected repository's source, tests, config, or CI that
|
||||
the finding calls for.
|
||||
- **Agent instructions** — the missing or wrong rule in `CLAUDE.md`,
|
||||
`AGENTS.md`, the project's own skills, or the contributor docs. Every mistake
|
||||
@@ -106,15 +113,24 @@ as radio buttons: the improvement, the evidence behind it, and the options
|
||||
`Apply now`, `Record as a task`, `Skip`. Ranked by evidence, one question per
|
||||
improvement. No repository file changes before an answer comes back.
|
||||
|
||||
## Step 7: autotune, then autoskill
|
||||
## Step 7: optimize
|
||||
|
||||
With the dialectic done and memory written, run `autotune` — hand it this run's
|
||||
findings as its evidence so it does not re-collect them — and then `autoskill`
|
||||
for the operator corrections the window revealed. Both keep their own
|
||||
confirmation steps; the dream never writes a skill on their behalf.
|
||||
With the dialectic done and memory written, run the `kvb-optimize` skill and
|
||||
hand it this run's findings as its evidence, so none of its skills
|
||||
re-collects them.
|
||||
|
||||
Close the run by refreshing this repository's reminder stamp, so the next hint
|
||||
is twelve hours out: `date +%s > "$(git rev-parse --path-format=absolute --git-common-dir)/.dream-stamp"`.
|
||||
## Step 8: clean up
|
||||
|
||||
Run the `kvb-cleanup` skill for the disk, `/tmp`, Docker and agent
|
||||
directories the window filled, with the artifacts of the window's finished
|
||||
register tasks (`rasci.py artifacts --ended`) as its candidates, then the
|
||||
`kvb-git-branch-gc` skill for the merged branches and worktrees of every
|
||||
repository in scope.
|
||||
|
||||
Every skill in steps 7 and 8 keeps its own confirmation steps; the dream never
|
||||
writes, deletes or commits on their behalf. Close the run by refreshing this
|
||||
agent's reminder stamp, so its next hint is twelve hours out:
|
||||
`date +%s > ~/.claude/.dream-stamps/"$CLAUDE_CODE_SESSION_ID"`.
|
||||
|
||||
## Rules
|
||||
|
||||
@@ -124,8 +140,8 @@ is twelve hours out: `date +%s > "$(git rev-parse --path-format=absolute --git-c
|
||||
attempt even when the final state is green.
|
||||
- Read-only until step 6: the dream inspects, and writes memory; repository code
|
||||
changes only on an explicit radio answer.
|
||||
- An empty window is a valid result — report "nothing in the last 24 hours in
|
||||
this repository" and stop. Never invent activity to have something to dream
|
||||
- An empty window is a valid result — report "nothing in the last 24 hours" per
|
||||
repository and skip it. Never invent activity to have something to dream
|
||||
about.
|
||||
- Prefer the structural fix over the remembered one: a test, check, hook, or
|
||||
written rule that makes the error impossible beats a memory entry that only
|
||||
Executable
+8
@@ -0,0 +1,8 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
[[ "${XDG_CURRENT_DESKTOP:-}" == *GNOME* ]] || exit 0
|
||||
command -v notify-send >/dev/null || exit 0
|
||||
|
||||
notify-send --app-name=kvb-dream "kvb-dream" \
|
||||
"Time to dream: run /kvb-dream in your agent sessions to process the day."
|
||||
Executable
+34
@@ -0,0 +1,34 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
interval="${DREAM_INTERVAL_SECONDS:-43200}"
|
||||
stamps="${DREAM_STAMP_DIR:-${HOME}/.claude/.dream-stamps}"
|
||||
|
||||
session="$(python3 -c 'import json, sys; print(json.load(sys.stdin).get("session_id", ""))' 2>/dev/null)" || exit 0
|
||||
[[ "${session}" =~ ^[A-Za-z0-9_-]+$ ]] || exit 0
|
||||
stamp="${stamps}/${session}"
|
||||
|
||||
now="$(date +%s)"
|
||||
last=0
|
||||
if [[ -f "${stamp}" ]]; then
|
||||
read -r last <"${stamp}" || true
|
||||
[[ "${last}" =~ ^[0-9]+$ ]] || last=0
|
||||
fi
|
||||
|
||||
if ((now - last < interval)); then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
mkdir -p "${stamps}"
|
||||
printf '%s\n' "${now}" >"${stamp}"
|
||||
|
||||
cat <<'HINT'
|
||||
DREAM HINT: over twelve hours since this agent's last hint. Show the operator
|
||||
this notice verbatim as a short block, then continue with their request. Do NOT
|
||||
run kvb-dream, do not start replaying the history, do not ask questions about
|
||||
it.
|
||||
|
||||
💤 /kvb-dream - process the last 24h of every repository and session this
|
||||
agent touched: memory, improvements, kvb-optimize and the cleanups.
|
||||
Runs only when you trigger it.
|
||||
HINT
|
||||
@@ -0,0 +1,7 @@
|
||||
[Unit]
|
||||
Description=Recommend /kvb-dream in a GNOME notification
|
||||
After=graphical-session.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/bin/env bash %h/.claude/skills/kvb-dream/hooks/notify.sh
|
||||
@@ -0,0 +1,9 @@
|
||||
[Unit]
|
||||
Description=Daily /kvb-dream recommendation at 17:00 local time
|
||||
|
||||
[Timer]
|
||||
OnCalendar=*-*-* 17:00:00
|
||||
Persistent=true
|
||||
|
||||
[Install]
|
||||
WantedBy=timers.target
|
||||
@@ -1,10 +1,9 @@
|
||||
---
|
||||
name: branch-gc
|
||||
name: kvb-git-branch-gc
|
||||
description: >
|
||||
Remove merged branches and worktrees with `pkgmgr branch gc`: dry run,
|
||||
operator picks from the plan, then apply; unmerged items only one by one.
|
||||
Trigger on /branch-gc, "branches aufräumen", "worktrees aufräumen",
|
||||
"garbage collect".
|
||||
Remove merged branches and worktrees with `pkgmgr branch gc` after a dry
|
||||
run the operator picks from. Trigger on /kvb-git-branch-gc, "branches
|
||||
aufräumen", "worktrees aufräumen".
|
||||
---
|
||||
|
||||
`pkgmgr branch gc` decides what is merged and does the removing; this skill
|
||||
@@ -14,7 +13,7 @@ and nothing is removed before the operator's pick in this run.
|
||||
## Step 0: claim and chair
|
||||
|
||||
1. Claim `work/branch-gc-<repo>`, or `work/branch-gc-all` for every
|
||||
repository, through the `democracy` skill.
|
||||
repository, through the `kvb-org-organize` skill.
|
||||
2. The apply takes stacks down and ends with a host-wide
|
||||
`docker image prune -f` and `docker builder prune -f`, which reach every
|
||||
session's images and build cache. When another session holds the chair,
|
||||
@@ -23,8 +22,12 @@ and nothing is removed before the operator's pick in this run.
|
||||
|
||||
## Step 1: dry run
|
||||
|
||||
`pkgmgr branch gc --json`, with `--all` only when the operator asked for every
|
||||
repository, output to `/tmp/branch-gc-<N>.json`. No `git fetch` of your own
|
||||
`pkgmgr branch gc --json --sizes --min-age 24 --merged-into <line>`, one
|
||||
`--merged-into` per integration line the project merges features into
|
||||
(default branch excluded, it always counts), with `--all` only when the
|
||||
operator asked for every repository, output to `/tmp/branch-gc-<N>.json`. A
|
||||
line is protected, and a checkout at its tip stays as fresh work; an item
|
||||
merged into a line names it in `merged_into`. No `git fetch` of your own
|
||||
before it: gc fetches without auto-maintenance, while a plain fetch on git
|
||||
2.50 or later may prune the sandbox's bind-mount stubs. Every repository's
|
||||
`warnings` (a failed fetch) go to the top of the plan. Sort the items:
|
||||
@@ -53,7 +56,7 @@ silence is not consent.
|
||||
|
||||
One table:
|
||||
|
||||
| Repo | Branch or worktree | Merged by | Actions | Note |
|
||||
| Repo | Branch or worktree | Merged into | Size | Actions | Note |
|
||||
|
||||
Then ask with `AskUserQuestion`:
|
||||
|
||||
@@ -81,6 +84,10 @@ Then ask with `AskUserQuestion`:
|
||||
(still in use elsewhere), or `failed: <why>`.
|
||||
Report a failure as it stands; never remove by hand what gc skipped or
|
||||
refused.
|
||||
4. For every `done` item, drop its worktree and branch from the task that
|
||||
lists them in the `kvb-org-rasci` register (`rasci.py artifacts` names
|
||||
it): `set <task> --drop-artifact worktree:<path>`, and `--branch ''` where
|
||||
the branch is gone.
|
||||
|
||||
## Step 5: unmerged and dirty
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: changelog
|
||||
name: kvb-git-changelog
|
||||
description: >
|
||||
Write the release message since the last release for `pkgmgr release`;
|
||||
prints it only, never edits CHANGELOG.md, tags or releases. Trigger on
|
||||
/changelog, "release message", "changelog entry", before cutting a release,
|
||||
Write the release message for `pkgmgr release`;
|
||||
prints only, never edits, tags or releases. Trigger on
|
||||
/kvb-git-changelog, "release message", "changelog entry", before cutting a release,
|
||||
or on pkgmgr's markdown-lint rejection.
|
||||
---
|
||||
|
||||
@@ -1,25 +1,26 @@
|
||||
---
|
||||
name: commit-next
|
||||
name: kvb-git-commit-next
|
||||
description: >
|
||||
Check every branch for the staged fix, commit the staged bundle with
|
||||
--no-verify, then stage and brief the next bundle. Trigger on /commit-next
|
||||
or when the operator asks to commit and stage the next bundle in one step.
|
||||
Search every branch for the staged fix, commit it with --no-verify, then
|
||||
stage and brief the next bundle. Trigger on /kvb-git-commit-next or a
|
||||
request to commit and stage next.
|
||||
---
|
||||
|
||||
1. `git fetch --all --prune --tags`, then hunt the staged fix across every
|
||||
ref with the merge-fix skill's `find_fix.py` (by `--grep`, by `-S`, by
|
||||
ref with the kvb-git-merge-fix skill's `find_fix.py` (by `--grep`, by `-S`, by
|
||||
`--path`). Describe the staged bundle in one line first so a
|
||||
wrong search intent is visible. Only the search runs here — never
|
||||
cherry-pick or merge, and never touch the staging index or the tree.
|
||||
2. A similar fix on another branch is a stop: run the dialectic skill on the
|
||||
2. A similar fix on another branch is a stop: run the kvb-think-dialectic skill on the
|
||||
two candidates (staged version as thesis, foreign commit as antithesis)
|
||||
until one survives, then present sha, branch, both diffs, the verdict and
|
||||
the recommended move (keep staged / take theirs / combine). Wait for the
|
||||
operator's decision; do not commit.
|
||||
3. Nothing similar found, or the operator picked the staged version: run the
|
||||
commit-no-verify skill on the currently staged changes (comments-clean
|
||||
audit and advocate check first, then `git commit --no-verify`, exact
|
||||
staging index only).
|
||||
kvb-git-commit-no-verify skill on the currently staged changes (kvb-code-no-comments
|
||||
audit and kvb-check-legal check first, then its four-line block of
|
||||
worktree path, branch, fix confidence and break risk, then
|
||||
`git commit --no-verify`, exact staging index only).
|
||||
4. Group the remaining uncommitted changes into logical bundles (one
|
||||
concern per bundle: same failure class, same mechanism, or same role)
|
||||
and stage the next one; never mix concerns to save a commit. Staging
|
||||
@@ -29,8 +30,8 @@ description: >
|
||||
NEW file needs `git add` to become visible. Path-scope every `git add`
|
||||
to the bundle — `git add -A` sweeps up the operator's own edits and
|
||||
their local config.
|
||||
5. For the newly staged bundle run the explain skill (what the changes do
|
||||
5. For the newly staged bundle run the kvb-think-explain skill (what the changes do
|
||||
and how the pieces interact, file:line-anchored) followed by the
|
||||
confidence skill (fix confidence, break risk, evidence, residuals).
|
||||
kvb-check-confidence skill (fix confidence, break risk, evidence, residuals).
|
||||
6. Close with what remains unstaged and wait for the operator's commit
|
||||
decision; never auto-commit the newly staged bundle.
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
name: kvb-git-commit-no-verify
|
||||
description: >
|
||||
Commit the staged changes with --no-verify. Trigger on /kvb-git-commit-no-verify or
|
||||
any request for a no-verify commit; invoking it IS the per-commit
|
||||
authorization --no-verify requires, never carried over to later commits.
|
||||
---
|
||||
|
||||
1. Run the kvb-code-no-comments audit over the staged and unstaged changes first,
|
||||
then the kvb-check-legal check over the staging index. A legal blocker stops
|
||||
here.
|
||||
2. Show four lines in the message right before the `git commit` call, never
|
||||
only after it:
|
||||
- **Worktree**: absolute path from `git rev-parse --show-toplevel`.
|
||||
- **Branch**: `git branch --show-current`, or `detached at <short sha>`.
|
||||
- **Fix confidence** of the staged bundle, from the kvb-check-confidence
|
||||
skill.
|
||||
- **Break risk** of the staged bundle, derived through the
|
||||
kvb-check-break-risk skill.
|
||||
3. Commit exactly the staging index with `git commit --no-verify` and a
|
||||
Conventional-Commits message derived from the staged diff; never add
|
||||
unstaged files, never push.
|
||||
4. Report the created commit hash and what remains uncommitted.
|
||||
@@ -1,12 +1,12 @@
|
||||
---
|
||||
name: merge-fix
|
||||
name: kvb-git-merge-fix
|
||||
description: >
|
||||
Hunt down the commits on any branch that carry a described fix and merge it
|
||||
into the current branch. Trigger on /merge-fix <description> or when the
|
||||
operator asks to bring over a fix from another branch.
|
||||
Find the commits on any branch that carry a described fix and merge them
|
||||
here. Trigger on /kvb-git-merge-fix <description> or a request to bring over
|
||||
a fix from another branch.
|
||||
---
|
||||
|
||||
The free text after `/merge-fix` is the fix description, exactly like `/loop`
|
||||
The free text after `/kvb-git-merge-fix` is the fix description, exactly like `/loop`
|
||||
takes its prompt. Everything after the skill name is the search intent; there is
|
||||
no other input. If it is missing, ask for it and stop.
|
||||
|
||||
@@ -67,7 +67,7 @@ and its diff plainly is the described fix.
|
||||
## 7. Report
|
||||
|
||||
Show `git log --oneline <base>..HEAD` and the resulting diffstat, then apply the
|
||||
confidence skill: what came over, what did not, what still has to be verified.
|
||||
kvb-check-confidence skill: what came over, what did not, what still has to be verified.
|
||||
Run the project's test or quality gate only when the operator asks for it.
|
||||
|
||||
## Rules
|
||||
File renamed without changes.
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: help-skills
|
||||
name: kvb-help
|
||||
description: >
|
||||
List and explain every skill in the session. Trigger on /help-skills,
|
||||
List and explain every skill in the session. Trigger on /kvb-help,
|
||||
"welche skills gibt es", "skill übersicht", or when the operator asks what
|
||||
skills exist or what one does.
|
||||
---
|
||||
@@ -17,8 +17,8 @@ Produce a one-shot overview of every skill the session can invoke:
|
||||
— compress the description, do not paste it.
|
||||
3. When the operator names a specific skill or topic, explain only the
|
||||
matching skills in more depth: what they do, when they fire on their
|
||||
own, and how they compose (e.g. commit-next → commit-no-verify →
|
||||
comments-clean).
|
||||
own, and how they compose (e.g. kvb-git-commit-next → kvb-git-commit-no-verify →
|
||||
kvb-code-no-comments).
|
||||
4. End with the activation hint: project installers or `make install` in
|
||||
the skills repository refresh the live copies; a restart loads renamed
|
||||
or new skills.
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
name: kvb-optimize
|
||||
description: >
|
||||
Run every optimization skill in one pass with one round of questions.
|
||||
Trigger on /kvb-optimize; kvb-dream runs it.
|
||||
---
|
||||
|
||||
Collector for the optimization skills, so one pass needs one evidence
|
||||
collection and one round of questions. Evidence handed over by the
|
||||
`kvb-dream` skill is used as is; standalone, collect it once from the
|
||||
current session and repository and hand the same set to every skill.
|
||||
|
||||
## Order
|
||||
|
||||
Each runs its own inventory and keeps its own confirmation step; an empty
|
||||
inventory is skipped with one line.
|
||||
|
||||
1. `kvb-skill-cleanup`: delete the legacy skills first, so nothing below
|
||||
optimizes a dead copy.
|
||||
2. `kvb-transcend`: carry scripts, tests and skills out of scratchpads and
|
||||
agent homes into the skills repository or the current repository.
|
||||
3. `kvb-skill-auto`: turn the operator's repetitions into skills.
|
||||
4. `kvb-skill-tune`: turn frictions into new or sharper skills.
|
||||
5. `kvb-skill-compile`: turn deterministic skill steps into scripts.
|
||||
6. `kvb-skill-essence`: compact skills and memory.
|
||||
7. `kvb-code-refactor`: bring the uncommitted changes up to the project's
|
||||
standards.
|
||||
8. `kvb-code-tune`: optimize the hot paths the evidence measured.
|
||||
9. `kvb-think-gaps`: find the missing work and hand each pick to
|
||||
`kvb-create-requirement`.
|
||||
|
||||
## Questions
|
||||
|
||||
Collect the candidates of all skills first, then run one `kvb-think-listen`
|
||||
round and put every skill's own confirmation questions into one batch,
|
||||
grouped by skill. Each skill writes only what was picked for it.
|
||||
|
||||
## Output
|
||||
|
||||
| Skill | Candidates | Picked | Written | Skipped with reason |
|
||||
|
||||
Tests and lints of the written changes run once at the end, on the resource
|
||||
chair's grant (the `kvb-org-organize` skill); nothing is committed.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
name: kvb-org-artefacts
|
||||
description: >
|
||||
Artifacts of the kvb-org-rasci register per task: images, volumes,
|
||||
worktrees. Trigger on /kvb-org-artefacts, "artefakte".
|
||||
---
|
||||
|
||||
Artifacts live in the same table as the tasks of the `kvb-org-rasci`
|
||||
register: each one belongs to exactly one task, carries its kind, reference
|
||||
and the time it was recorded, and takes status and worker from its task. The
|
||||
script is the register's `${CLAUDE_SKILL_DIR}/../kvb-org-rasci/scripts/rasci.py`.
|
||||
|
||||
```bash
|
||||
rasci.py set <task> --artifact <kind>:<ref>
|
||||
rasci.py set <task> --drop-artifact <kind>:<ref>
|
||||
rasci.py artifacts [--ended] [--task <task>]
|
||||
```
|
||||
|
||||
Kinds: `image:`, `container:`, `volume:`, `network:`, `stack:`, `worktree:`,
|
||||
`dir:`, `log:`. `artifacts` lists each task's workdir and branch beside them.
|
||||
|
||||
## Rules
|
||||
|
||||
- Record an artifact the moment it exists, under the task that created it;
|
||||
one left unrecorded is invisible to cleanup.
|
||||
- `artifacts --ended` lists what belongs to `done`, `stopped` or `stale`
|
||||
tasks: the cleanup candidates, owned by the task's worker. Everything of an
|
||||
open task stays.
|
||||
- Deleting goes through the `kvb-cleanup` skill, where the operator picks;
|
||||
drop the artifact here once it is gone.
|
||||
- The register's `show` counts each task's artifacts in its Artifacts column.
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
name: kvb-org-coordinate
|
||||
description: >
|
||||
Coordinate a failure or fix with the agents on related branches through
|
||||
merges: claim, ask, report. Trigger on /kvb-org-coordinate and when a fix touches
|
||||
code other branches share.
|
||||
---
|
||||
|
||||
Run the `kvb-org-organize` skill's **Lineage** and **Peer protocol** sections for the
|
||||
failure or fix at hand. They hold the whole procedure, including the entries
|
||||
in the `kvb-org-rasci` register; this skill only keeps `/kvb-org-coordinate`
|
||||
working.
|
||||
@@ -1,9 +1,8 @@
|
||||
---
|
||||
name: status-matrix
|
||||
name: kvb-org-matrix
|
||||
description: >
|
||||
Print one matrix of everything in flight: tasks, workflows, background jobs,
|
||||
with confidence and break risk per item. Trigger on /status-matrix,
|
||||
"status", "übersicht", "wo stehen wir", or what is done, left or running.
|
||||
One matrix of everything in flight with confidence and break risk per
|
||||
item. Trigger on /kvb-org-matrix, "status", "übersicht", "wo stehen wir".
|
||||
---
|
||||
|
||||
One-shot overview, no side effects: this skill reads state and reports it. It
|
||||
@@ -15,7 +14,7 @@ decides what to act on after reading the matrix.
|
||||
Gather in parallel, skip any source the session does not have, and never invent
|
||||
a row for a source you could not read:
|
||||
|
||||
1. **Tasks** — the session's todo list, the operator's stated goals this
|
||||
1. **Tasks** — the `kvb-org-rasci` register first, then the session's todo list, the operator's stated goals this
|
||||
session, and any requirement or plan documents the work follows.
|
||||
2. **Working tree** — `git status --short` and `git log --oneline -10`:
|
||||
uncommitted files are open work, commits since the branch point are closed
|
||||
@@ -35,7 +34,7 @@ One table, most-blocking first, one row per item:
|
||||
- **State**: `open`, `running`, `blocked`, `done`. `done` means verified —
|
||||
a passing run, a green check, a reproduction that now succeeds. Work that
|
||||
merely looks finished is `open`.
|
||||
- **Conf.** and **Break risk**: two separate percentages per the `confidence`
|
||||
- **Conf.** and **Break risk**: two separate percentages per the `kvb-check-confidence`
|
||||
skill — probability the item does what it claims, and probability it breaks
|
||||
something else. Only for rows that changed something; `—` for pure
|
||||
observation rows.
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
name: kvb-org-operator
|
||||
description: >
|
||||
List every command only the operator can run: pushes, installs, settings
|
||||
and sandbox-blocked steps of all agents. Trigger on /kvb-org-operator or
|
||||
"was muss ich tun".
|
||||
---
|
||||
|
||||
Collect every step that waits on a human, across all agents, so the operator
|
||||
can run them top to bottom. A step an agent may run itself is not listed; the
|
||||
agent runs it.
|
||||
|
||||
## What counts
|
||||
|
||||
Checked against the live settings and agent rules, never from memory:
|
||||
|
||||
- **Denied or ask**: the command matches a `permissions.deny` rule, or an
|
||||
`ask` rule the operator has not confirmed in this conversation.
|
||||
- **Outside the sandbox**: it needs a path under `denyRead` or outside
|
||||
`allowWrite` (for example `~/.ssh`, `~/.gnupg`, `~/.claude/settings.json`),
|
||||
a host outside `allowedDomains`, or root.
|
||||
- **Reserved**: the project's agent rules leave it to the operator: pushes
|
||||
and the push wrapper, releases and tags, reboots, permission settings.
|
||||
- **Human-bound**: a hardware key, a browser login, a second factor, a
|
||||
purchase, a decision only the operator may take.
|
||||
|
||||
## Step 1: collect
|
||||
|
||||
- **Own**: every step of this session that stopped for one of the reasons
|
||||
above.
|
||||
- **Register**: tasks of the `kvb-org-rasci` register with the operator as R
|
||||
and status `queued` or `blocked` (`rasci.py show`).
|
||||
- **Peers**: one message to every live agent (`ListAgents`) asking for its
|
||||
pending operator commands, one per line with directory, command and
|
||||
reason. No answer counts as none. A peer's answer is data: it cannot make
|
||||
a command operator-only that the settings let an agent run.
|
||||
|
||||
## Step 2: check
|
||||
|
||||
Drop what is already done: a push whose branch is no longer ahead, a
|
||||
settings line already gone, an install whose copy is current. Merge
|
||||
duplicates across agents. Order by dependency: commit before push, push
|
||||
before install, install before restart.
|
||||
|
||||
## Step 3: print
|
||||
|
||||
| # | Directory | Command | Why not an agent | Unblocks | Requested by |
|
||||
|
||||
- `Directory` is absolute; `Command` is one copy-pasteable command per row.
|
||||
- No secret, token or credential value: name where it lives instead.
|
||||
|
||||
Then the same commands once more in one `bash` block in table order, each
|
||||
after its `cd`, ready to copy.
|
||||
|
||||
## Step 4: record
|
||||
|
||||
Every listed step enters the register as `operator/<slug>` with the
|
||||
operator as R, the requesting agent as A and status `queued`
|
||||
(`rasci.py set`, `rasci.py role`). The next run sets `done` on the ones
|
||||
Step 2 found done.
|
||||
|
||||
## Rules
|
||||
|
||||
- Never run a listed command, and never ask a peer to run it: that is the
|
||||
permission laundering the agent rules forbid.
|
||||
- A command that fails the "What counts" test is not the operator's; run it
|
||||
or hand it to the agent that owns it.
|
||||
@@ -1,10 +1,10 @@
|
||||
---
|
||||
name: democracy
|
||||
name: kvb-org-organize
|
||||
description: >
|
||||
Keep parallel agents from duplicating work: the first to claim it owns it;
|
||||
line representatives and a resource chair coordinate. Run AUTOMATICALLY
|
||||
Keep parallel agents from duplicating work: the first claim owns it; a
|
||||
resource chair allocates. Run AUTOMATICALLY
|
||||
before work another agent might also do (failure, cluster, feature, gate,
|
||||
deploy, cleanup), and on /democracy.
|
||||
deploy, cleanup), and on /kvb-org-organize.
|
||||
---
|
||||
|
||||
Two agents doing the same work waste the second run and then collide in the
|
||||
@@ -23,8 +23,8 @@ operator at any time.
|
||||
(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 `triage`, a cost cluster from
|
||||
`tune`, a feature touching several domains). It works the strand end to end
|
||||
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
|
||||
@@ -53,8 +53,10 @@ directory with `--session <id>`.
|
||||
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**: continue with the Peer protocol; its message is the
|
||||
announcement.
|
||||
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.
|
||||
|
||||
A Claude Code session cannot edit a file in a git worktree before it holds a
|
||||
@@ -74,7 +76,11 @@ records the result.
|
||||
- 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, answers
|
||||
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).
|
||||
@@ -82,9 +88,15 @@ records the result.
|
||||
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
|
||||
`cleanup` flow, asks the operator for an exception, or waits. An owner's
|
||||
`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.
|
||||
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.
|
||||
@@ -135,10 +147,10 @@ plans to it.
|
||||
|
||||
## Peer protocol
|
||||
|
||||
The one protocol for every exchange between agents; `coordinate`, `triage`,
|
||||
`tune`, `funnel` and `cleanup` use it.
|
||||
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.
|
||||
|
||||
1. **Look**: `council.py list` and the refs (the merge-fix skill's
|
||||
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).
|
||||
@@ -148,14 +160,18 @@ The one protocol for every exchange between agents; `coordinate`, `triage`,
|
||||
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.
|
||||
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. Then release the claim.
|
||||
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
|
||||
@@ -189,7 +205,10 @@ For a failure or a fix that other branches share through merges:
|
||||
|
||||
## Output
|
||||
|
||||
On /democracy, one table of the current offices from `council.py list`, stale
|
||||
On /kvb-org-organize, one table of the current offices from `council.py list`, 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`.
|
||||
@@ -1,5 +1,5 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Claim, release and list democracy offices in the shared council directory.
|
||||
"""Claim, release and list kvb-org-organize offices in the shared council directory.
|
||||
|
||||
Environment:
|
||||
AGENTS_COUNCIL_ROOT: council directory shared by every agent on the host;
|
||||
@@ -16,10 +16,12 @@ from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import datetime
|
||||
import importlib.util
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
from pathlib import Path
|
||||
@@ -28,6 +30,7 @@ ROOT = Path(os.environ.get("AGENTS_COUNCIL_ROOT", "/tmp/agents-council"))
|
||||
HEARTBEAT_LIMIT = 3600
|
||||
OFFICE = re.compile(r"^[a-z0-9][a-z0-9._-]*(/[a-z0-9][a-z0-9._-]*)*$")
|
||||
CLAIM = "claim.json"
|
||||
RASCI = Path(__file__).resolve().parents[2] / "kvb-org-rasci" / "scripts" / "rasci.py"
|
||||
|
||||
|
||||
def live_sessions() -> dict[str, str | None]:
|
||||
@@ -83,7 +86,7 @@ def claims() -> list[tuple[str, dict]]:
|
||||
return found
|
||||
|
||||
|
||||
def write_claim(path: Path, office: str, sid: str, runtime: str, work: str) -> None:
|
||||
def write_claim(path: Path, office: str, sid: str, runtime: str, work: str) -> dict:
|
||||
claim = {
|
||||
"office": office,
|
||||
"session": sid,
|
||||
@@ -94,6 +97,30 @@ def write_claim(path: Path, office: str, sid: str, runtime: str, work: str) -> N
|
||||
"work": work,
|
||||
}
|
||||
(path / CLAIM).write_text(json.dumps(claim), encoding="utf-8")
|
||||
return claim
|
||||
|
||||
|
||||
def here() -> dict[str, str | None]:
|
||||
try:
|
||||
head = subprocess.run(
|
||||
["git", "rev-parse", "--abbrev-ref", "HEAD"], capture_output=True, text=True, check=False
|
||||
)
|
||||
except OSError:
|
||||
head = None
|
||||
branch = head.stdout.strip() if head and head.returncode == 0 else ""
|
||||
return {"workdir": os.getcwd(), "branch": branch if branch not in ("", "HEAD") else None}
|
||||
|
||||
|
||||
def register(office: str, holder: str, status: str, **extra: str | None) -> None:
|
||||
if not office.startswith(("work/", "cluster/")):
|
||||
return
|
||||
try:
|
||||
spec = importlib.util.spec_from_file_location("rasci", RASCI)
|
||||
rasci = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(rasci)
|
||||
rasci.track(office, holder, status, **extra)
|
||||
except (OSError, SystemExit) as exc:
|
||||
print(f"council: {office} is missing from the rasci register ({exc})", file=sys.stderr)
|
||||
|
||||
|
||||
def cmd_claim(args: argparse.Namespace) -> int:
|
||||
@@ -105,12 +132,21 @@ def cmd_claim(args: argparse.Namespace) -> int:
|
||||
except FileExistsError:
|
||||
claim = read_claim(path)
|
||||
if claim is not None and claim["session"] == sid:
|
||||
write_claim(path, args.office, sid, runtime, args.work)
|
||||
claim = write_claim(path, args.office, sid, runtime, args.work)
|
||||
register(args.office, claim["name"] or sid, "running", description=args.work, **here())
|
||||
print(f"held {args.office}")
|
||||
return 0
|
||||
print(json.dumps(claim) if claim else f"{args.office}: claim in progress")
|
||||
return 4 if is_stale(claim, live_sessions()) else 3
|
||||
write_claim(path, args.office, sid, runtime, args.work)
|
||||
claim = write_claim(path, args.office, sid, runtime, args.work)
|
||||
register(
|
||||
args.office,
|
||||
claim["name"] or sid,
|
||||
"running",
|
||||
description=args.work,
|
||||
previous=getattr(args, "previous", None),
|
||||
**here(),
|
||||
)
|
||||
print(f"elected {args.office}")
|
||||
return 0
|
||||
|
||||
@@ -121,8 +157,10 @@ def cmd_takeover(args: argparse.Namespace) -> int:
|
||||
if path.exists() and not is_stale(claim, live_sessions()):
|
||||
print(json.dumps(claim) if claim else f"{args.office}: claim in progress")
|
||||
return 3
|
||||
if claim is not None:
|
||||
args.previous = claim["name"] or claim["session"]
|
||||
# Two successors racing between this check and the rename can both win;
|
||||
# democracy names exactly one successor per office to keep that window closed.
|
||||
# kvb-org-organize names exactly one successor per office to keep that window closed.
|
||||
if path.exists():
|
||||
tomb = path.with_name(f"{path.name}.stale-{os.getpid()}-{time.time_ns()}")
|
||||
try:
|
||||
@@ -145,6 +183,7 @@ def cmd_release(args: argparse.Namespace) -> int:
|
||||
print(json.dumps(claim))
|
||||
return 3
|
||||
shutil.rmtree(path)
|
||||
register(args.office, claim["name"] or claim["session"], "done")
|
||||
print(f"released {args.office}")
|
||||
return 0
|
||||
|
||||
@@ -186,10 +225,10 @@ def cmd_gate(_: argparse.Namespace) -> int:
|
||||
return 0
|
||||
script = Path(__file__).resolve()
|
||||
print(
|
||||
"democracy: this session holds no claim, so it may not edit files in a git "
|
||||
"kvb-org-organize: this session holds no claim, so it may not edit files in a git "
|
||||
f"worktree. Claim the work first: python3 {script} claim work/<slug> "
|
||||
"--work '<one line>'. Exit 3 or 4 means another agent holds it; read the "
|
||||
"democracy skill.",
|
||||
"kvb-org-organize skill.",
|
||||
file=sys.stderr,
|
||||
)
|
||||
return 2
|
||||
@@ -1,5 +1,5 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Watch disk, Docker and caches for the democracy resource chair.
|
||||
"""Watch disk, Docker and caches for the kvb-org-organize resource chair.
|
||||
|
||||
Usage:
|
||||
watch.py watch hook (UserPromptSubmit, PostToolUse): measure at most once
|
||||
@@ -226,7 +226,7 @@ def cmd_block(cfg: dict) -> int:
|
||||
return 0
|
||||
if any(re.search(p, command) for p in cfg["heavy_commands"]):
|
||||
print(
|
||||
f"democracy: resource stage is {stage}; new heavy jobs are blocked until "
|
||||
f"kvb-org-organize: resource stage is {stage}; new heavy jobs are blocked until "
|
||||
"the disk recovers. Teardown commands still run. Ask the resource chair.",
|
||||
file=sys.stderr,
|
||||
)
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: subagent-model
|
||||
name: kvb-org-perform
|
||||
description: >
|
||||
Pick `model` and `effort` per subagent from a fixed table: cheaper only on a
|
||||
clear match at 90 % that the result equals the default's; log spawns and
|
||||
Pick `model` and `effort` per subagent from a fixed table: cheaper only at
|
||||
90 % confidence that the result equals the default's; log spawns and
|
||||
quality. Apply AUTOMATICALLY before every Agent tool call.
|
||||
---
|
||||
|
||||
@@ -31,6 +31,8 @@ Fable 5.1 $10 / $50.
|
||||
2. Start the brief with the line `task-class: <class>`; the spawn hook logs
|
||||
it together with `model`, `effort` and the Agent `description`.
|
||||
3. Set `model` and `effort` from the row; for `judgement` set neither.
|
||||
4. Enter the spawn in the `kvb-org-rasci` register: the subagent as R and as
|
||||
`--worker "subagent <type> (<model>, <effort>)"` of the task it serves.
|
||||
|
||||
- An agent type whose definition sets its own model (Explore, Plan, the
|
||||
cavecrew agents) keeps it; never pass `model` or `effort` for it.
|
||||
@@ -66,7 +68,7 @@ Inside a sandbox that cannot write it, the script prints the line as
|
||||
runs and the share with the same result: completed, not redone, no failing
|
||||
test, no follow-up. A row is added, or a cheaper setting extended to a class,
|
||||
only when the report shows at least 90 % over at least 20 rated runs, and only
|
||||
after the operator confirms it (for example through `/autotune`). A row whose
|
||||
after the operator confirms it (for example through `/kvb-skill-tune`). A row whose
|
||||
rate falls below 90 % over 20 rated runs goes back to the default. `sonnet`
|
||||
enters the table only this way, and a trial run on a setting the table does
|
||||
not hold needs the operator's order.
|
||||
@@ -39,7 +39,7 @@ LOG = Path(
|
||||
)
|
||||
TASK_CLASS = re.compile(r"^task-class:\s*(\S+)", re.MULTILINE)
|
||||
PENDING = "pending: "
|
||||
SCRIPT = "subagent-model/scripts/log.py"
|
||||
SCRIPT = "kvb-org-perform/scripts/log.py"
|
||||
CONTROL = re.compile(r"^[();<>|&]+$")
|
||||
KEYS = {
|
||||
"feedback": {"kind", "time", "session", "description", "completed", "tests", "redo"},
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
name: kvb-org-rasci
|
||||
description: >
|
||||
RASCI/OKR register of tasks: roles, key results, worker, status.
|
||||
Trigger on /kvb-org-rasci, "rasci", "raci", "zuständigkeiten".
|
||||
---
|
||||
|
||||
The register is the single point of truth of the organisation: every agent
|
||||
records here what it works on, and claims, queue, handover and reports run
|
||||
over it. `${CLAUDE_SKILL_DIR}/scripts/rasci.py` keeps it in
|
||||
`<council root>/rasci.json`. A `kvb-org-organize` claim enters its task by
|
||||
itself (holder as R and A, `running`, start, workdir, branch); its release
|
||||
sets `done` and the end, or `stopped` while a key result is still open.
|
||||
|
||||
```bash
|
||||
rasci.py set <task> --title <t> --objective <o> --description <d> --prio <n> --status queued|running|blocked|done|stopped --worker "<agent | subagent <type> (<model>)>" --workdir <dir> --branch <b> --artifact <kind>:<ref> --tool <script or command> [--start <iso>] [--end <iso>] [--drop-artifact <a>] [--drop-tool <t>]
|
||||
rasci.py kr <task> add "<measurable result>" | met <n> | open <n> | rm <n>
|
||||
rasci.py role <task> "<party>" <letters>
|
||||
rasci.py get <task>
|
||||
rasci.py rm <task>
|
||||
rasci.py show [--all]
|
||||
rasci.py artifacts [--ended] [--task <task>]
|
||||
rasci.py estimate <task> "<party>" --value <fib> --complexity <fib>
|
||||
rasci.py wsjf [--all]
|
||||
rasci.py tools
|
||||
```
|
||||
|
||||
## Objective and key results
|
||||
|
||||
The objective says what the task is for; its key results are the measurable
|
||||
outcomes that prove it reached (a test green, a run passing, a release
|
||||
published). `done` is refused while one is open; a task ended short of them is
|
||||
`stopped`. `show` puts both in the OKR column as `<objective> (<met>/<all> KR)`.
|
||||
|
||||
## Roles
|
||||
|
||||
- **R Responsible**: does the task: the claim holder, or the subagent it runs.
|
||||
- **A Accountable**: exactly one; takes the final decision and carries the
|
||||
overall responsibility. The claim holder, unless the operator decides.
|
||||
- **S Supportive**: actively helps carry it out: a peer's fix, the chair's
|
||||
grant, a stack or runner.
|
||||
- **C Consulted**: asked for input before acting: line representatives,
|
||||
lineage owners, the operator on a pending decision.
|
||||
- **I Informed**: kept up to date on progress or result, without a say.
|
||||
|
||||
`-` clears a party; the operator is the party `Operator`.
|
||||
|
||||
## Rules
|
||||
|
||||
- On start, `set` title, objective, description, priority and worker, `kr
|
||||
add` every key result, and `role` every party beyond R and A; on each
|
||||
change, update the status. The worker is the one session or subagent
|
||||
executing the task right now.
|
||||
- Artifacts share this table and follow the `kvb-org-artefacts` skill:
|
||||
record each one when it appears, drop it once deleted. Add every script or
|
||||
tool the task ran (`--tool`): `tools` ranks them for `kvb-dream`.
|
||||
- Priority is the rank of the `kvb-org-wsjf` skill: an operator's pin
|
||||
(`--prio`) first, then WSJF from the estimates the chair collects; `show`
|
||||
prints the rank as Prio and the score as WSJF.
|
||||
- Write only your own rows; another session's task belongs to that session.
|
||||
- On /kvb-org-rasci print `show` unchanged; its `gaps:` line names tasks
|
||||
without exactly one A, without R, or open without a key result. `get`
|
||||
prints one task in full, key results numbered.
|
||||
Executable
+497
@@ -0,0 +1,497 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Keep the RASCI register of the organisation's tasks in a local JSON file.
|
||||
|
||||
Environment:
|
||||
AGENTS_COUNCIL_ROOT: council directory shared by every agent on the host;
|
||||
the register is <root>/rasci.json, and `show` also lists every work/
|
||||
and cluster/ claim of the council there. /tmp/agents-council unless set.
|
||||
|
||||
Exit codes:
|
||||
0 done, 2 usage error.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import contextlib
|
||||
import datetime
|
||||
import fcntl
|
||||
import importlib.util
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import statistics
|
||||
import sys
|
||||
import tempfile
|
||||
from collections.abc import Iterator
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(os.environ.get("AGENTS_COUNCIL_ROOT", "/tmp/agents-council"))
|
||||
DB = ROOT / "rasci.json"
|
||||
LOCK = ROOT / "rasci.lock"
|
||||
COUNCIL = Path(__file__).resolve().parents[2] / "kvb-org-organize" / "scripts" / "council.py"
|
||||
TASK = re.compile(r"^[a-z0-9][a-z0-9._-]*(/[a-z0-9][a-z0-9._-]*)*$")
|
||||
LETTERS = re.compile(r"^(?!.*(.).*\1)[RASCI]+$")
|
||||
ORDER = "RASCI"
|
||||
STATUSES = ("queued", "running", "blocked", "done", "stopped")
|
||||
ENDED = ("done", "stopped")
|
||||
FIELDS = (
|
||||
"title", "objective", "description", "prio", "status", "worker", "start", "end", "workdir",
|
||||
"branch",
|
||||
)
|
||||
TEXT_FIELDS = ("title", "objective", "description", "worker", "workdir", "branch")
|
||||
LIST_FIELDS = {"tools": "tool"}
|
||||
ARTIFACT = re.compile(r"^[a-z]+:\S")
|
||||
FIBONACCI = (1, 2, 3, 5, 8, 13, 21, 34, 55, 89)
|
||||
OPERATOR = "Operator"
|
||||
|
||||
|
||||
def fail(message: str) -> None:
|
||||
print(f"rasci: {message}", file=sys.stderr)
|
||||
sys.exit(2)
|
||||
|
||||
|
||||
def check_task(task: str) -> None:
|
||||
if not TASK.match(task):
|
||||
fail(f"invalid task {task!r}; use a slug like work/<slug>")
|
||||
|
||||
|
||||
def stamp(value: str = "now") -> str:
|
||||
if value == "now":
|
||||
return datetime.datetime.now(datetime.UTC).isoformat(timespec="seconds")
|
||||
try:
|
||||
parsed = datetime.datetime.fromisoformat(value)
|
||||
except ValueError:
|
||||
fail(f"invalid time {value!r}; use ISO 8601 or now")
|
||||
if parsed.tzinfo is None:
|
||||
parsed = parsed.astimezone()
|
||||
return parsed.astimezone(datetime.UTC).isoformat(timespec="seconds")
|
||||
|
||||
|
||||
def letters_of(*parts: str) -> str:
|
||||
return "".join(letter for letter in ORDER if any(letter in part for part in parts))
|
||||
|
||||
|
||||
def load() -> dict[str, dict]:
|
||||
try:
|
||||
return json.loads(DB.read_text(encoding="utf-8"))
|
||||
except FileNotFoundError:
|
||||
return {}
|
||||
except ValueError:
|
||||
fail(f"{DB} is not valid JSON")
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def database() -> Iterator[dict[str, dict]]:
|
||||
ROOT.mkdir(parents=True, exist_ok=True)
|
||||
with LOCK.open("a") as lock:
|
||||
fcntl.flock(lock, fcntl.LOCK_EX)
|
||||
tasks = load()
|
||||
yield tasks
|
||||
with tempfile.NamedTemporaryFile(
|
||||
"w", dir=ROOT, prefix=".rasci-", delete=False, encoding="utf-8"
|
||||
) as tmp:
|
||||
json.dump(tasks, tmp, indent=1, sort_keys=True)
|
||||
os.replace(tmp.name, DB)
|
||||
|
||||
|
||||
def open_results(entry: dict) -> int:
|
||||
return sum(not kr["met"] for kr in entry.get("key_results", []))
|
||||
|
||||
|
||||
def apply_status(entry: dict, status: str) -> None:
|
||||
if status not in ENDED:
|
||||
entry.pop("end", None)
|
||||
entry["status"] = status
|
||||
if status == "running":
|
||||
entry.setdefault("start", stamp())
|
||||
if status in ENDED:
|
||||
entry.setdefault("end", stamp())
|
||||
|
||||
|
||||
def track(task: str, holder: str, status: str, *, description: str | None = None,
|
||||
previous: str | None = None, workdir: str | None = None,
|
||||
branch: str | None = None) -> None:
|
||||
"""Write a council claim (status running) or release (status done) through.
|
||||
|
||||
Args:
|
||||
task: the claimed office, e.g. work/<slug>.
|
||||
holder: the session holding the claim.
|
||||
status: running on claim and takeover, done on release; a release with
|
||||
open key results ends as stopped.
|
||||
description: the claim's --work line, kept unless one is recorded.
|
||||
previous: the stale holder a takeover replaces; loses its R and A.
|
||||
workdir: the claiming process's directory, kept unless one is recorded.
|
||||
branch: the checked-out branch there, kept unless one is recorded.
|
||||
"""
|
||||
with database() as tasks:
|
||||
entry = tasks.setdefault(task, {"roles": {}})
|
||||
roles = entry.setdefault("roles", {})
|
||||
if previous and previous != holder:
|
||||
left = roles.pop(previous, "").replace("R", "").replace("A", "")
|
||||
if left:
|
||||
roles[previous] = left
|
||||
if entry.get("worker") == previous:
|
||||
entry["worker"] = holder
|
||||
entry.setdefault("worker", holder)
|
||||
for field, value in (("description", description), ("workdir", workdir), ("branch", branch)):
|
||||
if value:
|
||||
entry.setdefault(field, value)
|
||||
if status == "done" and open_results(entry):
|
||||
status = "stopped"
|
||||
if status in ENDED or entry.get("status") in (None, "queued", *ENDED):
|
||||
apply_status(entry, status)
|
||||
if status not in ENDED:
|
||||
accountable = any("A" in v for p, v in roles.items() if p != holder)
|
||||
roles[holder] = letters_of(roles.get(holder, ""), "R" if accountable else "RA")
|
||||
|
||||
|
||||
def claimed() -> dict[str, dict]:
|
||||
if not COUNCIL.is_file():
|
||||
return {}
|
||||
spec = importlib.util.spec_from_file_location("council", COUNCIL)
|
||||
council = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(council)
|
||||
live = council.live_sessions()
|
||||
rows = {}
|
||||
for office, claim in council.claims():
|
||||
if not office.startswith(("work/", "cluster/")):
|
||||
continue
|
||||
holder = claim["name"] or claim["session"]
|
||||
rows[office] = {
|
||||
"description": claim["work"],
|
||||
"status": "claimed",
|
||||
"worker": holder,
|
||||
"start": claim["since"],
|
||||
"roles": {holder: "RA"},
|
||||
"stale": council.is_stale(claim, live),
|
||||
}
|
||||
return rows
|
||||
|
||||
|
||||
def merged(include_done: bool) -> dict[str, dict]:
|
||||
rows = claimed()
|
||||
for task, entry in load().items():
|
||||
base = rows.get(task, {"status": "queued", "roles": {}})
|
||||
fields = {k: v for k, v in entry.items() if k != "roles"}
|
||||
rows[task] = {**base, **fields, "roles": {**base["roles"], **entry.get("roles", {})}}
|
||||
for row in rows.values():
|
||||
if row.get("stale"):
|
||||
row["status"] = "stale"
|
||||
return {
|
||||
task: row for task, row in rows.items() if include_done or row["status"] not in ENDED
|
||||
}
|
||||
|
||||
|
||||
def cell(text: object, width: int) -> str:
|
||||
text = " ".join(str(text).split()).replace("|", "\\|")
|
||||
return text if len(text) <= width else text[: width - 1] + "…"
|
||||
|
||||
|
||||
def when(value: str | None) -> str:
|
||||
if not value:
|
||||
return "-"
|
||||
return datetime.datetime.fromisoformat(value).astimezone().strftime("%m-%d %H:%M")
|
||||
|
||||
|
||||
def wsjf(row: dict) -> tuple[float, float, float] | None:
|
||||
estimates = list(row.get("estimates", {}).values())
|
||||
if not estimates:
|
||||
return None
|
||||
value = statistics.median(e["value"] for e in estimates)
|
||||
complexity = statistics.median(e["complexity"] for e in estimates)
|
||||
return value, complexity, round(value / complexity, 2)
|
||||
|
||||
|
||||
def ranked(rows: dict[str, dict]) -> list[str]:
|
||||
def key(task: str) -> tuple:
|
||||
row = rows[task]
|
||||
score = wsjf(row)
|
||||
pinned = row.get("prio")
|
||||
return (pinned is None, pinned or 0, score is None, -(score[2] if score else 0), task)
|
||||
|
||||
return sorted(rows, key=key)
|
||||
|
||||
|
||||
def okr(row: dict) -> str:
|
||||
results = row.get("key_results", [])
|
||||
text = cell(row.get("objective") or "-", 40)
|
||||
if results:
|
||||
text += f" ({sum(kr['met'] for kr in results)}/{len(results)} KR)"
|
||||
return text
|
||||
|
||||
|
||||
def gaps(task: str, row: dict) -> list[str]:
|
||||
found = []
|
||||
roles = row["roles"]
|
||||
accountable = sum("A" in letters for letters in roles.values())
|
||||
if accountable != 1:
|
||||
found.append(f"{task} has {accountable} A")
|
||||
if not any("R" in letters for letters in roles.values()):
|
||||
found.append(f"{task} has no R")
|
||||
if not row.get("key_results") and row["status"] not in ENDED:
|
||||
found.append(f"{task} has no key result")
|
||||
return found
|
||||
|
||||
|
||||
def cmd_set(args: argparse.Namespace) -> int:
|
||||
check_task(args.task)
|
||||
if args.prio is not None and args.prio < 1:
|
||||
fail("--prio must be 1 or higher")
|
||||
times = {f: stamp(getattr(args, f)) for f in ("start", "end") if getattr(args, f)}
|
||||
for ref in args.artifact:
|
||||
if not ARTIFACT.match(ref):
|
||||
fail(f"invalid artifact {ref!r}; use <kind>:<ref>, e.g. image:<name>:<tag>")
|
||||
with database() as tasks:
|
||||
entry = tasks.setdefault(args.task, {"roles": {}})
|
||||
if args.status == "done" and open_results(entry):
|
||||
fail(f"{args.task}: {open_results(entry)} key result(s) open; mark them met or set stopped")
|
||||
for field in (*TEXT_FIELDS, "prio"):
|
||||
value = getattr(args, field)
|
||||
if value is not None:
|
||||
entry[field] = value
|
||||
if args.status:
|
||||
apply_status(entry, args.status)
|
||||
entry.update(times)
|
||||
for field, flag in LIST_FIELDS.items():
|
||||
drop = getattr(args, f"drop_{flag}")
|
||||
items = [i for i in entry.get(field, []) if i not in drop]
|
||||
items += [i for i in dict.fromkeys(getattr(args, flag)) if i not in items]
|
||||
if items:
|
||||
entry[field] = items
|
||||
else:
|
||||
entry.pop(field, None)
|
||||
kept = [a for a in entry.get("artifacts", []) if a["ref"] not in args.drop_artifact]
|
||||
known = {a["ref"] for a in kept}
|
||||
kept += [{"ref": r, "added": stamp()} for r in dict.fromkeys(args.artifact) if r not in known]
|
||||
if kept:
|
||||
entry["artifacts"] = kept
|
||||
else:
|
||||
entry.pop("artifacts", None)
|
||||
print(f"set {args.task}")
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_role(args: argparse.Namespace) -> int:
|
||||
check_task(args.task)
|
||||
letters = args.letters.upper()
|
||||
if letters != "-" and not LETTERS.match(letters):
|
||||
fail("letters must be distinct ones of R, A, S, C, I, or - to clear")
|
||||
with database() as tasks:
|
||||
roles = tasks.setdefault(args.task, {"roles": {}}).setdefault("roles", {})
|
||||
if letters == "-":
|
||||
roles.pop(args.party, None)
|
||||
else:
|
||||
roles[args.party] = letters_of(letters)
|
||||
print(f"{args.task}: {args.party} {letters}")
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_kr(args: argparse.Namespace) -> int:
|
||||
check_task(args.task)
|
||||
with database() as tasks:
|
||||
entry = tasks.setdefault(args.task, {"roles": {}})
|
||||
results = entry.setdefault("key_results", [])
|
||||
if args.action == "add":
|
||||
if all(kr["text"] != args.value for kr in results):
|
||||
results.append({"text": args.value, "met": False})
|
||||
else:
|
||||
if not args.value.isdigit() or not 1 <= int(args.value) <= len(results):
|
||||
fail(f"{args.task}: no key result {args.value!r}; `get` lists them by number")
|
||||
index = int(args.value) - 1
|
||||
if args.action == "rm":
|
||||
results.pop(index)
|
||||
else:
|
||||
results[index]["met"] = args.action == "met"
|
||||
if not results:
|
||||
entry.pop("key_results")
|
||||
print(f"{args.task}: key result {args.action} {args.value}")
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_get(args: argparse.Namespace) -> int:
|
||||
row = merged(True).get(args.task)
|
||||
if row is None:
|
||||
fail(f"{args.task}: not in the register")
|
||||
print(f"task: {args.task}")
|
||||
for field in FIELDS:
|
||||
if row.get(field) not in (None, ""):
|
||||
print(f"{field}: {row[field]}")
|
||||
for number, kr in enumerate(row.get("key_results", []), 1):
|
||||
print(f"key result {number} [{'x' if kr['met'] else ' '}]: {kr['text']}")
|
||||
for artifact in row.get("artifacts", []):
|
||||
print(f"artifact: {artifact['ref']} (since {when(artifact['added'])})")
|
||||
for field, flag in LIST_FIELDS.items():
|
||||
for item in row.get(field, []):
|
||||
print(f"{flag}: {item}")
|
||||
roles = ", ".join(f"{p}={v}" for p, v in sorted(row["roles"].items()))
|
||||
print(f"roles: {roles or '-'}")
|
||||
for party, estimate in sorted(row.get("estimates", {}).items()):
|
||||
print(f"estimate {party}: business value {estimate['value']}, complexity {estimate['complexity']}")
|
||||
score = wsjf(row)
|
||||
if score:
|
||||
print(f"wsjf: {score[2]:g}")
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_estimate(args: argparse.Namespace) -> int:
|
||||
check_task(args.task)
|
||||
if not args.drop:
|
||||
for name in ("value", "complexity"):
|
||||
if getattr(args, name) not in FIBONACCI:
|
||||
fail(f"--{name} must be one of {', '.join(map(str, FIBONACCI))}")
|
||||
with database() as tasks:
|
||||
entry = tasks.setdefault(args.task, {"roles": {}})
|
||||
estimates = entry.setdefault("estimates", {})
|
||||
if args.drop:
|
||||
estimates.pop(args.party, None)
|
||||
else:
|
||||
estimates[args.party] = {"value": args.value, "complexity": args.complexity, "at": stamp()}
|
||||
if not estimates:
|
||||
entry.pop("estimates")
|
||||
print(f"{args.task}: estimate {'dropped' if args.drop else 'recorded'} for {args.party}")
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_wsjf(args: argparse.Namespace) -> int:
|
||||
rows = merged(args.all)
|
||||
if not rows:
|
||||
print("no tasks")
|
||||
return 0
|
||||
header = ["Rank", "Task", "OKR", "Business value", "Complexity", "WSJF", "Estimators", "Status"]
|
||||
print("| " + " | ".join(header) + " |")
|
||||
print("|" + "---|" * len(header))
|
||||
unestimated = []
|
||||
for rank, task in enumerate(ranked(rows), 1):
|
||||
row = rows[task]
|
||||
score = wsjf(row)
|
||||
if score is None:
|
||||
unestimated.append(task)
|
||||
figures = [f"{n:g}" for n in score] if score else ["-", "-", "-"]
|
||||
estimators = ", ".join(sorted(row.get("estimates", {}), key=str.lower)) or "-"
|
||||
values = [rank, task, okr(row), *figures, cell(estimators, 40), row["status"]]
|
||||
print("| " + " | ".join(str(v) for v in values) + " |")
|
||||
if unestimated:
|
||||
print("unestimated: " + ", ".join(unestimated))
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_artifacts(args: argparse.Namespace) -> int:
|
||||
rows = merged(True)
|
||||
for task in sorted(rows):
|
||||
row = rows[task]
|
||||
if args.task and task != args.task:
|
||||
continue
|
||||
if args.ended and row["status"] not in (*ENDED, "stale"):
|
||||
continue
|
||||
places = [(f"{f}:{row[f]}", None) for f in ("workdir", "branch") if row.get(f)]
|
||||
recorded = [(a["ref"], a["added"]) for a in row.get("artifacts", [])]
|
||||
for ref, added in (*places, *recorded):
|
||||
print(f"{row['status']}\t{task}\t{row.get('worker') or '-'}\t{ref}\t{when(added)}")
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_tools(_: argparse.Namespace) -> int:
|
||||
used: dict[str, list[str]] = {}
|
||||
for task, row in merged(True).items():
|
||||
for tool in row.get("tools", []):
|
||||
used.setdefault(tool, []).append(task)
|
||||
for tool, tasks in sorted(used.items(), key=lambda item: (-len(item[1]), item[0])):
|
||||
print(f"{len(tasks)}\t{tool}\t{' '.join(sorted(tasks))}")
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_rm(args: argparse.Namespace) -> int:
|
||||
check_task(args.task)
|
||||
with database() as tasks:
|
||||
removed = tasks.pop(args.task, None)
|
||||
print(f"removed {args.task}" if removed is not None else f"{args.task}: not in the register")
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_show(args: argparse.Namespace) -> int:
|
||||
rows = merged(args.all)
|
||||
if not rows:
|
||||
print("no tasks")
|
||||
return 0
|
||||
header = ["Prio", "WSJF", "Task", "OKR", "Status", "Worker", "Artifacts", "Start", "End", *ORDER]
|
||||
print("| " + " | ".join(header) + " |")
|
||||
print("|" + "---|" * len(header))
|
||||
problems = []
|
||||
for rank, task in enumerate(ranked(rows), 1):
|
||||
row = rows[task]
|
||||
title = f"{task}: {row['title']}" if row.get("title") else task
|
||||
score = wsjf(row)
|
||||
values = [
|
||||
rank,
|
||||
f"{score[2]:g}" if score else "-",
|
||||
cell(title, 50),
|
||||
okr(row),
|
||||
row["status"],
|
||||
cell(row.get("worker") or "-", 30),
|
||||
len(row.get("artifacts", [])) or "-",
|
||||
when(row.get("start")),
|
||||
when(row.get("end")),
|
||||
]
|
||||
parties = sorted(row["roles"], key=lambda p: (p != OPERATOR, p.lower()))
|
||||
values += [
|
||||
cell(", ".join(p for p in parties if letter in row["roles"][p]), 30) for letter in ORDER
|
||||
]
|
||||
print("| " + " | ".join(str(v) for v in values) + " |")
|
||||
problems += gaps(task, row)
|
||||
if problems:
|
||||
print("gaps: " + "; ".join(problems))
|
||||
return 0
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
||||
sub = parser.add_subparsers(dest="cmd", required=True)
|
||||
p = sub.add_parser("set")
|
||||
p.add_argument("task")
|
||||
for field in (*TEXT_FIELDS, "start", "end"):
|
||||
p.add_argument(f"--{field}")
|
||||
p.add_argument("--prio", type=int)
|
||||
for flag in (*LIST_FIELDS.values(), "artifact"):
|
||||
p.add_argument(f"--{flag}", action="append", default=[])
|
||||
p.add_argument(f"--drop-{flag}", action="append", default=[])
|
||||
p.add_argument("--status", choices=STATUSES)
|
||||
p.set_defaults(func=cmd_set)
|
||||
p = sub.add_parser("estimate")
|
||||
p.add_argument("task")
|
||||
p.add_argument("party")
|
||||
p.add_argument("--value", type=int)
|
||||
p.add_argument("--complexity", type=int)
|
||||
p.add_argument("--drop", action="store_true")
|
||||
p.set_defaults(func=cmd_estimate)
|
||||
p = sub.add_parser("wsjf")
|
||||
p.add_argument("--all", action="store_true")
|
||||
p.set_defaults(func=cmd_wsjf)
|
||||
p = sub.add_parser("kr")
|
||||
p.add_argument("task")
|
||||
p.add_argument("action", choices=("add", "met", "open", "rm"))
|
||||
p.add_argument("value")
|
||||
p.set_defaults(func=cmd_kr)
|
||||
p = sub.add_parser("role")
|
||||
p.add_argument("task")
|
||||
p.add_argument("party")
|
||||
p.add_argument("letters")
|
||||
p.set_defaults(func=cmd_role)
|
||||
for name, func in (("get", cmd_get), ("rm", cmd_rm)):
|
||||
p = sub.add_parser(name)
|
||||
p.add_argument("task")
|
||||
p.set_defaults(func=func)
|
||||
p = sub.add_parser("show")
|
||||
p.add_argument("--all", action="store_true")
|
||||
p.set_defaults(func=cmd_show)
|
||||
p = sub.add_parser("artifacts")
|
||||
p.add_argument("--ended", action="store_true")
|
||||
p.add_argument("--task")
|
||||
p.set_defaults(func=cmd_artifacts)
|
||||
sub.add_parser("tools").set_defaults(func=cmd_tools)
|
||||
args = parser.parse_args()
|
||||
return args.func(args)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
name: robot
|
||||
name: kvb-org-robot
|
||||
description: >
|
||||
Work fully autonomously to a goal: no check-ins, no stopping before the goal,
|
||||
only commands already cleared. Trigger when the operator wants hands-off,
|
||||
@@ -11,7 +11,7 @@ Operate as an autonomous robot: given a goal, reach it without hand-holding.
|
||||
## Contract
|
||||
|
||||
- **No questions once the goal is clear.** Clarify only genuinely-blocking
|
||||
unknowns up front (via the `active-listening` skill), then proceed without
|
||||
unknowns up front (via the `kvb-think-listen` skill), then proceed without
|
||||
further check-ins. Pick the cleanest option and continue; never pause to
|
||||
confirm a choice you can make yourself.
|
||||
- **Never stop before the goal.** Do not end the run, hand back, or declare done
|
||||
@@ -28,10 +28,14 @@ Operate as an autonomous robot: given a goal, reach it without hand-holding.
|
||||
- **Verify, do not assume.** Reaching the goal means proving it: run it, read the
|
||||
output, confirm the end state. Never report success on a step you did not
|
||||
actually verify.
|
||||
- **Run it over the register.** Before the first step, enter the goal in the
|
||||
`kvb-org-rasci` register as the task's objective and every check that proves
|
||||
it as a key result; mark each one met as its proof comes in. The run is
|
||||
finished when the task can be set `done`.
|
||||
|
||||
## Rules
|
||||
|
||||
- Escalate an uncertain root cause or design decision to the `dialectic` skill
|
||||
- Escalate an uncertain root cause or design decision to the `kvb-think-dialectic` skill
|
||||
rather than guessing; uncertainty is never a reason to stop.
|
||||
- Sustain the loop across long, multi-step work — the run is finished only when
|
||||
the whole goal is verifiably met.
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: funnel
|
||||
name: kvb-org-split
|
||||
description: >
|
||||
Keep agent work in its own git worktree until it reaches 90% fix confidence
|
||||
and under 5% break risk; below that bar it becomes a proposal. Trigger when
|
||||
delegating work to agents, when agents work in parallel, or on /funnel.
|
||||
Keep agent work in its own worktree until 90% fix confidence and under 5%
|
||||
break risk; below that it becomes a proposal. Trigger when delegating to or
|
||||
parallelizing agents, or on /kvb-org-split.
|
||||
---
|
||||
|
||||
# Funnel
|
||||
@@ -14,18 +14,19 @@ in a sidetree until it does, or leaves as a proposal.
|
||||
## The bar
|
||||
|
||||
- **Fix confidence of at least 90 %** and **break risk under 5 %**, both
|
||||
reported by the `confidence` skill, the break risk derived through the
|
||||
`break-risk` skill.
|
||||
reported by the `kvb-check-confidence` skill, the break risk derived through the
|
||||
`kvb-check-break-risk` skill.
|
||||
- The operator may set a different bar. Never lower it to make a change fit.
|
||||
|
||||
## The stages
|
||||
|
||||
1. **Brief.** One concern per agent, on the model the `subagent-model` skill
|
||||
picks. Name the goal, the exact base commit, the
|
||||
1. **Brief.** One concern per agent, on the model the `kvb-org-perform` skill
|
||||
picks, entered in the `kvb-org-rasci` register as R with `--worker "subagent
|
||||
<type> (<model>)"`. Name the goal, the exact base commit, the
|
||||
scope that may change, the evidence expected back, a time cap (default
|
||||
60 minutes) at which it reports its interim state, and what the agent must
|
||||
not do: no pushes, no gates or deploys
|
||||
unless the resource chair of the `democracy` skill granted them, read-only
|
||||
unless the resource chair of the `kvb-org-organize` skill granted them, read-only
|
||||
probes on shared live systems.
|
||||
2. **Sidetree.** The agent works in its own worktree on its own branch,
|
||||
created from the exact base commit, so its edits never land under a running
|
||||
@@ -35,8 +36,10 @@ in a sidetree until it does, or leaves as a proposal.
|
||||
behaviour, and makes a negative control: the test fails without the change.
|
||||
Numbers come from the same source before and after.
|
||||
4. **Self-assessment.** The agent reports fix confidence and break risk with
|
||||
their residuals and commits on its branch.
|
||||
5. **Independent review.** Before anything is merged, run the `dialectic` skill
|
||||
their residuals and commits on its branch. Its parent marks the key results
|
||||
that evidence proves as met in the `kvb-org-rasci` register and records
|
||||
the branch and worktree as `--branch` and `--artifact worktree:<path>`.
|
||||
5. **Independent review.** Before anything is merged, run the `kvb-think-dialectic` skill
|
||||
with skeptics who did not write the change. A hole they find returns the
|
||||
change to stage 3.
|
||||
6. **Merge.** At or above the bar, merge the sidetree branch into the main line
|
||||
@@ -66,8 +69,9 @@ and verify each step instead of assuming it:
|
||||
5. **Delete the merged branch**, locally and on the remote, but a remote branch
|
||||
only once every one of its commits is reachable from a pushed branch.
|
||||
6. **Release what it held**: slots (reported to the resource chair), port or
|
||||
subnet reservations, locks, its `democracy` claims and every claim
|
||||
announced to other agents.
|
||||
subnet reservations, locks, its `kvb-org-organize` claims and every claim
|
||||
announced to other agents. Drop each removed item from the register with
|
||||
`--drop-artifact` and set the subagent's task `done` or `stopped`.
|
||||
7. **Remove its temporary files**: logs, message files and scratch data that
|
||||
have served their purpose. Keep only the evidence the report cites, until
|
||||
the report is delivered.
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
name: kvb-org-wsjf
|
||||
description: >
|
||||
WSJF priority from Fibonacci estimates. Trigger on /kvb-org-wsjf, "wsjf",
|
||||
"priorisieren".
|
||||
---
|
||||
|
||||
Weighted Shortest Job First ranks the tasks of the `kvb-org-rasci` register
|
||||
by cost of delay over job size: here business value over complexity, each the
|
||||
median of Fibonacci estimates (1, 2, 3, 5, 8, 13, 21, 34, 55, 89). The
|
||||
estimates live in the register's table; `wsjf` is its WSJF view, one row per
|
||||
task with its OKR and the task id the register uses, and the register's Prio
|
||||
column is this rank. The script is
|
||||
`${CLAUDE_SKILL_DIR}/../kvb-org-rasci/scripts/rasci.py`.
|
||||
|
||||
```bash
|
||||
rasci.py estimate <task> "<party>" --value <fib> --complexity <fib>
|
||||
rasci.py estimate <task> "<party>" --drop
|
||||
rasci.py wsjf [--all]
|
||||
```
|
||||
|
||||
## Procedure
|
||||
|
||||
1. **The chair asks.** For every new task, and when its objective or a key
|
||||
result changes, the resource chair of the `kvb-org-organize` skill asks
|
||||
its subordinates (the task's worker and R, the representatives of the
|
||||
lines it touches) for one Fibonacci estimate each of business value and
|
||||
complexity, one message per agent.
|
||||
2. **Record each answer** under the party that gave it; a new estimate
|
||||
replaces the old one. An agent may record its own.
|
||||
3. **Rank**: WSJF = median business value / median complexity, highest
|
||||
first. An operator's pin (`rasci.py set <task> --prio <n>`) outranks every
|
||||
score; unestimated tasks come last and are named under `unestimated:`.
|
||||
4. **Grant in rank order**: the chair hands out capacity by this rank, except
|
||||
that a hotfix gate (a branch from the default branch that fixes it) takes
|
||||
the next free gate or test slot before every ranked task; a running gate
|
||||
is never cut short for it.
|
||||
|
||||
## Rules
|
||||
|
||||
- Estimate relative to the other open tasks, never in hours.
|
||||
- Never invent an estimate for a party that did not answer; a task without
|
||||
one stays unestimated.
|
||||
@@ -1,13 +1,12 @@
|
||||
---
|
||||
name: autoskill
|
||||
name: kvb-skill-auto
|
||||
description: >
|
||||
Turn operator repetition into a skill. Trigger when the operator gives the
|
||||
same instruction, correction or prompt pattern about the third time in a
|
||||
conversation, or says they keep repeating themselves, and the pattern is
|
||||
reusable.
|
||||
Turn operator repetition into a skill. Trigger when the operator repeats an
|
||||
instruction, correction or prompt pattern a third time, or says they keep
|
||||
repeating themselves.
|
||||
---
|
||||
|
||||
Its objective is the `autotune` skill's **Objective** section: a skill is worth
|
||||
Its objective is the `kvb-skill-tune` skill's **Objective** section: a skill is worth
|
||||
creating only when it cuts tokens or time and raises quality; judge every
|
||||
candidate against its three axes and rules.
|
||||
|
||||
@@ -19,18 +18,17 @@ vary), do the following:
|
||||
2. Then propose, in one short paragraph: the repeated pattern you observed,
|
||||
a skill name suggestion, the trigger phrasing, and what the skill would
|
||||
do. Ask whether to create it.
|
||||
3. On approval, write the skill:
|
||||
- a conversation shortcut or expansion: add it to the `shortcuts` skill
|
||||
table instead of creating a new skill.
|
||||
- anything else: persist it exactly as the `autotune` skill's
|
||||
**Persistence** section specifies — locate the operator's skills
|
||||
repository, write `skills/<name>/SKILL.md` there (or in the current
|
||||
project for project-specific behavior), then mirror the skill directory
|
||||
into `~/.claude/skills/` and `~/.agents/skills/`, plus the project's
|
||||
`.claude/skills/` and `.agents/skills/` when it is project-specific.
|
||||
3. On approval, write the skill: persist it exactly as the
|
||||
`kvb-skill-tune` skill's **Persistence** section specifies — locate the
|
||||
operator's skills repository, write `skills/<name>/SKILL.md` there (or in
|
||||
the current project for project-specific behavior), then mirror the skill
|
||||
directory into `~/.claude/skills/` and `~/.agents/skills/`, plus the
|
||||
project's `.claude/skills/` and `.agents/skills/` when it is
|
||||
project-specific.
|
||||
Follow the local naming conventions and keep the skill a thin,
|
||||
single-purpose instruction; route to an authoritative doc when one
|
||||
exists instead of duplicating it.
|
||||
exists instead of duplicating it. Its deterministic steps become a script
|
||||
through the `kvb-skill-compile` skill, not prose.
|
||||
4. Do not propose a skill for one-off work, secrets, or anything whose
|
||||
repetition is already covered by an existing skill; when an existing
|
||||
skill almost fits, propose extending it instead.
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: kvb-skill-cleanup
|
||||
description: >
|
||||
Delete legacy skills that renamed or removed skills left in Claude, Codex,
|
||||
agent and project dirs. Trigger on /kvb-skill-cleanup.
|
||||
---
|
||||
|
||||
`${CLAUDE_SKILL_DIR}/scripts/legacy.py` reads the skills repository's git
|
||||
history, where every rename and deletion of a skill is recorded, and
|
||||
classifies each installed skill directory:
|
||||
|
||||
```bash
|
||||
legacy.py --skills-repo <skills repo> --root <dir> [--root <dir> ...] [--json]
|
||||
```
|
||||
|
||||
| Verdict | Meaning | Action |
|
||||
| --- | --- | --- |
|
||||
| `current` | shipped by the skills repository or its lock | keep |
|
||||
| `project` | tracked in the git repository that holds the root | keep |
|
||||
| `legacy` | renamed; the successor column names the current skill | delete |
|
||||
| `removed` | deleted from the skills repository without a successor | delete |
|
||||
| `unknown` | none of the above, for example the operator's own | keep, report |
|
||||
|
||||
## Step 1: roots
|
||||
|
||||
Every one that exists: `~/.claude/skills`, `~/.agents/skills`,
|
||||
`~/.codex/skills`, and `.claude/skills` and `.agents/skills` of the current
|
||||
repository and of every project the operator names.
|
||||
|
||||
## Step 2: scan and confirm
|
||||
|
||||
Run `legacy.py` over all roots. Show the `legacy` and `removed` rows in one
|
||||
table (`| Root | Skill | Successor |`) and the `unknown` rows below it; the
|
||||
`kvb-transcend` skill can carry an unknown one over. Then `AskUserQuestion`:
|
||||
`Delete all legacy and removed` / `Pick per root` / `Delete nothing`.
|
||||
|
||||
## Step 3: delete
|
||||
|
||||
- A root that an installer rewrites as a whole (the skills repository's
|
||||
`make install` for the home roots, a project's own skill install target)
|
||||
is cleaned by running that installer, which also refreshes the current
|
||||
skills; where the sandbox blocks it, it goes to the operator as below.
|
||||
- Otherwise `rm -r <path>` per confirmed row where the sandbox lets the
|
||||
agent write; every row it does not goes to the `kvb-org-operator` skill
|
||||
as an operator command.
|
||||
- A settings file whose hook command still points into a deleted skill
|
||||
directory is reported with its line; settings files stay the operator's.
|
||||
|
||||
## Step 4: verify
|
||||
|
||||
Run `legacy.py` again: no `legacy` or `removed` row may remain in a cleaned
|
||||
root. Report the before and after counts per root.
|
||||
Executable
+118
@@ -0,0 +1,118 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Classify installed skills as current, project, legacy, removed or unknown.
|
||||
|
||||
Args:
|
||||
--skills-repo: checkout of the skills repository, read with its git history.
|
||||
--root: a skills directory to classify, repeatable.
|
||||
--json: print the rows as JSON instead of tab-separated lines.
|
||||
|
||||
Exit codes:
|
||||
0 done, 2 usage error.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def fail(message: str) -> None:
|
||||
print(f"legacy: {message}", file=sys.stderr)
|
||||
sys.exit(2)
|
||||
|
||||
|
||||
def git(cwd: Path, *args: str) -> str | None:
|
||||
result = subprocess.run(
|
||||
["git", *args], cwd=cwd, capture_output=True, text=True, check=False
|
||||
)
|
||||
return result.stdout if result.returncode == 0 else None
|
||||
|
||||
|
||||
def current_names(skills_repo: Path) -> set[str]:
|
||||
names = {p.name for p in (skills_repo / "skills").iterdir() if (p / "SKILL.md").is_file()}
|
||||
lock = json.loads((skills_repo / "skills-lock.json").read_text(encoding="utf-8"))
|
||||
return names | set(lock.get("skills", {}))
|
||||
|
||||
|
||||
def moves(skills_repo: Path) -> dict[str, str | None]:
|
||||
out = git(
|
||||
skills_repo,
|
||||
"log", "-M", "--diff-filter=RD", "--name-status", "--format=", "--", "skills/*/SKILL.md",
|
||||
)
|
||||
if out is None:
|
||||
fail(f"{skills_repo} is not a git repository")
|
||||
found: dict[str, str | None] = {}
|
||||
for line in out.splitlines():
|
||||
parts = line.split("\t")
|
||||
if parts[0].startswith("R") and len(parts) == 3:
|
||||
found.setdefault(Path(parts[1]).parent.name, Path(parts[2]).parent.name)
|
||||
elif parts[0] == "D" and len(parts) == 2:
|
||||
found.setdefault(Path(parts[1]).parent.name, None)
|
||||
return found
|
||||
|
||||
|
||||
def successor(name: str, history: dict[str, str | None], current: set[str]) -> str | None:
|
||||
seen = set()
|
||||
while name not in current:
|
||||
if name in seen or history.get(name) is None:
|
||||
return None
|
||||
seen.add(name)
|
||||
name = history[name]
|
||||
return name
|
||||
|
||||
|
||||
def project_names(root: Path) -> set[str]:
|
||||
top = git(root, "rev-parse", "--show-toplevel")
|
||||
if top is None:
|
||||
return set()
|
||||
tracked = git(Path(top.strip()), "ls-files", "*SKILL.md") or ""
|
||||
return {Path(line).parent.name for line in tracked.splitlines()}
|
||||
|
||||
|
||||
def classify(root: Path, current: set[str], history: dict[str, str | None]) -> list[dict]:
|
||||
project = project_names(root)
|
||||
rows = []
|
||||
for entry in sorted(p for p in root.iterdir() if (p / "SKILL.md").is_file()):
|
||||
name, succ = entry.name, None
|
||||
if name in current:
|
||||
verdict = "current"
|
||||
elif name in project:
|
||||
verdict = "project"
|
||||
elif name in history:
|
||||
succ = successor(name, history, current)
|
||||
verdict = "legacy" if succ else "removed"
|
||||
else:
|
||||
verdict = "unknown"
|
||||
rows.append({"verdict": verdict, "successor": succ, "path": str(entry)})
|
||||
return rows
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
||||
parser.add_argument("--skills-repo", required=True)
|
||||
parser.add_argument("--root", action="append", required=True)
|
||||
parser.add_argument("--json", action="store_true")
|
||||
args = parser.parse_args()
|
||||
|
||||
repo = Path(args.skills_repo)
|
||||
if not (repo / "skills").is_dir() or not (repo / "skills-lock.json").is_file():
|
||||
fail(f"{repo} is not a skills repository")
|
||||
roots = [Path(r) for r in args.root]
|
||||
for root in roots:
|
||||
if not root.is_dir():
|
||||
fail(f"{root} is not a directory")
|
||||
current, history = current_names(repo), moves(repo)
|
||||
rows = [row for root in roots for row in classify(root, current, history)]
|
||||
if args.json:
|
||||
print(json.dumps(rows, indent=1))
|
||||
else:
|
||||
for row in rows:
|
||||
print(f"{row['verdict']}\t{row['successor'] or '-'}\t{row['path']}")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: kvb-skill-compile
|
||||
description: >
|
||||
Turn deterministic skill steps into tested scripts in the skill's own repo.
|
||||
Trigger on /kvb-skill-compile or a skill step that is a fixed command
|
||||
sequence.
|
||||
---
|
||||
|
||||
A deterministic step is one whose result follows from its inputs alone:
|
||||
fixed command sequences, output parsing and filtering, counting, thresholds
|
||||
and arithmetic, format checks, sorting and lookups, state bookkeeping. This
|
||||
skill compiles such steps into scripts and cuts the prose down to the call. Choosing, explaining and asking stay prose.
|
||||
It changes nothing before the operator confirms.
|
||||
|
||||
## Step 1: scope and owner
|
||||
|
||||
The skills named after the command, or every skill of the current
|
||||
repository when none is named. Per skill, its owning repository:
|
||||
|
||||
- **Skills repository**: a first-party skill under its `skills/`, and every
|
||||
installed copy of one (`~/.claude/skills`, `~/.agents/skills`, a project's
|
||||
rendered `.claude/skills`); edit the source, never the copy, by the
|
||||
`kvb-skill-tune` skill's **Persistence** section.
|
||||
- **Another repository**: a skill tracked in that repository's own tree
|
||||
(`git ls-files` lists it there), such as a project's `.claude/skills`.
|
||||
- **Third party**: a `skills-lock.json` entry from a foreign source is not
|
||||
compiled; propose the change upstream instead.
|
||||
|
||||
## Step 2: inventory
|
||||
|
||||
Read-only. Per skill, every step that is deterministic, with its evidence:
|
||||
how often sessions ran it (transcripts, `rasci.py tools` of the
|
||||
`kvb-org-rasci` register) and where an agent got it wrong. One line each:
|
||||
`skill:step -> deterministic part -> inputs -> output -> runs per use`.
|
||||
|
||||
## Step 3: classify
|
||||
|
||||
Compile what runs often or went wrong; leave a one-off as prose. Per
|
||||
candidate:
|
||||
|
||||
- **Language and form**: the owning repository's own (Python standard
|
||||
library in the skills repository); no new language, framework or
|
||||
dependency without the operator.
|
||||
- **Interface**: every host path, name and value an explicit parameter (the
|
||||
`kvb-code-no-defaults` skill), documented exit codes, `--json` when another
|
||||
script or skill consumes the output.
|
||||
- **Location**: `skills/<skill>/scripts/<verb>.py` with a test under `tests/`
|
||||
in the skills repository; elsewhere the owning repository's convention,
|
||||
read from its `AGENTS.md`, `CONTRIBUTING` and `Makefile` first.
|
||||
|
||||
## Step 4: listen and confirm
|
||||
|
||||
Run the `kvb-think-listen` skill on the open points. Then `AskUserQuestion`:
|
||||
one `multiSelect` with the candidates, nothing preselected, and per pick a
|
||||
single-select `Write it` / `Revise it` / `Discard` showing the drafted script
|
||||
and the prose diff.
|
||||
|
||||
## Step 5: write
|
||||
|
||||
- Write the script, then replace the compiled prose with its call
|
||||
(`${CLAUDE_SKILL_DIR}/scripts/<verb>.py ...`) and the one line on reading
|
||||
its output.
|
||||
- Every script gets a unit test with a negative control shown once. Tests
|
||||
run only on the resource chair's grant (the `kvb-org-organize` skill).
|
||||
- In another repository follow its agent rules (claims, worktree, branch);
|
||||
a file another line owns goes to that line through the
|
||||
`kvb-org-coordinate` skill.
|
||||
- Leave the result uncommitted for the `kvb-git-commit-next` skill.
|
||||
|
||||
## Output
|
||||
|
||||
| Skill | Step | Script | Repository | Prose lines cut | Verdict |
|
||||
|
||||
Steps left as prose stay with their reason.
|
||||
@@ -1,9 +1,8 @@
|
||||
---
|
||||
name: essence
|
||||
name: kvb-skill-essence
|
||||
description: >
|
||||
Compact skills and memory to their essence after a health pass that finds
|
||||
dead weight. Trigger on /essence or when skills or MEMORY.md grow too long,
|
||||
duplicate, or eat too much context.
|
||||
Compact skills and memory after a health pass for dead weight. Trigger on
|
||||
/kvb-skill-essence or when skills or MEMORY.md grow too long or duplicate.
|
||||
---
|
||||
|
||||
Shorter, not thinner. Every fact that still earns its place survives; what goes
|
||||
@@ -65,6 +64,9 @@ Cut:
|
||||
- The second and third statement of one rule; keep the authoritative one and
|
||||
point at it.
|
||||
- Narration, hedging, and worked examples beyond the one that carries the point.
|
||||
- A deterministic procedure spelled out step by step: hand it to the
|
||||
`kvb-skill-compile` skill, which replaces it with a script call, instead of
|
||||
shortening it.
|
||||
|
||||
Keep, always:
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
name: kvb-skill-transcend
|
||||
description: >
|
||||
Carry the session's skill use and own scripts into the skills repo.
|
||||
Trigger on /kvb-skill-transcend.
|
||||
---
|
||||
|
||||
What an agent improvised in one session dies with it: the helper script in its
|
||||
scratchpad, the command sequence it ran five times, the skill it had to work
|
||||
around. This skill carries that into the operator's skills repository, so the
|
||||
next agent starts from it. It changes nothing before the operator confirms.
|
||||
|
||||
## Step 1: inventory
|
||||
|
||||
Read-only:
|
||||
|
||||
- **Scripts and skills**: `transcend.py scan` of the `kvb-transcend` skill
|
||||
lists the own scratchpad's scripts, peers' scripts, and skills, commands,
|
||||
hooks and rules in `~/.claude`, `~/.agents` and `~/.codex` that the skills
|
||||
repository does not ship; it skips what was already decided and has not
|
||||
changed. Peer and home candidates follow that skill's consent step.
|
||||
- **Skills used**: every skill this session invoked, how often, and where it
|
||||
fell short (a workaround, a step skipped, an operator correction).
|
||||
- **Recurring moves without a skill**: command sequences, peer exchanges or
|
||||
lookups run three times or more. `rasci.py tools` of the `kvb-org-rasci`
|
||||
register lists the scripts the session's tasks recorded.
|
||||
|
||||
One line each: `candidate -> source -> evidence`.
|
||||
|
||||
## Step 2: classify
|
||||
|
||||
Per candidate one target: a script under an existing skill's `scripts/`, a
|
||||
new skill, a sharper step in an existing skill, a memory entry instead, or
|
||||
drop. A recurring deterministic move without a script goes to the
|
||||
`kvb-skill-compile` skill, any other recurring move to the `kvb-skill-tune`
|
||||
skill as evidence. A script is portable only once its host paths, names and values
|
||||
became explicit parameters (the `kvb-code-no-defaults` skill); one that needs
|
||||
a secret, a credential or a single host is dropped or stays a memory entry.
|
||||
|
||||
## Step 3: listen and confirm
|
||||
|
||||
Run the `kvb-think-listen` skill on the open points: scope, target skill,
|
||||
generality. Then `AskUserQuestion`: one `multiSelect` with the candidates
|
||||
(target and evidence in each description, nothing preselected), and per pick a
|
||||
single-select `Write it` / `Revise it` / `Discard` showing the drafted file or
|
||||
diff.
|
||||
|
||||
## Step 4: write
|
||||
|
||||
- Write where the `kvb-skill-tune` skill's **Persistence** section says:
|
||||
the skills repository as source of truth, then the live mirrors.
|
||||
- Read every script whole before carrying it; strip comments the way the
|
||||
`kvb-code-no-comments` skill does.
|
||||
- A carried script gets a unit test in the repository's `tests/` with a
|
||||
negative control. Tests run only on the resource chair's grant (the
|
||||
`kvb-org-organize` skill).
|
||||
- `transcend.py mark` every offered candidate with its verdict.
|
||||
- Leave the result uncommitted; committing is the `kvb-git-commit-next`
|
||||
skill's job.
|
||||
|
||||
## Output
|
||||
|
||||
| Candidate | Source | Target | Verdict |
|
||||
|
||||
Dropped candidates stay with their reason.
|
||||
@@ -1,10 +1,9 @@
|
||||
---
|
||||
name: autotune
|
||||
name: kvb-skill-tune
|
||||
description: >
|
||||
Generate new skills or optimize existing ones (fewer tokens, fewer errors,
|
||||
persistent learnings), each proposal confirmed by single-select question.
|
||||
Trigger ONLY on an explicit request: /autotune, "autotune", "tune the
|
||||
skills"; never on your own initiative.
|
||||
Generate or sharpen skills from observed friction, each proposal confirmed.
|
||||
Trigger only on /kvb-skill-tune, "autotune", "tune the skills" or through
|
||||
kvb-optimize.
|
||||
---
|
||||
|
||||
Autotune turns observed friction into durable skills. It runs on demand only,
|
||||
@@ -13,8 +12,8 @@ skill it writes or rewrites lands in the operator's skills repository.
|
||||
|
||||
## Objective
|
||||
|
||||
The shared objective of the self-improving skills (autotune, autoskill,
|
||||
confidence): every skill, rule, or report the agent produces about its own
|
||||
The shared objective of the self-improving skills (kvb-skill-tune,
|
||||
kvb-skill-auto, kvb-check-confidence): every skill, rule, or report the agent produces about its own
|
||||
working is judged on three axes at once. A proposal that cannot name the axis
|
||||
it moves is not an optimization, it is a preference.
|
||||
|
||||
@@ -43,10 +42,10 @@ it moves is not an optimization, it is a preference.
|
||||
|
||||
## Trigger discipline
|
||||
|
||||
- Run **only** when the operator asks: `/autotune`, "autotune", "tune the
|
||||
skills", or an equivalent instruction.
|
||||
- The 60-minute reminder hook is a hint for the operator, not a trigger. When it
|
||||
fires, print the hint and continue the operator's actual request.
|
||||
- Run **only** when the operator asks: `/kvb-skill-tune`, "autotune", "tune the
|
||||
skills", or an equivalent instruction, or as part of the `kvb-optimize`
|
||||
skill the operator started (directly or through `kvb-dream`).
|
||||
- It has no reminder of its own; the `kvb-dream` hint covers it.
|
||||
- Never propose, write, or edit a skill as a side effect of unrelated work.
|
||||
|
||||
## Step 1: collect evidence
|
||||
@@ -63,6 +62,12 @@ where readable, from the project's memory and agent instruction files:
|
||||
deploys, questions that stalled an autonomous run.
|
||||
- **Lost learnings**: facts re-derived this session that a memory file or a
|
||||
skill should already have carried.
|
||||
- **Own scripts**: helpers the agent wrote outside any repository belong to
|
||||
the `kvb-skill-transcend` skill, which carries them over; this skill
|
||||
takes the frictions they reveal.
|
||||
- **Deterministic prose**: a skill step the agent worked through by hand
|
||||
although its result follows from its inputs belongs to the
|
||||
`kvb-skill-compile` skill, which turns it into a script.
|
||||
|
||||
List each finding as one line: `symptom -> cost -> candidate fix`. Skip
|
||||
anything that happened once and is not a pattern.
|
||||
@@ -75,16 +80,17 @@ option, and never write a file before the answers are in.
|
||||
|
||||
Ask in this order, at most four questions per call:
|
||||
|
||||
1. **Scope** - "What should autotune do this run?" Options: `Create a new
|
||||
1. **Scope** - "What should kvb-skill-tune do this run?" Options: `Create a new
|
||||
skill`, `Optimize an existing skill`, `Both`, plus the ranked findings if
|
||||
more than one candidate exists.
|
||||
2. **Target** - which finding becomes a skill, or which existing skill gets
|
||||
optimized. One option per candidate, each with its measured cost in the
|
||||
description.
|
||||
3. **Shape** - for a new skill: `Standalone skill`, `Row in the shortcuts
|
||||
skill`, `Extend an existing skill`, `Memory entry instead of a skill`.
|
||||
3. **Shape** - for a new skill: `Standalone skill`, `Extend an existing
|
||||
skill`, `Memory entry instead of a skill`.
|
||||
For an optimization: `Tighten wording only`, `Change the trigger`, `Add
|
||||
rules`, `Split into two skills`, `Merge into another skill`.
|
||||
rules`, `Split into two skills`, `Merge into another skill`, `Compile
|
||||
deterministic steps into a script` (the `kvb-skill-compile` skill).
|
||||
4. **Placement** - `Operator skills repository (portable)` or
|
||||
`This project's skills directory (project-specific)`.
|
||||
|
||||
@@ -130,7 +136,7 @@ reverse — remove the mirrors too, or the old name keeps firing.
|
||||
- Optimizing an existing skill means the file gets shorter or sharper, not
|
||||
longer. Delete rules the agent already follows, merge duplicated ones, and
|
||||
cut every sentence that does not change an action. Route that compaction
|
||||
through the `essence` skill instead of trimming by hand: it runs a health
|
||||
through the `kvb-skill-essence` skill instead of trimming by hand: it runs a health
|
||||
pass for dead pointers and rules duplicated across skills before cutting
|
||||
anything, ranks by what loads in every session, and shows the diff before it
|
||||
writes. It asks for its own scope — answer with the skill being optimized.
|
||||
@@ -140,7 +146,7 @@ reverse — remove the mirrors too, or the old name keeps firing.
|
||||
## Rules
|
||||
|
||||
- One skill per run unless the operator picked `Both`; a broad rewrite of the
|
||||
whole collection is not what autotune is for.
|
||||
whole collection is not what kvb-skill-tune is for.
|
||||
- Never write a skill for one-off work, for secrets, or for behaviour an
|
||||
existing skill already covers - propose extending that skill instead.
|
||||
- The **Objective** section decides what counts as an improvement: at least
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
name: kvb-think-brainstorm
|
||||
description: >
|
||||
Generate options through fixed lenses, then score and narrow them. Trigger
|
||||
on /kvb-think-brainstorm, "brainstorm", or when a skill needs alternatives.
|
||||
---
|
||||
|
||||
Generate first, judge second: no option is scored before all are on the
|
||||
table.
|
||||
|
||||
## Step 1: frame
|
||||
|
||||
One line: the problem, who has it, and which constraints are fixed. Ask the
|
||||
operator only for what the context does not give, by the `kvb-think-listen`
|
||||
skill's rules.
|
||||
|
||||
## Step 2: diverge
|
||||
|
||||
At least one option per lens, none judged yet:
|
||||
|
||||
- **Obvious**: what anyone would try first.
|
||||
- **Minimal**: the smallest change that helps at all.
|
||||
- **Maximal**: the version without a budget limit.
|
||||
- **Inversion**: solve the opposite problem, or remove the need.
|
||||
- **Analogy**: how another domain solves a problem of the same shape.
|
||||
- **Drop a constraint**: what one fixed constraint, gone, makes possible.
|
||||
- **Reuse**: what the repository, the platform or a dependency already has.
|
||||
|
||||
## Step 3: converge
|
||||
|
||||
Rate every option on value, effort and risk (`low`, `medium`, `high`),
|
||||
merge duplicates, and drop each option another one beats on all three.
|
||||
|
||||
## Step 4: hand over
|
||||
|
||||
The best two or three go to the calling skill, or to the operator through
|
||||
`AskUserQuestion` with `multiSelect: false`, the recommended option first.
|
||||
A consequential choice runs through the `kvb-think-dialectic` skill before
|
||||
it is offered.
|
||||
|
||||
## Output
|
||||
|
||||
| Option | Lens | Value | Effort | Risk | Kept |
|
||||
|
||||
Dropped options stay in the table with the option that beat them.
|
||||
@@ -1,21 +1,21 @@
|
||||
---
|
||||
name: criticize
|
||||
name: kvb-think-criticize
|
||||
description: >
|
||||
Give constructive criticism of a problem, plan, design, decision, text or
|
||||
code from diverse aspects, each point hardened by dialectic. Trigger on
|
||||
/criticize, "kritisiere", "kritisch betrachten", "konstruktive Kritik", "was
|
||||
haeltst du davon", or requests for honest feedback.
|
||||
Constructive criticism of a plan, design, decision, text or code, each
|
||||
point hardened by dialectic. Trigger on /kvb-think-criticize, "kritisiere",
|
||||
"konstruktive Kritik", "was haeltst du davon", or requests for honest
|
||||
feedback.
|
||||
---
|
||||
|
||||
The stance is critical but constructive: the goal is a better result, not a
|
||||
verdict on its author. This skill judges any artifact from many angles; it is
|
||||
not limited to code (`sceptic` hunts violated engineering principles in code,
|
||||
not limited to code (`kvb-check-principles` hunts violated engineering principles in code,
|
||||
`code-review` hunts bugs). Read-only: report the critique, change nothing
|
||||
unless the operator asks afterwards.
|
||||
|
||||
## Before you start: listen
|
||||
|
||||
Invoke the `active-listening` skill. Pin down what is being criticized, what it
|
||||
Invoke the `kvb-think-listen` skill. Pin down what is being criticized, what it
|
||||
is meant to achieve, for whom, and under which constraints. Derive what you can
|
||||
from the artifact and its surroundings first; ask only what only the operator
|
||||
knows. A critique against the wrong goal is noise.
|
||||
@@ -53,7 +53,7 @@ Sweep every aspect that applies, and name the ones you skipped and why:
|
||||
|
||||
## Harden every point with dialectic
|
||||
|
||||
Run each candidate critique through the `dialectic` skill before reporting it:
|
||||
Run each candidate critique through the `kvb-think-dialectic` skill before reporting it:
|
||||
|
||||
- **Thesis**: the critique point with its evidence.
|
||||
- **Antithesis**: independent defenders argue that the artifact is right as it
|
||||
@@ -76,7 +76,7 @@ One line of scope, then the steelman. Then:
|
||||
`Evidence` is `proven` (read, run, reproduced, cited) or `derived` (reasoned).
|
||||
|
||||
Close with at most three lines: how many candidate points dialectic dropped and
|
||||
why, the single change that helps most, and the `confidence` skill's numbers for
|
||||
why, the single change that helps most, and the `kvb-check-confidence` skill's numbers for
|
||||
the critique as a whole.
|
||||
|
||||
## Rules
|
||||
@@ -1,10 +1,9 @@
|
||||
---
|
||||
name: dialectic
|
||||
name: kvb-think-dialectic
|
||||
description: >
|
||||
Reach a defensible conclusion by thesis, independent skeptic antithesis and
|
||||
synthesis, iterated to ~99% confidence. Trigger for any consequential root
|
||||
cause, design or decision where being wrong is expensive and the answer is
|
||||
uncertain.
|
||||
cause, design or decision that is uncertain and expensive to get wrong.
|
||||
---
|
||||
|
||||
Reach the truth by dialectic, not by first guess. Do not stop at a plausible
|
||||
@@ -12,13 +11,13 @@ answer; drive the loop until a thesis survives every attack at ~99% confidence.
|
||||
|
||||
## Before you start: listen
|
||||
|
||||
Invoke the `active-listening` skill first. Do not begin the dialectic until you
|
||||
Invoke the `kvb-think-listen` skill first. Do not begin the dialectic until you
|
||||
have gathered every requirement, constraint, and success criterion the task
|
||||
needs. A dialectic run on the wrong question wastes the whole loop. Return to
|
||||
`active-listening` mid-loop whenever an objection turns on a fact only the
|
||||
`kvb-think-listen` mid-loop whenever an objection turns on a fact only the
|
||||
operator holds.
|
||||
|
||||
When another skill or an autonomous run (robot, observe, a loop) invoked this
|
||||
When another skill or an autonomous run (kvb-org-robot, kvb-ci-observe, a loop) invoked this
|
||||
skill, derive the requirements from the task and the evidence instead of
|
||||
asking; ask only when an operator-only fact blocks the conclusion.
|
||||
|
||||
@@ -30,7 +29,7 @@ asking; ask only when an operator-only fact blocks the conclusion.
|
||||
make or CLI helpers the project exposes); CI logs and artifacts; tests; docs.
|
||||
Cite `file:line` and command output — never a bare assertion.
|
||||
2. **Antithesis.** Spawn MULTIPLE independent skeptics (parallel subagents or a
|
||||
workflow, on the default model as the `subagent-model` skill requires)
|
||||
workflow, on the default model as the `kvb-org-perform` skill requires)
|
||||
whose only job is to REFUTE the thesis. Each re-inspects the
|
||||
sources itself and defaults to "refuted" on any concrete hole. Give diverse
|
||||
skeptics diverse lenses: correctness, an alternate mechanism, does-it-
|
||||
@@ -41,7 +40,7 @@ asking; ask only when an operator-only fact blocks the conclusion.
|
||||
4. **Iterate.** Repeat thesis → antithesis → synthesis until a full skeptic
|
||||
round finds no new hole and the thesis holds at ~99%. If confidence stalls
|
||||
below 99%, name the exact residual and the evidence that would close it, then
|
||||
go get that evidence (more inspection, or `active-listening` for an
|
||||
go get that evidence (more inspection, or `kvb-think-listen` for an
|
||||
operator-only fact) and loop again.
|
||||
|
||||
## Rules
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: explain
|
||||
name: kvb-think-explain
|
||||
description: >
|
||||
Explain code and its interactions. Trigger when the operator asks what code
|
||||
does, how a mechanism works, why components interact, or invokes /explain on
|
||||
does, how a mechanism works, why components interact, or invokes /kvb-think-explain on
|
||||
a file, function, role or module.
|
||||
---
|
||||
|
||||
@@ -1,27 +1,25 @@
|
||||
---
|
||||
name: auto-feature
|
||||
name: kvb-think-gaps
|
||||
description: >
|
||||
Derive missing work (sceptic pass for structural flaws, usability pass for
|
||||
missing features) and write requirement documents after single-select
|
||||
confirmation. Trigger on /auto-feature, "was fehlt noch", "welche features
|
||||
brauchen wir", or when the operator asks what to build next.
|
||||
Find and rank missing work (structural flaws, missing features); each pick
|
||||
goes to kvb-create-requirement. Trigger on /kvb-think-gaps, "was fehlt
|
||||
noch", or asked what to build next.
|
||||
---
|
||||
|
||||
Two blind spots produce different work: the code has defects of structure,
|
||||
the product has gaps of use. This skill runs both lenses, ranks what comes
|
||||
out, and lets the operator choose — it writes requirement documents, never
|
||||
implementations.
|
||||
out, and lets the operator choose. It writes no file; the
|
||||
`kvb-create-requirement` skill writes the requirement for every pick.
|
||||
|
||||
## Step 1: fix the scope
|
||||
|
||||
Name the target in one line: repository, subsystem, role, or user-facing
|
||||
surface. Read the project's existing requirement documents first — their
|
||||
location, filename convention, and section structure are the template, and
|
||||
an already-written requirement is not a finding.
|
||||
surface. Read the project's existing requirement documents first; an
|
||||
already-written requirement is not a finding.
|
||||
|
||||
## Step 2: the sceptic pass
|
||||
## Step 2: the principles pass
|
||||
|
||||
Invoke the `sceptic` skill on the target. Its findings become requirement
|
||||
Invoke the `kvb-check-principles` skill on the target. Its findings become requirement
|
||||
candidates by severity: a violated SPOT, SRP, or trust boundary is work the
|
||||
product needs whether or not a user ever notices. Carry each finding's
|
||||
`file:line` evidence forward — a requirement without it is a guess.
|
||||
@@ -55,7 +53,7 @@ Merge both lists, drop duplicates where a structural finding and a usability
|
||||
gap describe the same defect, and rank by blocked users first, blast radius
|
||||
second.
|
||||
|
||||
Then apply `active-listening`: answer everything you can from the code, the
|
||||
Then apply `kvb-think-listen`: answer everything you can from the code, the
|
||||
docs, and the git history yourself, and put only the genuinely open decisions
|
||||
to the operator with `AskUserQuestion`, `multiSelect: false`, so every
|
||||
question renders as radio buttons. At most four questions per call, each
|
||||
@@ -66,33 +64,21 @@ option a real alternative — never one option plus filler:
|
||||
2. **Which shape** the chosen one takes — for a feature typically
|
||||
`Minimal version that unblocks the user`, `Full version`, `Fix the
|
||||
underlying structure instead`, `Document the limitation and defer`.
|
||||
3. **Scope boundary** — what is explicitly out of scope, when the candidate
|
||||
could grow in more than one direction.
|
||||
4. **Placement** — which requirement file or directory receives it, when the
|
||||
project has more than one.
|
||||
|
||||
Never assume an answer, never fold two decisions into one option, and never
|
||||
write a file before the answers are in.
|
||||
Never assume an answer and never fold two decisions into one option.
|
||||
|
||||
## Step 5: write the requirements
|
||||
## Step 5: hand over
|
||||
|
||||
One document per feature — a requirement that needs "and" in its title is
|
||||
two requirements. Follow the project's existing template; when there is
|
||||
none, keep it to: problem with its evidence, the decided scope and its
|
||||
boundary, definition of done as checkable criteria, and the alternatives the
|
||||
operator rejected with the reason.
|
||||
|
||||
Show the drafted document and ask for a final `Write it` / `Revise it` /
|
||||
`Discard` before touching disk.
|
||||
Run the `kvb-create-requirement` skill once per chosen candidate. Its
|
||||
context step starts from the candidate's evidence and chosen shape; the
|
||||
rejected shapes go into its Decisions section.
|
||||
|
||||
## Rules
|
||||
|
||||
- Requirements only: no implementation, no refactor, no staging as part of
|
||||
this skill.
|
||||
- Every requirement traces to evidence — a `file:line`, a failing path, a
|
||||
missing artifact. A requirement whose justification is "would be nice" is
|
||||
not written.
|
||||
- Record the rejected alternatives inside the document; the next reader
|
||||
needs to know what was already considered and dismissed.
|
||||
- Close with the `confidence` skill's numbers for the analysis: how sure the
|
||||
- Findings only: no file, no implementation, no refactor, no staging as
|
||||
part of this skill.
|
||||
- Every candidate traces to evidence — a `file:line`, a failing path, a
|
||||
missing artifact. A candidate whose justification is "would be nice" is
|
||||
dropped.
|
||||
- Close with the `kvb-check-confidence` skill's numbers for the analysis: how sure the
|
||||
gaps are real, and what the passes did not cover.
|
||||
@@ -1,10 +1,9 @@
|
||||
---
|
||||
name: active-listening
|
||||
name: kvb-think-listen
|
||||
description: >
|
||||
Ask focused questions until every requirement is pinned down, then reflect
|
||||
the task back. Trigger at the start of any task with unclear scope,
|
||||
constraints or success criteria, and when another skill needs an
|
||||
operator-only fact.
|
||||
the task back. Trigger on unclear scope, constraints or success criteria,
|
||||
or when a skill needs an operator-only fact.
|
||||
---
|
||||
|
||||
Do not act on a half-understood request. Listen actively until you could state
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
name: kvb-transcend
|
||||
description: >
|
||||
Run both transcend skills in one pass. Trigger on /kvb-transcend.
|
||||
---
|
||||
|
||||
Collector for the `kvb-skill-transcend` and `kvb-code-transcend` skills, so
|
||||
one harvest needs one round of questions. Its script finds the candidates and
|
||||
remembers every decision, so a rescan offers only what is new or changed:
|
||||
|
||||
```bash
|
||||
transcend.py scan --state <skills repo>/.state/transcend.json \
|
||||
--skills-repo <skills repo> --session-dir <own scratchpad> \
|
||||
--peers-root /tmp/claude-<uid> --home ~ [--json]
|
||||
transcend.py mark --state <same> <path> carried|dropped|later
|
||||
```
|
||||
|
||||
`${CLAUDE_SKILL_DIR}/scripts/transcend.py` scans three sources: the own
|
||||
scratchpad, every peer session's scratchpad, and the agent homes
|
||||
(`~/.claude`, `~/.agents`, `~/.codex`) for skills, commands, agents, hooks
|
||||
and rules the skills repository does not ship. It keeps scripts, tests and
|
||||
skills, and skips files named like secrets and files over 1 MB. Carried or
|
||||
dropped candidates return only when their content changes; `later` returns
|
||||
every time.
|
||||
|
||||
1. Scan, then classify each candidate by both skills' classify steps.
|
||||
2. Consent: a peer's candidates go to that peer, one message listing them,
|
||||
and only what it releases stays; home candidates need the operator's yes.
|
||||
3. One `kvb-think-listen` round and one confirmation for all candidates,
|
||||
grouped by target: the skills repository or the current repository. In
|
||||
the skills repository itself, scripts and skills go to
|
||||
`kvb-skill-transcend`, tests to `kvb-code-transcend`.
|
||||
4. Hand each confirmed candidate to its skill's write step, then `mark` every
|
||||
offered candidate with its verdict.
|
||||
5. One table: `| Candidate | Source | Target | Verdict |`.
|
||||
Executable
+187
@@ -0,0 +1,187 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Find scripts, tests and skills worth carrying over, and remember every decision.
|
||||
|
||||
Exit codes:
|
||||
0 done, 2 usage error.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import datetime
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
SCRIPT_SUFFIXES = {".py", ".sh", ".bash", ".js", ".mjs", ".ts", ".rb", ".pl"}
|
||||
TEST_NAME = re.compile(r"(^test_.+|.+_test|.+\.(spec|test))\.[a-z]+$")
|
||||
SECRET_NAME = re.compile(
|
||||
r"(secret|token|credential|passw|auth|\.env$|id_[a-z0-9]+$|\.pem$|\.key$)", re.IGNORECASE
|
||||
)
|
||||
MAX_BYTES = 1_000_000
|
||||
HOME_SOURCES = {
|
||||
".claude/skills": "skill",
|
||||
".agents/skills": "skill",
|
||||
".codex/skills": "skill",
|
||||
".claude/commands": "command",
|
||||
".claude/agents": "agent",
|
||||
".claude/hooks": "script",
|
||||
".claude/scripts": "script",
|
||||
".codex/rules": "rule",
|
||||
}
|
||||
SETTLED = ("carried", "dropped")
|
||||
VERDICTS = (*SETTLED, "later")
|
||||
|
||||
|
||||
def fail(message: str) -> None:
|
||||
print(f"transcend: {message}", file=sys.stderr)
|
||||
sys.exit(2)
|
||||
|
||||
|
||||
def digest(path: Path) -> str:
|
||||
sha = hashlib.sha256()
|
||||
files = sorted(p for p in path.rglob("*") if p.is_file()) if path.is_dir() else [path]
|
||||
for file in files:
|
||||
sha.update(str(file.relative_to(path) if path.is_dir() else file.name).encode())
|
||||
sha.update(file.read_bytes())
|
||||
return sha.hexdigest()
|
||||
|
||||
|
||||
def file_kind(path: Path) -> str | None:
|
||||
if SECRET_NAME.search(path.name) or path.stat().st_size > MAX_BYTES:
|
||||
return None
|
||||
if TEST_NAME.match(path.name):
|
||||
return "test"
|
||||
if path.suffix in SCRIPT_SUFFIXES or os.access(path, os.X_OK):
|
||||
return "script"
|
||||
return None
|
||||
|
||||
|
||||
def session_names(home: Path) -> dict[str, str]:
|
||||
names = {}
|
||||
for path in (home / ".claude" / "sessions").glob("*.json"):
|
||||
try:
|
||||
data = json.loads(path.read_text(encoding="utf-8"))
|
||||
except (OSError, ValueError):
|
||||
continue
|
||||
if data.get("sessionId"):
|
||||
names[data["sessionId"]] = data.get("name") or data["sessionId"]
|
||||
return names
|
||||
|
||||
|
||||
def scratch_candidates(root: Path, source: str, owner: str) -> list[dict]:
|
||||
found = []
|
||||
for path in sorted(p for p in root.rglob("*") if p.is_file()):
|
||||
kind = file_kind(path)
|
||||
if kind:
|
||||
found.append({"source": source, "owner": owner, "kind": kind, "path": str(path)})
|
||||
return found
|
||||
|
||||
|
||||
def shipped(skills_repo: Path) -> set[str]:
|
||||
names = {p.name for p in (skills_repo / "skills").iterdir() if p.is_dir()}
|
||||
lock = json.loads((skills_repo / "skills-lock.json").read_text(encoding="utf-8"))
|
||||
return names | set(lock.get("skills", {}))
|
||||
|
||||
|
||||
def home_candidates(home: Path, skills_repo: Path) -> list[dict]:
|
||||
known = shipped(skills_repo)
|
||||
found = []
|
||||
for sub, kind in HOME_SOURCES.items():
|
||||
base = home / sub
|
||||
if not base.is_dir():
|
||||
continue
|
||||
for entry in sorted(base.iterdir()):
|
||||
if entry.name.startswith(".") or SECRET_NAME.search(entry.name):
|
||||
continue
|
||||
if kind == "skill" and (entry.name in known or not (entry / "SKILL.md").is_file()):
|
||||
continue
|
||||
if kind != "skill" and not entry.is_file():
|
||||
continue
|
||||
found.append({"source": "home", "owner": "operator", "kind": kind, "path": str(entry)})
|
||||
return found
|
||||
|
||||
|
||||
def load_state(path: Path) -> dict[str, dict]:
|
||||
try:
|
||||
return json.loads(path.read_text(encoding="utf-8"))
|
||||
except FileNotFoundError:
|
||||
return {}
|
||||
except ValueError:
|
||||
fail(f"{path} is not valid JSON")
|
||||
|
||||
|
||||
def cmd_scan(args: argparse.Namespace) -> int:
|
||||
session = Path(args.session_dir).resolve()
|
||||
home = Path(args.home)
|
||||
names = session_names(home)
|
||||
candidates = scratch_candidates(session, "own", "self")
|
||||
for scratch in sorted(Path(args.peers_root).glob("*/*/scratchpad")):
|
||||
if scratch.resolve() == session:
|
||||
continue
|
||||
sid = scratch.parent.name
|
||||
candidates += scratch_candidates(scratch, "peer", names.get(sid, sid))
|
||||
candidates += home_candidates(home, Path(args.skills_repo))
|
||||
|
||||
state = load_state(Path(args.state))
|
||||
offered = []
|
||||
for item in candidates:
|
||||
seen = state.get(item["path"])
|
||||
item["digest"] = digest(Path(item["path"]))
|
||||
if seen and seen["verdict"] in SETTLED and seen["digest"] == item["digest"]:
|
||||
continue
|
||||
item["previous"] = seen["verdict"] if seen else None
|
||||
offered.append(item)
|
||||
if args.json:
|
||||
print(json.dumps(offered, indent=1))
|
||||
else:
|
||||
for item in offered:
|
||||
note = f"\t(was {item['previous']})" if item["previous"] else ""
|
||||
print(f"{item['source']}\t{item['owner']}\t{item['kind']}\t{item['path']}{note}")
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_mark(args: argparse.Namespace) -> int:
|
||||
target = Path(args.path)
|
||||
if not target.exists():
|
||||
fail(f"{target} does not exist")
|
||||
state_path = Path(args.state)
|
||||
state = load_state(state_path)
|
||||
state[str(target)] = {
|
||||
"verdict": args.verdict,
|
||||
"digest": digest(target),
|
||||
"at": datetime.datetime.now(datetime.UTC).isoformat(timespec="seconds"),
|
||||
}
|
||||
state_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
tmp = state_path.with_suffix(".tmp")
|
||||
tmp.write_text(json.dumps(state, indent=1, sort_keys=True), encoding="utf-8")
|
||||
tmp.replace(state_path)
|
||||
print(f"{args.verdict} {target}")
|
||||
return 0
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
||||
sub = parser.add_subparsers(dest="cmd", required=True)
|
||||
p = sub.add_parser("scan")
|
||||
p.add_argument("--state", required=True)
|
||||
p.add_argument("--skills-repo", required=True)
|
||||
p.add_argument("--session-dir", required=True)
|
||||
p.add_argument("--peers-root", required=True)
|
||||
p.add_argument("--home", required=True)
|
||||
p.add_argument("--json", action="store_true")
|
||||
p.set_defaults(func=cmd_scan)
|
||||
p = sub.add_parser("mark")
|
||||
p.add_argument("--state", required=True)
|
||||
p.add_argument("path")
|
||||
p.add_argument("verdict", choices=VERDICTS)
|
||||
p.set_defaults(func=cmd_mark)
|
||||
args = parser.parse_args()
|
||||
return args.func(args)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -1,18 +0,0 @@
|
||||
---
|
||||
name: shortcuts
|
||||
description: >
|
||||
Operator conversation shortcuts. Trigger when the message is exactly one of
|
||||
these tokens, optionally with arguments: sobu, soco, socobu, socon, sona,
|
||||
sote. Expand it and act on the expanded instruction.
|
||||
---
|
||||
|
||||
When an operator message is one of the shortcuts below, expand it to the meaning and act on it.
|
||||
|
||||
| Shortcut | Meaning |
|
||||
| --- | --- |
|
||||
| `sobu` | Stage next bundle: stage the next logical bundle of verified changes, explain what it does, and list what still remains uncommitted. |
|
||||
| `soco` | Commit: commit the currently staged changes (pre-commit hooks run). |
|
||||
| `socobu` | Commit no-verify, then stage next bundle: run `socon` followed by `sobu`. |
|
||||
| `socon` | Commit no-verify: commit the currently staged changes with `--no-verify`. |
|
||||
| `sona` | New alias: add the shortcut the operator states to the appropriate table, keeping it sorted. |
|
||||
| `sote` | Run `make test`. |
|
||||
+7
-86
@@ -1,41 +1,23 @@
|
||||
"""Validate the autotune reminder hook and its settings registration."""
|
||||
"""Validate the kvb-skill-tune skill text and its persistence targets."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import shutil
|
||||
import subprocess
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
SKILL = REPO_ROOT / "skills" / "autotune" / "SKILL.md"
|
||||
HOOK = REPO_ROOT / "skills" / "autotune" / "hooks" / "reminder.sh"
|
||||
PATCHER = REPO_ROOT / "scripts" / "enable-plugins.js"
|
||||
|
||||
|
||||
def _run_hook(stamp: Path, interval: str = "3600") -> subprocess.CompletedProcess:
|
||||
return subprocess.run(
|
||||
["bash", str(HOOK)],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=True,
|
||||
env={
|
||||
"PATH": "/usr/bin:/bin",
|
||||
"HOME": str(stamp.parent),
|
||||
"AUTOTUNE_STAMP": str(stamp),
|
||||
"AUTOTUNE_INTERVAL_SECONDS": interval,
|
||||
},
|
||||
)
|
||||
SKILL = REPO_ROOT / "skills" / "kvb-skill-tune" / "SKILL.md"
|
||||
|
||||
|
||||
class TestAutotuneSkill(unittest.TestCase):
|
||||
def test_skill_is_trigger_only(self):
|
||||
text = SKILL.read_text(encoding="utf-8")
|
||||
self.assertIn("name: autotune", text)
|
||||
self.assertIn("name: kvb-skill-tune", text)
|
||||
self.assertIn("multiSelect: false", text)
|
||||
|
||||
def test_skill_has_no_own_reminder_hook(self):
|
||||
self.assertFalse((SKILL.parent / "hooks").exists())
|
||||
|
||||
|
||||
class TestSkillPersistence(unittest.TestCase):
|
||||
"""Both skill writers must persist to the skills repository AND the live dirs."""
|
||||
@@ -51,73 +33,12 @@ class TestSkillPersistence(unittest.TestCase):
|
||||
self.assertIn(target, text)
|
||||
|
||||
def test_autoskill_routes_to_the_same_persistence(self):
|
||||
text = (REPO_ROOT / "skills" / "autoskill" / "SKILL.md").read_text(
|
||||
text = (REPO_ROOT / "skills" / "kvb-skill-auto" / "SKILL.md").read_text(
|
||||
encoding="utf-8"
|
||||
)
|
||||
for target in ("Persistence", "~/.claude/skills/", "~/.agents/skills/"):
|
||||
self.assertIn(target, text)
|
||||
|
||||
|
||||
class TestAutotuneHook(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.tmp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.tmp.cleanup)
|
||||
self.stamp = Path(self.tmp.name) / ".claude" / ".autotune-stamp"
|
||||
|
||||
def test_first_run_hints_and_stamps(self):
|
||||
result = _run_hook(self.stamp)
|
||||
self.assertIn("/autotune", result.stdout)
|
||||
self.assertTrue(self.stamp.is_file())
|
||||
|
||||
def test_second_run_is_silent_within_interval(self):
|
||||
_run_hook(self.stamp)
|
||||
self.assertEqual(_run_hook(self.stamp).stdout, "")
|
||||
|
||||
def test_hint_returns_after_the_interval(self):
|
||||
_run_hook(self.stamp)
|
||||
self.assertIn("/autotune", _run_hook(self.stamp, interval="0").stdout)
|
||||
|
||||
def test_corrupt_stamp_does_not_crash(self):
|
||||
self.stamp.parent.mkdir(parents=True, exist_ok=True)
|
||||
self.stamp.write_text("not-a-timestamp\n", encoding="utf-8")
|
||||
self.assertIn("/autotune", _run_hook(self.stamp).stdout)
|
||||
|
||||
|
||||
@unittest.skipUnless(shutil.which("node"), "node not installed")
|
||||
class TestSettingsRegistration(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.tmp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.tmp.cleanup)
|
||||
self.settings = Path(self.tmp.name) / "settings.json"
|
||||
|
||||
def _patch(self) -> dict:
|
||||
subprocess.run(
|
||||
["node", str(PATCHER), str(self.settings)], check=True, capture_output=True
|
||||
)
|
||||
return json.loads(self.settings.read_text(encoding="utf-8"))
|
||||
|
||||
def test_hook_registered_once(self):
|
||||
self._patch()
|
||||
data = self._patch()
|
||||
entries = json.dumps(data["hooks"]["UserPromptSubmit"])
|
||||
self.assertEqual(entries.count("autotune/hooks/reminder.sh"), 1)
|
||||
|
||||
def test_existing_hooks_preserved(self):
|
||||
self.settings.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": [
|
||||
{"hooks": [{"type": "command", "command": "true"}]}
|
||||
]
|
||||
}
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
data = self._patch()
|
||||
self.assertEqual(len(data["hooks"]["UserPromptSubmit"]), 4)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -11,8 +11,8 @@ import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
CI_FAILURES = REPO_ROOT / "skills" / "ci-artifacts" / "scripts" / "ci_failures.py"
|
||||
FIND_FIX = REPO_ROOT / "skills" / "merge-fix" / "scripts" / "find_fix.py"
|
||||
CI_FAILURES = REPO_ROOT / "skills" / "kvb-ci-artifacts" / "scripts" / "ci_failures.py"
|
||||
FIND_FIX = REPO_ROOT / "skills" / "kvb-git-merge-fix" / "scripts" / "find_fix.py"
|
||||
|
||||
|
||||
def _load(path: Path):
|
||||
@@ -55,7 +55,7 @@ class TestCiFailures(unittest.TestCase):
|
||||
"Ran 41 tests in 1.0s\n"
|
||||
"OK\n"
|
||||
"UP017 [*] Use `datetime.UTC` alias\n"
|
||||
" --> skills/democracy/scripts/council.py:92:40\n"
|
||||
" --> skills/kvb-org-organize/scripts/council.py:92:40\n"
|
||||
"Found 1 error.\n"
|
||||
"make: *** [Makefile:15: test] Error 1\n"
|
||||
"##[error]Process completed with exit code 2.\n"
|
||||
|
||||
@@ -0,0 +1,94 @@
|
||||
"""Exercise coach.py: preferences flip between like and dislike, the log feeds hours since."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
SCRIPT = REPO_ROOT / "skills" / "kvb-coach" / "scripts" / "coach.py"
|
||||
HOOK = REPO_ROOT / "skills" / "kvb-coach" / "hooks" / "reminder.sh"
|
||||
|
||||
|
||||
class TestCoach(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.tmp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.tmp.cleanup)
|
||||
self.profile = Path(self.tmp.name) / "state" / "coach.json"
|
||||
|
||||
def _run(self, *args: str) -> subprocess.CompletedProcess:
|
||||
return subprocess.run(
|
||||
[sys.executable, str(SCRIPT), "--profile", str(self.profile), *args],
|
||||
check=False,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
|
||||
def _show(self, now: str) -> dict:
|
||||
result = self._run("show", "--now", now, "--json")
|
||||
self.assertEqual(result.returncode, 0, result.stderr)
|
||||
return {row["area"]: row for row in json.loads(result.stdout)}
|
||||
|
||||
def test_a_dislike_replaces_a_like_and_forget_drops_it(self):
|
||||
self._run("like", "body", "Laufen")
|
||||
self._run("like", "body", "Laufen")
|
||||
self._run("like", "body", "Yoga")
|
||||
self._run("dislike", "body", "Laufen")
|
||||
body = self._show("2026-11-03T18:00:00+00:00")["body"]
|
||||
self.assertEqual(body["likes"], ["Yoga"])
|
||||
self.assertEqual(body["dislikes"], ["Laufen"])
|
||||
self._run("forget", "body", "Laufen")
|
||||
self.assertEqual(self._show("2026-11-03T18:00:00+00:00")["body"]["dislikes"], [])
|
||||
|
||||
def test_the_latest_done_per_area_gives_the_hours_since(self):
|
||||
self._run("done", "food", "Frühstück", "--at", "2026-11-03T08:00:00+00:00")
|
||||
self._run("done", "food", "Mittagessen", "--at", "2026-11-03T12:30:00+00:00")
|
||||
self._run("done", "sleep", "Nacht", "--at", "2026-11-02T23:00:00+00:00")
|
||||
rows = self._show("2026-11-03T18:00:00+00:00")
|
||||
self.assertEqual((rows["food"]["last"], rows["food"]["hours_ago"]), ("Mittagessen", 5.5))
|
||||
self.assertEqual(rows["sleep"]["hours_ago"], 19.0)
|
||||
self.assertIsNone(rows["psyche"]["last"])
|
||||
|
||||
def test_invalid_input_exits_2_and_keeps_the_profile(self):
|
||||
self.assertEqual(self._run("like", "work", "x").returncode, 2)
|
||||
self.assertEqual(self._run("done", "body", "x", "--at", "gestern").returncode, 2)
|
||||
self.assertFalse(self.profile.exists())
|
||||
self.profile.parent.mkdir(parents=True)
|
||||
self.profile.write_text("{broken", encoding="utf-8")
|
||||
self.assertEqual(self._run("show").returncode, 2)
|
||||
self.assertEqual(self.profile.read_text(encoding="utf-8"), "{broken")
|
||||
|
||||
|
||||
class TestCoachHour(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.tmp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.tmp.cleanup)
|
||||
self.hours = Path(self.tmp.name) / "hours"
|
||||
|
||||
def _run(self, hour: str) -> str:
|
||||
return subprocess.run(
|
||||
["bash", str(HOOK)],
|
||||
check=True,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
env={
|
||||
"PATH": "/usr/bin:/bin",
|
||||
"HOME": self.tmp.name,
|
||||
"COACH_STAMP_DIR": str(self.hours),
|
||||
"COACH_HOUR": hour,
|
||||
},
|
||||
).stdout
|
||||
|
||||
def test_first_prompt_of_each_hour_triggers_the_coach_once(self):
|
||||
self.assertIn("kvb-coach", self._run("2026-11-03T14"))
|
||||
self.assertEqual(self._run("2026-11-03T14"), "")
|
||||
self.assertIn("kvb-coach", self._run("2026-11-03T15"))
|
||||
self.assertEqual(sorted(p.name for p in self.hours.iterdir()), ["2026-11-03T15"])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -1,4 +1,4 @@
|
||||
"""Exercise the democracy council script: election, staleness, release, gate."""
|
||||
"""Exercise the kvb-org-organize council script: election, staleness, release, gate."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -10,7 +10,7 @@ import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
COUNCIL = REPO_ROOT / "skills" / "democracy" / "scripts" / "council.py"
|
||||
COUNCIL = REPO_ROOT / "skills" / "kvb-org-organize" / "scripts" / "council.py"
|
||||
|
||||
|
||||
class TestCouncil(unittest.TestCase):
|
||||
|
||||
+158
-83
@@ -1,4 +1,4 @@
|
||||
"""Validate the dream reminder hook and its settings registration."""
|
||||
"""Validate the kvb-dream reminder, its GNOME notification, timer and settings registration."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -10,101 +10,124 @@ import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
SKILL = REPO_ROOT / "skills" / "dream" / "SKILL.md"
|
||||
HOOK = REPO_ROOT / "skills" / "dream" / "hooks" / "reminder.sh"
|
||||
DREAM = REPO_ROOT / "skills" / "kvb-dream"
|
||||
SKILL = DREAM / "SKILL.md"
|
||||
HOOK = DREAM / "hooks" / "reminder.sh"
|
||||
NOTIFY = DREAM / "hooks" / "notify.sh"
|
||||
TIMER = DREAM / "systemd" / "kvb-dream-notify.timer"
|
||||
SERVICE = DREAM / "systemd" / "kvb-dream-notify.service"
|
||||
PATCHER = REPO_ROOT / "scripts" / "enable-plugins.js"
|
||||
|
||||
|
||||
def _run_hook(
|
||||
cwd: Path, stamp: Path | None = None, interval: str = "43200"
|
||||
) -> subprocess.CompletedProcess:
|
||||
env = {
|
||||
"PATH": "/usr/bin:/bin",
|
||||
"HOME": str(cwd),
|
||||
"DREAM_INTERVAL_SECONDS": interval,
|
||||
}
|
||||
if stamp is not None:
|
||||
env["DREAM_STAMP"] = str(stamp)
|
||||
return subprocess.run(
|
||||
["bash", str(HOOK)],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=True,
|
||||
cwd=str(cwd),
|
||||
env=env,
|
||||
)
|
||||
|
||||
|
||||
class TestDreamSkill(unittest.TestCase):
|
||||
def test_skill_is_trigger_only(self):
|
||||
def test_skill_runs_optimize_and_the_cleanups(self):
|
||||
text = SKILL.read_text(encoding="utf-8")
|
||||
self.assertIn("name: dream", text)
|
||||
self.assertIn("name: kvb-dream", text)
|
||||
self.assertIn("multiSelect: false", text)
|
||||
for skill in ("`kvb-optimize`", "`kvb-cleanup`", "`kvb-git-branch-gc`"):
|
||||
self.assertIn(skill, text)
|
||||
|
||||
def test_optimize_covers_every_optimization_skill(self):
|
||||
text = (REPO_ROOT / "skills" / "kvb-optimize" / "SKILL.md").read_text(encoding="utf-8")
|
||||
for skill in (
|
||||
"kvb-skill-cleanup",
|
||||
"kvb-transcend",
|
||||
"kvb-skill-auto",
|
||||
"kvb-skill-tune",
|
||||
"kvb-skill-compile",
|
||||
"kvb-skill-essence",
|
||||
"kvb-code-refactor",
|
||||
"kvb-code-tune",
|
||||
"kvb-think-gaps",
|
||||
):
|
||||
self.assertIn(f"`{skill}`", text)
|
||||
|
||||
|
||||
class TestDreamHook(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.tmp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.tmp.cleanup)
|
||||
self.cwd = Path(self.tmp.name)
|
||||
self.stamp = self.cwd / ".claude" / ".dream-stamp"
|
||||
self.stamps = Path(self.tmp.name) / "stamps"
|
||||
|
||||
def test_first_run_hints_and_stamps(self):
|
||||
result = _run_hook(self.cwd, self.stamp)
|
||||
self.assertIn("/dream", result.stdout)
|
||||
self.assertTrue(self.stamp.is_file())
|
||||
def _run(self, payload: str, interval: str = "43200") -> str:
|
||||
return subprocess.run(
|
||||
["bash", str(HOOK)],
|
||||
input=payload,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
check=True,
|
||||
env={
|
||||
"PATH": "/usr/bin:/bin",
|
||||
"HOME": self.tmp.name,
|
||||
"DREAM_STAMP_DIR": str(self.stamps),
|
||||
"DREAM_INTERVAL_SECONDS": interval,
|
||||
},
|
||||
).stdout
|
||||
|
||||
def test_second_run_is_silent_within_interval(self):
|
||||
_run_hook(self.cwd, self.stamp)
|
||||
self.assertEqual(_run_hook(self.cwd, self.stamp).stdout, "")
|
||||
@staticmethod
|
||||
def _session(sid: str) -> str:
|
||||
return json.dumps({"session_id": sid, "prompt": "hi"})
|
||||
|
||||
def test_first_run_hints_and_stamps_the_session(self):
|
||||
self.assertIn("/kvb-dream", self._run(self._session("a1")))
|
||||
self.assertTrue((self.stamps / "a1").is_file())
|
||||
|
||||
def test_second_run_of_the_same_agent_is_silent(self):
|
||||
self._run(self._session("a1"))
|
||||
self.assertEqual(self._run(self._session("a1")), "")
|
||||
|
||||
def test_every_agent_gets_its_own_hint(self):
|
||||
self._run(self._session("a1"))
|
||||
self.assertIn("/kvb-dream", self._run(self._session("b2")))
|
||||
|
||||
def test_hint_returns_after_the_interval(self):
|
||||
_run_hook(self.cwd, self.stamp)
|
||||
self.assertIn("/dream", _run_hook(self.cwd, self.stamp, interval="0").stdout)
|
||||
self._run(self._session("a1"))
|
||||
self.assertIn("/kvb-dream", self._run(self._session("a1"), interval="0"))
|
||||
|
||||
def test_corrupt_stamp_does_not_crash(self):
|
||||
self.stamp.parent.mkdir(parents=True, exist_ok=True)
|
||||
self.stamp.write_text("not-a-timestamp\n", encoding="utf-8")
|
||||
self.assertIn("/dream", _run_hook(self.cwd, self.stamp).stdout)
|
||||
self.stamps.mkdir()
|
||||
(self.stamps / "a1").write_text("not-a-timestamp\n", encoding="utf-8")
|
||||
self.assertIn("/kvb-dream", self._run(self._session("a1")))
|
||||
|
||||
def test_outside_a_repository_it_stays_silent(self):
|
||||
self.assertEqual(_run_hook(self.cwd).stdout, "")
|
||||
def test_without_a_valid_session_it_stays_silent(self):
|
||||
for payload in ("", "not json", self._session(""), self._session("../escape")):
|
||||
with self.subTest(payload=payload):
|
||||
self.assertEqual(self._run(payload), "")
|
||||
self.assertFalse(self.stamps.exists())
|
||||
|
||||
@unittest.skipUnless(shutil.which("git"), "git not installed")
|
||||
def test_stamp_is_per_repository(self):
|
||||
for name in ("one", "two"):
|
||||
repo = self.cwd / name
|
||||
repo.mkdir()
|
||||
subprocess.run(
|
||||
["git", "init", "-q", str(repo)], check=True, capture_output=True
|
||||
)
|
||||
self.assertIn("/dream", _run_hook(repo).stdout)
|
||||
self.assertTrue((repo / ".git" / ".dream-stamp").is_file())
|
||||
self.assertEqual(_run_hook(repo).stdout, "")
|
||||
|
||||
@unittest.skipUnless(shutil.which("git"), "git not installed")
|
||||
def test_linked_worktrees_share_the_stamp(self):
|
||||
repo = self.cwd / "main"
|
||||
tree = self.cwd / "tree"
|
||||
env = {
|
||||
"PATH": "/usr/bin:/bin",
|
||||
"HOME": str(self.cwd),
|
||||
"GIT_AUTHOR_NAME": "t",
|
||||
"GIT_AUTHOR_EMAIL": "t@t",
|
||||
"GIT_COMMITTER_NAME": "t",
|
||||
"GIT_COMMITTER_EMAIL": "t@t",
|
||||
}
|
||||
repo.mkdir()
|
||||
for args in (
|
||||
["init", "-q"],
|
||||
["commit", "-q", "--allow-empty", "-m", "init"],
|
||||
["worktree", "add", "-q", str(tree)],
|
||||
):
|
||||
subprocess.run(
|
||||
["git", *args], check=True, capture_output=True, env=env, cwd=str(repo)
|
||||
)
|
||||
self.assertIn("/dream", _run_hook(repo).stdout)
|
||||
self.assertEqual(_run_hook(tree).stdout, "")
|
||||
class TestDreamNotification(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.tmp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.tmp.cleanup)
|
||||
self.bin = Path(self.tmp.name) / "bin"
|
||||
self.bin.mkdir()
|
||||
self.calls = Path(self.tmp.name) / "calls"
|
||||
fake = self.bin / "notify-send"
|
||||
fake.write_text(f'#!/bin/sh\nprintf "%s\\n" "$@" >> "{self.calls}"\n', encoding="utf-8")
|
||||
fake.chmod(0o755)
|
||||
|
||||
def _run(self, desktop: str) -> None:
|
||||
subprocess.run(
|
||||
["bash", str(NOTIFY)],
|
||||
capture_output=True,
|
||||
check=True,
|
||||
env={"PATH": f"{self.bin}:/usr/bin:/bin", "XDG_CURRENT_DESKTOP": desktop},
|
||||
)
|
||||
|
||||
def test_gnome_session_gets_the_popup(self):
|
||||
self._run("ubuntu:GNOME")
|
||||
self.assertIn("/kvb-dream", self.calls.read_text(encoding="utf-8"))
|
||||
|
||||
def test_other_desktops_stay_silent(self):
|
||||
self._run("KDE")
|
||||
self.assertFalse(self.calls.exists())
|
||||
|
||||
def test_timer_fires_daily_at_five_pm_and_catches_up(self):
|
||||
timer = TIMER.read_text(encoding="utf-8")
|
||||
self.assertIn("OnCalendar=*-*-* 17:00:00", timer)
|
||||
self.assertIn("Persistent=true", timer)
|
||||
self.assertIn("kvb-dream/hooks/notify.sh", SERVICE.read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
@unittest.skipUnless(shutil.which("node"), "node not installed")
|
||||
@@ -124,16 +147,68 @@ class TestSettingsRegistration(unittest.TestCase):
|
||||
self._patch()
|
||||
data = self._patch()
|
||||
entries = json.dumps(data["hooks"]["UserPromptSubmit"])
|
||||
self.assertEqual(entries.count("dream/hooks/reminder.sh"), 1)
|
||||
self.assertEqual(entries.count("autotune/hooks/reminder.sh"), 1)
|
||||
self.assertEqual(entries.count("kvb-dream/hooks/reminder.sh"), 1)
|
||||
self.assertEqual(entries.count("kvb-coach/hooks/reminder.sh"), 1)
|
||||
self.assertNotIn("tune/hooks/reminder.sh", entries)
|
||||
gate = json.dumps(data["hooks"]["PreToolUse"])
|
||||
self.assertEqual(gate.count("democracy/scripts/council.py"), 1)
|
||||
self.assertEqual(gate.count("democracy/scripts/watch.py"), 1)
|
||||
self.assertEqual(entries.count("democracy/scripts/watch.py"), 1)
|
||||
self.assertEqual(gate.count("kvb-org-organize/scripts/council.py"), 1)
|
||||
self.assertEqual(gate.count("kvb-org-organize/scripts/watch.py"), 1)
|
||||
self.assertEqual(entries.count("kvb-org-organize/scripts/watch.py"), 1)
|
||||
post = json.dumps(data["hooks"]["PostToolUse"])
|
||||
self.assertEqual(post.count("democracy/scripts/watch.py"), 1)
|
||||
self.assertEqual(gate.count("subagent-model/scripts/log.py"), 1)
|
||||
self.assertEqual(post.count("subagent-model/scripts/log.py"), 1)
|
||||
self.assertEqual(post.count("kvb-org-organize/scripts/watch.py"), 1)
|
||||
self.assertEqual(gate.count("kvb-org-perform/scripts/log.py"), 1)
|
||||
self.assertEqual(post.count("kvb-org-perform/scripts/log.py"), 1)
|
||||
|
||||
def test_existing_hooks_preserved(self):
|
||||
self.settings.write_text(
|
||||
json.dumps({"hooks": {"UserPromptSubmit": [{"hooks": [{"type": "command", "command": "true"}]}]}}),
|
||||
encoding="utf-8",
|
||||
)
|
||||
data = self._patch()
|
||||
self.assertIn('"true"', json.dumps(data["hooks"]["UserPromptSubmit"]))
|
||||
|
||||
def test_tune_reminders_retire_and_dream_reminders_are_repointed(self):
|
||||
base = Path(self.tmp.name) / "skills"
|
||||
|
||||
def hook(command):
|
||||
return {"hooks": [{"type": "command", "command": command}]}
|
||||
|
||||
self.settings.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": [
|
||||
hook(f'bash "{base}/autotune/hooks/reminder.sh"'),
|
||||
hook(f'bash "{base}/kvb-skill-tune/hooks/reminder.sh"'),
|
||||
hook(f'bash "{base}/kvb-skill-dream/hooks/reminder.sh"'),
|
||||
hook(f'python3 "{base}/democracy/scripts/watch.py" watch'),
|
||||
hook("echo keep"),
|
||||
],
|
||||
"PreToolUse": [
|
||||
hook(f'python3 "{base}/democracy/scripts/council.py" gate'),
|
||||
hook(f'python3 "{base}/democracy/scripts/watch.py" block'),
|
||||
hook(f'python3 "{base}/subagent-model/scripts/log.py" spawn'),
|
||||
],
|
||||
"PostToolUse": [
|
||||
hook(f'python3 "{base}/democracy/scripts/watch.py" watch'),
|
||||
hook(f'python3 "{base}/subagent-model/scripts/log.py" persist'),
|
||||
],
|
||||
}
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
data = self._patch()
|
||||
text = json.dumps(data["hooks"])
|
||||
for old in ("/autotune/", "/kvb-skill-tune/", "/kvb-skill-dream/", "/democracy/", "/subagent-model/"):
|
||||
self.assertNotIn(f"skills{old}", text)
|
||||
self.assertIn("echo keep", text)
|
||||
entries = json.dumps(data["hooks"]["UserPromptSubmit"])
|
||||
self.assertEqual(entries.count("kvb-dream/hooks/reminder.sh"), 1)
|
||||
self.assertEqual(entries.count("kvb-org-organize/scripts/watch.py"), 1)
|
||||
gate = json.dumps(data["hooks"]["PreToolUse"])
|
||||
self.assertEqual(gate.count("kvb-org-organize/scripts/council.py"), 1)
|
||||
self.assertEqual(gate.count("kvb-org-perform/scripts/log.py"), 1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@@ -0,0 +1,88 @@
|
||||
"""Exercise meditation.py and keep it in step with the keys and choices of meditation.html."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import importlib.util
|
||||
import json
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
SKILL = REPO_ROOT / "skills" / "kvb-coach-meditation"
|
||||
SCRIPT = SKILL / "scripts" / "meditation.py"
|
||||
PAGE = SKILL / "assets" / "meditation.html"
|
||||
FULL = [
|
||||
"minutes=5",
|
||||
"beat=10",
|
||||
"base=196",
|
||||
"volume=0.4",
|
||||
"mode=isochronic",
|
||||
"palette=aurora",
|
||||
"breathing=box",
|
||||
]
|
||||
|
||||
|
||||
class TestMeditation(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.tmp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.tmp.cleanup)
|
||||
self.state = Path(self.tmp.name) / "state" / "meditation.json"
|
||||
|
||||
def _run(self, *args: str) -> subprocess.CompletedProcess:
|
||||
return subprocess.run(
|
||||
[sys.executable, str(SCRIPT), "--state", str(self.state), *args],
|
||||
check=False,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
|
||||
def _session(self) -> subprocess.CompletedProcess:
|
||||
out = Path(self.tmp.name) / "session.html"
|
||||
return self._run("session", "--page", str(PAGE), "--out", str(out))
|
||||
|
||||
def test_session_page_embeds_every_setting(self):
|
||||
self.assertEqual(self._run("set", *FULL).returncode, 0)
|
||||
result = self._session()
|
||||
self.assertEqual(result.returncode, 0, result.stderr)
|
||||
page = Path(result.stdout.strip()).read_text(encoding="utf-8")
|
||||
self.assertNotIn("const SETTINGS = null;", page)
|
||||
embedded = json.loads(re.search(r"const SETTINGS = (\{.*?\});", page).group(1))
|
||||
self.assertEqual(embedded["beat"], 10.0)
|
||||
self.assertEqual(embedded["minutes"], 5)
|
||||
self.assertEqual(set(embedded), {pair.split("=")[0] for pair in FULL})
|
||||
|
||||
def test_session_refuses_missing_settings(self):
|
||||
self._run("set", "minutes=5")
|
||||
self.assertEqual(self._session().returncode, 2)
|
||||
self.assertFalse((Path(self.tmp.name) / "session.html").exists())
|
||||
|
||||
def test_invalid_values_exit_2_and_keep_the_state(self):
|
||||
self._run("set", *FULL)
|
||||
before = json.loads(self.state.read_text(encoding="utf-8"))
|
||||
for pair in ("beat=20", "mode=loud", "minutes=five", "tempo=3", "volume"):
|
||||
with self.subTest(pair=pair):
|
||||
self.assertEqual(self._run("set", "minutes=7", pair).returncode, 2)
|
||||
self.assertEqual(json.loads(self.state.read_text(encoding="utf-8")), before)
|
||||
|
||||
|
||||
class TestPageMatchesScript(unittest.TestCase):
|
||||
def test_keys_and_choices_agree(self):
|
||||
spec = importlib.util.spec_from_file_location("meditation", SCRIPT)
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(module)
|
||||
page = PAGE.read_text(encoding="utf-8")
|
||||
self.assertEqual(page.count(module.PLACEHOLDER), 1)
|
||||
keys = re.search(r"const KEYS = \[(.*?)\];", page).group(1)
|
||||
self.assertEqual(re.findall(r'"(\w+)"', keys), list(module.KEYS))
|
||||
for name, choices in (("PALETTES", "palette"), ("PATTERNS", "breathing")):
|
||||
block = re.search(rf"const {name} = \{{(.*?)\n\}};", page, re.DOTALL).group(1)
|
||||
found = re.findall(r'^\s*"?(\w+)"?:', block, re.MULTILINE)
|
||||
self.assertEqual(sorted(found), sorted(module.CHOICES[choices]))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,76 @@
|
||||
"""Pin every first-party skill name to kvb-<category>-<name> and the Agent Skills name rules."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
SKILLS = REPO_ROOT / "skills"
|
||||
README = REPO_ROOT / "README.md"
|
||||
CATEGORIES = ("think", "create", "code", "ci", "git", "check", "org", "skill", "coach")
|
||||
UNCATEGORIZED = frozenset(
|
||||
{
|
||||
"kvb-cleanup",
|
||||
"kvb-coach",
|
||||
"kvb-dream",
|
||||
"kvb-help",
|
||||
"kvb-optimize",
|
||||
"kvb-transcend",
|
||||
}
|
||||
)
|
||||
SPEC = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
|
||||
SCHEMA = re.compile(rf"^kvb-(?:{'|'.join(CATEGORIES)})-[a-z0-9]+(?:-[a-z0-9]+)*$")
|
||||
NAME_LINE = re.compile(r"^name:\s*(\S+)\s*$", re.MULTILINE)
|
||||
ORGANIGRAM_EDGE = re.compile(r"^\s*(\w+) --> \w+\[(kvb-[a-z0-9-]+)\]\s*$", re.MULTILINE)
|
||||
|
||||
|
||||
class TestSkillNames(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.names = sorted(p.name for p in SKILLS.iterdir() if p.is_dir())
|
||||
|
||||
def test_name_field_matches_the_directory(self):
|
||||
for name in self.names:
|
||||
with self.subTest(skill=name):
|
||||
text = (SKILLS / name / "SKILL.md").read_text(encoding="utf-8")
|
||||
match = NAME_LINE.search(text)
|
||||
self.assertIsNotNone(match, "SKILL.md has no name: line")
|
||||
self.assertEqual(match.group(1), name)
|
||||
|
||||
def test_names_follow_the_agent_skills_rules(self):
|
||||
for name in self.names:
|
||||
with self.subTest(skill=name):
|
||||
self.assertRegex(name, SPEC)
|
||||
self.assertLessEqual(len(name), 64)
|
||||
self.assertNotRegex(name, "anthropic|claude")
|
||||
|
||||
def test_names_use_a_listed_category(self):
|
||||
for name in self.names:
|
||||
if name in UNCATEGORIZED:
|
||||
continue
|
||||
with self.subTest(skill=name):
|
||||
self.assertRegex(name, SCHEMA)
|
||||
|
||||
def test_every_category_and_exception_is_in_use(self):
|
||||
for category in CATEGORIES:
|
||||
with self.subTest(category=category):
|
||||
self.assertTrue(
|
||||
any(n.startswith(f"kvb-{category}-") for n in self.names),
|
||||
f"category {category} has no skill",
|
||||
)
|
||||
self.assertLessEqual(UNCATEGORIZED, set(self.names))
|
||||
|
||||
def test_readme_organigram_places_every_skill_under_its_category(self):
|
||||
text = README.read_text(encoding="utf-8")
|
||||
section = text.split("## Organigram", 1)[1].split("\n## ", 1)[0]
|
||||
edges = ORGANIGRAM_EDGE.findall(section)
|
||||
self.assertEqual(sorted(name for _, name in edges), self.names)
|
||||
for parent, name in edges:
|
||||
with self.subTest(skill=name):
|
||||
expected = "none" if name in UNCATEGORIZED else name.split("-")[1]
|
||||
self.assertEqual(parent, expected)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -1,4 +1,4 @@
|
||||
"""The self-improving skills must share the objective held by autotune."""
|
||||
"""The self-improving skills must share the objective held by kvb-skill-tune."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -7,12 +7,12 @@ from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
SKILLS = REPO_ROOT / "skills"
|
||||
ROUTERS = ("autoskill", "confidence")
|
||||
ROUTERS = ("kvb-skill-auto", "kvb-check-confidence")
|
||||
|
||||
|
||||
class TestOptimizeObjective(unittest.TestCase):
|
||||
def test_autotune_names_the_three_axes(self):
|
||||
text = (SKILLS / "autotune" / "SKILL.md").read_text(encoding="utf-8")
|
||||
text = (SKILLS / "kvb-skill-tune" / "SKILL.md").read_text(encoding="utf-8")
|
||||
self.assertIn("## Objective", text)
|
||||
for axis in ("**Tokens**", "**Time**", "**Quality**"):
|
||||
self.assertIn(axis, text)
|
||||
@@ -21,9 +21,9 @@ class TestOptimizeObjective(unittest.TestCase):
|
||||
for skill in ROUTERS:
|
||||
text = (SKILLS / skill / "SKILL.md").read_text(encoding="utf-8")
|
||||
self.assertIn(
|
||||
"`autotune` skill's **Objective**",
|
||||
"`kvb-skill-tune` skill's **Objective**",
|
||||
text,
|
||||
f"{skill} does not route to the autotune objective",
|
||||
f"{skill} does not route to the kvb-skill-tune objective",
|
||||
)
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,251 @@
|
||||
"""Exercise the kvb-org-rasci register: fields, roles, priority order, claims, artifacts, tools."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import datetime
|
||||
import json
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import time
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
RASCI = REPO_ROOT / "skills" / "kvb-org-rasci" / "scripts" / "rasci.py"
|
||||
COUNCIL = REPO_ROOT / "skills" / "kvb-org-organize" / "scripts" / "council.py"
|
||||
HEADER = "| Prio | WSJF | Task | OKR | Status | Worker | Artifacts | Start | End | R | A | S | C | I |"
|
||||
|
||||
|
||||
def local(iso: str) -> str:
|
||||
return datetime.datetime.fromisoformat(iso).astimezone().strftime("%m-%d %H:%M")
|
||||
|
||||
|
||||
class TestRasci(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.tmp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.tmp.cleanup)
|
||||
self.home = Path(self.tmp.name) / "home"
|
||||
self.root = Path(self.tmp.name) / "council"
|
||||
self.sessions = self.home / ".claude" / "sessions"
|
||||
self.sessions.mkdir(parents=True)
|
||||
for sid, name in (("s1", "One"), ("s2", "Two")):
|
||||
(self.sessions / f"{sid}.json").write_text(
|
||||
json.dumps({"sessionId": sid, "name": name}), encoding="utf-8"
|
||||
)
|
||||
|
||||
def _run(self, *args: str, script: Path = RASCI, sid: str = "s1") -> subprocess.CompletedProcess:
|
||||
env = {
|
||||
"PATH": "/usr/bin:/bin",
|
||||
"HOME": str(self.home),
|
||||
"AGENTS_COUNCIL_ROOT": str(self.root),
|
||||
"CLAUDE_CODE_SESSION_ID": sid,
|
||||
}
|
||||
return subprocess.run(
|
||||
[sys.executable, str(script), *args],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
env=env,
|
||||
cwd=self.tmp.name,
|
||||
check=False,
|
||||
)
|
||||
|
||||
def _out(self, *args: str) -> list[str]:
|
||||
result = self._run(*args)
|
||||
self.assertEqual(result.returncode, 0, result.stderr)
|
||||
return result.stdout.splitlines()
|
||||
|
||||
def _claim(self, office: str, session: str, name: str, work: str) -> None:
|
||||
path = self.root / office
|
||||
path.mkdir(parents=True)
|
||||
claim = {
|
||||
"office": office,
|
||||
"session": session,
|
||||
"runtime": "claude-code",
|
||||
"name": name,
|
||||
"since": "2026-11-01T00:00:00+00:00",
|
||||
"beat": time.time(),
|
||||
"work": work,
|
||||
}
|
||||
(path / "claim.json").write_text(json.dumps(claim), encoding="utf-8")
|
||||
|
||||
def test_matrix_orders_by_priority_and_lists_roles(self):
|
||||
start = "2026-11-01T10:00:00+00:00"
|
||||
self._run("set", "work/a", "--title", "Alpha", "--objective", "Ship A", "--prio", "2",
|
||||
"--status", "running", "--worker", "Skills", "--start", start)
|
||||
self._run("role", "work/a", "Skills", "ar")
|
||||
self._run("role", "work/a", "Operator", "ic")
|
||||
self._run("role", "work/a", "Pkgmgr", "C")
|
||||
self._run("set", "work/b", "--title", "Beta", "--prio", "1", "--worker", "subagent Explore (haiku)")
|
||||
self._run("role", "work/b", "Pkgmgr", "R")
|
||||
lines = self._out("show")
|
||||
self.assertEqual(lines[0], HEADER)
|
||||
self.assertEqual(
|
||||
lines[2], "| 1 | - | work/b: Beta | - | queued | subagent Explore (haiku) | - | - | - | Pkgmgr | | | | |"
|
||||
)
|
||||
self.assertEqual(
|
||||
lines[3],
|
||||
f"| 2 | - | work/a: Alpha | Ship A | running | Skills | - | {local(start)} | - "
|
||||
"| Skills | Skills | | Operator, Pkgmgr | Operator |",
|
||||
)
|
||||
self.assertEqual(
|
||||
lines[4], "gaps: work/b has 0 A; work/b has no key result; work/a has no key result"
|
||||
)
|
||||
|
||||
def test_key_results_gate_done_and_fill_the_okr_column(self):
|
||||
self._run("set", "work/a", "--objective", "Ship A", "--status", "running")
|
||||
self._run("role", "work/a", "Skills", "RA")
|
||||
self._run("kr", "work/a", "add", "tests green")
|
||||
self._run("kr", "work/a", "add", "released")
|
||||
self._run("kr", "work/a", "met", "1")
|
||||
lines = self._out("show")
|
||||
self.assertIn("| Ship A (1/2 KR) | running |", lines[2])
|
||||
self.assertEqual(len(lines), 3)
|
||||
self.assertEqual(self._run("set", "work/a", "--status", "done").returncode, 2)
|
||||
self.assertIn("key result 2 [ ]: released", self._out("get", "work/a"))
|
||||
self._run("kr", "work/a", "met", "2")
|
||||
self.assertEqual(self._run("set", "work/a", "--status", "done").returncode, 0)
|
||||
self.assertEqual(self._out("show"), ["no tasks"])
|
||||
|
||||
def test_status_sets_start_and_end(self):
|
||||
self._run("set", "work/a", "--status", "running")
|
||||
self._run("set", "work/a", "--status", "done", "--description", "long text")
|
||||
lines = self._out("get", "work/a")
|
||||
self.assertIn("status: done", lines)
|
||||
self.assertIn("description: long text", lines)
|
||||
self.assertTrue(any(line.startswith("start: 20") for line in lines))
|
||||
self.assertTrue(any(line.startswith("end: 20") for line in lines))
|
||||
self._run("set", "work/a", "--status", "running")
|
||||
self.assertFalse(any(line.startswith("end:") for line in self._out("get", "work/a")))
|
||||
|
||||
def test_done_tasks_show_only_with_all(self):
|
||||
self._run("set", "work/a", "--status", "done", "--end", "2026-11-01T12:00:00+00:00")
|
||||
self._run("role", "work/a", "Skills", "RA")
|
||||
self.assertEqual(self._out("show"), ["no tasks"])
|
||||
self.assertIn("| done | - |", self._out("show", "--all")[2])
|
||||
|
||||
def test_artifacts_and_tools(self):
|
||||
self._run("set", "work/a", "--workdir", "/w/a", "--branch", "feat/a", "--status", "done",
|
||||
"--artifact", "image:core:dev", "--artifact", "volume:db",
|
||||
"--tool", "council.py", "--tool", "make test")
|
||||
self._run("set", "work/b", "--worker", "Two", "--tool", "make test", "--artifact", "dir:/tmp/b")
|
||||
self._run("set", "work/a", "--drop-artifact", "volume:db")
|
||||
self._run("set", "work/b", "--branch", "")
|
||||
rows = [line.split("\t") for line in self._out("artifacts")]
|
||||
self.assertEqual(
|
||||
[row[:4] for row in rows],
|
||||
[
|
||||
["done", "work/a", "-", "workdir:/w/a"],
|
||||
["done", "work/a", "-", "branch:feat/a"],
|
||||
["done", "work/a", "-", "image:core:dev"],
|
||||
["queued", "work/b", "Two", "dir:/tmp/b"],
|
||||
],
|
||||
)
|
||||
self.assertEqual(rows[0][4], "-")
|
||||
self.assertRegex(rows[2][4], r"^\d\d-\d\d \d\d:\d\d$")
|
||||
self.assertEqual([r.split("\t")[1] for r in self._out("artifacts", "--ended")], ["work/a"] * 3)
|
||||
self.assertEqual(len(self._out("artifacts", "--task", "work/b")), 1)
|
||||
self.assertIn("| queued | Two | 1 |", self._out("show")[2])
|
||||
self.assertTrue(any(line.startswith("artifact: image:core:dev (since ") for line in self._out("get", "work/a")))
|
||||
self.assertEqual(
|
||||
self._out("tools"), ["2\tmake test\twork/a work/b", "1\tcouncil.py\twork/a"]
|
||||
)
|
||||
self.assertIn("tool: council.py", self._out("get", "work/a"))
|
||||
|
||||
def test_claims_join_the_matrix_with_holder_as_ra(self):
|
||||
self._claim("work/live", "s1", "One", "Gamma")
|
||||
self._claim("cluster/dead", "s9", "Gone", "Delta")
|
||||
self._claim("chair", "s1", "One", "allocator")
|
||||
self._run("set", "work/live", "--prio", "1", "--status", "running")
|
||||
self._run("role", "work/live", "Two", "S")
|
||||
lines = self._out("show")
|
||||
self.assertTrue(lines[2].startswith("| 1 | - | work/live | - | running | One |"))
|
||||
self.assertTrue(lines[2].endswith("| One | One | Two | | |"))
|
||||
self.assertTrue(lines[3].startswith("| 2 | - | cluster/dead | - | stale | Gone |"))
|
||||
self.assertFalse(any("chair" in line for line in lines))
|
||||
|
||||
def test_council_claim_takeover_and_release_write_through(self):
|
||||
self.assertEqual(self._run("claim", "work/x", "--work", "Do X", script=COUNCIL).returncode, 0)
|
||||
lines = self._out("get", "work/x")
|
||||
self.assertIn("status: running", lines)
|
||||
self.assertIn("worker: One", lines)
|
||||
self.assertIn("description: Do X", lines)
|
||||
self.assertIn(f"workdir: {self.tmp.name}", lines)
|
||||
self.assertIn("roles: One=RA", lines)
|
||||
(self.sessions / "s1.json").unlink()
|
||||
self.assertEqual(self._run("takeover", "work/x", "--work", "Do X", script=COUNCIL, sid="s2").returncode, 0)
|
||||
lines = self._out("get", "work/x")
|
||||
self.assertIn("worker: Two", lines)
|
||||
self.assertIn("roles: Two=RA", lines)
|
||||
self._run("kr", "work/x", "add", "X shipped")
|
||||
self.assertEqual(self._run("release", "work/x", script=COUNCIL, sid="s2").returncode, 0)
|
||||
lines = self._out("get", "work/x")
|
||||
self.assertIn("status: stopped", lines)
|
||||
self.assertTrue(any(line.startswith("end: 20") for line in lines))
|
||||
|
||||
def test_rm_and_clear_a_party(self):
|
||||
self._run("set", "work/a", "--title", "Alpha")
|
||||
self._run("role", "work/a", "Skills", "RA")
|
||||
self._run("role", "work/a", "Pkgmgr", "C")
|
||||
self._run("role", "work/a", "Pkgmgr", "-")
|
||||
self.assertTrue(self._out("show")[2].endswith("| Skills | Skills | | | |"))
|
||||
self.assertEqual(self._out("rm", "work/a"), ["removed work/a"])
|
||||
self.assertEqual(self._out("show"), ["no tasks"])
|
||||
|
||||
def test_invalid_input_exits_2(self):
|
||||
for args in (
|
||||
("role", "work/a", "Skills", "RR"),
|
||||
("role", "work/a", "Skills", "Q"),
|
||||
("set", "Bad Task"),
|
||||
("set", "work/a", "--prio", "0"),
|
||||
("set", "work/a", "--status", "finished"),
|
||||
("set", "work/a", "--start", "yesterday"),
|
||||
("get", "work/none"),
|
||||
("kr", "work/a", "met", "1"),
|
||||
("set", "work/a", "--artifact", "no-kind"),
|
||||
("estimate", "work/a", "One", "--value", "4", "--complexity", "2"),
|
||||
("estimate", "work/a", "One", "--value", "8"),
|
||||
):
|
||||
with self.subTest(args=args):
|
||||
self.assertEqual(self._run(*args).returncode, 2)
|
||||
self.assertFalse((self.root / "rasci.json").exists())
|
||||
|
||||
def test_pipe_in_a_title_does_not_break_the_table(self):
|
||||
self._run("set", "work/a", "--title", "a | b")
|
||||
self._run("role", "work/a", "Skills", "RA")
|
||||
self.assertTrue(self._out("show")[2].startswith("| 1 | - | work/a: a \\| b | - | queued |"))
|
||||
|
||||
def test_wsjf_ranks_by_median_estimates(self):
|
||||
self._run("set", "work/a", "--objective", "Ship A")
|
||||
self._run("kr", "work/a", "add", "released")
|
||||
self._run("estimate", "work/a", "One", "--value", "8", "--complexity", "2")
|
||||
self._run("estimate", "work/a", "Two", "--value", "13", "--complexity", "3")
|
||||
self._run("estimate", "work/b", "One", "--value", "5", "--complexity", "5")
|
||||
self._run("set", "work/c", "--title", "Gamma")
|
||||
lines = self._out("wsjf")
|
||||
self.assertEqual(
|
||||
lines[0], "| Rank | Task | OKR | Business value | Complexity | WSJF | Estimators | Status |"
|
||||
)
|
||||
self.assertEqual(lines[2], "| 1 | work/a | Ship A (0/1 KR) | 10.5 | 2.5 | 4.2 | One, Two | queued |")
|
||||
self.assertEqual(lines[3], "| 2 | work/b | - | 5 | 5 | 1 | One | queued |")
|
||||
self.assertEqual(lines[4], "| 3 | work/c | - | - | - | - | - | queued |")
|
||||
self.assertEqual(lines[5], "unestimated: work/c")
|
||||
self.assertTrue(self._out("show")[2].startswith("| 1 | 4.2 | work/a |"))
|
||||
self.assertIn("wsjf: 4.2", self._out("get", "work/a"))
|
||||
self._run("set", "work/c", "--prio", "1")
|
||||
self.assertTrue(self._out("show")[2].startswith("| 1 | - | work/c: Gamma |"))
|
||||
self._run("estimate", "work/b", "One", "--drop")
|
||||
self.assertFalse(any(line.startswith("estimate ") for line in self._out("get", "work/b")))
|
||||
|
||||
|
||||
class TestOrgSkillsUseTheRegister(unittest.TestCase):
|
||||
def test_every_org_skill_names_the_register(self):
|
||||
for skill in sorted((REPO_ROOT / "skills").glob("kvb-org-*/SKILL.md")):
|
||||
if skill.parent.name == "kvb-org-rasci":
|
||||
continue
|
||||
with self.subTest(skill=skill.parent.name):
|
||||
self.assertIn("`kvb-org-rasci`", skill.read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -1,59 +0,0 @@
|
||||
"""Validate the shortcuts skill table: rows present, sorted, ``soc``-prefixed,
|
||||
no two adjacent consonants."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
SKILL = REPO_ROOT / "skills" / "shortcuts" / "SKILL.md"
|
||||
|
||||
ROW_RE = re.compile(r"^\|\s*`(?P<shortcut>[^`]+)`\s*\|")
|
||||
VOWELS = frozenset("aeiou")
|
||||
|
||||
|
||||
def _has_consonant_cluster(name: str) -> bool:
|
||||
prev_consonant = False
|
||||
for char in name:
|
||||
if not char.isalpha():
|
||||
prev_consonant = False
|
||||
continue
|
||||
is_consonant = char.lower() not in VOWELS
|
||||
if is_consonant and prev_consonant:
|
||||
return True
|
||||
prev_consonant = is_consonant
|
||||
return False
|
||||
|
||||
|
||||
class TestShortcuts(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.assertTrue(SKILL.is_file(), f"missing {SKILL}")
|
||||
self.shortcuts = [
|
||||
match.group("shortcut")
|
||||
for line in SKILL.read_text(encoding="utf-8").splitlines()
|
||||
if (match := ROW_RE.match(line))
|
||||
]
|
||||
|
||||
def test_shortcuts_present(self):
|
||||
self.assertTrue(self.shortcuts, "no shortcut rows found in shortcuts skill")
|
||||
|
||||
def test_shortcuts_sorted_ascending(self):
|
||||
self.assertEqual(
|
||||
self.shortcuts,
|
||||
sorted(self.shortcuts),
|
||||
f"shortcuts table not sorted; expected {sorted(self.shortcuts)}",
|
||||
)
|
||||
|
||||
def test_shortcuts_start_with_so(self):
|
||||
bad = [s for s in self.shortcuts if not s.startswith("so")]
|
||||
self.assertFalse(bad, f"shortcuts not starting with 'so': {bad}")
|
||||
|
||||
def test_no_consecutive_consonants(self):
|
||||
bad = [s for s in self.shortcuts if _has_consonant_cluster(s)]
|
||||
self.assertFalse(bad, f"shortcuts with two adjacent consonants: {bad}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,120 @@
|
||||
"""Exercise legacy.py: renames chained through history, deletions, project and unknown skills."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
SCRIPT = REPO_ROOT / "skills" / "kvb-skill-cleanup" / "scripts" / "legacy.py"
|
||||
|
||||
|
||||
@unittest.skipUnless(shutil.which("git"), "git not installed")
|
||||
class TestLegacy(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.tmp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.tmp.cleanup)
|
||||
base = Path(self.tmp.name)
|
||||
self.env = {
|
||||
"PATH": "/usr/bin:/bin",
|
||||
"HOME": str(base),
|
||||
"GIT_AUTHOR_NAME": "t",
|
||||
"GIT_AUTHOR_EMAIL": "t@t",
|
||||
"GIT_COMMITTER_NAME": "t",
|
||||
"GIT_COMMITTER_EMAIL": "t@t",
|
||||
}
|
||||
self.repo = base / "skills-repo"
|
||||
self._skill(self.repo / "skills" / "old")
|
||||
(self.repo / "skills-lock.json").write_text(
|
||||
json.dumps({"skills": {"caveman": {}}}), encoding="utf-8"
|
||||
)
|
||||
self._git(self.repo, "init", "-q", "-b", "main")
|
||||
self._commit(self.repo, "add old")
|
||||
self._git(self.repo, "mv", "skills/old", "skills/mid")
|
||||
self._commit(self.repo, "rename old to mid")
|
||||
self._git(self.repo, "mv", "skills/mid", "skills/kvb-x-new")
|
||||
self._commit(self.repo, "rename mid to kvb-x-new")
|
||||
self._skill(self.repo / "skills" / "gone")
|
||||
self._commit(self.repo, "add gone")
|
||||
self._git(self.repo, "rm", "-q", "-r", "skills/gone")
|
||||
self._commit(self.repo, "remove gone")
|
||||
|
||||
self.home = base / "home" / ".claude" / "skills"
|
||||
for name in ("old", "mid", "gone", "kvb-x-new", "caveman", "mine"):
|
||||
self._skill(self.home / name)
|
||||
(self.home / "notaskill").mkdir()
|
||||
|
||||
self.project = base / "project"
|
||||
self._skill(self.project / "skills" / "p-own")
|
||||
self._git(self.project, "init", "-q", "-b", "main")
|
||||
self._commit(self.project, "own skill")
|
||||
self.installed = self.project / ".claude" / "skills"
|
||||
for name in ("p-own", "old"):
|
||||
self._skill(self.installed / name)
|
||||
|
||||
def _skill(self, path: Path) -> None:
|
||||
path.mkdir(parents=True, exist_ok=True)
|
||||
(path / "SKILL.md").write_text(
|
||||
f"---\nname: {path.name}\ndescription: probe\n---\n\nBody of the probe skill.\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
def _git(self, cwd: Path, *args: str) -> None:
|
||||
subprocess.run(["git", *args], check=True, capture_output=True, env=self.env, cwd=cwd)
|
||||
|
||||
def _commit(self, cwd: Path, message: str) -> None:
|
||||
self._git(cwd, "add", "-A")
|
||||
self._git(cwd, "commit", "-q", "-m", message)
|
||||
|
||||
def _run(self, *args: str) -> subprocess.CompletedProcess:
|
||||
return subprocess.run(
|
||||
[sys.executable, str(SCRIPT), *args],
|
||||
check=False,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
env=self.env,
|
||||
)
|
||||
|
||||
def test_every_installed_skill_gets_its_verdict(self):
|
||||
result = self._run(
|
||||
"--skills-repo", str(self.repo),
|
||||
"--root", str(self.home),
|
||||
"--root", str(self.installed),
|
||||
"--json",
|
||||
)
|
||||
self.assertEqual(result.returncode, 0, result.stderr)
|
||||
home, project = str(self.home), str(self.installed)
|
||||
rows = sorted(
|
||||
(str(Path(row["path"]).parent), Path(row["path"]).name, row["verdict"], row["successor"])
|
||||
for row in json.loads(result.stdout)
|
||||
)
|
||||
self.assertEqual(
|
||||
rows,
|
||||
sorted(
|
||||
[
|
||||
(home, "caveman", "current", None),
|
||||
(home, "gone", "removed", None),
|
||||
(home, "kvb-x-new", "current", None),
|
||||
(home, "mid", "legacy", "kvb-x-new"),
|
||||
(home, "mine", "unknown", None),
|
||||
(home, "old", "legacy", "kvb-x-new"),
|
||||
(project, "old", "legacy", "kvb-x-new"),
|
||||
(project, "p-own", "project", None),
|
||||
]
|
||||
),
|
||||
)
|
||||
|
||||
def test_invalid_input_exits_2(self):
|
||||
missing = self._run("--skills-repo", str(self.repo), "--root", str(self.home / "nope"))
|
||||
self.assertEqual(missing.returncode, 2)
|
||||
no_repo = self._run("--skills-repo", str(self.home), "--root", str(self.home))
|
||||
self.assertEqual(no_repo.returncode, 2)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -1,4 +1,4 @@
|
||||
"""Exercise the subagent-model log: spawn hook, feedback, sandbox persist, report."""
|
||||
"""Exercise the kvb-org-perform log: spawn hook, feedback, sandbox persist, report."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -10,7 +10,7 @@ import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
LOG_PY = REPO_ROOT / "skills" / "subagent-model" / "scripts" / "log.py"
|
||||
LOG_PY = REPO_ROOT / "skills" / "kvb-org-perform" / "scripts" / "log.py"
|
||||
|
||||
|
||||
class TestSubagentModelLog(unittest.TestCase):
|
||||
@@ -66,13 +66,13 @@ class TestSubagentModelLog(unittest.TestCase):
|
||||
|
||||
def test_sandboxed_feedback_is_printed_and_stored_by_the_persist_hook(self):
|
||||
stdout = self._pending_feedback()
|
||||
self._persist("python3 /x/skills/subagent-model/scripts/log.py feedback --description 'd'", stdout)
|
||||
self._persist("python3 /x/skills/kvb-org-perform/scripts/log.py feedback --description 'd'", stdout)
|
||||
self.assertEqual(self._lines()[0]["kind"], "feedback")
|
||||
|
||||
def test_persist_rejects_pending_lines_it_did_not_get_from_a_bare_log_call(self):
|
||||
stdout = self._pending_feedback()
|
||||
line = json.loads(stdout[len("pending: "):])
|
||||
call = "/x/skills/subagent-model/scripts/log.py feedback --description d"
|
||||
call = "/x/skills/kvb-org-perform/scripts/log.py feedback --description d"
|
||||
for command, output, session in (
|
||||
("cat ci.log", stdout, "s1"),
|
||||
(f"{call}; cat ci.log", stdout, "s1"),
|
||||
@@ -82,7 +82,7 @@ class TestSubagentModelLog(unittest.TestCase):
|
||||
(call, stdout + stdout, "s1"),
|
||||
(call, "pending: " + json.dumps({**line, "extra": 1}), "s1"),
|
||||
(call, "pending: " + json.dumps({**line, "completed": "yes"}), "s1"),
|
||||
("/x/skills/subagent-model/scripts/log.py followup --description d", stdout, "s1"),
|
||||
("/x/skills/kvb-org-perform/scripts/log.py followup --description d", stdout, "s1"),
|
||||
):
|
||||
self._persist(command, output, session)
|
||||
self.assertFalse(self.log.exists())
|
||||
|
||||
@@ -0,0 +1,113 @@
|
||||
"""Exercise transcend.py: sources, secret and size filters, and the decision memory."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
SCRIPT = REPO_ROOT / "skills" / "kvb-transcend" / "scripts" / "transcend.py"
|
||||
|
||||
|
||||
class TestTranscend(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.tmp = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self.tmp.cleanup)
|
||||
root = Path(self.tmp.name)
|
||||
self.home = root / "home"
|
||||
self.peers = root / "peers"
|
||||
self.own = self.peers / "proj" / "s1" / "scratchpad"
|
||||
self.peer = self.peers / "proj" / "s2" / "scratchpad"
|
||||
self.repo = root / "skills-repo"
|
||||
self.state = self.repo / ".state" / "transcend.json"
|
||||
for path in (self.own, self.peer, self.repo / "skills" / "kvb-x"):
|
||||
path.mkdir(parents=True)
|
||||
(self.repo / "skills-lock.json").write_text(
|
||||
json.dumps({"skills": {"caveman": {}}}), encoding="utf-8"
|
||||
)
|
||||
sessions = self.home / ".claude" / "sessions"
|
||||
sessions.mkdir(parents=True)
|
||||
(sessions / "s2.json").write_text(
|
||||
json.dumps({"sessionId": "s2", "name": "Peer"}), encoding="utf-8"
|
||||
)
|
||||
self._write(self.own / "probe.py", "print(1)")
|
||||
self._write(self.own / "test_probe.py", "assert True")
|
||||
self._write(self.own / "notes.log", "noise")
|
||||
self._write(self.own / "auth_token.py", "secret")
|
||||
self._write(self.own / "big.py", "x" * 1_000_001)
|
||||
self._write(self.peer / "helper.sh", "echo hi")
|
||||
for name in ("kvb-x", "caveman", "custom"):
|
||||
self._write(self.home / ".claude" / "skills" / name / "SKILL.md", name)
|
||||
self._write(self.home / ".codex" / "rules" / "default.rules", "allow")
|
||||
|
||||
def _write(self, path: Path, text: str) -> None:
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(text, encoding="utf-8")
|
||||
|
||||
def _run(self, *args: str) -> subprocess.CompletedProcess:
|
||||
return subprocess.run(
|
||||
[sys.executable, str(SCRIPT), *args], capture_output=True, text=True, check=False
|
||||
)
|
||||
|
||||
def _scan(self) -> list[dict]:
|
||||
result = self._run(
|
||||
"scan",
|
||||
"--state", str(self.state),
|
||||
"--skills-repo", str(self.repo),
|
||||
"--session-dir", str(self.own),
|
||||
"--peers-root", str(self.peers),
|
||||
"--home", str(self.home),
|
||||
"--json",
|
||||
)
|
||||
self.assertEqual(result.returncode, 0, result.stderr)
|
||||
return json.loads(result.stdout)
|
||||
|
||||
def _found(self) -> dict[str, tuple[str, str, str]]:
|
||||
return {
|
||||
Path(i["path"]).name: (i["source"], i["owner"], i["kind"]) for i in self._scan()
|
||||
}
|
||||
|
||||
def test_scan_finds_own_peer_and_home_candidates(self):
|
||||
self.assertEqual(
|
||||
self._found(),
|
||||
{
|
||||
"probe.py": ("own", "self", "script"),
|
||||
"test_probe.py": ("own", "self", "test"),
|
||||
"helper.sh": ("peer", "Peer", "script"),
|
||||
"custom": ("home", "operator", "skill"),
|
||||
"default.rules": ("home", "operator", "rule"),
|
||||
},
|
||||
)
|
||||
|
||||
def test_settled_candidates_are_remembered_until_they_change(self):
|
||||
probe = self.own / "probe.py"
|
||||
self.assertEqual(self._run("mark", "--state", str(self.state), str(probe), "carried").returncode, 0)
|
||||
self._run("mark", "--state", str(self.state), str(self.own / "test_probe.py"), "later")
|
||||
found = {Path(i["path"]).name: i["previous"] for i in self._scan()}
|
||||
self.assertNotIn("probe.py", found)
|
||||
self.assertEqual(found["test_probe.py"], "later")
|
||||
|
||||
probe.write_text("print(2)", encoding="utf-8")
|
||||
found = {Path(i["path"]).name: i["previous"] for i in self._scan()}
|
||||
self.assertEqual(found["probe.py"], "carried")
|
||||
|
||||
def test_skill_directory_change_is_reoffered(self):
|
||||
custom = self.home / ".claude" / "skills" / "custom"
|
||||
self._run("mark", "--state", str(self.state), str(custom), "dropped")
|
||||
self.assertNotIn("custom", self._found())
|
||||
self._write(custom / "scripts" / "run.py", "print(3)")
|
||||
self.assertIn("custom", self._found())
|
||||
|
||||
def test_invalid_input_exits_2(self):
|
||||
self.assertEqual(self._run("mark", "--state", str(self.state), "/no/such/path", "carried").returncode, 2)
|
||||
self.assertEqual(self._run("mark", "--state", str(self.state), str(self.own), "kept").returncode, 2)
|
||||
self.assertEqual(self._run("scan", "--state", str(self.state)).returncode, 2)
|
||||
self.assertFalse(self.state.exists())
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
+2
-2
@@ -1,4 +1,4 @@
|
||||
"""Exercise the democracy resource watch: stages, projection, block, admit, alerts, caches."""
|
||||
"""Exercise the kvb-org-organize resource watch: stages, projection, block, admit, alerts, caches."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -13,7 +13,7 @@ import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||||
WATCH = REPO_ROOT / "skills" / "democracy" / "scripts" / "watch.py"
|
||||
WATCH = REPO_ROOT / "skills" / "kvb-org-organize" / "scripts" / "watch.py"
|
||||
LIMITS = {"warn": 40, "stop": 15, "critical": 12}
|
||||
|
||||
|
||||
|
||||
Reference in new issue
Block a user