@kernel.chat/kbot 3.97.4 → 3.99.0

package/skills/music-production/ableton-session-build/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: ableton-session-build
+description: Use when the user wants to build a track, beat, or arrangement in Ableton Live. kbot drives Ableton via OSC — you don't type notes, you describe the idea.
+version: 1.0.0
+author: kbot
+license: MIT
+platforms: [darwin]
+metadata:
+  kbot:
+    tags: [ableton, music, osc, m4l, production]
+    related_skills: [serum2-preset-craft, dj-set-builder]
+---
+
+# Ableton Session Build
+
+kbot has 14 Ableton tools, 9 M4L devices, and a full OSC bridge. You describe a beat; kbot lays it down in a live session.
+
+## Iron Law
+
+```
+VERIFY THE OSC BRIDGE FIRST. EVERY TIME.
+```
+
+Without a live bridge, every tool call silently fails. Check before you plan.
+
+## Preflight (2 commands)
+
+1. `ableton_session_info` — if this returns tempo + tracks, you're connected.
+2. If it times out: remind the user to start Live and enable the AbletonOSC remote script (`Link/Tempo/MIDI → Control Surface → AbletonOSC`).
+
+## Production Flow
+
+1. **Set the frame**: `ableton_transport` to set tempo, key hint via scene naming, time signature.
+2. **Create tracks**: one `ableton_create_track` per role (drums, bass, pad, lead, FX).
+3. **Load sounds**: `ableton_load_sample` for one-shots; `ableton_load_plugin` for Serum/synths; `ableton_load_preset` for factory patches.
+4. **Write patterns**: `ableton_midi` with note arrays. Use `generate_drum_pattern` / `generate_melody_pattern` as starting points.
+5. **Arrange**: `ableton_scene` to build verse/chorus/drop scenes; `ableton_clip` to fire them.
+6. **Mix**: `ableton_mixer` for levels/pan; `ableton_effect_chain` for returns; `ableton_device` for insert FX.
+7. **Capture**: render via transport record, or have the user bounce the arrangement.
+
+## Specialist Escalations
+
+- Preset design needed? Use `serum2-preset-craft`.
+- Full DJ set needed? Use `dj-set-builder`.
+- Sound too generic? Route to `aesthete` specialist with the current session_info for creative direction.
+
+## Anti-Patterns
+
+- Writing MIDI before verifying the bridge responds. Silent failures waste the whole session.
+- Loading plugins without checking the user has them installed. Use `ableton_browse` first.
+- Generating 32-bar patterns in one call. Work in 4- and 8-bar loops; iterate.
+
+## Known Fragility
+
+- AbletonOSC's `set/notes` endpoint quirks — if clip writes fail, fall back to setting notes via `ableton_clip.write_notes` with explicit velocity + duration.
+- Sample loading can 404 if the browser index is stale. `ableton_browse --refresh` fixes it.
+- Clip firing during a running session can drop the first beat. Fire on scene boundary, not mid-bar.
+
+## What Emerges
+
+The user stops thinking in Live's UI and starts describing ideas. "Make it darker" becomes a legitimate prompt because kbot knows darker = minor key + sub-bass boost + reverb tail + plate on the snare. This is the skill paying off over sessions.

