Measured, not claimed

A live bench runs the same model on the same trap tasks with no pack, with Superpowers and with SeniorOS. Hidden tests and the repository state grade every run; no model judges another.

| Host and model | No pack | Superpowers | SeniorOS | |---|---|---|---| | Claude Code, Claude Sonnet (8 core tasks, 3 trials each) | 17/24 | 19/24 | 24/24 | | Claude Code, Claude Haiku (19 tasks, 3 trials each) | 52/57 | 53/57 | 57/57 | | Antigravity, Gemini Flash (4 hard tasks, 3 trials each) | not run | 8/12 | 12/12 | | Antigravity, Gemini Flash (multi-regression refactor, 4 trials) | 0/4 | 0/4 | 4/4 |

On a strong model SeniorOS does not win by finding more bugs, it wins on discipline: Claude Sonnet alone fixed a bug three times without a test that proves the fix, and three times discarded a colleague's work in progress and force-pushed main; with SeniorOS it wrote the test and stopped to ask every time. Across both models SeniorOS made no false "tests pass" claim. Every run, task and caveat (including which tasks were written alongside the changes they reward) is in evals/bench/, and you can rerun it with one command.

Why SeniorOS exists

Coding agents can already generate a lot of code. The expensive failures usually happen around the code:

• reading half the repository for a one-line change;
• reading too little before touching auth, data, or infrastructure;
• changing unrelated files because they looked “helpful”;
• declaring success without running the project's real checks;
• weakening tests instead of understanding the regression;
• forgetting architectural decisions between sessions;
• treating a button rename and a production migration with the same ritual.

SeniorOS treats these as engineering-system problems, not prompt-writing problems.

The goal is not to make the model sound senior. The goal is to make the workflow behave like disciplined engineering.

How it works

SeniorOS pushes agent work toward a risk-adaptive loop:

Goal Contract
    ↓
Relevant Context
    ↓
Risk Assessment
    ↓
Right-Sized Execution
    ↓
Proof
    ↓
Review
    ↓
Ship / Not Proven / Blocked

The important part is that not every task gets the same process.

| Task | SeniorOS behavior | |---|---| | Rename a button | Direct edit + proportionate verification | | Add an API route | Light plan + relevant tests | | Change authentication | Full context + security/risk review + proof | | Production migration | Strict plan + rollback thinking + explicit boundaries | | “Just make CI green” | Investigate root cause before weakening meaningful checks |

The difference in one line

normal agent loop:   request → generate → edit → "done"
SeniorOS loop:       request → understand → assess → execute → prove → review → state what is known

SeniorOS prefers:

PROOF BASELINE: PASS
Residual risk: LOW
Skipped checks: none

instead of:

Everything looks good! 🚀

because optimism remains stubbornly absent from every serious test framework.

Quick start

Requires Node.js 20 or newer. No clone needed: the CLI is published on npm as senioros, and its command is senior.

1. Install SeniorOS for your coding agent

Claude Code (recommended: the plugin adds the routing rules and the destructive-command guard):

/plugin marketplace add joshsegatt/SeniorOS
/plugin install senioros@senioros

Cursor: a plugin with the routing rules, the destructive-command guard and the finish gate. Until it is listed in the Cursor marketplace, add a clone of this repository as a local plugin (adapters/cursor).

Google Antigravity (skills, routing rules and hooks in ~/.gemini, backed up and reversible):

npx senioros install --target antigravity

Or as a native Antigravity plugin, with the skills and routing rules only (no guard or finish gate):

agy plugin install https://github.com/joshsegatt/SeniorOS

Use one or the other, not both, or the skills are listed twice.

Codex: a plugin with the routing rules, the destructive-command guard and the finish gate. After installing, open /hooks in Codex and trust the three SeniorOS hooks (adapters/codex):

codex plugin marketplace add joshsegatt/SeniorOS
codex plugin add senioros@senioros

OpenCode (1.x): a plugin with the skills, the routing rules, the destructive-command guard and the finish gate. Add it to opencode.json and restart OpenCode (adapters/opencode):

{ "plugin": ["senioros"] }

Skills only, for any agent, run inside your project:

npx senioros install --target codex --scope project
npx senioros install --target claude --scope project    # skills only, without the plugin's rules and guard
npx senioros install --target generic --scope project   # portable Agent Skills layout

