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 is also optional. Set VAULTSPEC_CORE_TYPESAFE_API_KEY and
vaultspec-core vault search (MCP: search) answers questions about the vault with the
passage that answers them. Every search sends vault text to the TypeSafe API. Without a
key, everything else works. A vault search then names what to run instead: a
vaultspec-rag vault search when the workspace provisions vaultspec-rag, otherwise
vaultspec-core vault list and grep. Code search is always vaultspec-rag's job. See
vaultspec-core vault search.
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
Release files for vaultspec-core 0.2.6
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.2.6.tar.gz | 6.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| vaultspec_core-0.2.6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 8.2 MB
Release files / vaultspec_core-0.2.6.tar.gz
| Download URL | vaultspec_core-0.2.6.tar.gz |
|---|---|
| Size | 6.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a01e55408523ddf3bf9a609bbd1d0c34f60f04b687ceba43eedd5f70992e7ead
|
|
BLAKE2b-256 checksum How to use checksums |
a3f05c4adf0a740d4d07fb14b96b2c1006ab84b1bea9a6f2fbe3a0b14650842a
|
| 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.2.6-py3-none-any.whl
| Download URL | vaultspec_core-0.2.6-py3-none-any.whl |
|---|---|
| Size | 1.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a7f7e4e55b959d641fb968218f0de6fd61e7cd3adf79cc7114ee9be48f465afe
|
|
BLAKE2b-256 checksum How to use checksums |
54907620047686a7b04467b8471fe4274faff83e1a82b559693a29a61640d9d2
|
| 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}
|