package/skills/orchestration/cross-agent-blackboard/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: cross-agent-blackboard
+description: Use when more than one agent works on the same problem. The blackboard is the shared context — without it, agents duplicate work and contradict each other.
+version: 1.0.0
+author: kbot
+license: MIT
+metadata:
+  kbot:
+    tags: [agents, coordination, blackboard, multi-agent]
+    related_skills: [specialist-routing, agent-handoff]
+---
+
+# Cross-Agent Blackboard
+
+Single-agent sessions use memory. Multi-agent sessions need a blackboard — a shared write-read surface every participating agent sees.
+
+## When
+
+- `kbot --architect` (plan + implement by two agents)
+- `/team` running all 6 specialists against the same change
+- `agent_handoff` passing control with preserved context
+- Matrix agents collaborating on a research question
+
+## Iron Law
+
+```
+ANY AGENT TAKING OVER MUST READ THE BLACKBOARD BEFORE ACTING.
+ANY AGENT LEAVING MUST WRITE TO THE BLACKBOARD BEFORE EXITING.
+```
+
+## Protocol
+
+Blackboard entries have four fields: `type` (decision/finding/blocker/artifact), `key` (short slug), `value` (the payload), `author` (agent id).
+
+- `blackboard_write({ type, key, value })` — before handing off or pausing.
+- `blackboard_read({ keyPrefix?, type? })` — on entry or after a long subagent call.
+- `blackboard_query()` — full dump when context is lost.
+
+## Example Flow (from a real session)
+
+1. `researcher` investigates a library version incompatibility.
+2. Writes `{ type: 'finding', key: 'axios.v1-vs-v2', value: 'v2 breaks the retry middleware' }`.
+3. Hands off to `coder` via `agent_handoff`.
+4. `coder` reads the blackboard, sees the finding, and skips re-researching.
+5. Writes `{ type: 'artifact', key: 'axios-pin', value: 'pinned to 1.6.7 in package.json' }`.
+6. `guardian` runs later, reads both entries, confirms no regression, writes `{ type: 'decision', key: 'axios-pin', value: 'approved' }`.
+
+Total time from research to verified fix: 8 minutes. Without the blackboard: each agent would re-derive context, easily 25+ minutes.
+
+## Anti-Patterns
+
+- Passing context through the user ("please tell the next agent X"). The user is not a message bus.
+- Writing vague entries ("looked into the bug"). Name the finding concretely or don't write it.
+- Reading only your own writes. Other agents' entries are the whole point.
+
+## What Emerges
+
+With the blackboard habit, specialist chains start behaving like one compound agent. The user types one prompt, three specialists take turns, and the handoffs are invisible — because context never dropped.

package/skills/orchestration/specialist-routing/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: specialist-routing
+description: Use when a task clearly belongs to a specialist agent. Route first, reason second — don't let the general agent muddle through a domain it has a specialist for.
+version: 1.0.0
+author: kbot
+license: MIT
+metadata:
+  kbot:
+    tags: [agents, routing, specialists, delegation]
+    related_skills: [matrix-agent-spawn, cross-agent-blackboard, agent-handoff]
+---
+
+# Specialist Routing
+
+kbot ships with 25+ specialists (run `kbot agents list` for the current roster). The default `kernel` agent is a generalist — competent everywhere, excellent nowhere. The feeling of "kbot is sharp" comes from routing into the right specialist before work starts.
+
+## Iron Law
+
+```
+IF A SPECIALIST EXISTS FOR THIS DOMAIN, THE GENERALIST DOES NOT TOUCH IT.
+```
+
+## The Roster
+
+| Signal | Specialist | Why |
+|---|---|---|
+| "review my code", "refactor", "fix this test" | `coder` | strongest code-patching track record |
+| "research X", "find me", "what does the literature say" | `researcher` | web + arxiv + citation graph |
+| "design this", "make it look right", a11y | `aesthete` | design tokens + spacing + typography |
+| "is this safe", secrets, auth, permissions | `guardian` | OWASP checks, dep audit, redact |
+| CI, deploys, env vars, launchd, docker | `infrastructure` | full infra toolkit |
+| a statistical question, backtesting, distributions | `quant` | stats + finance + probability |
+| a 30+ minute deep dive, multi-source | `investigator` | multi-step research workflow |
+| "write" anything long-form | `writer` | content creation + editing |
+| strategy, tradeoffs, business framing | `strategist` | structured decision support |
+| how it's going, "predict X" | `oracle` | forecasting + anticipation |
+
+## Trigger
+
+The moment the user's first message can be classified into the table above. The learned router handles this automatically when confidence ≥ 0.7; below that, you route explicitly: `kbot --agent <id> "..."`.
+
+## Procedure
+
+1. **Classify the task** against the table. If two match, pick the one closer to the *verb* (review → coder; design review → aesthete).
+2. **If none match**, stay on `kernel` and invoke the skill that fits instead.
+3. **When in doubt**, use `--architect` (plan with one specialist, implement with another) or `--plan` (read-only scoping first).
+4. **If the specialist gets stuck**, use `agent_handoff` to pass to another specialist with context — don't fall back to the generalist silently.
+
+## Anti-Pattern
+
+- Running everything on the default agent "for consistency." You lose every specialist advantage.
+- Choosing a specialist by *topic* instead of *verb*. "Music" isn't a specialist; `aesthete` handles creative direction and `coder` handles the OSC scripting.
+- Routing between specialists mid-task without writing to the blackboard — the next specialist loses context.
+
+## What Emerges
+
+Users develop muscle memory for `kbot --agent <id>`. Over weeks, the learned router picks up which specialist wins which task *for this user* (not average) and routes preemptively. The experience becomes: "I type the prompt, the right expert answers." That's the routing skill paying compound interest.

