Metadata-Version: 2.4
Name: vaultspec-core
Version: 0.1.50
Summary: A governed development framework for AI-assisted engineering
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,governance,mcp,spec-driven-development
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: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=1.28.1
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: 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: prek>=0.3.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest-durations>=1.0.0; extra == 'dev'
Requires-Dist: pytest-reportlog>=0.4.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

<div align="center">

<img src="docs/assets/logo.svg" alt="vaultspec-core family logo" width="150" />

# vaultspec-core

**The agent harness: the pipeline, the vault, and the CLI that drives them.**

[![build](https://img.shields.io/github/actions/workflow/status/nevenincs/vaultspec-core/ci.yml?branch=main&style=for-the-badge&label=build&logo=githubactions&logoColor=white&labelColor=1b1a16)](https://github.com/nevenincs/vaultspec-core/actions/workflows/ci.yml)
[![release](https://img.shields.io/pypi/v/vaultspec-core?style=for-the-badge&label=release&logo=pypi&logoColor=white&labelColor=1b1a16&color=8A72B5)](https://pypi.org/project/vaultspec-core/)
[![runtime](https://img.shields.io/badge/runtime-Python%203.13%2B-3F9AA6?style=for-the-badge&logo=python&logoColor=white&labelColor=1b1a16)](https://www.python.org/downloads/)
[![license](https://img.shields.io/github/license/nevenincs/vaultspec-core?style=for-the-badge&label=license&logo=opensourceinitiative&logoColor=white&labelColor=1b1a16&color=B3823C)](./LICENSE)

[![cli](https://img.shields.io/badge/cli-bundled-B5703F?style=for-the-badge&logo=gnubash&logoColor=white&labelColor=1b1a16)](./docs/CLI.md)
[![mcp](https://img.shields.io/badge/mcp-bundled-B05A6B?style=for-the-badge&logo=modelcontextprotocol&logoColor=white&labelColor=1b1a16)](./docs/MCP.md)

[Get started](#getting-started) · [Product](#the-pipeline-at-a-glance) ·
[Documentation](#learn-more) · [Family](#the-vaultspec-family) ·
[Support](#status-help-and-license)

</div>

<p align="center">
<img src="docs/assets/demo.gif" alt="vaultspec pipeline demo - provisioning a project, scaffolding research, ADR, and plan, then checking and graphing the vault" width="880" />
</p>

Vaultspec guides agents through a `Research → Decide → Plan → Execute → Verify` pipeline
(the Decide stage produces an Architecture Decision Record, or ADR, for each choice),
similar in spirit to spec-driven frameworks like Superpowers, with one difference:
nothing is throwaway. All work leaves a papertrail in the project's `.vault`. Documents
are bound together by feature tags and wiki-link references, together representing the
project's decision and execution history - a second brain your agents read before they
write.

We hold ourselves to it, too: vaultspec-core is developed with vaultspec. Its own
`.vault` currently holds 900+ CLI-scaffolded documents across 100+ features. Every
terminal render on this page is real output: the stills are captured against that live
vault, and the pipeline demo above runs against a scratch project.

## What is included?

`vaultspec-core` implements the natural language description of the workflow, and the
machinery that enforces it:

- **Rules, skills, and agent personas** for Claude, Codex, Gemini, and Antigravity,
  seeded from one `.vaultspec` source of truth and synced per provider.
- **A CLI** that scaffolds, audits, and repairs every vault document - templates, tag
  taxonomy, wiki-link resolution, and plan structure are enforced, never hand-written.
- **Structured plans** that scale with the work: four complexity tiers (`L1`-`L4`) with
  waves, phases, and steps under stable canonical identifiers.
- **A Model Context Protocol (MCP) server** for MCP-capable clients.

<p align="center">
<img src="docs/assets/term-status.svg" alt="vaultspec-core status - live output from this repository's own vault" width="880" />
</p>

See the [framework manual](./docs/framework.md) for the full tour.

> [!TIP]
> The framework favours semantic search via the core's optional sister project,
> [vaultspec-rag](https://github.com/nevenincs/vaultspec-rag).

## Getting started

### 1. Install

For the quickest, dependency-free project bootstrap, run from a git project folder:

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

Use it as a tool or dependency:

```bash
# You can add it as a local tool
uv tool install vaultspec-core

# Or a project dependency
uv add vaultspec-core
```

### 2. Bootstrap

If you added it as a project dependency, bootstrap from inside your environment:

```bash
uv run vaultspec-core install
```

See the [CLI reference](./docs/CLI.md) for installation options.

> [!NOTE]
> `vaultspec-core install` handles project integration separately: it manages a block in
> your `.gitignore` and `.gitattributes`, writes pre-commit hooks, and drops an
> `.mcp.json` for Model Context Protocol clients by default.

Install picks a mode for how the pre-commit hooks and the MCP server launch. Tool mode
is the default and runs vaultspec-core through `uvx`, so it never enters your project's
dependency set. Dependency mode runs it through `uv run` and is selected automatically
when your `pyproject.toml` lists vaultspec-core. Dev mode also runs through `uv run`,
but places vaultspec-core in the default `dev` dependency group instead, so it doesn't
ship in your built distributions. Pin any with `vaultspec-core install --mode tool`,
`vaultspec-core install --mode dependency`, or `vaultspec-core install --mode dev`. The
choice is recorded per package in a committed `workspace.json`, so a workspace running
vaultspec-core alongside a companion package can declare each in its own mode. An
existing workspace has its mode inferred and recorded the next time you run
`vaultspec-core install --upgrade`.

### 3. Sync

All development paper trails live in `.vault` as markdown files. Rules, agents, and
skills are seeded from `.vaultspec` via:

```bash
uv run vaultspec-core sync
```

> [!TIP]
> Make sure to run
>
> ```bash
> uv run vaultspec-core install --upgrade
> ```
>
> after a library update as the shipped agents, skills and rules might change between
> library versions.

## The pipeline at a glance

The pipeline breaks down into these steps:
`[R] Research  →  [D] Decide (ADRs)  →  [P] Plan  →  [E] Execute  →  [V] Verify`.
Research has a parallel entry point - Reference (`/vaultspec-code-research`) - that
grounds the work in existing source code; a feature starts from either, or both. Each
step ships with its skills, agents, and CLI verbs.

To start using the framework describe the work you want done in natural language:

> "Start a new vaultspec pipeline to research options for adding full-text search to the
> API."

The synced rules guide the agent through the pipeline stage by stage, writing documents
into `.vault/` as it goes: a research note, then a decision record, a plan, execution
records, and a final review. You approve each checkpoint before the agent moves on.

Invoke a stage skill directly - for example `/vaultspec-research` - to enter the
pipeline at a specific stage. See the [framework manual](./docs/framework.md) for how
each one works.

### Skills

Skills are the slash-commands that drive each stage of the pipeline. Six map to the
pipeline stages; two helpers - curate and documentation - cover everyday upkeep. The
[framework manual](./docs/framework.md) gives full guidance on each, plus two further
skills for team coordination and project management.

**Which skill, when**

| When you want to                              | Skill                      |
| :-------------------------------------------- | :------------------------- |
| Explore a problem and weigh options           | `/vaultspec-research`      |
| Ground the work in the existing codebase      | `/vaultspec-code-research` |
| Record the decision and its consequences      | `/vaultspec-adr`           |
| Turn the decision into an implementation plan | `/vaultspec-write`         |
| Work through the plan, step by step           | `/vaultspec-execute`       |
| Audit the finished work by severity           | `/vaultspec-code-review`   |
| Repair vault links, frontmatter, and naming   | `/vaultspec-curate`        |
| Draft user-facing documentation               | `/vaultspec-documentation` |

## Every feature leaves a paper trail

One feature tag binds a feature's whole lifecycle - research, decision, plan, execution
records, and audit - into a linked graph the CLI can trace, validate, and visualize:

<p align="center">
<img src="docs/assets/term-graph.svg" alt="vaultspec-core vault graph - a feature's document graph" width="880" />
</p>

Documents are scaffolded and structurally maintained through the `vaultspec-core vault`
command group - frontmatter, filenames, and plan structure are never hand-written, while
the body prose stays yours to edit. The CLI enforces templates, tag taxonomy, and
wiki-link resolution so your vault stays consistent.

```bash
# Scaffold a document from a template
vaultspec-core vault add research --feature search-api

# Find and inspect documents
vaultspec-core vault list --feature search-api

# Validate frontmatter, links, and cross-references (--fix to auto-repair)
vaultspec-core vault check all --fix

# Visualize a feature's dependency graph
vaultspec-core vault graph --feature search-api
```

Plans carry deeper structure - waves, phases, and steps. The
[framework manual](./docs/framework.md) covers that structure.

### The vault, rendered in Obsidian

The vault is plain Markdown with wiki-links, so it opens directly in
[Obsidian](https://obsidian.md): point a vault at `.vault/` and the feature tags and
document links render as a navigable graph network, while every document's frontmatter -
tags, dates, and `related:` wiki-links - shows up as first-class properties.

<p align="center">
<img src="docs/assets/obsidian-vault.png" alt="A vaultspec vault opened in Obsidian - the document corpus as a graph network on the left, an accepted ADR with its tags, dates, and related wiki-links on the right" width="880" />
</p>

A vaultspec project's vault in Obsidian: the whole document corpus as a graph, and an
accepted ADR open beside it with its tags and related records one click away.

## A vault that audits itself

Structure only helps if it holds. `vaultspec-core vault check` runs a battery of
validators over the corpus - frontmatter, tags, links, dangling references, leftover
placeholders, plan schema, encoding - and every finding ships with a fix hint, with
`--fix` applying the safe ones automatically:

<p align="center">
<img src="docs/assets/term-check.svg" alt="vaultspec-core vault check all - validators with fix hints" width="880" />
</p>

## Ask your history questions

A vault is only as useful as its recall. The optional sister project
[vaultspec-rag](https://github.com/nevenincs/vaultspec-rag) indexes both the vault and
the codebase for hybrid semantic search, so agents (and you) can ask *why* something was
decided and get the decision record back:

<p align="center">
<img src="docs/assets/term-rag.svg" alt="vaultspec-rag search - semantic recall of a decision record" width="880" />
</p>

## MCP server

vaultspec-core ships a Model Context Protocol server, and `vaultspec-core install` drops
its `.mcp.json` by default. Seven tools cover the everyday surface - `find`, `create`,
`edit`, `status`, `check`, `plan_progress`, `plan_edit` - and a `discover`/`invoke`
gateway reaches the rest of the CLI. Where the server is connected, the synced rules
treat it as the primary transport, falling back to CLI verbs for structural and sync
operations. The launch command in `.mcp.json` follows the install mode - `uvx` in tool
mode, `uv run` in dependency mode. See the [MCP reference](./docs/MCP.md) for setup and
the tool catalog.

## The vaultspec family

| Project                                                                 | Role                                                                      | Maturity |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------- |
| vaultspec-core                                                          | The agent harness: the pipeline, the vault, and the CLI that drives them. | Beta     |
| [vaultspec-rag](https://github.com/nevenincs/vaultspec-rag)             | The semantic search component for vault and code.                         | Beta     |
| [vaultspec-dashboard](https://github.com/nevenincs/vaultspec-dashboard) | The application that runs it all as a UI.                                 | Beta     |
| [vaultspec-a2a](https://github.com/nevenincs/vaultspec-a2a)             | Headless agent-to-agent orchestration.                                    | Beta     |

## Learn more

| Guide                                   | What it covers                                              |
| --------------------------------------- | ----------------------------------------------------------- |
| [Framework manual](./docs/framework.md) | The development workflow, skills, agents, and customization |
| [CLI reference](./docs/CLI.md)          | Every command, flag, and option for vaultspec-core          |
| [MCP reference](./docs/MCP.md)          | The MCP server tools, setup, and configuration              |

## Release pipeline

Releases follow [release-please](https://github.com/googleapis/release-please): merging
conventional commits (`feat:`, `fix:`, `feat!:`) to `main` keeps an open Release PR with
the next version and changelog in sync. Merging that PR creates a GitHub Release and
tag, which triggers `release-please.yml` to dispatch the `publish.yml` workflow for that
tag. `publish.yml` builds the package, runs smoke tests against the built wheel and
sdist, and publishes to PyPI over OIDC trusted publishing - no long-lived PyPI token is
stored in the repo.

## Status, help, and license

vaultspec-core is in Beta and actively developed. The version badge shows the current
release. File bugs and questions on the
[issue tracker](https://github.com/nevenincs/vaultspec-core/issues). Bug reports,
feature ideas, and pull requests are welcome. vaultspec-core is released under the
[MIT License](./LICENSE).
