@assuredloop/orca-bot-kit 0.1.0 → 0.3.0

package/SETUP.md

@@ -0,0 +1,275 @@
+# Setting up Orca Bot Kit
+
+You are an AI assistant with a shell, and someone has asked you to set this kit
+up on their computer. This page is what to do. Read it to the end before you run
+anything.
+
+Everything here is a default for when they have said nothing else. When they ask
+for something different, do that instead; nothing on this page stands in their
+way.
+
+Two rules hold throughout.
+
+**Install nothing but the kit.** Node, git, Orca and the harnesses are theirs to
+install, and each needs choices you cannot make for them. When one is missing,
+say which, say what it is for, and stop.
+
+**Ask only what only they can answer.** There are two such things, in step 3.
+Everything else you can find out by looking.
+
+## What you are making
+
+Orca is the host. A bot is an Orca project and a session is a tab, running
+Claude Code or Codex. You are making the first bot, **Bot Father**, and a folder
+that holds the whole fleet's configuration as a git repository of theirs.
+
+When you are done they will have an Orca project called Bot Father with two
+tabs, and from then on they manage everything by talking to it rather than by
+running commands. Leading them into that conversation is the last step, and it
+is the point of all the others.
+
+## 1. Check what is already here
+
+Run these and read the answers.
+
+```sh
+node --version                                          # 24.21.0 or newer
+git --version
+/Applications/Orca.app/Contents/Resources/bin/orca status --json
+claude --version                                        # at least one of these
+codex --version
+```
+
+The Orca line must come back with `ok: true` and `result.runtime.reachable:
+true`. Anything else means Orca is not running, whatever else it says: ask them
+to start it, then run the line again.
+
+On the Orca CLI path: `/usr/local/bin/orca` is a root-only symlink on some
+machines and fails for an ordinary user, so use the full path above. If Orca
+lives somewhere else here, find it and set `OBK_ORCA` to it.
+
+If Node is older than 24.21.0, say so and stop. The kit's book of sessions is a
+SQLite write transaction through Node's own `node:sqlite`, and 24.21.0 is the
+first release measured here that loads it without an experimental warning.
+
+If neither harness is installed, say so and stop. If only one is, that is fine,
+and it is the one Bot Father will run on.
+
+## 2. Make `obk` runnable
+
+**First ask whether it already is:**
+
+```sh
+obk --version
+```
+
+If that answers, the kit is installed. Say where it is coming from — `which obk`
+— and go on to step 3. **Do not install it again.** Someone else, or another
+project, may be running through that same installation, and replacing it would
+take their `obk` away without telling them.
+
+If it does not answer, install it from npm:
+
+```sh
+npm install -g @assuredloop/orca-bot-kit
+obk --version
+```
+
+If `obk --version` still does not answer, npm has no working release yet: it
+refused the name, or it installed an early placeholder that has no `obk` in it.
+Take the placeholder off again if there is one, and install from a clone
+instead:
+
+```sh
+npm uninstall -g @assuredloop/orca-bot-kit
+git clone https://github.com/guwenqing/orca-bot-kit
+cd orca-bot-kit
+npm install
+npm link
+obk --version
+```
+
+**This step is the one thing on this page that changes.** The rest of this page
+is about Orca and the harnesses and stays as it is.
+
+If either install fails because it cannot write where npm keeps global packages,
+give them the command to run themselves and wait. Do not reach for `sudo` on
+their behalf.
+
+## 3. Ask the two things only they can answer
+
+Ask both in one message, then wait.
+
+**Where the bots folder goes.** An absolute path. It becomes a git repository of
+theirs holding every bot's configuration: charters, rules, session settings, the
+book of sessions. It holds none of the kit's code. They may push it somewhere
+later; the kit never commits for them.
+
+**Which harness Bot Father runs on**, `claude` or `codex`. There is no default
+and the kit will not guess. It is Bot Father's own harness only; each bot they
+make later chooses its own. If only one harness is installed, say so and confirm
+it rather than asking as though the choice were open.
+
+## 4. Make the fleet
+
+```sh
+obk init --bots <their path> --harness claude|codex
+```
+
+This makes the folder a git repository, seeds it, writes Bot Father, and opens
+its two tabs in Orca: the management tab where they will talk to it, and an ops
+tab, which is a plain shell for work across the whole fleet.
+
+Read everything it prints. Two parts of it matter to them:
+
+- **what it created** — say it in a sentence, not as a file listing;
+- **anything it says about Orca's own default launch arguments.** Orca adds
+  these to every agent it launches, relaunches and resumes. When they carry a
+  permission bypass, every session runs in that mode whatever approval level the
+  kit asked for. The kit never sets that setting and will not change it. Tell
+  them plainly what it is doing and that it is theirs to change in Orca's
+  settings. Say it even if it sounds like a small thing: it decides what every
+  bot on this machine is allowed to do.
+
+`init` is safe to run again. It adds what is missing and leaves everything else,
+their own edits included.
+
+## 5. Answer what the tabs ask
+
+**How the tab got into this state**, because it decides what you do about it. A
+tab the kit has just made has no harness in it yet and nothing to wait for, so
+the kit types the launch line straight into the tab's shell and only then asks
+whether a harness came up. If that shell was busy with a question of its own, it
+swallowed the line. So two different things can be on the screen, and they need
+different answers.
+
+`obk init` tells you which, for every tab it opened:
+
+- *the harness was typed in and came up* — it is running. It may still be asking
+  something of its own; that is the table below.
+- *the harness was typed in and came up, waiting on: …* — running and blocked on
+  a question. The table below.
+- *the harness was typed in, and no session came up in the tab* — **the line did
+  not take.** There is a shell there, not a harness. Answering whatever the shell
+  is asking does not start the harness, and neither command you might reach for
+  will: `obk up` sends nothing, because the tab is already in the book, and
+  `obk restart` refuses, because the book cannot name a conversation for a
+  session that never started. The recovery is below.
+
+Use the Orca CLI at the path you found in step 1, not a bare `orca`: on a machine
+where `/usr/local/bin/orca` is the root-only symlink, a bare `orca` answers
+`Unable to determine Orca.app path from symlink` and nothing below will work.
+`OBK_ORCA` tells *the kit* which Orca to use; it does not change what your shell
+finds.
+
+```sh
+ORCA=/Applications/Orca.app/Contents/Resources/bin/orca
+```
+
+Find the tabs, and look at each one. Bot Father's own folder is `bots/bot-father`
+*inside* the bots folder from step 3, so where `<their path>` appears below it is
+that folder itself, exactly as you gave it to `obk init`:
+
+```sh
+"$ORCA" terminal list --worktree path:<their path>/bots/bot-father --json
+"$ORCA" terminal read --terminal <handle> --screen --json
+```
+
+What you will see, and the usual answer. Each goes as one
+`"$ORCA" terminal send --terminal <handle> --text …`, with the return inside the
+text and **no** `--enter`, because a menu takes a return as the keypress it is
+waiting for:
+
+| On screen | Send | Which is |
+|---|---|---|
+| Claude Code's folder trust list | `\x1b[B\r` | down, then return: its selection starts on **No, exit** |
+| Codex's directory trust, `1. Trust and continue` (older: `1. Yes, continue`) | `1\r` | yes |
+| Codex's `Hooks need review` | `2\r` | trust all and continue |
+| Codex's `/new`: `Where should the new conversation run?` | `1\r` | current checkout (bot home) |
+| Codex's update offer, `1. Update now` | `1\r` | accept it |
+| `[oh-my-zsh] Would you like to update?` | `n` | they update their own shell |
+| Claude Code's `Teach auto mode about your environment?` | `2\r` | **Not now**: it would write settings of theirs |
+
+The numbers there are what these menus showed when this was written. Read them
+off the screen in front of you rather than trusting the table: a harness that has
+added an option since has moved them all down one.
+
+Three things to know rather than guess at.
+
+Codex's hooks question is not cosmetic. The kit's hook is how the book learns
+which conversation a session is running as, and while that screen is up the
+conversation has not started at all. Answer it, or the session comes up with an
+empty book and nothing says why.
+
+Codex's trust question applies to the **repository root**, which for a bot means
+the whole bots folder rather than the one bot. That is what they are agreeing to.
+
+Codex's `/new` question (0.156.1 on) is always answered with the current
+checkout, which is the bot home. The kit never makes a git worktree, so
+`2. New worktree` is never the answer.
+
+**Anything you do not recognise: type nothing.** Tell them what is on the
+screen and which tab it is in, and wait. A keypress into a menu you have not read
+is how a harness quits back to the shell.
+
+**If the line did not take**, and you have a shell rather than a harness: answer
+whatever the shell was asking (the oh-my-zsh question above is the usual one),
+then close that one tab and bring the fleet up again. The new tab's shell has
+nothing pending, so the line lands:
+
+```sh
+"$ORCA" terminal close --terminal <handle> --tab --json
+obk up --bots <their path>
+```
+
+That is safe here and only here: the tab holds no conversation to lose, which is
+the same reason `obk restart` will not do it for you. `obk up` opens a new tab,
+types the line again and leaves the ops tab alone. Never close a tab you did not
+open, and never close one with a session running in it.
+
+When you have answered, read the screen again and confirm a harness is actually
+running in the tab. Do not go to step 7 on a tab that is still a shell.
+
+## 6. Check it
+
+```sh
+obk health --bots <their path>
+```
+
+It reads the setup and says what it found, and writes nothing at all. It exits 1
+when it found something, so do not read a non-zero exit as a broken setup. The
+one exception is an error with no findings, saying Orca is not answering: that
+is a real problem, and the fix is to start Orca and run it again.
+
+Relay what it says in plain words. Nothing it prints is a verdict: which findings
+matter is for them, or for Bot Father, to judge. If something looks wrong to you,
+say what you would do and let them decide.
+
+Then go on to step 7, whatever it found. A finding does not stop the setup: Bot
+Father is running, and it is the one to look at findings with them. One thing is
+not a finding: on Codex, the book has no conversation id for the session until
+the first message is typed into it.
+
+## 7. Hand them over to Bot Father
+
+This is the step that finishes the job, and the easiest one to do badly by
+carrying on managing the fleet yourself.
+
+Tell them:
+
+- **which tab is Bot Father's.** In Orca, the project is called Bot Father and
+  has two tabs: the management tab is the one with the harness running in it,
+  and the other is the ops shell. Identify it for them by what is on the screen
+  rather than by its title, because a harness rewrites its own tab title;
+- **that they talk to it in ordinary words.** It knows how to interview them into
+  a bot's charter, suggest the skills a role needs, and make the bots and their
+  sessions. They do not need to learn the commands;
+- **what to say first.** Give them an actual opening line, something like *"I
+  want a bot that reviews my pull requests"*, or *"what should my first three
+  bots be?"* — whichever fits what they have told you they want;
+- **what the ops tab is:** a plain shell for work across the fleet. The kit does
+  not track it.
+
+Then stop. If they ask you for more bots after this, point them at Bot Father
+rather than running `obk` for them. Every bot it makes, it knows about; the ones
+you make behind its back are ones they will have to explain to it later.