package/skills/self-improvement/autopoiesis-loop/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: autopoiesis-loop
+description: Use when planning multi-session work. The autopoiesis loop is kbot using itself to improve itself — every session should end a little sharper than it started.
+version: 1.0.0
+author: kbot
+license: MIT
+metadata:
+  kbot:
+    tags: [self-improvement, meta, dogfood, autopoiesis]
+    related_skills: [skill-self-authorship, teacher-trace-curation, dream-to-commit]
+---
+
+# The Autopoiesis Loop
+
+kbot is the tool *and* the workbench. Every session has two outputs: the thing the user asked for, and the incremental improvement to kbot itself. Sessions that only produce the first are leaving compound interest on the table.
+
+## The Five Moves (once per session)
+
+1. **Session start** — run `kbot bootstrap`. The bootstrap agent surfaces the highest-leverage improvement based on accumulated signals. Do this before feature work, not instead of it.
+2. **During work** — notice repeated patterns. Each repetition is a skill waiting to be written (`skill-self-authorship`).
+3. **On friction** — missing tool? `forge-reflex`. Wrong specialist? Update the learned router via corrective feedback.
+4. **Session end** — update `SCRATCHPAD.md` with what you learned (not what you did). The next session's opening context reads this file.
+5. **Overnight** — the dream engine consolidates transcripts into memory entries. The daemon reviews diffs, runs code quality scans, translates i18n. Work continues while the user sleeps.
+
+## Iron Law
+
+```
+NEVER END A SESSION WORSE THAN IT STARTED.
+```
+
+If kbot hit a wall and you didn't leave a corrective signal behind (a skill, a memory, a scratchpad note, a corrected learned-router pattern), the loop is broken.
+
+## The Three Signals That Compound
+
+- **Corrections** — user says "no, do X instead." These go into `~/.kbot/corrections/` and load as closed-loop prompts.
+- **Teacher traces** — every non-local Claude call is logged to `~/.kbot/teacher/traces.jsonl`. Weekly, `kbot train-self` fine-tunes local models on the best ones.
+- **Skills** — successful patterns distilled into `~/.kbot/skills/`. Loaded on relevance.
+
+Each of these runs automatically once wired up. The skill is knowing to wire them up in the first place.
+
+## What Emerges
+
+Three weeks of active use and kbot's answers start feeling tuned to *this user* specifically. Six weeks in, the local model (via `train-self`) is answering basic questions at zero cost. Three months in, kbot's corrections archive has more collective wisdom than the user's own notes.
+
+## Anti-Pattern
+
+Running kbot as a pure consumer — asking questions, using answers, never looking at what's in `~/.kbot/`. You're paying for the loop with every API call but not collecting the dividend.

