@kernel.chat/kbot 3.98.0 → 3.99.1

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`).