Metadata-Version: 2.5
Name: vibesop
Version: 8.5.0
Summary: Engineering tools for AI-assisted development: skill routing, workflow verification, traces, and experience retrieval.
Project-URL: Homepage, https://github.com/nehcuh/vibesop-py
Project-URL: Documentation, https://github.com/nehcuh/vibesop-py#readme
Project-URL: Repository, https://github.com/nehcuh/vibesop-py.git
Project-URL: Issues, https://github.com/nehcuh/vibesop-py/issues
Author: nehcuh
License: MIT
License-File: LICENSE
Keywords: ai,claude-code,orchestration,skill-routing,skillos,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: anthropic<1.0.0,>=0.45.0
Requires-Dist: fastapi<1.0.0,>=0.115.0
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: idna>=3.15
Requires-Dist: jinja2<4.0.0,>=3.1.0
Requires-Dist: numpy<3.0.0,>=1.26.0
Requires-Dist: openai<2.0.0,>=1.60.0
Requires-Dist: packaging<25.0.0,>=24.0.0
Requires-Dist: pydantic-settings<3.0.0,>=2.14.2
Requires-Dist: pydantic<3.0.0,>=2.10.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.0
Requires-Dist: pyyaml<7.0.0,>=6.0.0
Requires-Dist: questionary<3.0.0,>=2.1.0
Requires-Dist: rich<14.0.0,>=13.9.0
Requires-Dist: ruamel-yaml<0.19.0,>=0.18.6
Requires-Dist: typer<1.0.0,>=0.15.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.30.0
Provides-Extra: all
Requires-Dist: basedpyright<2.0.0,>=1.24.0; extra == 'all'
Requires-Dist: fastembed<1.0.0,>=0.8.0; extra == 'all'
Requires-Dist: numpy<3.0.0,>=1.24.0; extra == 'all'
Requires-Dist: pdoc>=16.0.0; extra == 'all'
Requires-Dist: pre-commit<5.0.0,>=4.0.0; extra == 'all'
Requires-Dist: pytest-asyncio<2.0.0,>=1.0.0; extra == 'all'
Requires-Dist: pytest-cov<7.0.0,>=6.0.0; extra == 'all'
Requires-Dist: pytest-mock>=3.15.1; extra == 'all'
Requires-Dist: pytest-rerunfailures>=16.1; extra == 'all'
Requires-Dist: pytest-xdist>=3.8.0; extra == 'all'
Requires-Dist: pytest<10.0.0,>=9.0.3; extra == 'all'
Requires-Dist: ruff<1.0.0,>=0.9.0; extra == 'all'
Requires-Dist: sentence-transformers<6.0.0,>=5.5.0; extra == 'all'
Provides-Extra: dashboard
Provides-Extra: dev
Requires-Dist: basedpyright<2.0.0,>=1.24.0; extra == 'dev'
Requires-Dist: pdoc>=16.0.0; extra == 'dev'
Requires-Dist: pre-commit<5.0.0,>=4.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio<2.0.0,>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov<7.0.0,>=6.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.15.1; extra == 'dev'
Requires-Dist: pytest-rerunfailures>=16.1; extra == 'dev'
Requires-Dist: pytest-xdist>=3.8.0; extra == 'dev'
Requires-Dist: pytest<10.0.0,>=9.0.3; extra == 'dev'
Requires-Dist: ruff<1.0.0,>=0.9.0; extra == 'dev'
Provides-Extra: semantic
Requires-Dist: fastembed<1.0.0,>=0.8.0; extra == 'semantic'
Requires-Dist: numpy<3.0.0,>=1.24.0; extra == 'semantic'
Requires-Dist: sentence-transformers<6.0.0,>=5.5.0; extra == 'semantic'
Provides-Extra: test
Requires-Dist: basedpyright<2.0.0,>=1.24.0; extra == 'test'
Requires-Dist: pdoc>=16.0.0; extra == 'test'
Requires-Dist: pre-commit<5.0.0,>=4.0.0; extra == 'test'
Requires-Dist: pytest-asyncio<2.0.0,>=1.0.0; extra == 'test'
Requires-Dist: pytest-cov<7.0.0,>=6.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.15.1; extra == 'test'
Requires-Dist: pytest-rerunfailures>=16.1; extra == 'test'
Requires-Dist: pytest-xdist>=3.8.0; extra == 'test'
Requires-Dist: pytest<10.0.0,>=9.0.3; extra == 'test'
Requires-Dist: ruff<1.0.0,>=0.9.0; extra == 'test'
Description-Content-Type: text/markdown