package/skills/self-improvement/skill-self-authorship/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: skill-self-authorship
+description: Use at the end of any session where you solved something non-obvious or repeated a pattern 3+ times. Write a new skill so the next session doesn't re-derive it.
+version: 1.0.0
+author: kbot
+license: MIT
+metadata:
+  kbot:
+    tags: [skills, meta, autopoiesis, learning]
+    related_skills: [forge-reflex, autopoiesis-loop, teacher-trace-curation]
+---
+
+# Skill Self-Authorship
+
+The skills that ship with kbot cover known territory. The skills that make *your* kbot feel psychic are the ones it writes for itself during use.
+
+## When to Write a New Skill
+
+At least one of these must be true:
+- You solved something that took 5+ tool calls and got it right.
+- You repeated the same sequence of tool calls 3+ times this week.
+- You corrected kbot twice on the same kind of mistake.
+- A user gave explicit feedback "remember this" / "always do X" / "never do Y."
+- A daemon surfaced a recurring failure kbot had to work around.
+
+## Skill Anatomy
+
+Use `~/.kbot/skills/<category>/<kebab-name>/SKILL.md`. Frontmatter:
+
+```yaml
+---
+name: kebab-name
+description: One sentence — "when to use."
+version: 1.0.0
+author: kbot-self
+license: MIT
+metadata:
+  kbot:
+    tags: [2-5 lowercase tags]
+    related_skills: [other skills this connects to]
+---
+```
+
+Body structure:
+1. **Iron Law** — the one rule that, if broken, invalidates the skill.
+2. **Trigger** — the exact situation that should make kbot reach for this.
+3. **Procedure** — 3–6 numbered steps. Not prose. Commands and decisions.
+4. **Anti-patterns** — the failure modes to refuse.
+
+## The "When to Use" Line Is Everything
+
+The relevance scorer reads `description` and `tags` first. If your description is "general debugging tips" the skill will never load. If it's "use when any vitest test fails with ENOENT" it loads exactly when needed. Write for the trigger, not the topic.
+
+## Self-Patching
+
+Use the `skill_manage` tool after a skill executes:
+- `skill_manage({ action: "get", query: "<skill-id>" })` — check current success rate.
+- If the skill failed, `skill_manage({ action: "patch", query: "<skill-id>", issue: "<what went wrong>" })` appends the issue.
+- If a better step sequence was discovered, `skill_manage({ action: "patch", query: "<skill-id>", steps: "[...]" })` replaces the steps and bumps version.
+- `skill_manage({ action: "report" })` shows the success-rate distribution across all skills.
+
+A skill with a 20% success rate after 10 executions is a bug report — rewrite or delete (`action: "delete"`).
+
+## What Emerges
+
+After 30 days of active use, `~/.kbot/skills/` reflects the user's actual work more precisely than any config file. The skills library is the durable shadow of every problem kbot helped solve.
+
+## Anti-Pattern
+
+Writing a skill for every clever thing you did. Skills have a maintenance cost — each one competes for token budget and relevance scoring attention. Write one skill per *repeated* problem, not per *interesting* problem.

