Project Supervisor

Project Supervisor is the project-neutral control plane for autonomous multi-agent software development. Projects provide a strict YAML adapter; the supervisor provides atomic queueing, leases, worktree/evidence roots, shell-free verification, recovery decisions, and typed handoff contracts.

This 0.5.0 release is the reusable control-plane foundation. It now has atomic SQLite ownership transitions, lease heartbeat/expiry/release, bounded command execution, evidence manifests, and structured handoffs. OS-agent launching, independent-review orchestration, and project cutover remain deliberately separate provider work.

Install in any GitHub project

The package is designed to be installed into each consuming project rather than copied into it:

python -m pip install project-supervisor
project-supervisor init
# edit .project-supervisor.yaml and ensure its status_file exists
project-supervisor check

init creates .project-supervisor.yaml in the current project. Once present, the adapter is discovered automatically from the project root or a child directory. The explicit form remains available for scripts and CI:

project-supervisor --project C:\path\to\project\.project-supervisor.yaml check

For a GitHub checkout before a PyPI release exists:

python -m pip install "project-supervisor @ git+https://github.com/Smkzz/project-supervisor.git@main"

For stable automation, pin a release tag or PyPI version. The consumer templates in templates/project/ include a pinned requirements file, Dependabot config, and a scheduled compatibility workflow. Dependabot opens a reviewable upgrade PR whenever a new release is published; the workflow validates the installed version. This is the automatic-update path for existing projects while keeping their dependency state visible and reproducible.

The package repository includes GitHub Actions for test/build checks and PyPI trusted publishing on v* tags. Publishing still requires a real GitHub remote, the PyPI project name, and trusted-publisher configuration.

The complete repository/PyPI setup checklist is in docs/GITHUB_RELEASE_CHECKLIST.md.

Development gates

python -m pip install ".[dev]"
python -m ruff check project_supervisor tests
python -m ruff format --check project_supervisor tests
python -m mypy project_supervisor
python -m pytest --cov=project_supervisor --cov-report=term-missing --cov-fail-under=75
python -m build
python -m twine check dist/*
python -m pip check

The release is intentionally tag-driven: the vX.Y.Z tag must match the single-sourced package version before PyPI publishing is allowed.

Adapter contract

schemaVersion: 1
project:
  name: demo
  root: C:/path/to/project
  markers: [package.json]
  queue_file: .supervisor/queue.yaml
  status_file: STATUS.md
  state_db: .supervisor/state.sqlite3
  evidence_root: .supervisor/evidence
  worktree_root: .supervisor/worktrees
  job_id_pattern: 'JOB-[0-9]+'
  max_retries: 2
  capabilities:
    snapshot_read: true
    verification: true
    queue: true
    worker_launch: false
    independent_review: false
    hosted_gate: false
    publish: false
  verification_profiles:
    fast:
      commands:
        - argv: [python, -m, pytest, -q]
          cwd: .
          timeout_seconds: 300
          shell: false
          side_effects: read_only
  snapshot:
    sources:
      - path: orchestration/state.json
        format: json
        role: runtime
        optional: true
  worker_profiles: {}
  reviewer_profiles: {}
  protected_paths: [.git, .supervisor]
  agent_scopes:
    implementer: [src]
    verifier: []
    reviewer: [docs/reviews]

All configured paths are relative to the project root and are checked for containment. Commands use explicit argv, relative cwd, bounded timeout, optional non-secret environment values, shell: false, and an explicit side_effects declaration (read_only, control_plane, project, external, or unknown). The package does not assume backend, frontend, Flutter, Node, or any other repository layout. Capabilities are explicit so the supervisor can fail closed when a project has not yet supplied a worker, reviewer, hosted-gate, or publish integration.

Inspect and verify a project

python -m project_supervisor.cli --project C:\path\to\project-adapter.yaml paths
python -m project_supervisor.cli --project C:\path\to\project-adapter.yaml check
python -m project_supervisor.cli --project C:\path\to\project-adapter.yaml snapshot
python -m project_supervisor.cli --project C:\path\to\project-adapter.yaml verify --job-id JOB-1 --profile fast
python -m project_supervisor.cli --project C:\path\to\project-adapter.yaml shadow-verify --profile fast
python -m project_supervisor.cli --project C:\path\to\project-adapter.yaml coordinate --job-id JOB-1 --agent-id worker-1 --reviewer-id reviewer-1 --revision abcdef1

Verification writes a deterministic command manifest below the adapter's contained evidence root. A failed command returns a non-zero exit code and is never reported as a pass.

Shadow verification runs only commands explicitly declared side_effects: read_only. It reports accepted: false, does not mutate queue, state, worktrees, or evidence, and refuses delegated commands that may reconcile a control plane or touch the project. Use ordinary verify only after accepting the declared side effects. The snapshot command reads adapter-declared JSON and Markdown sources into one normalized, provenance-hashed view.

Queue lifecycle

python -m project_supervisor.cli --project adapter.yaml queue-init
python -m project_supervisor.cli --project adapter.yaml queue-add --job-id JOB-1 --payload-json '{"goal":"run tests"}'
python -m project_supervisor.cli --project adapter.yaml queue-claim --job-id JOB-1 --agent-id agent-1
python -m project_supervisor.cli --project adapter.yaml queue-heartbeat --job-id JOB-1 --agent-id agent-1 --lease-token TOKEN
python -m project_supervisor.cli --project adapter.yaml queue-complete --job-id JOB-1 --agent-id agent-1 --lease-token TOKEN --event-id evt-1 --status completed --result-json '{"ok":true}'

Claims, completion, heartbeat, release, and expiry use SQLite write transactions. A late or mismatched lease cannot complete another worker's job; repeated completion with the same event ID is idempotent.

The typed gate API consumes concrete command results, evidence validation, review handoffs, canary results, and approval records. The older boolean gate function remains only as a compatibility shim and is not sufficient for acceptance.

The provider interface supports Codex/local workers. The coordination API runs one worker and then one distinct reviewer only when the adapter declares both capabilities; it requires complete handoffs, safe changed paths, exact revision/tree identity, and validated evidence before returning APPROVED. Adapters provide those processes through worker_profiles and reviewer_profiles; profile argv values are explicit, shell-free templates with only job_id, agent_id, revision, tree, and handoff_path fields. Each coordinate run writes coordination.json beside its evidence. It does not claim a queue lease automatically; callers must claim a generic queue lease first. The command extends that lease for its declared budget, then completes or releases it according to the final coordination state. The example adapters under examples/ cover Flutter and Gomoku without machine-specific roots, but intentionally leave worker/reviewer launch capabilities disabled until each project has a reviewed integration provider.