cybervisor 0.3.0

Autonomous CLI supervisor for staged AI workflows

cybervisor

cybervisor is an autonomous CLI supervisor for development runs. It executes a default 5-stage pipeline with Gemini CLI, Claude Code, or a mock agent, supports customizing stages in YAML config, installs runtime hooks for non-interactive execution, enforces optional stage-result contracts, and keeps audit logs in JSONL.

cybervisor works best when it sits on top of a speckit repository. speckit gives the project durable product and planning memory under .specify/, and cybervisor turns that context into an autonomous execution loop with review, correction, and verification stages.

What it does

• Runs the default five ordered stages: Spec, Review Spec, Implement, Review Code, Verify
• Allows custom stage lists in cybervisor.yaml
• Supports optional structured stage-result contracts and artifact-driven routing
• Fails fast when the selected agent CLI or hook verifier credentials are missing
• Writes non-secret hook runtime metadata and settings snapshots under .cybervisor/hooks/ for non-mock runs
• Keeps verifier credentials in ~/.cybervisor/config.yaml instead of persisting them under .cybervisor/hooks/
• Snapshots .gemini/settings.json or .claude/settings.json and restores the exact pre-run content on exit
• Streams live agent output to stderr and persists per-stage logs under .cybervisor/
• Exits with 130 on SIGINT or SIGTERM after cleanup

Requirements

• Python 3.11+
• uv
• One of:
  • gemini on PATH
  • claude on PATH
  • mock mode for local deterministic runs
• ~/.cybervisor/config.yaml with verifier settings for non-mock runs

Install For Use In Another Project

Install the CLI onto your PATH:

uv tool install cybervisor

After installation, verify:

cybervisor --version

If you prefer pip:

pip install cybervisor

Quick Start In Your Project

Recommended flow: start with a repository that already uses speckit, then let cybervisor add the autonomous pipeline scaffold on top.

If your project does not have speckit yet, initialize that first so the repo has .specify/ context for specs, plans, tasks, and constitution-driven workflows.

In the project you want cybervisor to supervise, bootstrap the default scaffold:

cybervisor init

cybervisor init chooses the scaffold based on the repo:

• If .specify/ already exists, it creates the speckit-oriented robust scaffold.
• If .specify/ is missing, it creates a standalone default scaffold.

In a standalone repo, that creates:

• cybervisor.yaml
• .cybervisor/contracts/prompts/Specify.md
• .cybervisor/contracts/prompts/Review Spec.md
• .cybervisor/contracts/prompts/Plan.md
• .cybervisor/contracts/prompts/Tasks.md
• .cybervisor/contracts/prompts/Review Code.md
• .cybervisor/contracts/prompts/Verify.md

In a speckit repo, the robust scaffold is leaner because it expects specification context to already live in .specify/:

• cybervisor.yaml
• .cybervisor/contracts/prompts/Review Spec.md
• .cybervisor/contracts/prompts/Review Code.md
• .cybervisor/contracts/prompts/Verify E2E.md

Set a global default agent:

cybervisor use claude

Then configure verifier settings in ~/.cybervisor/config.yaml:

llm:
  api_key: ...
  # Optional overrides
  # base_url: https://api.openai.com/v1
  # model: auto

Then run cybervisor from that project directory:

cybervisor "Create a 360 feedback system"
# equivalent explicit form
cybervisor run "Create a 360 feedback system"

cybervisor expects cybervisor.yaml in the current working directory by default, reads global runtime defaults from ~/.cybervisor/config.yaml, writes runtime files under .cybervisor/, and patches the selected agent's local settings during the run so the packaged hook can enforce autonomy and contract rules. For the standalone default scaffold, planning and implementation handoffs live in stage contract artifacts under .cybervisor/contracts/artifacts/, and each run resets both .cybervisor/contracts/artifacts/ and any leftover .cybervisor/artifacts/ state before the first stage starts.

Recommended With speckit

The strongest setup is:

1. Use speckit to establish the repo's specification system and .specify/ memory.
2. Run cybervisor init in that same repo.
3. Let cybervisor supervise implementation, review, and verification loops using the repo's existing speckit context.

Why this pairing works well:

• speckit keeps the long-lived product, plan, task, and constitution context in-repo.
• cybervisor adds autonomous stage orchestration, retries, hook enforcement, and audit logging.
• cybervisor init detects .specify/ automatically and installs the robust scaffold intended for speckit repositories.
• The combined flow is better suited for real project work than using cybervisor as a completely standalone prompt runner.

If you want a lightweight experiment, the standalone scaffold still works. For ongoing repository development, speckit should be the default recommendation.

Usage

cybervisor "Create a 360 feedback system"
cybervisor run "Create a 360 feedback system"

Start from a specific stage:

cybervisor "Create a 360 feedback system" --start-stage "Implement"

Stop before a specific stage:

cybervisor "Create a 360 feedback system" --start-stage "Implement" --end-before "Verify"

Version and help:

cybervisor --version
cybervisor --help

What You Need In The Target Project

• A cybervisor.yaml file in the project root, or --config pointing to one
• Preferably an existing .specify/ directory from speckit
• gemini or claude installed on PATH for real runs, or mock for deterministic local testing
• A global default agent saved in ~/.cybervisor/config.yaml via cybervisor use <agent_tool>
• Verifier settings configured in ~/.cybervisor/config.yaml for non-mock runs
• Write access to the project directory so cybervisor can create .cybervisor/

Develop cybervisor Itself

If you want to contribute to this repository rather than use the packaged CLI in another repo:

uv sync
uv run cybervisor --version

If you want persistent defaults for this repo on your machine, use cybervisor use <agent_tool> and set verifier values in ~/.cybervisor/config.yaml:

agent_tool: claude
llm:
  api_key: ...
  # Optional overrides
  # base_url: https://api.openai.com/v1
  # model: auto

More detail lives in:

• Configuration
• Pipeline authoring guide
• Runtime behavior
• Demo and Docker
• Adding an adapter

Development

Validation commands used by this repo:

uv run mypy --strict src
uv run pytest

Useful focused runs:

uv run pytest tests/integration/test_pipeline_e2e.py
uv run pytest tests/unit/test_hooks.py tests/unit/test_pipeline.py tests/unit/test_signals.py

Release helper:

./scripts/publish.sh

That script bumps the version in pyproject.toml with a patch release by default, refreshes uv.lock, removes the old dist/, builds fresh artifacts, and publishes them with uv publish. Pass minor or major to change the bump type.

Specs Directory

Feature folders under specs/ are archival implementation artifacts after delivery. The current source of truth for runtime behavior is the checked-in code plus the main project docs and constitution.

Repository layout

src/cybervisor/        Core CLI package
assets/hooks/          Hook prompt assets and fixtures
scripts/               Demo bootstrap and end-to-end scripts
templates/demo/        Demo project scaffold
tests/                 Unit and integration coverage
specs/                 Speckit feature artifacts
.specify/              Constitution, templates, and repo scripts
AGENTS.md              Symlink to .specify/memory/constitution.md
GEMINI.md              Symlink to AGENTS.md
CLAUDE.md              Symlink to AGENTS.md

Agent docs

The agent mandate files are symlinked by design:

• AGENTS.md -> .specify/memory/constitution.md
• GEMINI.md -> AGENTS.md
• CLAUDE.md -> AGENTS.md

If mandate content needs to change, update .specify/memory/constitution.md, not the symlinks.