# VibeSOP

> **Engineering tools and empirical research for reliable AI-assisted development.**
>
> [中文](README.zh-CN.md) · [Documentation](docs/INDEX.md) · [Project status](docs/PROJECT_STATUS.md) · [Research](docs/research/README.md)

[![Python](https://img.shields.io/badge/Python-3.12%2B-blue.svg)](pyproject.toml)
[![Version](https://img.shields.io/badge/Version-8.5.0-blue.svg)](https://github.com/nehcuh/vibesop-py/releases)
[![PyPI](https://img.shields.io/pypi/v/vibesop.svg)](https://pypi.org/project/vibesop/)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

VibeSOP is a **multi-agent AI engineering workflow** system. It routes requests
to the right skill or agent, verifies delivery against explicit criteria, and
records observable execution evidence. Around that core it provides skill
selection, governance over what may gate a release, and experience/knowledge
accumulation across AI coding agents. The repository also contains experiments on
when skills, specifications, orchestration, review, and memory improve the
work—and when they add overhead.

**SkillOS is the skill-management subsystem**, not the whole project. VibeSOP
also covers routing, verification, observability, governance, and
experience/knowledge accumulation. Reliability is the objective; the presence of
these tools does not establish an automatic or proven end-to-end software
factory. See the [project positioning](docs/POSITIONING.md).

## Version and availability

| Surface | State |
|---|---|
| Current source and package metadata | **8.5.0** (source candidate; tag/publish pending) |
| Previous public release | **8.4.1**, published 2026-09-15 |
| Commit / changelog references to 8.3.1 | Internal repair-batch labels; no 8.3.1 release exists |
| Skill format | SKILL.md v3.0; independent of the package version |
| Fixed-role committee v2 | Unfinished research; separate from the installed package |

The capabilities below describe this release. Local experiment data is not part
of the installed package. Details and release evidence: [project status](docs/PROJECT_STATUS.md).

## What you can do

| Need | Tools in the source tree | Boundary |
|---|---|---|
| Select and maintain skills | `vibe route`, skill installation, scopes, lifecycle management | No-match is a valid result; a skill need not be injected into every task |
| Plan work and check delivery | Execution plans, dependency tracking, verifier selection, blocked-plan handling | A generated plan or a model's approval is not proof of completion |
| Inspect what happened | Traces, replay, observability, machine acceptance records | Evidence must come from the execution being evaluated |
| Retrieve prior work | `vibe recall`, feedback, clustering and cross-project pools | Retrieval is implemented; continual improvement is not guaranteed |
| Run recurring work | `vibe loop` and scheduler integration | Behavior depends on the configured executor, schedule and environment |
| Evaluate an engineering method | Research reports, protocols, controlled runs and evidence manifests | Experimental branches and results are not automatically shipping features |

The hook path hands skill context to the host coding agent. Runtime, loop and
validation tools have their own execution paths. Platform configuration support,
hook support and end-to-end verification should be checked separately in the
[integration guide](docs/agent-integration.md).

## Quick start

Python **3.12+** is required. Install the public package with uv:

```sh
uv tool install vibesop
vibe --version
vibe quickstart
```

The routing demo uses a local lightweight path; LLM-enhanced routing requires a
configured provider. Review the selected skill and plan before relying on it.

To work from source:

```sh
git clone https://github.com/nehcuh/vibesop-py.git
cd vibesop-py
uv sync --extra dev
uv run vibe --version
uv run vibe quickstart
```

Inside a source checkout, use `uv run vibe` in place of `vibe` to avoid accidentally
invoking an older globally installed package.

## Integrations

Generate configuration for the agent you use, then restart that agent:

| Agent | Command |
|---|---|
| Claude Code | `vibe build claude-code --output ~/.claude` |
| Grok Build | `vibe build grok-build --output ~/.grok` |
| Kimi CLI | `vibe build kimi-cli --output ~/.kimi-code` |
| Pi | `vibe build pi --output .pi` |
| OpenCode | `vibe build opencode --output ~/.config/opencode` |
| Cursor | `vibe build cursor --output ~/.cursor` |

These are configuration-generation targets, not a claim of identical runtime
behavior across agents. Use `vibe doctor` and the platform-specific documentation
to check your environment.

## LLM configuration

For a CLI subprocess, configure a supported provider, for example:

```sh
export ANTHROPIC_API_KEY="your-key"
vibe route "help me debug this code"
```

An in-process integration can supply its host LLM through `AgentRouter.set_llm()`.
Provider options and platform-specific setup are in the
[configuration guide](docs/SKILL_LLM_CONFIG_GUIDE.md) and
[agent integration guide](docs/agent-integration.md).

## Workflow examples

```sh
vibe route "help me debug this code"
vibe plan list
vibe recall "configuration merge lost user hooks"
vibe loop list
vibe doctor
```

`recall` needs recorded traces and its embedding dependencies. Cross-project
retrieval is explicit (`--cross-project`) and requires a populated pool.
A blocked plan needs its reported problem resolved; it must not be treated as a
completed or ready-to-run task. See the
[verification contract](docs/architecture/verification-contract.md).

### Routing evidence (source candidate 8.5.0)

`vibe observe routing` reports no-match, near-miss, and decision-source
evidence from local route spans. It is report-only: it never edits the eval
dataset, thresholds, or routing policy. Generate a hermetic eval payload, then
observe spans against it:

```sh
# 1. Produce a fresh hermetic eval payload (near-miss over-injection evidence).
uv run python scripts/eval_routing.py --hermetic --json --json-out /tmp/eval-routing.json

# 2. Observe local route spans against it (reads .vibe/observability/spans.jsonl
#    by default; exit 4 means not enough scorable spans yet).
uv run vibe observe routing --eval-json /tmp/eval-routing.json --json
```

Spans come from real `vibe route` runs. See the
[operator runbook](docs/observe-routing.md) for metric definitions, thresholds,
exit codes, and cron/CI wrappers.

For commands and realistic scenarios, see the [CLI reference](docs/user/CLI_REFERENCE.md),
[command handbook](docs/user/COMMAND_HANDBOOK.md), and [use cases](docs/USE_CASES.en.md).

## Research and engineering principles

Our experiments ask how specifications, skills, models and execution environments
interact; whether more reviewers or fixed expert roles justify their cost; and
whether stored experience produces useful future behavior.

- [Research overview](docs/research/README.md): findings, source material and limitations.
- [Experiment registry](docs/experiments/README.md): settled cohorts and unfinished v2 research.
- [Research survey](docs/research/research-survey.md): the broader evidence record.
- [Engineering methodology](docs/enterprise-agent-methodology.md): proposed practices, with tested components distinguished from untested end-to-end hypotheses.
- [Article collection](docs/essays/README.md): explanations for a broader audience.

We select skills when useful, define acceptance criteria, retain failures and
interruptions, and separate model review from execution evidence. We do not infer
universal gains from more skills, more agents, or more stored traces. Dataset,
model, budget and measurement conditions belong beside each reported result.

Some raw runs live in a checksummed local archive and are **not included in a Git
clone or the wheel**. Experiment evidence manifests describe their locations and
restoration requirements. Research protocols and package releases have separate
version histories.

## Development

```sh
uv sync --extra dev
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run basedpyright --level error
uv run pytest
```

A documented test command is not a claim that the current checkout passed it.
Verification scope and dated evidence belong in the relevant change or report.

Start with the [architecture guide](docs/dev/architecture-overview.md),
[contribution guide](CONTRIBUTING.md), and [current roadmap](docs/ROADMAP.md).
The next release should reconcile source changes, migration notes and release
checks; a positioning update alone does not justify a new version.

## Documentation and project history

[All documentation](docs/INDEX.md) · [Project status](docs/PROJECT_STATUS.md) ·
[Design principles](docs/PHILOSOPHY.md) · [Changelog](CHANGELOG.md) ·
[Historical reviews](docs/archive/reviews/README.md) ·
[Workspace recovery](docs/maintenance/README.md)

## License and acknowledgments

[MIT](LICENSE). VibeSOP integrates with community skill ecosystems including
[superpowers](https://github.com/obra/superpowers),
[oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex), and other installable
packs. Skills and host agents retain their own authorship, licenses and runtime
requirements.

Report issues and discuss the project on [GitHub](https://github.com/nehcuh/vibesop-py).
