What it is
Supreme Team routes a coding request through design → build → review, with a
gate between every phase. Each phase boundary is checked against evidence on disk
before the next phase is handed its work. Where the host allows interception,
the runtime hooks are what turns the rules into refusals instead of advice. They
are off until you register them, and an install that skips them says so in capital
letters: without hooks a guarded path can be written, a lifecycle request can
bypass admiral, and a run heartbeat goes stale. Registering them is the one
install step that changes what the assistant can do (see
Install.md).
First ten minutes
- Install — hand Install.md to your agent, or run the installer for your OS from scripts/ (
bash ./scripts/install.sh, or powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1). The skill files copy without Python; the checks and hooks need Python 3.13 or newer.
- Register the hooks —
bash ./scripts/install.sh --register-hooks (-RegisterHooks on Windows). This is the enforcement layer: the pre-tool hook refuses guarded, frozen and single-writer writes, the prompt hook sends lifecycle work through admiral, and the post-tool hook keeps the run heartbeat alive. It edits host config files and asks first on a terminal; Claude Code, Codex and GitHub Copilot take config entries, Cursor and OpenCode a plugin. Skip it and everything above is advice the model may ignore; the installer ends every such run with a banner saying so.
- Restart your assistant so it loads the skills and the hooks, then check the installed copy.
- Start a run — call
admiral. It interviews you, writes the scope down, creates a run on disk, and hands off phase one. A governed run reads a lot of text; QUICK-START.md says how much and how to avoid it.
- Let it flow — small reversible edits skip the whole route and just get done (the Tier 0 fast path); security, deploy, and production work are never Tier 0 and take the full route. Routing is instruction, not enforcement: registered hooks remind the model on every prompt and refuse guarded writes, but nothing forces a request through
admiral.
Review gates
Every phase boundary hits a gatekeeper. The package and its hashed evidence go
through two deterministic validators, then a gatekeeper issues one verdict:
APPROVED advances, REVISE returns every finding at once, grouped by owner,
and only for a mechanical failure, a Critical, or an unresolved Major (three rounds at
most: the gate records the third consecutive REVISE as ESCALATE to you and holds the
boundary until you decide), ESCALATE comes to you. The cross-stage gate judges the crossing and
carries the phase gate's judgment, so a package is not reviewed twice for the same
question. Evidence that names its source files by
sha256 fails with input hash drift when one of them changes, instead of the gate
trusting a stale log. Scan and render records must name their sources; a test or
probe record that names none is accepted as the submitter's own statement, and the
gate says so in warnings rather than implying it was verified.
More in docs/gatekeepers.md.
Persistence & recovery
Run state lives in skillset-saves/ inside your project. Checkpoints publish
behind a journal, so an interrupted publish is visible and repairable, a stale lock
reclaim leaves a trace, and a lost pointer is not a lost run. Kill the session
mid-run and the next one resumes from the same files.
More in docs/persistent-saves.md.
How well it works
BENCHMARK.md has the results measured on the current tree: the seven
test suites, the three validators and lint, and the skill rubric scored on the four
gatekeeper packages (docs/reviews/). Routing accuracy is not in it, because that is
a paid model run that was not repeated, and CI runs neither.
Check an installation
Python 3.13 or newer is the floor for everything in this section. Commands in
these documents are written for a repository checkout, start at its root and say
python; on macOS and Linux that is python3 (Ubuntu 22.04 and later and current
macOS ship no python), on Windows py -3. In an installed copy skills/ is the
install root. Install.md states both
substitutions.
The checkout (package_check.py and the tests need one):
python skills/scripts/check_runtime.py
python skills/scripts/validate_manifests.py
python skills/scripts/package_check.py --root .
python skills/harness/hooks/check_readiness.py --host auto
The installed copy, from any directory:
python3 ~/.agents/skills/scripts/check_runtime.py
python3 ~/.agents/skills/scripts/validate_manifests.py
python3 ~/.agents/skills/harness/hooks/check_readiness.py --host auto
py -3 "$env:USERPROFILE\.agents\skills\scripts\check_runtime.py"
py -3 "$env:USERPROFILE\.agents\skills\scripts\validate_manifests.py"
py -3 "$env:USERPROFILE\.agents\skills\harness\hooks\check_readiness.py" --host auto
Run the tests
Seven suites, standard library only, Python 3.13 or newer. Run them from a
repository checkout. CI runs these same commands on Windows, macOS and Linux,
on Python 3.13 and 3.14, with and without PyYAML installed
(CONTRIBUTING.md explains how to run one suite or all of them).
python -m unittest discover -s skills/harness/hooks -p "test_*.py"
python -m unittest discover -s skills/harness/gatekeeper -p "test_*.py"
python -m unittest discover -s skills/validation -p "test_*.py"
python -m unittest discover -s skills/scripts -p "test_*.py"
python -m unittest discover -s skills/taste -p "test_*.py"
python -m unittest discover -s scripts -p "test_*.py"
python -m unittest discover -s skills/skill-maker/skill-creator -p "test_*.py"
Documentation
License
Supreme Team is released under the MIT License. Copyright (c) 2026 TykoDev.