SeniorOS refuses to overwrite an existing skill unless you explicitly pass --force. In the bench, Claude never loaded the skills on its own without the plugin's session-start rules, so prefer the plugin in Claude Code.

Upgrading from 0.1: skills are now prefixed with senior- (senior-debugging, senior-finish, …). senior install lists any old, unprefixed SeniorOS skills it finds so you can delete them; it never deletes them for you.

2. Use the CLI

Run it once with npx, or install the senior command globally:

npm install -g senioros

Then, inside your project:

senior init                # create the .senior/ project state
senior inspect             # detected stack facts
senior risk --base main    # risk of the current branch
senior finish              # run the proof baseline

Every command also works without the global install, for example npx senioros risk --base main.

senior init creates a small, versionable project intelligence layer:

.senior/
├── README.md
├── project.json
├── decisions.md
└── work-ledger.jsonl

3. Develop SeniorOS itself

git clone https://github.com/joshsegatt/SeniorOS.git
cd SeniorOS
npm install
npm run check
npm link    # puts your local build on PATH as `senior`

Choose your path

For vibe coders

You stay focused on what you want built.

Add Google login.

SeniorOS encourages the agent to handle the engineering beneath that request:

inspect existing auth
→ identify affected routes/models
→ assess risk
→ implement minimally
→ run real checks
→ review regressions
→ report evidence

What you gain

• less random code churn;
• fewer “fixed one thing, broke three things” sessions;
• clearer end-of-task status;
• persistent project context;
• stricter handling of risky changes without micromanaging every safe edit.

For senior developers

SeniorOS gives the agent explicit engineering primitives instead of a persona prompt:

• Context as a budget — load what the decision needs.
• Risk-adaptive rigor — scale process with blast radius and reversibility.
• Deterministic mechanics — scripts for repeatable checks.
• Proof contracts — completion backed by observable evidence.
• Durable decisions — architecture survives individual sessions.
• Eval-driven evolution — changes should improve measured behavior.

You keep architectural control. The harness reduces repeated supervision and makes agent behavior more inspectable.

The CLI

senior init
senior inspect
senior risk
senior risk --base main
senior finish
senior finish --json
senior prove --regression --test "npm test -- cart"
senior doctor
senior install --target claude --scope project
senior install --target codex --scope project
senior install --target generic --scope project
senior install --target antigravity
senior uninstall --target antigravity

| Command | What it does | |---|---| | senior init | Creates project-level SeniorOS state and baseline intelligence files | | senior inspect | Produces concise repository context for the agent | | senior risk | Classifies a deterministic baseline risk from uncommitted changes | | senior risk --base <ref> | Classifies a branch or PR: everything since the merge-base with <ref>, plus uncommitted work | | senior finish | Runs available verification and reports the proof baseline | | senior finish --json | Same, with a machine-readable report on stdout (script output goes to stderr) | | senior prove --regression --test "<cmd>" | Proves a regression test catches the bug: passes with the fix, fails with it reverted, passes again restored | | senior prove --restore | Puts the working tree back after a proof that was killed mid-run | | senior doctor | Diagnoses SeniorOS installation/configuration problems | | senior install | Installs the skill pack into a supported host layout |

Current proof order

typecheck → lint → test → build

Every check is reported as PASS, FAIL, or SKIP. A missing test command is SKIP, not “tests passed” after a brief spiritual consultation.

The proof stops at the first failure; later checks are reported as SKIP with the reason not run: "<check>" failed.

senior risk fails with an actionable error outside a git repository or with an unknown --base ref, instead of reporting a misleading LOW.

Regression proof

"I added a regression test" is easy to say and often untrue: the test passes with or without the fix. senior prove --regression checks it:

$ senior prove --regression --test "node tests/cart.test.js" --expect-failure "expected 10"
Regression proof: PROVEN
  The test passes with the fix, fails without it, and passes again after restoring it.
  Fix files, reverted for run 2: src/cart.js
  Test files, kept in place:     tests/cart.test.js
  1. with the fix      PASS    exit 0  0.1s  as expected
  2. without the fix   FAIL    exit 1  0.0s  as expected
  3. fix restored      PASS    exit 0  0.0s  as expected
  Working tree restored and verified (1 file, sha256 match).
  Evidence: .senior/runtime/evidence/…-regression.json

