Metadata-Version: 2.5
Name: vibesop
Version: 8.4.1
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.4.1-blue.svg)](https://github.com/nehcuh/vibesop-py/releases/tag/v8.4.1)
[![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 provides tools for selecting skills, planning tasks, checking delivery,
recording execution evidence, and retrieving past experience 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 describes the skill-management subsystem.** The project now includes
workflow engineering and empirical research as well. 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.4.1** |
| Previous public release | **8.4.0**, published 2026-09-14 |
| 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).

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).
