Metadata-Version: 2.5
Name: grok-bot-os
Version: 1.0.0
Summary: Operating system for Grok Bot teams: slow-burn Health A queue. Not the testing-os dogfood-swarm CLI.
Project-URL: Homepage, https://mcp-tool-shop-org.github.io/grok-bot-os/
Project-URL: Repository, https://github.com/mcp-tool-shop-org/grok-bot-os
Author: mcp-tool-shop
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/grok-bot-os/readme.png" width="280" alt="grok-bot-os">
</p>

<p align="center">
  <a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
</p>

# grok-bot-os

<p align="center">
  <a href="https://github.com/mcp-tool-shop-org/grok-bot-os/actions"><img src="https://github.com/mcp-tool-shop-org/grok-bot-os/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://www.npmjs.com/package/@mcptoolshop/grok-bot-os"><img src="https://img.shields.io/npm/v/@mcptoolshop/grok-bot-os.svg" alt="npm"></a>
  <a href="https://pypi.org/project/grok-bot-os/"><img src="https://img.shields.io/pypi/v/grok-bot-os.svg" alt="PyPI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
  <a href="https://mcp-tool-shop-org.github.io/grok-bot-os/"><img src="https://img.shields.io/badge/landing-page-0ea5e9.svg" alt="Landing page"></a>
</p>

Versioned operating system for **Grok Bot** teams. Orchestrator, Builder,
Reviewer, and Researcher sit in a Grok Bot group chat. **Coordinator** is
Grok Build on the operator's machine — not a Grok Bot. Work moves through a
live `QUEUE.md` on the Bot VM. Default cadence: one coding job at a time,
many in review, Coordinator merges when the human is back. Health A is the
**default lane**, not the ceiling — Coordinator can open Health B–D and
named features on this same queue.

**Status:** v1.0.0 on PyPI (`grok-bot-os`), npm (`@mcptoolshop/grok-bot-os`), and GitHub Releases.

## What this is not

- Not the `testing-os` dogfood-swarm CLI (`swarm init` / 10-phase).
- Not `swarm-control-plane` (SQLite waves, domain freeze, receipts).
- Not Role OS. Role OS orchestrates Codex. This OS orchestrates Grok Bots
  on the cloud VM via QUEUE.

Stay on **this queue** for one-locus work (Health A default; later classes
when Coordinator names them). Escalate to swarm-control-plane only when
the job is **cross-cutting** (frozen domains, wave receipts — Kim 2025 is
about seats, not a Health A ceiling). Grounding:
[`docs/RESEARCH.md`](docs/RESEARCH.md).

## Install / use

Registries (optional — the live OS is still a git clone on the Bot VM):

```
pip install grok-bot-os
npm install @mcptoolshop/grok-bot-os
```

`pip` installs `route-scratch` and `check-queue-fields`. The Bot VM still
clones this repo per `CLONE-POLICY.md` and runs `python3 scripts/route-scratch.py`.

1. Clone the OS and the consumer per `CLONE-POLICY.md`. Coordinator
   workstation: a local clone of this repo. Bot VM:
   `/workspace/studio/<repo>` only after a ticket names `owner/repo`.
   Never copy the Coordinator tree onto the VM. Never copy `.swarm`.
   Bots never copy the scratch transport clone.
2. The generic OS contract is `SLOW-BURN.md` in this git. Consumer holds
   (PR numbers, hours) live in `consumers/<name>.md`. Do **not** overwrite
   a VM `SLOW-BURN.md` that still carries consumer PR numbers until
   Orchestrator is reading **both** git files.
3. Paste **all four** Bot profiles (Name / Title / Description) from
   `bots/orchestrator.md`, `bots/builder.md`, `bots/reviewer.md`, and
   `bots/researcher.md` **before** adding anyone to the group. Then add
   those four to one Grok Bot **group chat** — still four seats, no fifth
   (Kim 2025). Coordinator is not a Bot (`bots/coordinator.md`).
4. Seed live `QUEUE.md` on the VM from `QUEUE.template.md` plus the
   consumer file (stop / prerequisite / owner / fallback in full). Live
   QUEUE and `TO-COORDINATOR.md` stay on the VM.
5. Run Orchestrator once (clock or `@Orchestrator`) so it pulls consumer
   `main` and assigns the first `ready` row. **The first coding job is an
   Orchestrator @**, never a human paste and never “add Orchestrator after
   idle.”
6. Only then may Builder code. Scratch routing: `ROUTE.md` +
   `scripts/route-scratch.py` on the VM. Poll with `gh api` only (no
   `git fetch`). Fail-closed: seed last-sha first; do not advance it on
   exit != 0. Empty stdout after exit 0 = silent. Researcher
   `SendToAgent`s Bot `DELIVER`s only.

Coordinator session-open (Grok Build TUI on the operator's machine):
`git pull` the local scratch-transport clone, then read new
`to: grok-build` envelopes. Do not paste Bot-group logs.
`TO-COORDINATOR.md` is the VM append-only log, not the transport. The
TUI has no inbound ping and no API to Grok Bot. Do not reconstruct
state from the group transcript (KC 2026).

## QUEUE contract (do not compress)

Every QUEUE row, Orchestrator `@`, and scratch ticket carries **stop /
prerequisite / owner / fallback** in full. **`see SLOW-BURN` is
forbidden** (Sun 2026). Ready Dependabot / patch rows skip Reviewer.
Hold / major / behavior still require Reviewer 🛑. Coordinator still
merges every `coordinator-merge`.

Builder does not review itself. Reviewer pass on a mergeable PR is 🛑.
Merge stays on Grok Build (Panickssery 2024; Kambhampati 2024).

Finalize emojis, last line only: ✅ Bot done, no Coordinator · 🔧 rework ·
🛑 Coordinator must act.

## Trust model

**Touches:** public git playbooks; `gh api` against
`mcp-tool-shop/rig-bridge-scratch` from an already-authenticated `gh`
on the VM; markdown QUEUE on the VM.

**Does not touch:** npm registry, consumer `main`, Coordinator swarm
sqlite (`.swarm`, `~\.grok\*.sqlite`), PATs, `auth.json`,
`mcp_credentials.json`, telemetry, GitHub MCP token fields.

**Permissions:** read this repo; `gh api` as `mcp-tool-shop` for scratch
routing. Bots never merge. Coordinator merges every `coordinator-merge`
(`--admin` if Actions dark). Reviewer 🛑 is required for hold / major /
behavior. Ready patch / Dependabot PRs skip Reviewer. Auto-merge is an
optional later consumer-side alternative, not this repo's CI. No
Dependabot merge of hold PRs.

No telemetry. No secrets in source or in tool-call examples.

## Layout

| Path | What |
|------|------|
| `SLOW-BURN.md` | Generic OS: seats, QUEUE class, pipeline, emojis |
| `ROUTE.md` | Scratch `to:` ids + poll + Orchestrator outbox |
| `CLONE-POLICY.md` | What the VM may clone; Coordinator `git pull` of `the local scratch-transport clone` |
| `QUEUE.template.md` | Columns including class + four constraint fields |
| `TO-COORDINATOR.template.md` | VM append-only log format (not the transport) |
| `bots/*.md` | Paste-ready profiles. `coordinator.md` is not a Bot |
| `scripts/route-scratch.py` | `gh api` compare → DELIVER lines |
| `consumers/` | Per-repo catalog, holds, hours |
| `docs/RESEARCH.md` | Study-swarm citations + implications |
| `site/` | Landing + Starlight handbook |

## License

MIT.

---

Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>
