vaultspec-core

Installing vaultspec-core

Before you begin

Install uv and your coding agent. Core supports CPython 3.13 and 3.14; uv downloads a supported interpreter if needed.

Run the project setup from your repository root. Git is not required to install, but committing the records and policy lets teammates share them.

Core 0.1.73 has an installer bug that skips ignore rules when .gitignore is missing. Create the file before you install:

Command

touch .gitignore

PowerShell has no touch; use New-Item -ItemType File .gitignore there.

Skipping this costs nothing visible. The install still succeeds, still exits 0, and still reports no problem - it simply writes no ignore rules at all, and the managed block below is absent rather than incomplete. With the empty file in place first, the same install writes it:

Captured output

# >>> vaultspec-managed (do not edit this block) >>>
.vault/.obsidian/
.vault/.trash/
.vault/data/
.vault/logs/
.vaultspec/*.lock
.vaultspec/_snapshots/
.vaultspec/mcp-ownership.json
.vaultspec/providers.json
/.agents/mcp_config.json.lock
/.codex/config.toml.lock
/.gitignore.lock
/.mcp.json.lock
/.pre-commit-config.yaml.lock
# <<< vaultspec-managed <<<

0.1.73 is the version the command below resolves to: 0.1.73 is what PyPI serves as current, and what a fresh install reports back under verify the install. The fix is on main, so this applies until the next release rather than to some older one you might already have.

Core does not require a GPU. The search package has separate hardware requirements.

Install

1. From your repository root, install the command-line tool:

   Command

   uv tool install vaultspec-core
   

2. Configure the current project for all supported coding agents:

   Command

   vaultspec-core install
   

3. Verify the installation.

For other installation options, see distribution channels and command prefixes.

Recorded run: uvx vaultspec-core install Recorded project setup with uvx vaultspec-core install. This route does not add Core to PATH. The capture is abridged where the replay shows an ellipsis.

Text of this recording

my-app on main
❯ uvx vaultspec-core install

Installed vaultspec
  Target Y:\code\my-app
  Synced 3 rules, 10 skills, 10 agents
  Enabled claude, gemini, antigravity, codex
  Installed MCP server
  …

Next action:
  Framework installed. Start research on your first feature
    vaultspec-core vault add research --feature {feature_tag}
my-app on main
❯

How you run it afterwards

After a tool installation or standalone download, use the command on your PATH:

Command

vaultspec-core status

When running Core through uvx, keep that prefix on every command:

Command

uvx vaultspec-core status

For a project dependency, add Core to the project and use uv run:

Command

uv add vaultspec-core
uv run vaultspec-core status

For development-only dependencies, see provisioning modes.

If your shell cannot find vaultspec-core, check the prefix: uvx does not add the command to PATH. For a tool installation, follow uv’s PATH instructions if it reports that the executable directory is missing from PATH.

What it writes

The installer creates records directories, project policy, and coding-agent configuration:

File listing

.vault/          the records: research, adr, plan, exec, audit, reference, index
.vaultspec/      the harness: rules, skills, agents, system, hooks, mcps,
                 templates, reference
.claude/ .gemini/ .codex/ .agents/    generated per-provider configuration
CLAUDE.md AGENTS.md GEMINI.md         the file each agent reads on startup
.mcp.json        the MCP server declaration
.pre-commit-config.yaml               vault checks, for pre-commit to wire
.gitattributes   a managed block pinning line endings
.gitignore       a managed block for runtime-state ignore rules

.vault/ starts empty apart from its subdirectories. It fills as you work.

Commit .vaultspec/workspace.json with the project policy so teammates share the provisioning mode. Keep machine-local ownership records, locks, and snapshots untracked; see ignored runtime files.

Agent configuration

Coding agent	Skill instructions	Agent definitions	System guidance
Claude Code	.claude/skills/	.claude/agents/	.claude/rules/vaultspec-system.builtin.md
Codex	Folded into .codex/config.toml	.codex/config.toml	.codex/rules/vaultspec-system.builtin.md
Gemini CLI	Folded into .gemini/SYSTEM.md	.gemini/agents/	.gemini/SYSTEM.md
Antigravity	.agents/skills/	Not generated	No dedicated output

The first column is the one that decides whether you have anything to type. Measured on a fresh install of 0.1.73: ten skill directories under .claude/skills/ and ten under .agents/skills/, and no skills directory for either of the other two. .agents/ is Antigravity’s, and nothing the install writes points Codex or Gemini at it - searched for .agents across .codex/, .gemini/, AGENTS.md and GEMINI.md, and it does not appear. What those two get instead is the same instruction set folded into files they already read, so their stages are driven from the command line rather than invoked by name.

To edit .vaultspec/ sources and sync your changes, see customize project policy.

Choose a provisioning mode

The mode controls how generated project commands launch core. Leave --mode unset to reuse the saved mode, or detect it from pyproject.toml on a new installation.

• tool is the default. Commands launch through uvx; core is not a project dependency.

• dev uses core from the default development dependency group. Contributors get it through uv sync, and generated commands use the project environment.

• dependency uses core as a runtime dependency. Choose this only when your package calls core at runtime; it becomes a dependency of your published package.

The mode does not add the package to pyproject.toml. For a development dependency, run uv add --dev vaultspec-core, then configure the harness:

Command

vaultspec-core install --mode dev

The tool mode is separate from uv tool install, which installs the command for your shell. See command prefixes.

Install for one agent only

The installer configures every provider it supports. To configure one, name it:

Command

vaultspec-core install claude

Valid providers are all, core, claude, gemini, antigravity, and codex. core writes the framework without configuring any agent, which is what you want if you drive the pipeline entirely from the command line.

To keep everything except one piece, skip it instead. --skip is repeatable and takes a provider name, core, mcp, or precommit:

Command

vaultspec-core install --skip precommit

Preview before writing

Preview the affected paths without changing the project:

Command

vaultspec-core install --dry-run

Review the paths before installing into a project with existing agent configuration. The preview’s unchanged marker does not guarantee that a modified bundled file will retain its contents.

For an existing installation, follow the upgrade steps. install --force restores bundled files and can replace your edits to them; commit your changes first. User-added rules survive.

Force a sync

Force sync prunes stale generated files and can overwrite provider configuration, including custom MCP launch settings. Review your changes before running it:

Command

vaultspec-core sync --force

This removes generated copies of deleted source rules. Unmanaged files in provider directories are not pruned. See the sync reference for options.

Do not rely on ordinary syncs to preserve a hand-edited MCP entry indefinitely. See MCP ownership and read-only settings before changing its launch arguments.

Ignored runtime files

The managed block in .gitignore excludes runtime state such as .vault/data/, caches, and lock files. Keep your feature records and project policy in Git.

Ignore rules do not untrack files that were already committed. Check whether runtime data is tracked:

Command

git ls-files -- .vault/data

If that command lists files, remove them from Git’s index while leaving them on disk:

Command

git rm -r --cached -- .vault/data

Review and commit the staged removals. If the listing is empty, no cleanup is needed.

Verify the install

Check the installed CLI version, workspace configuration, and vault validation:

Command

vaultspec-core --version
vaultspec-core doctor

Captured output

0.1.73
workspace diagnosis
  framework ok .vaultspec/ present
  claude ok dir: complete
  gemini ok dir: complete
  antigravity ok dir: complete
  codex ok dir: complete
  builtins ok current
  gitignore ok complete
  gitattributes ok complete
  mcp ok .mcp.json present
  migration ok all registered migrations applied
  vault content ok no generated template annotations
  precommit ok all hooks present
  rename integrity ok all rules, skills, and agents names are consistent
  install mode (vaultspec-core) ok declared tool; artifacts match
  semantic search none vaultspec-rag not provisioned; core discovery and find cover document lookup without it

Vault Check - All
  ok structure: clean
  ok frontmatter: clean
  ok annotations: clean
  ok encoding: clean

Captured on a fresh install of 0.1.73 into an empty repository, exit 0. Read it down the verdict column - ok, warn or none - rather than reading every row.

Two abridgements. The process registry row is omitted, because it reports machine-global records left by other projects and says nothing about this workspace. The vault check runs nineteen entries where four are shown, and all nineteen read clean on a vault with no documents in it yet.

Compare your version with published releases. Address reported problems and rerun vaultspec-core doctor. See workspace and vault verification for check details and exit codes.

semantic search none means RAG is not provisioned for this workspace; Core works without it. To add search, follow the RAG installation guide.

To run vault checks when you commit, activate the Git hooks. Installing hook configuration alone does not enable Git to run it.

Upgrade

Commit your project changes first. Refreshing bundled content replaces edits to bundled files while preserving user-added rules.

If you installed Core with uv tool install, upgrade the CLI:

Command

uv tool upgrade vaultspec-core

uv respects any version constraints set at installation. After updating Core, refresh the project’s bundled content from its root:

Command

vaultspec-core install --upgrade

Inspect migration status without changing the project:

Command

vaultspec-core migrations status

If migrations are pending, apply them:

Command

vaultspec-core migrations run

Review the changed files before committing. See the migration reference for options and exit codes.

Uninstall

Uninstall removes .vaultspec/, provider directories, and generated configuration. It preserves .vault/ unless you add --remove-vault; back up your feature records before using that option.

Preview the affected paths without removing anything:

Command

vaultspec-core uninstall --dry-run

Review the list and save any configuration you need. Then confirm removal:

Command

vaultspec-core uninstall --force

For permanent removal, review the remaining vaultspec blocks in .gitignore and .gitattributes. Remove them if you no longer need their rules. After all vaultspec processes have stopped, remove leftover .gitignore.lock, .mcp.json.lock, and .pre-commit-config.yaml.lock files. Leave these files and blocks in place if you plan to reinstall.

Joining a project that already has it

Clone the repository and install the CLI using the project’s installation route. From the clone’s root, create your local provider configuration from the shared .vaultspec/ policy:

Command

vaultspec-core install

Use plain install for a fresh clone, not --upgrade or --force. The installer establishes local manifest state from the existing policy. A second install reports already installed; see upgrading when updating an existing installation.

Git hooks do not travel with a clone. Activate the commit checks locally. If the project uses search, set up your own index. Then run vaultspec-core status to find the team’s in-flight work:

Command

vaultspec-core status

Captured output

Vault Status

Plans in flight  (at least one open step)
  2026-09-06-payment-retries-plan   L2   -   P0/1   0/1 steps   0%   next P01.S01      2026-09-06

Recent changes
  adr
    2026-09-06-payment-retries-adr  2026-09-06
  plan
    2026-09-06-payment-retries-plan  2026-09-06
  research
    2026-09-06-payment-retries-research  2026-09-06

Active features
  payment-retries  3 docs plan  L2 0/1 0%  2026-09-06

Discovery
  vaultspec-rag not provisioned - use find and grep for discovery

Totals
  Total documents: 3
  Total features:  1

Plans in flight is the answer to what anyone is working on: one row per plan that still has an open Step, carrying its tier, how far through its Phases and Steps it is, and the identifier of the next Step to pick up. A clone with nothing started prints none there and the rest of the report unchanged, so an empty first section means the vault is idle rather than unreadable.

Discovery reports whether the search component is available in this project; the line above is what it prints when only Core is installed.

Where to go next

• Run a feature with your coding agent.

• Drive the vault from the command line.

• Look up document types and workflow concepts.