package/skills/self-improvement/teacher-trace-curation/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: teacher-trace-curation
+description: Use weekly. The teacher log captures every non-local Claude call — curate the best ones into training data so the local model learns from your actual work.
+version: 1.0.0
+author: kbot
+license: MIT
+metadata:
+  kbot:
+    tags: [training, fine-tuning, mlx, local-model, dataset]
+    related_skills: [autopoiesis-loop, skill-self-authorship]
+---
+
+# Teacher Trace Curation
+
+Every time kbot calls Claude, the prompt + response is written to `~/.kbot/teacher/traces.jsonl`. Left alone, this is just a log. Curated, it's the dataset that teaches the local model to answer *your* questions without touching the API.
+
+## Iron Law
+
+```
+ONLY SUCCESSFUL, CORRECTED, AND USER-APPROVED TRACES ENTER THE DATASET.
+```
+
+Failed traces teach the model to fail. Garbage in is not "more data."
+
+## The Weekly Ritual
+
+1. `kbot train-self --mode default --max-examples 500 --iters 200 --num-layers 8` — curates + fine-tunes in one pass. The curator runs first, scores traces, and writes `~/.kbot/teacher/dataset-default.jsonl`.
+2. Review the top 50 entries in the dataset file. Skim titles + first 200 chars.
+3. Remove anything you wouldn't want the local model to imitate:
+   - Responses you corrected mid-session.
+   - Hallucinated library names or APIs.
+   - Advice you later decided was wrong.
+4. Re-run step 1 with the cleaned dataset if you made significant deletions.
+5. Test: `ollama run kernel-self:<timestamp>` on a task from the last week. Compare against the Claude baseline.
+
+For longer cycles of evaluation + retraining, use `kbot train-cycle` which chains curate → train → evaluate → merge across multiple iterations.
+
+## The Quality Signal That Matters Most
+
+Was this answer *used* without correction? The curator scores partly on: no correction in the next 5 turns, no follow-up question asking for clarification, no user rephrasing. Approved-by-silence is the strongest endorsement.
+
+## What You're Actually Building
+
+A local model that answers "how do I deploy this?" using *your* deploy flow, not Anthropic's generic best practice. Your infrastructure, your naming, your conventions, your past decisions. That's what the local model becomes over weeks.
+
+## Anti-Pattern
+
+Training on everything. Larger datasets with noisy data fine-tune *worse* models than small curated datasets. 200 excellent examples beat 2,000 mediocre ones every time.
+
+## Integration
+
+- `KBOT_TEACHER_LOG=1` in `~/.zshrc` keeps the logger always-on.
+- `launchd` plist at `~/Library/LaunchAgents/com.kernel.kbot-train-self.plist` runs the curation + training weekly.
+- The trained model gets tagged `kernel-self:<timestamp>` in Ollama and becomes available to every kbot command via `--model kernel-self:latest`.

package/skills/software-development/systematic-debugging/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: systematic-debugging
+description: Use when any test fails, any bug surfaces, or any behavior is unexpected. Enforces root-cause analysis before code changes.
+version: 1.0.0
+author: kbot
+license: MIT
+metadata:
+  kbot:
+    tags: [debugging, root-cause, investigation, tdd]
+    related_skills: [test-driven-development, ship-pipeline, specialist-routing]
+---
+
+# Systematic Debugging
+
+Random fixes waste time and create new bugs. Before writing a single line of fix, you must understand *why* it broke.
+
+## Iron Law
+
+```
+NO FIX WITHOUT A NAMED ROOT CAUSE.
+```
+
+If you can't finish the sentence "It broke because ___", you are not ready to edit.
+
+## When to Use
+
+- Any failing test
+- Any exception in a log
+- Any "this used to work"
+- Any UI regression
+- Any flaky behavior
+- Any build failure
+
+Especially use this under time pressure — "quick fix" almost always means "new bug tomorrow."
+
+## Four Phases
+
+### Phase 1 — Reproduce
+
+- Run the failing case *exactly*. Don't paraphrase the command.
+- Capture the full error: message, stack, file, line.
+- If you can't reproduce, you don't understand the bug yet — stop and gather more evidence.
+
+Tools: `bash` to run the command, `kbot_read` to open the file at the stack trace line, `git_diff` to see what changed recently.
+
+### Phase 2 — Isolate
+
+- Binary-search the change set. Use `git log --oneline -20` and check the last commit that touched the area.
+- Trace the data flow upstream from the symptom. The bug almost never lives where the exception fires.
+- Find a *working* similar case in the same codebase. What's different?
+
+Tools: `grep` for the bad value, `git_log` for history, subagent with Explore to map the call graph.
+
+### Phase 3 — Hypothesize
+
+- Write down one sentence: "I think this is caused by X because Y."
+- Predict what the smallest possible reproduction looks like.
+- Predict what the smallest possible fix looks like.
+
+Do **not** write code yet. Share the hypothesis first if the user is watching.
+
+### Phase 4 — Fix
+
+1. Write a failing test that captures the bug (see `test-driven-development`).
+2. Make the minimal change that turns it green.
+3. Run the full suite. No regressions.
+4. Commit with a message that names the root cause, not the symptom.
+
+## The Rule of Three
+
+If your third fix attempt failed, **stop**. Don't try a fourth. The bug is not where you think it is, or the architecture is wrong. Escalate — use `kbot_plan` or hand off to a specialist agent.
+
+## Red Flags (stop and restart)
+
+- "Let me just try this and see"
+- "I'll comment this out for now"
+- Changing more than one thing per commit
+- Adding a try/except to make the error go away
+- "It works on my machine"
+
+## How kbot Helps
+
+- `kbot --thinking` shows reasoning — use it when debugging complex issues.
+- `kbot --agent coder` routes to the specialist with strongest code-patching track record.
+- `kbot --plan` forces read-only investigation mode for Phase 1 & 2.
+- `forge_tool` builds a throwaway diagnostic script when stdlib tools aren't enough.

