@assuredloop/orca-bot-kit 0.1.0 → 0.2.0

package/skills/obk-bot-building/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: obk-bot-building
+description: >-
+  Bringing a bot into being: finding out whether the job wants one at all,
+  interviewing its owner into a charter that says what it owns, what good
+  looks like and what it must ask about first, splitting a role that carries
+  unrelated work, giving each session a duty of its own, choosing the skills
+  the job needs and no more, and carrying an existing conversation across.
+  Use when someone wants a new bot, another session on a bot they have, a
+  role written down, or a session they already run brought in.
+---
+
+# Making a bot
+
+A bot is a job somebody holds, not a prompt that came out well. The work is
+the interview; the files it leaves behind are the easy part, and the kit's
+own commands write them.
+
+These are defaults for work where nothing says otherwise. A user who asks for
+something else gets what they asked for; say which of these you left and why.
+
+## Ask whether this wants a new bot
+
+Look at the fleet before you add to it. Where a bot already there could own
+this job, say so and offer that instead: a second bot with an overlapping job
+splits the context, and now two of them half-know the same thing and neither
+is accountable for it.
+
+A new bot earns its place when the work has an owner who is not the owner of
+any existing one, or when a real bottleneck has shown up: the shared context
+is noisy, the bot cannot review its own work, or the permissions the job
+needs are wider than the ones it has now. Wanting the work done faster is not
+one of those.
+
+Say which it is, in one line, before you write anything.
+
+## Name it after a job a person could hold
+
+Inbox Manager, Expense Manager, API Reviewer. A name that describes a job
+brings its own boundary with it, and everyone reading the roster later knows
+what to send it and what not to.
+
+A name that describes a tool, a model, a mood or everything ("assistant")
+does not, and leaves a bot nobody can hold to anything.
+
+## The interview writes the charter
+
+Three questions, and they are the charter: what this bot owns, what good work
+looks like for it, and what it must ask about before it acts.
+
+Ask the three together, and bring an answer of your own to each. Someone who
+is handed a blank page writes a paragraph they will not recognise in a month;
+someone who is handed a draft corrects it in a sentence, and the correction is
+the part worth having. Say which parts of your draft you inferred so they know
+what to push back on.
+
+Write what they said, in their words. Where an answer is too vague to act on,
+keep it and ask again rather than tidying it into something that only looks
+finished. A charter nobody recognises is worse than a short one: it will be
+followed.
+
+Stop when those three are answered. The rest of what a bot needs is settings,
+and settings are not an interview.
+
+## Split a role that carries unrelated work
+
+Where the job needs several unrelated verbs, it is two jobs. Say so and
+propose the split rather than writing one charter that covers both, and split
+by domain rather than by how much work there is: a bot with a narrow domain
+and a lot to do is fine, and a bot with two domains and very little is not.
+
+The test is whether one sentence can say what it owns without an "and" doing
+the heavy lifting.
+
+## Say what it may do alone, and what it must ask about
+
+Sort by what can be undone. What is reversible, it does; what is not, it asks
+about first. A limit is a normal part of a charter and reads as a plain
+sentence: read-only, does not modify. Never sends anything outside the company
+without a yes. Never spends money.
+
+Give the limit teeth by saying what evidence it brings when it escalates, so
+asking is one message rather than a conversation.
+
+Within that boundary the bot acts on its own; that is the point of writing it
+down.
+
+## The role, the task, and the procedure
+
+Three lifetimes, and they belong in three places. The role is durable and
+lives in the charter. A task is one assignment and lives in the message that
+asks for it. A procedure is reusable and lives in a skill.
+
+A one-off correction is a task. Do not let it rewrite the role: "not like
+that, do it this way today" said once becomes a rule forever, and a year later
+nobody can say why the bot refuses something reasonable. Where a correction
+really is durable, say that you are changing the charter, and change it.
+
+## A session is a duty, not a copy
+
+Sessions of one bot share its home, its rules and its skills. What tells them
+apart is the start prompt, and nothing else: it is sent when the tab is made
+and again after a clear, and it is the only thing that says this tab is the
+one that reviews and that one is the one that answers mail.
+
+Each carries its own harness, model, effort, context window and approval
+level. Leave a setting out and the harness's own default applies, which is
+usually right; do not put a model id in because it sounds current. Where the
+model someone asked for is not available, say so and ask. Never quietly run
+on another one: a bot that silently changed model is a bot whose output
+nobody can compare with last week's.
+
+Approval is the ordinary automatic level unless the user asks for something
+else in plain words. Do not raise it to make a session smoother.
+
+## Offer a line-up rather than a blank page
+
+Someone making their first bots does not know what a good set looks like, so
+propose one and say what each part is for. A pair of developers on different
+models with an architect over them, where one implements, the other writes
+the acceptance tests and reviews, and the architect settles disagreements and
+digs into the hard causes. A workhorse, a writer and a thinker, for work that
+is not development.
+
+Suggestions only: they take out or rename what they like, and you build what
+they end up with.
+
+## Give it the skills the job needs, and no more
+
+Match the skills to the work, not to the title. Something that mostly finds
+things out wants `obk-researching`; something that writes for people wants
+`obk-writing`; a bot that decides wants `obk-decision-memo`. A developer bot
+wants `obk-tdd`, `obk-reviewing` and `obk-debugging`, a reviewer the reviewing
+one above all, and an architect `obk-arch` on top. Someone's own errands want
+`obk-personal-facilitation`.
+
+Every extra skill is more for the bot to read and one more thing that might
+fire when it should not. Where you are not sure, leave it out and add it when
+the job shows it is missing.
+
+A skill can come from the kit, from the user's own folder, from a repo
+online, or from a path on disk. An online source is pinned to a version, and
+it is worth saying out loud that a source carrying scripts or hooks runs on
+their machine on their risk.
+
+## Bringing in a session they already run
+
+Someone moving in usually has a conversation going that they do not want to
+lose. Take the harness's own id for it and record it against the session in
+the book (by hand, since no command takes an outside id), and `obk up` brings
+it back with its history. Whether a harness resumes a conversation that was
+started in another folder is something to try before promising.
+
+Everything else is best effort, and say so plainly rather than promising a
+clean move: what was in that session's own settings, the rules it worked to,
+the skills it had. Carry across what you can find, list what you could not,
+and let them tell you what mattered.
+
+## Write it down
+
+The kit's command line does the writing, and the files belong to the user:
+`obk bot create` makes the bot, `obk session add` gives it a session, `obk
+source add` records where online skills come from and `obk skills fetch`
+clones them, `obk skills add` puts one on a bot, `obk skills build` links
+them, and `obk up` opens what is missing in Orca. `obk bot change` gives a
+bot a new charter, `obk session change` changes a session's settings, and
+`obk skills remove` takes a skill off a list (then `obk skills build`). `obk
+pause` stops a bot or a session for now and `obk unpause` brings it back;
+`obk retire` ends one. For a special case no command covers, such as a bot's
+rules list, edit the file, run `obk rules build` or `obk skills build`, and
+say that you edited it by hand.
+Run `obk --help` for the flags of the version actually installed rather than
+trusting a line you remember.
+
+A bot that should learn across its sessions can use its harness's own memory,
+turned on for that bot alone, whatever the user's own setting is for everything
+else. The harness writes it, loads it and keeps it tidy itself. On Claude Code
+that is three keys in the bot's `.claude/settings.json`, beside the kit's hook:
+`autoMemoryEnabled: true`; `env` setting `CLAUDE_CODE_DISABLE_AUTO_MEMORY` to
+`"0"` where the user turns memory off that way; and `autoMemoryDirectory`
+naming a folder of the bot's own outside the bots repo, by an absolute path or
+one starting with `~/`, because without it
+every bot in the repo shares one memory. The first 200 lines or 25 KB of its
+index load at every start. Codex's memories belong to the user and are shared
+by every Codex session, so a Codex bot cannot have its own; say so before
+turning them on for one. It is a hand edit, and say that you made it.
+
+After each change, commit what it changed in the bots folder; the kit never
+commits by itself.
+
+Do the reversible part and stop at the line. Making a bot, adding a session
+and linking skills add things and are safe to run again; closing a tab,
+pausing or retiring a bot and restarting anything are not, and they wait for
+the word.
+
+## When the bot is already running
+
+Changing a bot whose sessions are up is the ordinary case rather than the
+awkward one. Both harnesses read a skill through the link and notice a change
+to the skills directory while a session is running, so putting a skill on a
+bot, or taking one off, reaches a live session without restarting it.
+
+Noticing is not the same as confirmed. Check that the session can actually see
+the skill before telling anyone it is there, and check by asking that session
+rather than by looking again at the disk you just wrote: what you wrote is not
+evidence about what another process has loaded. Where it has not appeared, say
+so and say what would make it appear. A restart is the user's to ask for, and
+taking one because it is the quick way ends a conversation they were in the
+middle of.
+
+Instructions are not skills. A session is working from the rules it read when
+it started, so a change to a bot's `AGENTS.md` may not reach one that is
+already up even when a skill change would, and a session's model, effort or
+approval only changes when it is started again (`obk restart`, on the user's
+word). Say which you changed, and what that means for the sessions running
+now. Where everything needs restarting, remind them to do it from Bot Father's
+ops tab.
+
+And tell them. A bot's sessions share its rules and its skills, so a change
+made for one of them lands on all of them, and the session that asked is not
+the only one affected. Say what changed and what it means for what they are
+doing, in their own tabs, rather than leaving them to find out mid-task.
+
+## What they get back
+
+Its card: the name, the harness, model and effort of its sessions, a two-line
+charter, and its one hard limit. Its sessions and what each is for. The skills
+it has and where they came from. And the one thing you need from them, where
+something is still open.
+
+Point at the charter rather than reproducing it, and say what you inferred
+rather than what they told you, so the parts they have not really agreed to
+are the parts they read.
+
+Sources and licences: [NOTICE.md](NOTICE.md).

