Metadata-Version: 2.4
Name: cybervisor
Version: 0.2.1
Summary: Autonomous CLI supervisor for staged AI workflows
Author: crzidea
Project-URL: Homepage, https://github.com/crzidea/cybervisor
Project-URL: Repository, https://github.com/crzidea/cybervisor
Project-URL: Issues, https://github.com/crzidea/cybervisor/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: setproctitle>=1.3.4; platform_system != "Windows"

# 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 inherited `CYBERVISOR_LLM_*` env vars 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`](https://docs.astral.sh/uv/)
- One of:
  - `gemini` on `PATH`
  - `claude` on `PATH`
  - `mock` mode for local deterministic runs
- `CYBERVISOR_LLM_API_KEY` for non-mock runs

Optional local env loading is supported from `.env` in the working directory. `cybervisor` reads only `CYBERVISOR_LLM_BASE_URL`, `CYBERVISOR_LLM_API_KEY`, and `CYBERVISOR_LLM_MODEL`, and does not override variables already exported in the shell.

## Install For Use In Another Project

Install the CLI onto your `PATH`:

```bash
uv tool install cybervisor
```

After installation, verify:

```bash
cybervisor --version
```

If you prefer `pip`:

```bash
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:

```bash
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`

Export your verifier credentials in that project shell, or create a local `.env` file there:

```bash
export CYBERVISOR_LLM_API_KEY=...
# Optional overrides
# export CYBERVISOR_LLM_BASE_URL=https://api.openai.com/v1
# export CYBERVISOR_LLM_MODEL=auto
```

Then run `cybervisor` from that project directory:

```bash
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, 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

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

Start from a specific stage:

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

Stop before a specific stage:

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

Version and help:

```bash
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
- `CYBERVISOR_LLM_API_KEY` set 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:

```bash
uv sync
uv run cybervisor --version
```

Local env for this repo can be bootstrapped from:

```bash
cp .env.example .env
```

More detail lives in:

- [Configuration](docs/configuration.md)
- [Runtime behavior](docs/runtime-behavior.md)
- [Demo and Docker](docs/demo-and-docker.md)
- [Adding an adapter](docs/adapters/adding-an-adapter.md)

## Development

Validation commands used by this repo:

```bash
uv run mypy --strict src
uv run pytest
```

Useful focused runs:

```bash
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:

```bash
./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

```text
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.
