vaultspec-core

Agent harness: the pipeline, the vault, and the CLI that drives them.

Get started · Product · Documentation · Family · Support

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.

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.

See the framework manual for the full tour.

[!TIP] The framework favours semantic search via the core's optional sister project, vaultspec-rag.

Getting started

1. Install

Every command below is run through uv, which is the one thing you need beforehand. It is not usually already present — a stock macOS machine has neither uv nor Homebrew, and its system Python is 3.9, below what this package supports.

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv fetches a supported interpreter itself, so you do not need to install Python separately. The supported range is whatever requires-python in pyproject.toml declares — currently 3.13 and 3.14.

Then, for the quickest project bootstrap, run from a git project folder:

uvx vaultspec-core install

Use it as a tool or dependency:

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

# Or a project dependency
uv add vaultspec-core

Or install the standalone binaries, which need no Python toolchain on the machine:

# Windows, via Scoop
scoop bucket add nevenincs https://github.com/nevenincs/homebrew-tap
scoop install vaultspec-core

# macOS and Linux, via Homebrew
brew tap nevenincs/tap https://github.com/nevenincs/homebrew-tap
brew install vaultspec-core

Both place vaultspec-core and vaultspec-mcp. The first launch of either bootstraps its pinned runtime and needs network once. Homebrew covers macOS on Apple Silicon and Linux on x86-64; Intel macOS and Linux arm64 are not built, and docs/channels.md says why.

The tap is the account root rather than this repository, so it is added once and carries every vaultspec product.

2. Bootstrap

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

uv run vaultspec-core install

See the CLI reference 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:

uv run vaultspec-core sync

[!TIP] Make sure to run

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 for how each one works.

Skills

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

Which skill, when

/vaultspec-rag-discovery drives the optional sister project and needs vaultspec-rag installed; the other ten ship with vaultspec-core.

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:

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.

# 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 covers that structure.

The vault, rendered in Obsidian

The vault is plain Markdown with wiki-links, so it opens directly in Obsidian: 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.

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:

Ask your history questions

A vault is only as useful as its recall. The optional sister project 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:

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 for setup and the tool catalog.

The vaultspec family

Learn more

Release pipeline

Releases follow 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. Bug reports, feature ideas, and pull requests are welcome. vaultspec-core is released under the MIT License.