package/skills/obk-debugging/LICENSES.md

@@ -0,0 +1,67 @@
+<!-- The licences of the sources this skill was consolidated from. They travel
+     with the skill directory because the licences require it of anyone who
+     distributes the material. NOTICE.md says what was taken from each source;
+     this file carries the permission notices themselves. -->
+
+# Licences of the sources
+
+`obk-debugging` consolidates material from the sources named in
+[NOTICE.md](NOTICE.md). Their licences are reproduced below in full.
+
+## MIT
+
+The MIT permission notice below applies to the work of each of these copyright
+holders, and is reproduced with each of their notices. The path after each one
+is the licence file it was read from, in the research pack's source clones.
+
+- **`mattpocock/skills`**, Copyright (c) 2026 Matt Pocock
+  (`mattpocock_skills/LICENSE`)
+- **Cursor `plugins`, the pstack plugin**, Copyright (c) 2026 Lauren Tan
+  (`cursor_plugins/pstack/LICENSE`)
+- **`obra/superpowers`**, Copyright (c) 2025 Jesse Vincent
+  (`obra_superpowers/LICENSE`)
+- **`addyosmani/agent-skills`**, Copyright (c) 2025 Addy Osmani
+  (`addyosmani_agent-skills/LICENSE`)
+- **`garrytan/gstack`**, Copyright (c) 2026 Garry Tan
+  (`garrytan_gstack/LICENSE`)
+- **`KentBeck/BPlusTree3`, for his own rules file**, Copyright (c) 2025 Kent Beck
+  (`KentBeck_BPlusTree3/LICENSE`)
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+Copyright (c) 2026 Lauren Tan
+Copyright (c) 2025 Jesse Vincent
+Copyright (c) 2025 Addy Osmani
+Copyright (c) 2026 Garry Tan
+Copyright (c) 2025 Kent Beck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## Sources that could not be read
+
+- **`tw93/Waza`** is not among the clones in the research pack. Its `hunt`
+  skill is quoted in the pack's `source-book-2.md`, which records the
+  repository as MIT. What this skill takes from it is written in our own words.
+
+These are named in NOTICE.md for honesty about where the material came from.
+No text of theirs is reproduced in this skill, and their licence files were not
+available here to reproduce.

