Metadata-Version: 2.5
Name: vaultspec-core
Version: 0.2.1
Summary: Decision-driven harness for coding agents, and humans.
Project-URL: Bug Tracker, https://github.com/nevenincs/vaultspec-core/issues
Project-URL: Documentation, https://github.com/nevenincs/vaultspec-core/tree/main/docs/framework.md
Project-URL: Homepage, https://github.com/nevenincs/vaultspec-core
Project-URL: Repository, https://github.com/nevenincs/vaultspec-core
Author-email: Gergely Wootsch <hello@gergely-wootsch.com>
License: MIT License
        
        Copyright (c) 2026 Gergely Wootsch
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: acp,adr,ai-assisted,decision-driven-development,governance,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.13
Requires-Dist: mcp>=2.0.0
Requires-Dist: networkx>=3.6
Requires-Dist: phart>=0.5.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=14.3.2
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: rustworkx>=0.18.0
Requires-Dist: sse-starlette>=3.2.0
Requires-Dist: starlette>=0.52.1
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn>=0.41.0
Provides-Extra: dev
Requires-Dist: identify>=2.0.0; extra == 'dev'
Requires-Dist: mdformat-frontmatter>=2.0.10; extra == 'dev'
Requires-Dist: mdformat-gfm-alerts>=1.0.0; extra == 'dev'
Requires-Dist: mdformat-gfm>=1.0.0; extra == 'dev'
Requires-Dist: mdformat>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.4.0; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: ruff>=0.15.2; extra == 'dev'
Requires-Dist: ty>=0.0.15; extra == 'dev'
Description-Content-Type: text/markdown

<img src="docs/assets/logo.png" width="150" alt="Vaultspec logo">

# vaultspec-core

Decision-driven harness for coding agents, and humans.

Vaultspec is a coding harness: it implements a structured coding workflow focused on
#features, decision records and the documents grounding them. It bundles rules, agents,
skills, and tools to author the documents that describe and track a feature's
development.

The harness supports Claude Code, Codex, Gemini CLI, and Antigravity.

[![build](https://img.shields.io/github/actions/workflow/status/nevenincs/vaultspec-core/ci.yml?branch=main&style=flat&label=build&logo=githubactions&logoColor=white&labelColor=24292f&color=57606a)](https://github.com/nevenincs/vaultspec-core/actions/workflows/ci.yml)
[![release](https://img.shields.io/pypi/v/vaultspec-core?style=flat&label=release&logo=pypi&logoColor=white&labelColor=24292f&color=57606a)](https://pypi.org/project/vaultspec-core/)
[![runtime](https://img.shields.io/badge/runtime-Python%203.13%20%7C%203.14-57606a?style=flat&logo=python&logoColor=white&labelColor=24292f)](https://www.python.org/downloads/)
[![license](https://img.shields.io/github/license/nevenincs/vaultspec-core?style=flat&label=license&logo=opensourceinitiative&logoColor=white&labelColor=24292f&color=57606a)](https://github.com/nevenincs/vaultspec-core/blob/main/LICENSE)

[Install](#install) · [Start a feature](#start-a-feature) ·
[Documentation](#documentation)

## Install

Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then run this
from your repository root:

```bash
uvx vaultspec-core install
```

Vaultspec supports Python 3.13 and 3.14. uv downloads a supported interpreter if needed.

The installer writes rules, skills, and agent configuration into your project and
configures a Model Context Protocol (MCP) server so your agent can call the tools.

Workflow documents live in `.vault/`; the policy lives in `.vaultspec/`. Commit both so
teammates share the records and rules. Installation also manages ignore rules for local
state and writes pre-commit configuration. Activating commit hooks is a
[separate choice](docs/framework.md#configure-project-integrations).

Keep the `uvx` prefix when running commands yourself. For persistent or project-local
installation, see [installation options](docs/framework.md#installation-options).
[Homebrew and Scoop](docs/channels.md) provide binaries that need no separate Python
install and no network: each one carries its own interpreter, Vaultspec and every
dependency.

## Start a feature

Open your repository in your coding agent and describe the work:

> Add full-text search to the API. Use the feature tag search-api. Check existing
> decisions first, and show me any new decision and implementation plan for approval.

The agent uses the parts of the workflow the task needs:

- Routine changes can proceed directly within your request.
- A costly-to-reverse choice needs evidence and an approved architecture decision record
  (ADR). Reuse an existing accepted ADR when it already covers the work.
- Work that needs durable sequencing or handoff uses a plan, with or without a new ADR.
  The agent implements and verifies each Step, logs the changes, and reviews the
  integrated result.

Rules guide the agent's decisions; tools maintain document structure and progress.
Record checks complement tests and review, but do not prove the code is correct.
Approval covers the agreed scope, including ordinary in-scope corrections; new choices
outside that authorization need your input.

A feature tag groups the work's records. To see recorded progress:

```bash
uvx vaultspec-core status search-api
```

For planned work, ask the agent to resume the feature from its next open Step. The
[workflow guide](docs/framework.md#begin-a-pipeline) explains how to choose a route,
approve work, and continue across sessions.

## Documentation

- [Documentation index](docs/README.md): choose a guide for your task.
- [Framework manual](docs/framework.md): run the workflow and customize its rules.
- [Document syntax](docs/syntax.md): edit prose and manage document structure.
- [Verifying a workspace](docs/verification.md): check the setup and repair errors.
- [CLI reference](docs/CLI.md) and [MCP reference](docs/MCP.md): commands, tools, and
  configuration.

Open `.vault/` in [Obsidian](https://obsidian.md) to browse its linked documents. The
optional [vaultspec-rag](https://github.com/nevenincs/vaultspec-rag) package adds
semantic search across the vault and your code.

## Support and license

vaultspec-core is in beta. Report bugs, ask questions, or propose changes on the
[issue tracker](https://github.com/nevenincs/vaultspec-core/issues). For contributions
and releases, see [maintainer documentation](docs/README.md#for-maintainers).

Released under the [MIT License](LICENSE).