package/skills/software-development/test-driven-development/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: test-driven-development
+description: Use when adding any new behavior or fixing any bug. Red → Green → Refactor, enforced.
+version: 1.0.0
+author: kbot
+license: MIT
+metadata:
+  kbot:
+    tags: [tdd, testing, quality, vitest]
+    related_skills: [systematic-debugging, ship-pipeline]
+---
+
+# Test-Driven Development
+
+## Iron Law
+
+```
+THE FIRST COMMIT ON ANY BEHAVIOR CHANGE IS A FAILING TEST.
+```
+
+No exceptions. Not "I'll add tests after." Not "this is too small." The failing test proves you understood the behavior before you wrote it.
+
+## Why
+
+- Writing the test first forces you to design the interface, not the implementation.
+- A failing test that turns green is the only honest proof the fix works.
+- Tests written after the fact confirm what you already did, not what you should have done.
+- Coverage that grows alongside code never has a "we should add tests" backlog.
+
+## The Cycle
+
+### RED
+
+1. Decide what the new behavior is, in one sentence.
+2. Write the smallest test that would fail if the behavior is missing.
+3. Run it. Confirm it fails for the *right reason* (not a typo, not a missing import).
+
+### GREEN
+
+1. Write the minimum code that makes the test pass.
+2. No extra features. No refactoring yet. No "while I'm here."
+3. Run the test. Confirm green.
+
+### REFACTOR
+
+1. Now — and only now — clean up the implementation.
+2. Rename, extract, deduplicate. Tests still green the whole time.
+3. If a refactor turns a test red, you changed behavior — revert and think.
+
+## kbot Toolchain
+
+- Framework: **Vitest** (`.test.ts` next to source).
+- Runner: `npx vitest run` (one-shot) or `npx vitest` (watch).
+- Typecheck gate: `npx tsc --noEmit` before every commit. Strict mode is non-negotiable.
+- UI tests: `@testing-library/react`.
+- E2E: Playwright (`npm run test:e2e`).
+
+## Mocking Policy
+
+- Mock Supabase. Never call the real API in tests.
+- Mock the Claude proxy. Never call the real API in tests.
+- Do NOT mock your own pure functions — test them directly.
+- Do NOT mock file I/O — use `tmpdir()` fixtures.
+
+## Anti-Patterns
+
+- Tests that assert implementation details (internal method calls) instead of observable behavior.
+- Tests that share state between cases. Each test starts clean.
+- Test names like `it('works')`. Name the behavior: `it('rejects unauthenticated requests')`.
+- "Fix the test" when the test correctly catches a regression. Fix the code.
+
+## When kbot Should Run Tests Autonomously
+
+After any edit under `src/` or `packages/kbot/src/`, kbot runs `npm run typecheck` and `npx vitest run <affected>` before reporting success. No UI claim without a browser check (see `ship-pipeline`).