What plans are in flight?
Check a feature’s plans, completed steps, and next open step before starting or resuming work.
Grounded, decision-based plans for long-horizon coding work
Vaultspec implements a managed workflow of steps. It works best when there's a feature to implement that requires research, consideration of architectural options, and an executable plan. The pipeline preserves its document trail as persistent records in the project's own .vault/ folder.
#feature
Gather evidence
.vault/research/Decide direction
Plan work
Track the steps
Verify code
Continue work from any provider
The research, decisions, and plan already live in your vault, so any agent can read them and continue the work. Every step leaves a paper trail, keeping context provider-agnostic.
› Can we implement a new calendar module displaying past release dates, with a month and year switcher and filters?Recording deferred.
› Can we implement a new calendar module displaying past release dates, with a month and year switcher and filters?Recording deferred.
› Can we implement a new calendar module displaying past release dates, with a month and year switcher and filters?Recording deferred.
Documents managed through templates, schemas, and tools for reading and writing
Vaultspec ships with the tools required to author, verify, organize, link, and edit the document graph. Because the documents are connected, every feature retains a history of execution records, decisions, and links to related features.
Is the vault healthy?
Check the vault for broken links, invalid metadata, and structural errors. Add --fix to apply supported automatic corrections.
Where is this implemented?
Find an implementation with a plain-language query. Use --type code to search code only.
vaultspec-core status search-index
$ vaultspec-core status search-indexRecording deferred.
Project rules, agents, and skills are seeded from a central source
Vaultspec ships with built-in rules you can customize, and lets you add project-specific skills and tools. Run vaultspec-core sync to update the files read by your configured coding agents.
Rules
3 rules
Set project-wide instructions for the workflow, document operations, and code discovery.
Skills
10 skills
Guide tasks such as research, decision recording, planning, implementation, and review. Helpers cover documentation, curation, and project management.
Agent personas
10 personas
Assign specialist roles for research, planning, implementation, and review, with separate executor tiers for different task complexity.
Loaded on start
vaultspec- Spec Skills
vaultspec-cli- Vaultspec Core CLI
vaultspec-discovery- Codebase and intent discovery
Invoked per task
vaultspec-adrpipeline- Capture an architectural decision as an ADR in .vault/adr/. Use after research, before planning, when a significant design choice and its trade-offs must be recorded.
vaultspec-code-researchpipeline- Ground a coding task in real source code, reference implementations, and library docs. Use before implementing a complex feature or when documentation is thin.
vaultspec-code-reviewpipeline- Run a formal code review for safety, intent, and quality. Use to verify completed work before marking it done.
vaultspec-executepipeline- Execute an approved implementation plan, dispatching agent personas per step. Use when a plan document is ready to build.
vaultspec-researchpipeline- Explore an unfamiliar problem and weigh options before committing. Use when unsure how to approach a complex feature, refactor, or bug.
vaultspec-writepipeline- Write an implementation plan of waves, phases, and steps. Use only after the authorizing ADR - or the cluster of ADRs a roll-up plan executes - is approved.
vaultspec-curatehelper- Reconcile the ADR architecture corpus against the codebase and the feature lifecycle documents against the single-home-fact boundary. Use to audit ADR status and supersession, find ADR-vs-ADR, ADR-vs-code, and document-vs-document conflicts (restated grounding, displaced decisions, forked facts), and action them. Mechanical .vault/ hygiene is the CLI's job; this skill does the semantic reconciliation the CLI cannot.
vaultspec-documentationhelper- Write one polished user-facing document through a structured pipeline. Use to create or rewrite a README, guide, or feature doc.
vaultspec-projectmanagerhelper- Coordinate GitHub Projects: triage issues, track milestones, provision worktrees, manage releases. Use for project management outside the pipeline.
vaultspec-teamhelper- Start a multi-agent coding team for a hard challenge. Use when a problem is too large for a single agent.
Dispatched per step
vaultspec-adr-researcherread-only- Research a problem and formalize the decision as an ADR. Use to turn open questions into an ADR.
vaultspec-code-reviewerread-only- Review code for safety, architectural intent, and quality. Use for final verification before done.
vaultspec-docs-curatorread-write- Reconcile the ADR architecture corpus against the codebase and the lifecycle documents against the single-home-fact boundary - status, supersession, conflicts, restated grounding, displaced decisions. Use to curate architecture decisions.
vaultspec-high-executorread-write- Implement complex, high-reasoning steps: core refactors, architecture, advanced features. Use for the hardest steps.
vaultspec-low-executorread-write- Implement clear-cut, low-risk steps: small edits, docs, simple logic. Use for routine steps.
vaultspec-project-coordinatorread-write- Coordinate GitHub Projects: issue triage, milestones, worktrees, releases. Use for project-management tasks.
vaultspec-reference-auditorread-only- Audit a codebase to produce a Reference of features, patterns, and best practices. Use to document how code works.
vaultspec-researcherread-only- Gather, analyze, and synthesize information on a question. Use for general research.
vaultspec-standard-executorread-write- Implement typical feature work and well-defined steps. Use for standard execution.
vaultspec-writerread-write- Digest research and ADRs into a grounded, auditable implementation plan. Use to author a plan.
Latest changes
Read from each project's published releases and changelog when this page was built.
Current release
0.2.4- Feature
firmwarecarry the code boundary to the surfaces that write code - Feature
mcpmake the gateway child cancellable and name the server executable after its package - Fix
cipoint the package managers at a release that exists - and 2 more
Current release
0.4.32- Fixmake a closed hardware gate name what is actually missing
Install Vaultspec
Install vaultspec-core to set up the harness in your repository. Add vaultspec-rag if you want semantic search over your code and documents.
vaultspec-core
BetaPython installs require CPython 3.13 or 3.14 on macOS, Linux, or Windows. With uv, a supported interpreter is downloaded if needed. Standalone binaries need no separate Python installation.
From PyPI, with uv or pip
Runs in a cached, isolated environment. Reuse the command prefix for later commands.
uvx vaultspec-core installInstalls the command on your PATH for repeated use.
uv tool install vaultspec-coreAdds a project dependency. Contributors install it with uv sync and run commands through uv run.
uv add vaultspec-coreuv run vaultspec-core installInstalls Core from PyPI without uv.
pip install vaultspec-coreWith Homebrew, on macOS and Linux
brew install nevenincs/tap/vaultspec-coreApple silicon macOS, and x86_64 and arm64 Linux.
With Scoop, on Windows
scoop bucket add nevenincs https://github.com/nevenincs/homebrew-tapscoop install nevenincs/vaultspec-coreStandalone binaries, no Python installation needed
| Platform | vaultspec-core |
|---|---|
| macOS · Apple silicon | vaultspec-core-v0.2.4-aarch64-apple-darwin.tar.gz |
| Linux · x86_64 | vaultspec-core-v0.2.4-x86_64-unknown-linux-gnu.tar.gz |
| Linux · arm64 | vaultspec-core-v0.2.4-aarch64-unknown-linux-gnu.tar.gz |
| Windows · x86_64 | vaultspec-core-v0.2.4-x86_64-pc-windows-msvc.zip |
Version 0.2.4, published with checksums. Each download is an archive: extract it, then run the vaultspec-core inside. See direct downloads.
Set up a repository & upgrade
Use the command prefix that matches your installation.
Run vaultspec-core install from your repository root to create the vault and configure your agents. For existing projects, follow the guides to join a project or upgrade Core.
vaultspec-rag
BetaSearch runs as a local service. You can use the harness without it.
Indexing and search require an NVIDIA GPU with CUDA on Linux or Windows, or Apple silicon with MPS. CPU-only and AMD inference are not supported.
From PyPI, with uv or pip
Runs in a cached, isolated environment. Reuse the command prefix for later commands.
uvx --from "vaultspec-rag[gpu]" vaultspec-rag installInstalls the command on your PATH for repeated use.
uv tool install --python 3.13 "vaultspec-rag[gpu,mcp]"For CUDA on Linux or Windows, check the GPU build. Then follow project setup on every platform.
Adds a project dependency. Contributors install it with uv sync and run commands through uv run.
uv add "vaultspec-rag[gpu]"uv run vaultspec-rag install --syncThe [gpu] extra is what lets it index and search.
With Homebrew, on macOS and Linux
brew install nevenincs/tap/vaultspec-ragx86_64 and arm64 Linux only. There is no macOS formula; on Apple silicon use a Python route.
With Scoop, on Windows
scoop bucket add nevenincs https://github.com/nevenincs/homebrew-tapscoop install nevenincs/vaultspec-ragStandalone binaries, no Python installation needed
| Platform | vaultspec-rag |
|---|---|
| macOS · Apple silicon | |
| Linux · x86_64 | vaultspec-rag-x86_64-unknown-linux-gnu |
| Linux · arm64 | vaultspec-rag-aarch64-unknown-linux-gnu |
| Windows · x86_64 | vaultspec-rag-x86_64-pc-windows-msvc.exe |
Version 0.4.24, published with checksums. The Python routes install 0.4.25. There is no macOS binary; on Apple silicon use a Python route.
After installation, start a feature with your coding agent.