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

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

Do not run python cli/overseer — cli/overseer is a shell script, not Python.

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).

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)
         │                                       │
         ▼                                       ▼
  overseer 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/overseer review --freeze <spec-path> [--dry-run].
5. Auto phase (if applicable): implement exactly against the frozen spec; run tests.
6. Governance sync: ./cli/overseer 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, overseer governance-sync and overseer review --freeze are the portable fallback — no Cursor-only gate on core governance.

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/overseer init --regime git-only --non-interactive
./cli/overseer status --check-footprint
./cli/overseer governance-sync --dry-run

Repos that already have hand-authored handover/roadmap files should use init --migrate instead (see docs/K6-PILOT-OPERATOR-RUNBOOK.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/overseer 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/overseer):
./cli/overseer -C <your-repo> init --regime git-only --non-interactive

# Or migrate an existing repo with living docs:
./cli/overseer -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/overseer 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/overseer sync              # preview drift
./cli/overseer sync -y           # apply kit footprint updates
./cli/overseer status --check-footprint

Status

K12 DONE — Track N public landing, scenario gallery, Apache-2.0 LICENSE, SECURITY.md, GitHub→MuseHub funnel. 380 seven-tier tests green. See docs/ROADMAP.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).