• The fix is every changed non-test file (or what you pass with --fix <path>); tests stay in place.
• --expect-failure <regex> requires the failure to be the original bug, not, say, a syntax error.
• --base main proves fixes that are already committed on a branch.
• Verdicts: PROVEN, or NOT PROVEN with fix-fails-test, test-misses-bug, failed-for-other-reason, unstable (flaky) or interrupted.

Your work is never at risk: every file is backed up before the fix is reverted and restored byte-for-byte, verified by sha256, even on errors or Ctrl+C. If the process is killed outright, the next proof refuses to run until senior prove --restore puts everything back. Evidence lives in .senior/runtime/, which ignores itself in git.

Project configuration

Optional .senior/config.json adapts the proof and the risk rules to your project, in any language:

{
  "schemaVersion": 1,
  "proof": {
    "checks": [
      { "name": "lint", "command": "ruff check ." },
      { "name": "test", "command": "pytest -q" }
    ]
  },
  "risk": {
    "ignore": ["docs/**", "**/*.snap"],
    "rules": [
      { "code": "billing", "points": 4, "reason": "Billing logic changed.", "pattern": "^src/billing/" }
    ]
  }
}

• proof.checks replaces the package-script baseline and runs in order; the proof stops at the first failure.
• risk.rules adds project rules (regular expressions over repository-relative paths) to the built-in ones.
• risk.ignore stops matching paths from counting toward risk. It never hides the built-in secrets rule.

The file is validated strictly: an unknown key, a duplicate check name or an invalid pattern makes senior risk and senior finish fail with the exact location, so a typo cannot silently turn a gate off. senior doctor shows whether the config is valid.

Core skills

The foundation ships with six focused Agent Skills.

Skill quality contract

A SeniorOS skill should:

• solve one recognizable engineering goal;
• route precisely;
• keep root SKILL.md concise;
• use progressive disclosure for deeper references;
• move deterministic mechanics into scripts;
• define verification and exit conditions;
• stay out of the way when heavyweight process is unnecessary;
• include eval coverage for trigger, non-trigger, and failure/edge behavior.

npm run validate:skills
npm run validate:evals

Proof Engine

The Proof Engine exists because “the model believes it worked” is not a production signal.

available project checks
          ↓
typecheck / lint / tests / build
          ↓
 PASS / FAIL / SKIP per check
          ↓
      proof baseline
          ↓
agent/human evaluates task-specific acceptance criteria

SeniorOS deliberately separates repository checks from task truth.

A green build is evidence. It does not automatically prove that a business flow, browser interaction, external integration, or data migration is correct unless that behavior was actually verified.

Future proof layers are planned around runtime assertions, browser evidence, security checks, regression baselines, task-specific acceptance contracts, and trace evidence.

Project Memory

senior init creates explicit project memory instead of hoping conversation history behaves like an architecture database.

Example:

## 2026-10-25 — Database ORM

Decision: Keep Drizzle.
Reason: Existing repository uses Drizzle consistently.
Do not: Introduce Prisma for unrelated features.

Important context becomes:

• versionable;
• inspectable;
• reviewable;
• portable across sessions and agents.

Runtime-only state belongs under .senior/runtime/ and stays out of Git.

Evals

SeniorOS treats evals as product engineering, not post-launch decoration.

SeniorOS has 34 eval cases covering the core skills, and a live bench of 17 trap tasks that runs real agents (Claude Code, Google Antigravity) with and without skill packs; see Measured, not claimed.

Each case captures intent such as:

{
  "prompt": "task shown to the agent",
  "expected": {
    "shouldTrigger": true,
    "requiredBehaviors": ["observable behavior"],
    "forbiddenBehaviors": ["unwanted behavior"]
  }
}

Evaluation is designed in layers:

1. Structural — manifests, fixtures, repository invariants.
2. Trajectory — routing, files read, tools called, approvals, verification.
3. Outcome — builds, tests, runtime behavior, forbidden side effects.
4. Rubric — model grading only where human-like judgment is genuinely necessary.

See evals/README.md.

Architecture

SeniorOS
│
├── Runtime CLI
│   ├── project intelligence
│   ├── risk engine
│   ├── proof engine
│   ├── work ledger
│   └── host installer
│
├── Agent Skills
│   ├── senior engineering router
│   ├── project intelligence
│   ├── debugging
│   ├── review
│   ├── finish
│   └── authoring
│
├── Evals
│
├── Host adapters
│   ├── Claude Code
│   ├── Codex
│   └── generic Agent Skills
│
└── Project state
    └── .senior/

