Contributing to Overseer Kit
Thanks for helping improve 🆗 Overseer Kit — portable governance for AI-assisted development. This guide covers how to propose changes safely.
What belongs in this repository
Ship only product-facing material:
| In scope | Out of scope (do not commit) |
|---|---|
| CLI, adapters, templates, policy, tests | Personal Cursor/user-rule paste dumps |
Public docs under docs/ (and maintainer freezes under docs/archive/phases/) |
Private sister-product pilot laundry / machine-specific runbooks |
Landing static site under docs/landing/ |
Secrets, tokens, .env*, private signing keys |
| Contributor / security / license docs | Live posture flips, staging deploys, real payments |
Operator-local notes stay off this tree. If a doc is only useful on one private machine or one private consumer deploy, it does not belong here.
Before you start
- Read
README.mdanddocs/README.md. - Skim
docs/OVERSEER-KIT-SPEC.md— do not redesign frozen architecture inside a Build phase. - Prefer a feature branch for every change. Never push or merge directly to
mainwithout maintainer (Tier-3) authorization. - Security issues: follow
SECURITY.md— do not open a public issue for undisclosed vulnerabilities.
Development setup
Requires Python 3.11+.
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
# Sanity
./cli/ok status
./cli/ok --help
cli/ok is the canonical POSIX entrypoint (python -m cli.main). The
cli/overseer shim remains for compatibility and prints a one-line deprecation.
Making a change
- Create a feature branch from current
main. - Keep changes scoped. Match existing style; avoid drive-by refactors.
- Update living governance docs together when a phase/status changes:
docs/ROADMAP.mddocs/OVERSEER-HANDOVER.md
- Prefer
./cli/ok governance-sync --dry-runbefore claiming docs match VCS reality. - Open a pull request against
main. Describe intent, risk, and how you tested.
Authority tiers (short form)
| Tier | Examples |
|---|---|
| 1 — do | Feature-branch commits/pushes, tests, non-secret doc hygiene |
| 2 — recommend once | Persistence / adapter contract shape (record the decision) |
| 3 — stop for maintainer | Merge to main, live capability flips, secrets, real money, data deletion |
Full policy: policy/tiers.yaml.
Tests (RULE #0)
New behavior needs coverage across the seven tiers in policy/test-tiers.yaml
where applicable: unit, integration, end-to-end, stress, data-integrity,
performance, security.
# Full suite
.venv/bin/pytest -q
# Focused
.venv/bin/pytest -q tests/security/
Do not mark a Build phase DONE on green tests alone when freeze/build gates
apply — maintainers run /build-verification-review (or ok review paths) per
kit policy.
Docs map for contributors
| Doc | Role |
|---|---|
docs/GIT-ONLY-QUICKSTART.md |
Adopt with plain GitHub |
docs/MIGRATE-EXISTING-REPO.md |
init --migrate for repos that already have handover/roadmap |
docs/CONSUMER-ADAPTER-PATTERN.md |
How a product repo plugs into the kit |
docs/CHECK-OK.md |
Ad-hoc honesty / freeze + build verification paste |
docs/archive/README.md |
Maintainer archive map (phase freezes + vision) |
Pull request checklist
- [ ] Feature branch (not direct-to-
main) - [ ] Tests updated or justified N/A for docs-only
- [ ] No secrets, absolute private paths, or
.env*files - [ ] ROADMAP + HANDOVER updated together when status changes
- [ ] SECURITY.md path used for vulnerability reports
- [ ] License remains MIT (
LICENSE)
Code of conduct expectation
Be respectful and constructive. Assume good faith. Maintainers may close PRs that
rewrite frozen contracts without a Thinking freeze, invent Tier-3 automation, or
introduce MuseHub-only baselines (every core governance feature must keep working
on git-only).
Maintainers only
Repository visibility / DNS / signing-secret flips are Tier 3. Use
docs/PUBLIC-VISIBILITY-CHECKLIST.md
before making this repository public.