vaultspec-core 0.1.18

A governed development framework for AI-assisted engineering

vaultspec-core

---

A research and decision driven framework for your coding agents - with a paper trail

Vaultspec is a spec-driven development rulebook for your AI coders. It enforces a structured pipeline around AI-assisted development - research, decide, plan, execute, review - and provides tools to manage the document storage.

Each stage produces durable markdown artifacts in your repository that allow collaborating agents to share context and you to track development progress.

---

How it works

vaultspec-core structures AI-assisted development into a repeatable pipeline centered around features. Two directories form the backbone:

• .vaultspec/ holds the framework configuration - rules, templates, agent personas, and system prompts that shape how AI tools behave.
• .vault/ is the paper trail - research notes, architecture decision records (ADRs), implementation plans, execution logs, and review and audit trails.

Two entry points ship with the framework:

• vaultspec-core is the CLI that manages your workspace - installing, syncing, and validating framework resources. See the CLI reference for the full command surface.
• MCP server exposes vault discovery and document creation to MCP-capable clients like Claude Code. Invoked via uv run python -m vaultspec_core.mcp_server.app (a vaultspec-mcp console script is also installed but module invocation is preferred to avoid binary locking on Windows). See the MCP reference for setup and tool documentation.

The framework manual walks through the development workflow and explains how to customize rules, skills, agents, and system prompts.

---

Getting started

Prerequisites

• Python 3.13 or later
• uv - a fast Python package manager

Install from source

vaultspec-core is not yet published on PyPI. Install from the repository:

git clone https://github.com/wgergely/vaultspec-core.git
cd vaultspec-core
uv sync

vaultspec-core --version

Initialize a workspace

vaultspec-core install --target ./my-project

This scaffolds .vaultspec/ and .vault/ inside the target directory, seeds the builtin rules, agents, skills, and templates, syncs resources to provider config directories, and writes an .mcp.json for MCP-capable clients.

To install for a specific AI tool only:

vaultspec-core install claude --target ./my-project

After editing any framework files under .vaultspec/, re-sync to push changes to provider directories:

vaultspec-core sync

Start using it

Open your AI tool in the project directory. The install step synced rules, skills, and agent personas into each provider's config directory (.claude/, .gemini/, .agents/, .codex/) and wrote an .mcp.json for MCP-capable clients. Your AI tool will pick these up automatically.

The framework requires research and architectural decisions before coding begins. Just describe what you want to build in natural language:

"Research options for adding full-text search to the API"

The synced rules guide the AI to follow the pipeline - it will produce structured research findings in .vault/research/, then progress through architectural decisions, planning, execution, and review. Each stage writes records to .vault/ and references the output of earlier stages.

You can also invoke skills explicitly to start a specific stage. The bundled skills (vaultspec-research, vaultspec-adr, vaultspec-write, vaultspec-execute, vaultspec-code-review) read the relevant vault records and structure the AI's output accordingly.

The framework manual walks through each stage in detail with examples.

---

The development workflow

Every feature flows through five stages. The AI does the analytical work; you approve each checkpoint before the next stage starts.

Stage	You	The AI
Research	Review and approve the findings	Explores the problem, documents options
Decide	Approve the decision record	Drafts an ADR based on research
Plan	Review and approve the implementation plan	Breaks the decision into concrete steps
Execute	Stay available if the AI gets stuck	Works through each step autonomously
Review	Read the report and decide if the work ships	Audits the result, flags any issues

Everything produced - findings, ADRs, plans, execution records, and review reports - is saved in .vault/.

---

Working with the vault

The vault subcommand manages documents in .vault/. A few common operations:

# Scaffold a new document from a template

vaultspec-core vault add research --feature search-api

# List and inspect documents

vaultspec-core vault list --feature search-api
vaultspec-core vault stats --feature search-api

# Validate frontmatter, links, and cross-references (--fix to auto-repair)

vaultspec-core vault check all --fix

# Visualize the dependency graph for a feature

vaultspec-core vault graph --feature search-api

Valid document types: adr, audit, exec, plan, reference, research. Generated feature indexes live in .vault/index/ and are managed by vault feature index. See the CLI reference for the full command surface.

---

Schema migrations

When a release of vaultspec-core changes the on-disk shape of .vault/, the new layout is delivered through a versioned migration registry rather than a recurring pre-commit hook. Each registered migration runs once per upgrade and never again. Three triggers cover every consumer path:

• vaultspec-core install --upgrade runs every pending migration after re-seeding builtins.
• Any vault subcommand (e.g. vault add, vault feature index, vault check) lazily applies pending migrations before its primary action, so consumers who never run install --upgrade still observe the new layout.
• vaultspec-core migrations status and vaultspec-core migrations run give explicit control for operators who prefer manual application.

The registry compares each migration's target_version against the workspace manifest's vaultspec_version; entries whose target exceeds the manifest run in version order, then the manifest version is bumped on success. A migration that raises leaves the manifest version unchanged, so the next invocation re-attempts.

---

Further reading

Guide	What it covers
Framework manual	Development workflow, skills, and customization
CLI reference	All commands, flags, and options for vaultspec-core
MCP reference	MCP server tools, setup, and configuration

Getting help

Open an issue on GitHub.

---

Contributing and license

Contributions are welcome - bug reports, feature ideas, or pull requests. Browse what's in progress on GitHub Issues.

vaultspec-core is released under the MIT License.