🆗 Overseer Kit

Portable governance for AI-assisted development: handover/roadmap discipline, VCS hygiene, freeze-contract review, and repo-agnostic tooling you inject into any project.

What it is

The Overseer Kit is the single canonical source for the overseer method — a disciplined way to run phased AI-assisted work without losing context between sessions, merging without review, or letting governance docs drift from reality.

Instead of hand-copying handover notes, tier rules, and model labels into every repository, you vendor the kit locally and keep one small config file: .overseer/config.yaml.

./cli/ok init              # first install (POSIX shim → python -m cli.main)
./cli/ok sync              # pull template/policy updates
./cli/ok status            # drift + VCS regime check
./cli/ok governance-sync   # handover/roadmap hygiene (default: dry-run)
./cli/ok review --freeze <path>

# Equivalent without the shim:
.venv/bin/python -m cli.main governance-sync --dry-run

Do not run python cli/ok — cli/ok is a shell script, not Python. The compatibility shim cli/overseer prints a one-line stderr deprecation and runs the same runtime.

Guardrail: every baseline capability works on plain GitHub. MuseHub is an optional substrate that deepens version control — it never gates core governance features.

Core concepts

Handover and Overseer Handover

Think of ROADMAP as the plan (what phases exist, their status, which model tier each uses) and HANDOVER as the baton (what to do right now, copy-pasted into the next session).

RULE #8 (Orchestrator): after ok init / ok sync, day-to-day phased work follows the vendored always-on rule .cursor/rules/orchestrator.mdc — paste the handover prompt, freeze-review before Auto, build-verify before DONE, keep roadmap + handover in sync via ok governance-sync. Do not keep a separate hand-rolled “update ROADMAP.md / OVERSEER_HANDOVER.md” protocol beside the kit.

ROADMAP

docs/ROADMAP.md (from template) is the phase control board:

• Build queue table: phase → model label → status → deliverable
• Phase Model Key (Thinking, Auto, Thinking → Auto, Operator + Auto)
• Definition of Done per phase (tests, governance sync, no secrets)

Phases move TODO → WIP → DONE → BLOCKED. Only one THE ONE NEXT STEP should be active in the handover at a time.

Benefits

How it works (end-to-end flow)

┌─────────────────────────────────────────────────────────────────┐
│  ROADMAP — phases, model labels, status, Definition of Done      │
└────────────────────────────┬────────────────────────────────────┘
                             │
         ┌───────────────────┴───────────────────┐
         ▼                                       ▼
  Thinking / {step}a                      Auto / {step}b
  (design + freeze spec)                  (build to frozen spec)
         │                                       │
         ▼                                       ▼
  ok review --freeze                  seven-tier tests
  (pass / findings / blocked)                      │
         │                                       ▼
         └───────────────┬───────────────────────┘
                         ▼
              governance-sync (handover + roadmap)
                         │
                         ▼
              feature-branch commit (Tier 1)
                         │
                         ▼
              PR → merge to main (Tier 3 — human)

Step-by-step (one phase)

1. Read docs/ROADMAP.md target phase and docs/OVERSEER-HANDOVER.md NEXT block.
2. Paste the handover prompt into your AI session (any tool — see below).
3. Thinking phase (if applicable): produce or update a frozen spec; commit on a feature branch.
4. Freeze review: ./cli/ok review --freeze <spec-path> [--dry-run].
5. Auto phase (if applicable): implement exactly against the frozen spec; run tests.
6. Governance sync: ./cli/ok governance-sync --dry-run then apply when correct.
7. Close: update ROADMAP status row + handover NEXT block together; feature-branch commit.
8. Publish: open PR; merge to main only with Tier-3 operator authorization.

For Thinking → Auto phases, the handover emits two prompts: {step}a (Thinking) then {step}b (Auto) — never both at once unless {step}a is incomplete.

Where models are set

Models are labels and routing policy, not hard-coded API calls. The kit tells you which class of model to use; you select the actual model in your IDE or CLI.

The kit never chooses your API model automatically during normal build work — it enforces that you declare the tier so sessions stay consistent.

AI tool compatibility

The kit is IDE- and vendor-neutral at the core. Policy, templates, handover paste blocks, and the overseer CLI work the same regardless of which assistant you use.

What changes per tool

Degrade path (by design): if Cursor Automations are unavailable, ok governance-sync and ok review --freeze are the portable fallback — no Cursor-only gate on core governance.

Overseer App (Track Q — local UI + desktop)

Open the local console

The public site never mints session credentials and does not run the console. Use one of:

Path 1 — Download Mac console (preferred on Apple Silicon)

1. Confirm Python 3.11+ (python3 --version).
2. Download the signed Apple Silicon (aarch64) .dmg: Overseer.Kit_0.1.0_aarch64.dmg (Release v0.1.0; signing.status: signed).
3. Optionally verify SHA256SUMS.txt + manifest (see the desktop runbook).
4. Bind a governed checkout before launch: set OVERSEER_REPO_ROOT to the absolute path of the repo that already has .overseer/ from ok init. Without that env var, the app binds the bundled kit root inside the app resources — useful for dogfooding the kit, not a project folder picker.
5. Open the app; desktop shell auto-fills session bootstrap.
6. Confirm the chrome shows the expected bound path before any write action.

