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.
Install · Start a feature · Documentation
Install
Install uv, then run this from your repository root:
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.
Keep the uvx prefix when running commands yourself. For persistent or project-local
installation, see installation options.
Homebrew and Scoop 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:
uvx vaultspec-core status search-api
For planned work, ask the agent to resume the feature from its next open Step. The workflow guide explains how to choose a route, approve work, and continue across sessions.
Documentation
- Documentation index: choose a guide for your task.
- Framework manual: run the workflow and customize its rules.
- Document syntax: edit prose and manage document structure.
- Verifying a workspace: check the setup and repair errors.
- CLI reference and MCP reference: commands, tools, and configuration.
Open .vault/ in Obsidian to browse its linked documents. The
optional vaultspec-rag package adds
semantic search across the vault and your code.
Hosted vault search and ADR cross-referencing are optional. Set
VAULTSPEC_CORE_TYPESAFE_API_KEY in the environment, or import it by name with
vaultspec-core install --env VAULTSPEC_CORE_TYPESAFE_API_KEY (add --upgrade for an
existing installation; see
local provisioning) to enable:
vaultspec-core vault search(MCP:search): answers vault questions with a supporting passage.vaultspec-core vault adr crossref(MCP:crossref): suggests related ADRs and flags possible conflicts for the author to reconcile.
These calls send vault text to the TypeSafe API. Without a key, they send nothing and
name a discovery fallback: a vaultspec-rag vault search when the workspace provisions
vaultspec-rag, otherwise vaultspec-core vault list and grep. The workflow can continue
with that evidence. Code search is always vaultspec-rag's job.
Support and license
vaultspec-core is in beta. Report bugs, ask questions, or propose changes on the issue tracker. For contributions and releases, see maintainer documentation.
Released under the MIT License.
1 maintainer
Metadata
1 maintainer
Release files for vaultspec-core 0.3.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| vaultspec_core-0.3.2.tar.gz | 7.1 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| vaultspec_core-0.3.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 8.4 MB
Release files / vaultspec_core-0.3.2.tar.gz
| Download URL | vaultspec_core-0.3.2.tar.gz |
|---|---|
| Size | 7.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a0660233250f6f24671dd09fdd6971eea40a28c1d6589f293b4acc89ddf361fc
|
|
BLAKE2b-256 checksum How to use checksums |
a18d8165eeb39f67dd9ed9658a08727a9b1eb455b9522e63da11aad26a42dc5f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / vaultspec_core-0.3.2-py3-none-any.whl
| Download URL | vaultspec_core-0.3.2-py3-none-any.whl |
|---|---|
| Size | 1.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
61334376f2ea2ed724b47d7f4510be73341aaccb5699c402734930a0c1a002bf
|
|
BLAKE2b-256 checksum How to use checksums |
de80f38f810b5cd7a6440a2ca8e1d8d2b0fa754080db6911b3979d7bc68510cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