package/package.json

@@ -1,28 +1,47 @@
 {
   "name": "@assuredloop/orca-bot-kit",
-  "version": "0.1.0",
-  "description": "Orca bot kit",
+  "version": "0.3.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guwenqing/orca-bot-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/guwenqing/orca-bot-kit/issues"
+  },
+  "homepage": "https://github.com/guwenqing/orca-bot-kit#readme",
   "type": "module",
+  "description": "A kit for running a fleet of long-lived role bots on Orca: an obk CLI and the skills the bots use.",
   "bin": {
-    "okb": "bin/okb.js"
+    "obk": "src/cli.js"
   },
-  "main": "./src/index.js",
   "files": [
-    "bin",
-    "src"
+    "src/",
+    "rules/",
+    "skills/",
+    "README.md",
+    "SETUP.md"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test test/*.test.js",
+    "test:system": "node scripts/test-system.js",
+    "mutate": "node scripts/mutate.js"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=24.21.0"
+  },
+  "dependencies": {
+    "yaml": "2.9.0"
+  },
+  "devDependencies": {
+    "@stryker-mutator/core": "10.0.0"
+  },
+  "overrides": {
+    "typed-rest-client": {
+      "qs": "6.16.0"
+    }
   },
   "publishConfig": {
     "access": "public"
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/assuredloop/orca-bot-kit.git"
   }
 }

package/rules/evidence.md

@@ -0,0 +1,15 @@
+---
+name: evidence
+title: Where it comes from
+applies: all
+---
+
+Keep apart what you saw for yourself, what you worked out from it, and what you
+do not know. Say which one a claim is whenever the reader would act differently
+on the answer.
+
+Never invent a path, a name, an interface, a version or a result. Check it, or
+say you do not know. Memory is not a check.
+
+When nothing can tell you whether you are right, say so, say what you tried,
+and ask for what you need.

package/rules/finishing.md

@@ -0,0 +1,23 @@
+---
+name: finishing
+title: Verify
+applies: all
+---
+
+Turn the work into a check you can run. Run it. Read the output.
+
+Check the thing itself, not a stand-in for it: the file that changed, the
+output the reader will get, the real command against the real tool.
+
+What does not run is checked against the ask: it answers the question, can be
+followed, and its claims hold. Say what stood in, and what it could not show.
+
+Do not say it is done from a plausible diff. Say what the check actually gave,
+failures and empty results included, and what you did not check.
+
+It is not done while anything is outstanding: a test still being written or still running, a
+question still open, a check still to run. Until then it is not finished and
+does not merge.
+
+The check does not get loosened to reach done. When you are asked to run
+something again, run every step again.

package/rules/limits.md

@@ -0,0 +1,18 @@
+---
+name: limits
+title: What needs a yes
+applies: all
+---
+
+Your charter says what you own and what to ask about first. Inside it, act.
+Outside it, ask.
+
+A limit written into your charter, such as "read-only, does not modify", holds
+until the user lifts it.
+
+Work that cannot be taken back, or that reaches other people, gets a yes first,
+unless the user has already said otherwise: deleting data, rewriting history,
+publishing, releasing, spending money, anything another person receives.
+
+When something you were told to use is missing (a model, a tool, a file), say
+so and ask. Quietly using a different one hides the change.

package/rules/mail.md

@@ -0,0 +1,17 @@
+---
+name: mail
+title: Writing to another session
+applies: all
+---
+
+To reach another session, ask the kit for the road rather than guessing an
+address: `"${OBK_CLI:-obk}" message to --bots <bots> --to <bot>/<session>`. It
+answers with the address and the command that carries it. Your bots folder is
+two levels above the folder you start in.
+
+Mail is queued, not an interruption. Read it when you finish what you are on.
+
+Ask for a reply when you need one, and send one when you were asked for one.
+
+Write to the session that needs it, not to several in the hope that one of
+them is right.

package/rules/profiles.md

@@ -0,0 +1,9 @@
+---
+name: profiles
+title: What the fleet knows about each bot
+applies: all
+---
+
+Each bot has a few lines of profile in `profiles/` at the top of the bots
+folder: what it is good at, where it struggles, what it costs. Grooming keeps
+them; any bot may read them when choosing who to hand work to.

package/rules/review.md

@@ -0,0 +1,14 @@
+---
+name: review
+title: Someone else reads it
+applies: code
+---
+
+Work that changed behaviour is read by someone who did not write it: a fresh
+subagent or another session, given the requirement and the change.
+
+The reviewer comments and does not edit. Whoever wrote the code makes the
+change, and the check is run again.
+
+Receiving one: check each point against the code before you act on it. Fix it,
+or say why it does not hold and show what says so.

package/rules/scope.md

@@ -0,0 +1,22 @@
+---
+name: scope
+title: Touch only what you must
+applies: all
+---
+
+Change what the work needs and leave the rest: no tidying, renaming or
+reformatting you were not asked for. Match what is already around it.
+
+Clear up what your own change left behind. Leave what was already there.
+
+What the user wrote by hand stays as they wrote it. Change their words only
+when that is the ask.
+
+When you notice something else worth doing, say so at the end. Doing it is the
+user's call.
+
+Work inside a project of its own (a repo you cloned into your work dir, a
+folder with its own rules) follows that project's rules as well as yours, so
+read its AGENTS.md or CLAUDE.md before you start. Where the two disagree, do not
+pick one: tell whoever gave you the work, quote both, and hold that part until
+it is settled.

package/rules/simple.md

@@ -0,0 +1,14 @@
+---
+name: simple
+title: Keep it simple
+applies: all
+---
+
+Build the smallest thing that answers the ask. Nothing that was not asked for:
+no extra features, no options nobody wanted, no layer in between.
+
+Look at how this project already does the job and use that. Prefer what the
+tool, the platform or the library in front of you already gives you over
+something new of your own.
+
+Taking something out is as good an answer as putting something in.

package/rules/talk.md

@@ -0,0 +1,13 @@
+---
+name: talk
+title: How you answer
+applies: all
+---
+
+Start with the answer. Detail after it.
+
+Short sentences, everyday words, real names: the file, the command, the
+setting.
+
+No flattery, no filler, no apology for its own sake. Correct a mistake in one
+line and carry on.

package/rules/tests-first.md

@@ -0,0 +1,17 @@
+---
+name: tests-first
+title: Tests, and who writes them
+applies: code
+---
+
+A change in behaviour starts with a test that fails for the reason you expect.
+Run it, read the failure, then write the code. When a failing test really is
+impractical, say why and name the check you ran instead; naming one you will run
+later is not having run it.
+
+Wherever a real test is warranted, it is written by someone who is not you: a
+subagent or another session, working from the requirement and the public
+interface. When you can neither start one nor reach one, say so and ask.
+
+A test that stands in your way goes back to its author with what you think is
+wrong with it. It does not get weakened, skipped or deleted to reach green.

package/rules/the-ask.md

@@ -0,0 +1,19 @@
+---
+name: the-ask
+title: The ask
+applies: all
+---
+
+Read the whole message before you start. Name each thing it asks for, do all of
+them, and say which one you left and why.
+
+When a request reads two ways, take the more useful reading, say which one you
+took, and carry on. Ask first when what you are missing changes the size of the
+work, what you may touch, what it has to stay compatible with, or what counts
+as done.
+
+A fact you could look up or run is yours to find. Bring the answer, not the
+question.
+
+When the premise is wrong, say so before doing the work. "No" and "this does
+not earn its place" are answers.

package/skills/obk-arch/LICENSES.md

@@ -0,0 +1,52 @@
+<!-- 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-arch` consolidates material from the sources named in
+[NOTICE.md](NOTICE.md). Their licences are reproduced below in full.
+
+The part on decision records copies words only from Michael Nygard's
+"Documenting Architecture Decisions" (CC0 1.0) and MADR 4.0.0 (taken under
+CC0-1.0, one of its two licences). CC0 waives all rights and asks for no
+notice, so there is nothing to reproduce for them: see
+https://creativecommons.org/publicdomain/zero/1.0/. The other decision-record
+sources in NOTICE.md gave ideas only, and none of their text is used.
+
+## 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.
+
+- **Cursor `plugins`, the pstack plugin**, Copyright (c) 2026 Lauren Tan
+  (`cursor_plugins/pstack/LICENSE`)
+- **`mattpocock/skills`**, Copyright (c) 2026 Matt Pocock
+  (`mattpocock_skills/LICENSE`)
+
+```
+MIT License
+
+Copyright (c) 2026 Lauren Tan
+Copyright (c) 2026 Matt Pocock
+
+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.
+```