Apple Silicon (aarch64) Mac · signed+notarized · requires Python 3.11+. Set OVERSEER_REPO_ROOT to your governed repo. Windows/Linux signed installers are not published yet. No in-app folder picker in Auto v1.

Path 2 — Browser (ok app)

1. From a governed repo: ok app --open (or ok app, then open the printed URL).
2. Copy session_credential and csrf_token from that terminal.
3. Paste into Session bootstrap → Connect.
4. Credentials are process-lifetime only; never commit them.

Path 3 — Dev desktop

1. From kit root: ./scripts/bundle-desktop-kit.sh then cd desktop && npm install && npm run tauri dev.
2. Same auto-fill as Path 1; needs Python 3.11+ + Rust/Node for dev builds.

This console is bound to one local checkout. Reads and writes (when confirmed) apply only to that tree — not to overseerkit.com and not to arbitrary remote repos. Desktop Path 1/3: set OVERSEER_REPO_ROOT to your governed repo; otherwise the shell binds the bundled kit.

Two review gates (honesty discipline)

SD-3 Thinking → Auto is two gates, not one:

Skills run in the agent session (not a background daemon). The always-on rule prevents marking DONE without verification. Escalation categories still stop for a human.

Custom doc names (VideoFactory, MuseHub, multi-repo workspaces): set docs.handover, docs.roadmap, docs.handover_title, docs.roadmap_title in .overseer/config.yaml — see docs/consumers/videofactory/OVERSEER-SETUP.md.

VCS regimes

Same CLI commands in every regime. The adapter layer handles the differences fail-closed.

Git-only (start here)

No MuseHub required. See docs/GIT-ONLY-QUICKSTART.md.

./cli/ok init --regime git-only --non-interactive
./cli/ok status --check-footprint
./cli/ok governance-sync --dry-run

Repos that already have hand-authored handover/roadmap files should use init --migrate instead (see docs/MIGRATE-EXISTING-REPO.md and CONTRIBUTING.md).

MuseHub optional upgrade (muse+git-mirror)

How to connect a repo:

1. Install Muse and authenticate (muse --version).

2. Initialize Muse in the repo: muse -C <repo-root> init (creates .muse/ locally).

3. Flip .overseer/config.yaml to regime: muse+git-mirror, canonical: muse, and set vcs.git.mirror_branch (typically muse-mirror).

4. Run ./cli/ok sync — seeds MUSE-BRIDGE-WORKFLOW.md and scripts/muse-bridge-deploy.sh when the regime requires them.

5. Day-to-day: muse commit on feature branches in Muse.

6. Publish to GitHub: only via the safe deploy script:

   ./scripts/muse-bridge-deploy.sh "mirror: <summary>"
   

   Flow: Muse main → isolated .muse/mirror/ → origin/muse-mirror → PR → main.

Hard rules (SD-14):

• Never muse bridge git-export --git-dir . on your working tree.
• Never git push origin main when Muse is canonical — mirror via muse-mirror PR only.

Full operator steps: docs/K7-DOGFOOD-OPERATOR-RUNBOOK.md and root MUSE-BRIDGE-WORKFLOW.md.

Install and day-to-day usage

First install (any repo)

# From a clone of this kit (or path to cli/ok):
./cli/ok -C <your-repo> init --regime git-only --non-interactive

# Or migrate an existing repo with living docs:
./cli/ok -C <your-repo> init --migrate --from-config <prepared.yaml> --non-interactive

This writes: governance docs, policy/, .cursor/ fragments, .overseer/version.lock, and AGENTS.md (when in footprint).

Every session

1. Open docs/OVERSEER-HANDOVER.md → copy Paste-ready prompt.
2. Work on a feature branch (Tier 1).
3. Run tests for your phase tier.
4. Before ending: ./cli/ok governance-sync --dry-run → fix drift → apply if needed.
5. Commit docs + code together on the feature branch.
6. Open PR; merge only with Tier-3 authorization.

Pull kit updates

./cli/ok sync              # preview drift
./cli/ok sync -y           # apply kit footprint updates
./cli/ok status --check-footprint

Status

K12 DONE — Track N public landing, scenario gallery, MIT LICENSE, SECURITY.md, GitHub→MuseHub funnel. See docs/ROADMAP.md. Contributor guide: CONTRIBUTING.md.

Public landing: open docs/landing/index.html locally or enable GitHub Pages from the /docs/landing path on your default branch.

Runtime vs governance

This kit owns the governance layer (docs, VCS adapters, hygiene agent, freeze reviewer). Multi-agent product runtime (orchestrator / worker / checker patterns) lives in consumer codebases — see docs/OVERSEER-KIT-SPEC.md. The kit does not ship product adapters.

Docs

Dogfood

This repo uses its own handover/roadmap workflow while being built. VCS regime: muse+git-mirror — MuseHub canonical, GitHub mirror via scripts/muse-bridge-deploy.sh only (see .overseer/config.yaml and AGENTS.md).