opsinist
An operations department for AI coding agents, in files — roles, work, cost, evidence and escalation out of one git repository.
Open source Open in the app JSON README (API)
About
An operations department for AI coding agents, in files — roles, work, cost, evidence and escalation out of one git repository.
Details
- Kind
- Plugins
- Topic
- Version control
- Publisher
- jamillazarev
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.2.16
- Stars
- 1
- Last push
- 2026-09-06T22:53:39Z
- Repository state
- ativo
- Language
- Shell
- License
- Apache-2.0
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-09-07 14:38:11
- Origin id
jamillazarev/opsinist
README
<p align="center"> <img src="assets/opsinist-docs.png" alt="Opsinist" width="240"> </p> <h1 align="center">opsinist</h1> <p align="center"> Run a company of AI agents out of <b>one git repository</b> — any craft, not just code.<br> The team, the process, the history, the cost — all files: <b>clone it and everything travels.</b><br> Gates that say what enforces them, doors that refuse instead of hoping, evidence on every claim. </p> <p align="center"> <a href="https://ai.jamillazarev.com/skills/opsinist"><img alt="docs" src="https://img.shields.io/badge/docs-ai.jamillazarev.com-black"></a> <a href="https://github.com/jamillazarev/opsinist/releases/latest"><img alt="release" src="https://img.shields.io/github/v/release/jamillazarev/opsinist?label=release&color=black"></a> <a href="LICENSE"><img alt="license" src="https://img.shields.io/github/license/jamillazarev/opsinist?label=license&color=black"></a> <a href="https://github.com/jamillazarev/opsinist/actions/workflows/preflight.yml"><img alt="preflight" src="https://github.com/jamillazarev/opsinist/actions/workflows/preflight.yml/badge.svg?branch=main"></a> <a href="https://ai.jamillazarev.com/skills/opsinist/coverage"><img alt="coverage map" src="https://img.shields.io/badge/coverage-map-black"></a> </p> --- Most tools for running agent teams ask you to trust a dashboard. **This one is an operations department in markdown** — a budgeted core and forty-three trigger-loaded chapters you can read, diff and delete, including the parts it admits it cannot enforce. Not a task list with AI bolted on: the machinery a company runs on, as files, in a repository you already own. --- ## One minute in ```sh claude plugin marketplace add jamillazarev/opsinist claude plugin install opsinist@opsinist ``` Then say what you need — no command required, any language. It reads what you have and takes the right entrance: | What you have | Where it goes | |---|---| | nothing yet | the interview, then your first task | | a repository already | an audit, then a debt list you approve | | a backlog somewhere else | a mapping shown before anything is written | | one job, no team | three questions and none of the machinery | | a question | an answer, and nothing is created | **Two questions are never skipped** — how much you want to be in the loop, and who may direct this. Everything else has a default good enough to leave alone. --- ## Different, by design - **Clone the repo and the whole project comes with it.** No platform, no database, no account — `project = f(repo)`; delete every cache and it rebuilds. - **Gates tell you what actually enforces them** — request, validator, git-host, runtime, or **`prose-only`, which means nothing does**, listed by name. A gate believed in but not enforced is worse than a stated rule. - **A stage changes through a door that refuses with the reason** — and the ladder you see is drawn from the same block the door reads, so picture and enforcement cannot drift. - **How deeply work is described is one cut on one ladder, owned by the kind of work** — a bug wants its reproduction, a newsletter its model issue, a chore the floor. - **"Remember this" lands in files, never in the chat's memory** — routed to a guide line, a decision, a register, and the home is named back to you. - **A release names how it goes out** — soft, canary, staged, flag-gated, shadow — under three unbending rules: guardrails own the halt · the kill switch is named before the first user · expansion surfaces, never advances itself. - **A gap found mid-build calls the owner, not the editor** — nobody edits the artefact another craft is standing on, in either direction. - **A run may not end leaving the machinery uncommitted** — *the reach gate*. The ending is refused, once, naming the files, in a project this system operates and a session that opened it. The checks in the guard are enforced *at the commit*, so work that stops short of one is held by prose alone; measured on the light tier, 2026-08-22: 0 commits in 10 runs, and 5 of 5 answering after. - **A new standing commitment says what it replaces** — a library, a supplier, a subscription, a licence. Does it need to exist · is it already here · does the craft's own staple do it · is it native · one line — every rung but the last is a judgement no script can make, and whether the answer was written down is not. - **Every move on the map names the job it is hired for** — *when this happens, someone wants to do this, so they can get that*. A job story opens on a situation, so it can be checked and it can be wrong; *"as a user I want"* cannot be wrong, which is why there are no user stories here. - **A market size is a checkable claim or it is not written** — TAM, SAM and SOM each carry where the figure came from and when, and a derived one carries its arithmetic. **`unknown` passes**: the gate asks that a number be traceable, not that a number exist, because a rule demanding numbers is answered with invented ones. - **Every claim carries how it is known** — measured, cited, recalled, judgement — and nobody promotes another's guess by quoting it. A hundred synthetic respondents are one bias repeated a hundred times, and you are told before anything runs. - **A run that dies resumes** — committed · applied · remains, read from the repository; **applied work is never redone**. - **Nothing moves by itself and nobody waits** — everything surfaces as ready; long work leaves the turn and comes back with the answer; helpers run at the tier their own work needs, each named in the record. - **Autonomy is earned per role and can go down** — and no history buys the four gated kinds — spending, leaving the repo, destroying, reshaping the team. - **It knows when the repository isn't yours** — a guest leaves not one of our files behind, and your record still lives with you, complete. - **It works outside software** — *ship* is an episode published, a batch sent, an issue mailed; a chip maker has no data flows and a bakery has no deploys. - **It maintains itself through its own machinery** — proposed, never self-merged; validators run in CI on every push and refuse what prose cannot. The full inventory — every entity, register and rule, grouped and argued — lives in **[the docs](https://ai.jamillazarev.com/skills/opsinist/)**: start at [the skill](https://ai.jamillazarev.com/skills/opsinist/the-skill), skim [93+ situations](https://ai.jamillazarev.com/skills/opsinist/use-cases) or [the facts](https://ai.jamillazarev.com/skills/opsinist/facts) — one true sentence each. --- ## The commands You never need one — anything a command does, a sentence reaches. The palette is the front door plus twenty verbs, each a door to a flow that exists anyway: | | What it is for | |---|---| | `/opsinist:advisor` | **the front door** — the corpus: the laws, the routing, what to load when | | `/opsinist:init` | start or continue a project — what is here is **read, not asked** | | `/opsinist:join` | take over an existing repo: audit first, one classified debt list, nothing fixed unseen | | `/opsinist:import` | bring a backlog in — mapping shown first, imported text treated as untrusted | | `/opsinist:consult` | a question, not a build — **nothing is put into your project** | | `/opsinist:hire` · `/opsinist:fire` | grow the roster from a need · park a role, archived, never deleted | | `/opsinist:status` · `/opsinist:cost` | what runs, waits, and aged past its promise · what work cost, leaks named | | `/opsinist:ship` | a release: the batch, the guards, the rollout it declares | | `/opsinist:review` · `/opsinist:decompose` | call another craft to look · cut a feature into workable tasks | | `/opsinist:map` · `/opsinist:decide` | the product as moves and things · one decision loop, recorded | | `/opsinist:automate` · `/opsinist:skill` | a real trigger or an honest manual one · create, screen, compress, extract | | `/opsinist:upgrade` · `/opsinist:migrate` · `/opsinist:recover` | move the machinery · move the project · resume the dead run | | `/opsinist:report` | something went wrong — packaged from evidence, yours or the skill's own | | `/opsinist:audience` | ask the audience — personas with the signal pyramid kept honest | --- ## Install everywhere else The packaging is the open [Agent Skills](https://agentskills.my/specification/) standard — some thirty tools read it. As a bare skill: ```sh npx skills add jamillazarev/opsinist ``` Antigravity, Codex / ChatGPT, Kimi, Gemini CLI, Cursor, OpenCode, Copilot CLI, Factory Droid and Pi each have their route → **[INSTALL.md](INSTALL.md)**. Installing is solved; **what each runtime lets an agent do differs**, and the row that matters most is delegation: | | Installs | Delegation | Enforced tool allowlist | Worktrees | How we know | |---|---|---|---|---|---| | **Claude Code** | yes | yes | yes | yes | **measured** — the behavioural suite runs here | | **Gemini CLI** | yes | not confirmed | a policy engine exists | yes | surface **measured**; behaviour not yet run | | **Codex CLI** | yes | reported | not checked | not checked | **cited** from its docs, not from a run | | the rest | expect yes | ask | ask | ask | **unknown** | *Measured* ran here; *cited* is the vendor's claim; *unknown* means nobody looked — a capability written down because it would be convenient is the failure this project is built against → [runtimes.md](runtimes.md). Moving a project between runtimes takes no migration: nothing load-bearing lives in a session. **Updating** — one route per install, and **check the version, not the command's reply**: | Installed as | Update it with | |---|---| | **Claude Code plugin** | `claude plugin marketplace update opsinist` **then** `claude plugin update opsinist@opsinist` — the first line is the one people skip | | **Codex plugin** | `codex plugin marketplace upgrade` then `codex plugin add opsinist@opsinist` | | **Gemini CLI extension** | `gemini extensions uninstall opsinist` then `gemini extensions install https://github.com/jamillazarev/opsinist` — **not `extensions update`** | | **a copied skills directory** | re-run the installer or re-copy — **nothing announces a drifted copy** | ```sh bash scripts/find-installs.sh ``` names every install on the machine with its version and route, and exits non-zero on a dangling symlink or a stale copy. --- ## What is inside | | | |---|---| | **[SKILL.md](skills/advisor/SKILL.md)** | the core: the laws, the front door, and what to load when | | **[GLOSSARY.md](GLOSSARY.md)** | one word, one meaning — and the pairs that look alike and are not | | **[PATTERNS.md](PATTERNS.md)** | the twenty-seven shapes this system reuses, named once | | **[lenses.md](lenses.md)** | four readings before anything of consequence ships | | **forty-three chapters** — the methodology, one trigger each | loaded when their subject comes up, never all at once. **Not templates** — those are their own set in `templates/`, copied into a project when an entity is born | | **[storing.md](storing.md)** | which of the six layers land in the repository, and which stay with you | | **[runtimes.md](runtimes.md)** | which gates are real in the runtime you are actually in | | **[evals/](evals/)** | scenarios scored by pass-rate, including nine that press on the rules | | **[sources/](sources/)** | the evidence behind every slow-rotting claim, with archive links and dates | The core is a router with a declared budget. **A line added to it is paid by every run of every agent, forever** — which is why procedures, examples and reference tables live in chapters. --- ## How you would know it is working **Success here shows up as an absence.** Nothing was decided twice. Nothing was rebuilt that was already built. No bill arrived that nobody saw coming. Nobody asked *"who chose this, and why?"* and got silence. These are the tests we would rather be judged on — written down now so they cannot be quietly swapped later for whatever looks good: **Can a stranger continue?** Hand the repository to someone who was not there, with a task. If they can pick it up without asking what was meant, `project = f(repo)` is true. If they have to ask, it was a slogan. **Did the dead run resume** without redoing work that was already applied? That claim is on the box; this is the number that keeps it honest. **Is the waste share falling?** *Spent on work that produced nothing* is a visible number, not a feeling. Over time, on one project, it should go down. **How often do you go behind it?** Re-reading diffs you were told were done, recounting costs, re-checking the board — each is a failure even when every gate is green, because **a console you audit is not a console.** And one number we deliberately do **not** treat as success: the eval pass-rate. It is a regression detector, not evidence anything was ever good — this project has already watched a run score thirteen passes while quietly breaking one of its own laws. --- Apache-2.0. The name **opsinist** and its mascot are reserved — see [TRADEMARKS.md](TRADEMARKS.md).