package/skills/obk-debugging/NOTICE.md

@@ -0,0 +1,115 @@
+<!-- Attribution for the sources this skill was built from. Kept out of
+     SKILL.md so it is not read into context on every use; it travels with
+     the skill directory, which is what the licences require. -->
+
+# Sources and licences
+
+The skill `obk-debugging` was consolidated for this kit from these, all MIT,
+with thanks:
+
+- **mattpocock/skills**, `engineering/diagnosing-bugs`. The whole shape of it.
+  The feedback loop as the skill itself and worth disproportionate effort, the
+  ten ways to build one in order, tightening it for speed, sharpness and
+  repeatability, raising the rate on an intermittent bug rather than chasing a
+  clean one, the four things that make a loop finished, the refusal to
+  hypothesise before the command exists, reproducing the reported symptom
+  rather than a nearby one, cutting until every part is load-bearing, three to
+  five ranked falsifiable candidates with the prediction each makes, showing
+  the ranked list to whoever is there, one variable per probe, a debugger over
+  logs and never logging everything, tagging temporary logs with one marker,
+  measuring before fixing a slow thing, the regression test at a correct seam
+  and "no correct seam is itself the finding", redacting secrets from anything
+  shown, and the list to clear before calling it done.
+- **Waza**, `hunt`, through the verbatim passages in the research pack. The
+  gate sentence and its form ("I believe the root cause is X because Y", named
+  to a file, function, line or condition), the rule that the cause must explain
+  every symptom including the one waved away, running the one probe that would
+  fail if you were wrong and discarding on contradiction rather than stacking a
+  fix on it, every log as a yes-or-no question and a log that changes behaviour
+  being evidence in itself, the rationalisation tells, the sibling sweep with
+  every match answered in writing, bisecting only with a pass/fail command
+  decided up front and a clean tree first, reading the diff when the last good
+  version is close, the same symptom after a fix meaning stop patching and
+  re-read the path, and stopping after three failed hypotheses. The owner
+  marked the gate sentence as worth borrowing in his own notes; the rest of
+  `hunt` came in on the research's recommendation.
+- **Cursor pstack**, `principle-fix-root-causes` and the `poteto-mode`
+  playbooks. Not adding guards to silence a crash, a workaround needing a
+  paragraph meaning the code is wrong, checking for the pattern rather than the
+  instance, suspecting stored state first when something fails after a restart,
+  and from `principle-attack-the-premise`, two fixes sharing one premise
+  meaning the premise is what to suspect and test next, written down before
+  another fix is tried, while it may still not be the cause. From the
+  `hillclimb` playbook: several runs and the median, keeping a change only
+  when the number moves past the noise, and correctness outranking the
+  number. From the `perf-issue` playbook: measuring before claiming a limit, the
+  families a fix takes used as hypothesis generators rather than a checklist,
+  and capturing the measurement again afterwards to compare against the
+  baseline. Every shipped line tracing to runtime evidence with the smallest
+  change the evidence justifies and reverting what a refuted idea motivated,
+  and verifying on the same surface with "inconclusive is not a pass" and a
+  unit test showing branch behaviour rather than absence of the bug. From its
+  `runtime-forensics` and
+  `trace-forensics` playbooks: an existing capture is read rather than re-run,
+  turned into a queryable shape before reading and reduced elsewhere when it is
+  large; narrowing to the hot call path, to the retainer chain from a leaked
+  object back to a root, or to a blocked thread and its wait reason; mapping
+  the finding to file, symbol and line, with a frame that has no source behind
+  it not yet being a diagnosis; confirming against a paired capture or else
+  calling it the strongest hypothesis the artefact supports; and proving the
+  mechanism on the live process where it can still be reached.
+- **obra/superpowers**, `systematic-debugging` with `root-cause-tracing` and
+  `condition-based-waiting`. Logging what enters and leaves each boundary and
+  reading where it first goes wrong before digging in, tracing backwards
+  through the call chain to where the wrong value was born and fixing it there,
+  logging before the dangerous operation rather than after it fails, printing
+  to the error stream in tests because a logger may be swallowed, three failed
+  fixes meaning the architecture rather than the hypothesis is wrong and what
+  that looks like, waiting for the condition rather than for a duration,
+  reading fresh state inside the loop, always setting a limit with a message,
+  the case where a fixed wait is right and what has to accompany it, and the
+  things someone says when they can see you are guessing. Also, when the
+  cause really is external, handling at the boundary and a way to see it next
+  time, with most "no root cause" being an investigation stopped early; and
+  finding the test that leaves state behind by running them one at a time.
+
+- **obra/superpowers**, `systematic-debugging`, further to the above. Finding
+  the nearest thing that works in the same codebase, reading it properly rather
+  than skimming, and listing every difference however small without deciding in
+  advance which cannot matter.
+- **addyosmani/agent-skills**, `debugging-and-error-recovery`. The decision
+  tree for a bug you cannot reproduce on demand, sorted into timing,
+  environment, state left behind and genuinely random, with what to try in each
+  and documenting the conditions as a real answer for the last; and treating
+  error output as untrusted data, since a message from a dependency, a log or a
+  build can carry something shaped like an instruction and is to be read for
+  clues rather than followed; keeping the evidence before a restart or a
+  clean-up; and a test that looks wrong going back rather than being obeyed.
+- **Waza**, `hunt`, further to the above. Its gotchas: walking back out of a
+  library frame into your own code, suspecting persisted output written by the
+  old code when the algorithm changed and the output did not, trusting the
+  observation over the log and treating the gap as an un-instrumented path, a
+  guard that refuses having a set of causes rather than one, taking a
+  lower-layer baseline before blaming the visible thing, diagnosing an external
+  tool before switching it, and never restarting more than twice without new
+  evidence.
+
+- **garrytan/gstack**, `investigate`: earlier fixes in the same area pointing
+  at the shape of the code, and the rest of the suite still passing after the
+  fix.
+- **Kent Beck's own rules file**: two tests for a defect, one at the interface
+  and the smallest one where the fault lives.
+- **Cursor pstack**, `runtime-forensics`, further to the above: when the
+  question is why, the deliverable is the diagnosis, not a fix.
+
+The owner's own framing leads the skill: reproduce it, find the difference in
+environment, version and context, and the hard cases being random and slow
+(research-pack dialogue, 2026-09-19 18:45). The plain opening and the dropped
+slogans follow his remark that the source's voice was too strong and too
+personal (18:41 and 18:46).
+
+Left behind on purpose: the iron-law capitals and "refuse to give up" framing,
+validating at every layer as a general answer (it contradicts fixing the cause,
+and the kit's own rules say the smallest change that works), per-vendor tooling
+names and control-skill machinery, fixed model choices, and the parts that
+assume a particular tracker or pull-request flow.