The long-term system direction expands toward:

Goal Engine
Context Router
Risk Engine
Skill Router
Execution Engine
Proof Engine
Review Engine
Outer Loop
Work Ledger
Project Memory
Eval Lab
Observability
Host Adapters

Read ARCHITECTURE.md for system boundaries.

Host support

Claude Code

/plugin marketplace add joshsegatt/SeniorOS
/plugin install senioros@senioros

The plugin ships the skills plus two hooks: routing rules at session start and a guard that asks before destructive Bash commands. senior install --target claude --scope project installs the skills alone under .claude/skills/.

See adapters/claude-code/README.md.

Codex

codex plugin marketplace add joshsegatt/SeniorOS
codex plugin add senioros@senioros

The plugin ships the skills plus three hooks, which Codex runs once you trust them in /hooks: routing rules at session start, a guard that denies destructive Bash commands (Codex hooks cannot ask, so the user runs a confirmed one), and the finish gate. senior install --target codex --scope project installs the skills alone under .codex/skills/.

See adapters/codex/README.md.

OpenCode

{ "plugin": ["senioros"] }

The npm package's main is an OpenCode 1.x plugin: it registers the skills, adds the routing rules to the system prompt, fails destructive bash calls (OpenCode's tool hook cannot ask, so the user runs a confirmed one), and runs the finish gate when a session goes idle.

See adapters/opencode/README.md.

Google Antigravity

npx senioros install --target antigravity     # add --turbo if terminal auto-execution is on Turbo
npx senioros uninstall --target antigravity   # removes only what the installer added

Registers the skills, adds the routing rules to ~/.gemini/GEMINI.md and installs hooks for project context, a destructive-command guard and the proof gate. Files it changes are backed up once; your own rules and hooks are kept.

See adapters/antigravity/README.md. The live bench that compares SeniorOS with no pack and with other packs lives in evals/bench/.

Generic / portable

senior install --target generic --scope project

Installs into .agents/skills/, a neutral layout suitable for host adapters and portable packaging.

Design principles

1. Proof over confidence — observable evidence beats confident prose.
2. Risk-adaptive process — a typo and a production migration do not deserve the same ritual.
3. Progressive disclosure — load deeper guidance only when relevant.
4. Deterministic mechanics belong in code — repeated checks should not depend on model memory.
5. Context is a budget — read what is needed, not everything available.
6. Durable project intelligence — important decisions should survive the current chat.
7. No surprise destructive actions — production, credentials, irreversible data changes, deployment, and history rewrites require explicit boundaries.
8. Portable by default — the engineering layer should not belong to a single model vendor.
9. Evals before mythology — better should be measured whenever it can be measured.

Brand system

The official identity is intentionally restrained: engineering, not science fiction.

• Brand kit: brand/README.md
• Visual guidelines: brand/docs/visual-style.md
• Social preview source: brand/social/social-preview.svg
• Logo assets: brand/logo/

The social preview is prepared at 1280×640 for the GitHub repository settings.

What SeniorOS is not

SeniorOS is not:

• another general-purpose coding model;
• a giant “act like a senior engineer” persona prompt;
• a substitute for your test suite, security program, or code review;
• permission for agents to perform destructive production work autonomously;
• tied to one model vendor;
• finished.

That last point matters. The project is shipping as a tested foundation rather than pretending its first release solved agentic engineering forever. Software already has enough heroic README fiction.

Roadmap

Next major layers include:

• richer Goal Contracts;
• project graph and selective Context Engine;
• risk-aware Outer Loop;
• task-specific Proof Contracts;
• multi-agent Work Ledger and file ownership;
• controlled tool/MCP contracts;
• host-specific eval runners;
• trace grading and regression comparison;
• database, security, frontend, and deployment packs;
• evidence-derived trust scoring;
• observability for agent trajectories.

See ROADMAP.md.

Security

Agent Skills can influence tool use and repository changes. Treat third-party skills as executable engineering policy, not harmless Markdown.

Read SECURITY.md.

Contributing

SeniorOS should become stronger through evidence, not longer through accumulated folklore.

If a contribution adds process, it should answer:

1. What failure mode does this prevent?
2. When should it trigger?
3. When should it stay out of the way?
4. How will we know it improved behavior?

Read CONTRIBUTING.md.

Creator

License

Apache-2.0. See LICENSE.