vaultspec-core

Use the command lineLink to Use the command line

Run commands from your repository root. Use the command prefix for your installation with the commands shown here.

This page covers the operations you run yourself. To run a complete feature through your coding agent, follow the feature workflow.

Check progressLink to Check progress

Run status for a read-only overview of in-flight plans, completion, next open steps, and recent changes:

vaultspec-core status

If a feature has a plan, narrow the report to its tag. Replace notes-search with your feature’s tag:

vaultspec-core status notes-search

The report links execution evidence; it does not prove the implementation is correct. See the status reference for output details and workspace verification for checks.

Create documentsLink to Create documents

Create a research document. Replace payment-retries with your feature tag and "Payment retry options" with your title:

vaultspec-core vault add research --feature payment-retries --title "Payment retry options"

Next action:
  Define an Architecture Decision Record (ADR) for your research
    vaultspec-core vault add adr --feature payment-retries --related 2026-09-05-payment-retries-research
Created: .vault/research/2026-09-05-payment-retries-research.md

Captured on 0.1.73. The Created path is absolute in the real output and shortened here. Supplying --title is what keeps the run quiet: without it the scaffolder reports WARNING Potential unhydrated placeholder found in template: {topic} as it writes.

The command assigns the filename, frontmatter, and tags. Open the file named in Created and write its body using the research guidance.

Complete the research before running the command under Next action. That command creates an architecture decision record (ADR) linked to your research file.

To create another research document for the same feature, add --topic backoff. See the creation reference for other document types and options, and document syntax for fields maintained by the CLI.

Edit a planLink to Edit a plan

Start with an existing plan in .vault/plan/ with tier: L2. For other tiers, restructuring, or removal, see the plan command reference. That reference writes the plan argument the other way round, as a full .vault/plan/...md path after the flags rather than a stem before them. Both resolve, and so does a stem after the flags: measured on one plan on 0.1.73, all three added a Step. It is house style between a page written here and a page copied from the harness, not two different commands.

Replace PLAN in each command with your plan’s filename without .md. Adapt the example titles and actions to your work.

Add a phase:

vaultspec-core vault plan phase add PLAN --title "Retry the capture" --intent "Retry failed captures with exponential backoff."

Use the returned phase ID in place of P01. Replace src/billing/retry.py with the file path the step affects, then add the step:

vaultspec-core vault plan step add PLAN --phase P01 --action "Retry a failed capture with exponential backoff" --scope "src/billing/retry.py"

After completing the work and verification, mark the step complete. Replace P01.S01 with the returned step ID:

Usage synopsis
```
vaultspec-core vault plan step check PLAN P01.S01
```
This command marks the checkbox; it doesn’t run tests.

Reach a tier above L2Link to Reach a tier above L2

L1 is Steps. L2 adds Phases, L3 adds Waves above them, and L4 adds an Epic frame above those. The tier is a frontmatter field, tier: L4, and the containers it requires have to be present or the plan fails its own check.

There is one route to a plan above L2, and it is not the obvious one. Scaffolding straight at the tier you want leaves a plan you cannot edit. L1 is the only tier whose scaffold passes its own check on the day it is written; at L2 the fresh document is already short a Phase, and the walkthrough above only hides it by adding one in the next command:

vaultspec-core vault add plan --feature search-api --tier L4 --related 2026-09-05-search-api-adr
vaultspec-core vault plan check 2026-09-05-search-api-plan

[error] PLAN010 line 0: L4 plan must contain an Epic intent block
  fix (manual): Reconcile the 'tier:' frontmatter field with the document's heading structure per the convention ADR's tier-driven structure rules.
[error] PLAN010 line 0: L4 plan must contain at least one Wave heading
  fix (manual): Reconcile the 'tier:' frontmatter field with the document's heading structure per the convention ADR's tier-driven structure rules.

The scaffold succeeds and the plan it wrote is invalid, at the moment it is written: the tier in the frontmatter promises containers the document does not have. Both missing containers are named on that first run, so the requirements are not withheld from you. What the check will not do is create them, and adding them by hand clears that list one entry at a time. The Wave is allowed - Added Wave W01 - and the Epic intent the same run already named is still outstanding:

vaultspec-core vault plan wave add --title "Index the corpus" --intent "Get documents into a searchable store." 2026-09-05-search-api-plan
vaultspec-core vault plan check 2026-09-05-search-api-plan

[error] PLAN010 line 0: L4 plan must contain an Epic intent block
  fix (manual): Reconcile the 'tier:' frontmatter field with the document's heading structure per the convention ADR's tier-driven structure rules.

Filling a tier’s containers by hand is not a route, it is doing one container at a time what a single verb does in one call.

Build at L2 and promote. Promotion is the verb that creates the containers, so it asks for their titles rather than writing placeholders: run it without them and it names exactly which are missing - Cannot promote L2 -> L4 without the following flag(s): --wave-title, --wave-intent, and it adds that “the CLI does not write TODO placeholders into plan documents”.

It asks only for the containers it has to create, which is worth knowing before you read the reference. Its promotion example passes --epic-intent and nothing else, and that is correct for the plan it is written against: promoting an L3 to L4 adds the Epic frame over a Wave that already exists, so there is no Wave to name. The same command from L2 has to create the Wave as well, and refuses until you name it. Read the flags as a function of the distance you are moving rather than of the tier you are moving to.

vaultspec-core vault plan tier promote --target L4 --epic-intent "Ship full-text search across the API, tracked as EPIC-412." --wave-title "Index the corpus" --wave-intent "Get documents into a searchable store." 2026-09-05-search-api-plan

Tier promoted to L4. (Preserved 3 unknown blocks)

That plan passes vault plan check with exit 0, and what it wrote is:

## Epic intent

Ship full-text search across the API, tracked as EPIC-412.

## Wave `W01` - Index the corpus

Get documents into a searchable store.

### Phase `W01.P01` - Tokenizer

Choose and wire the tokenizer.

- [ ] `W01.P01.S01` - Wire the tokenizer into the index writer; `src/search/index.py`.

The Epic intent is a section, not a frontmatter field, and it is where an external tracker reference belongs. Each container carries its intent as the paragraph under its heading. And the identifiers lengthen as the tiers nest: the Step that was S01 at L1 is W01.P01.S01 here, because a Step is addressed by its whole path once there is more than one container above it.

Demotion is the same verb backwards, and it is worth running once before you need it. It removes the containers above the target tier and reports what it kept:

vaultspec-core vault plan tier demote --target L2 2026-09-05-search-api-plan
vaultspec-core vault plan check 2026-09-05-search-api-plan

Tier demoted to L2. (Preserved 3 unknown blocks)
[error] PLAN010 line 0: L2 plan must contain at least one Phase heading
  fix (manual): Reconcile the 'tier:' frontmatter field with the document's heading structure per the convention ADR's tier-driven structure rules.

The demote succeeds with exit 0 and leaves the plan failing its own check with exit 1. That is the same asymmetry as the scaffold: these verbs move the tier and strip what sits above it, and neither one writes the containers the tier you land on requires. Promotion is the exception, and only because it refuses to run until you have named them. After a demotion, add the Phase yourself.

Keep it healthyLink to Keep it healthy

Check the records after editing them:

vaultspec-core vault check all

Follow the verification guide to interpret exit codes, apply supported repairs, and review the changes before committing. Use the CI examples to check records automatically.

One thing about the summary line is worth knowing before you try to reconcile it: the three numbers do not subtract. Here is one vault, checked, repaired, and checked again, showing only the last line of each report:

  Total: 6 errors, 36 warnings
  Total: 6 errors, 27 warnings, 19 fixed
  Total: 6 errors, 27 warnings

Thirty-six warnings, nineteen fixed, twenty-seven left. fixed counts the repairs applied; the warning count beside it is a fresh count taken afterwards, against a corpus those repairs have already changed. Repairing one thing can settle a check that was never counted and unsettle one that was, so the middle line is a new reading rather than the first line minus the repairs. The third line confirms it by agreeing with the second. Compare runs, not arithmetic.

Rename a feature without breaking its trailLink to Rename a feature without breaking its trail

A feature tag is in the filename of every document that carries it, in the frontmatter of each one, and in the related: links between them. Renaming it by hand means editing all three in step, and the check that would catch a miss runs after the damage. One verb does the whole set.

Preview it first. This is the one place the preview earns its keep, because it tells you the size of what you are about to do:

vaultspec-core vault feature rename payment-retries capture-retries --dry-run

Dry-run: Previewing feature rename 'payment-retries' -> 'capture-retries'
Planned renames (3 documents):
  .vault/adr/2026-09-04-payment-retries-adr.md  ->  .vault/adr/2026-09-04-capture-retries-adr.md
  .vault/plan/2026-09-04-payment-retries-plan.md  ->  .vault/plan/2026-09-04-capture-retries-plan.md
  .vault/research/2026-09-04-payment-retries-research.md  ->  .vault/research/2026-09-04-capture-retries-research.md
Predicted: 3 tag rewrite(s), 2 related-link rewrite(s)
No incoming cross-feature links found.

The last two lines are the ones to read. tag rewrite(s) and related-link rewrite(s) are the edits inside the files, which are the part a by-hand rename forgets, and the cross-feature line says whether any other feature points at this one. Drop the flag to apply:

vaultspec-core vault feature rename payment-retries capture-retries

Next action:
  Verify your vault is completely clean after renaming the feature
    vaultspec-core vault check all
Renamed 3 documents 'payment-retries' -> 'capture-retries'.
  .vault/adr/2026-09-04-payment-retries-adr.md  ->  .vault/adr/2026-09-04-capture-retries-adr.md
  .vault/plan/2026-09-04-payment-retries-plan.md  ->  .vault/plan/2026-09-04-capture-retries-plan.md
  .vault/research/2026-09-04-payment-retries-research.md  ->  .vault/research/2026-09-04-capture-retries-research.md
3 tag rewrite(s), 2 related-link rewrite(s)

It exits 0 and the counts match the preview, which is what you are checking.

Body prose is not rewritten, and that reaches further than the reference’s wording suggests, because a document’s title is body prose. The research file above still carries payment-retries in its own heading afterwards. The trail is intact and every heading is stale, which is the half of this operation you finish by hand. Nothing finds those mentions for you.

Paths above are written with /. That run was made on Windows, where the tool prints \.

Retire a feature without deleting itLink to Retire a feature without deleting it

A vault accumulates. Every feature you finish stays in feature list beside the ones you are working on, and the list is the inventory a later reader - or a later you - reads to find out what this project has decided. A finished feature that never leaves it makes that list worse the longer the project runs.

Archiving is the way out, and it is the only one that keeps the records. Start from what the list holds:

vaultspec-core vault feature list

  billing  1 docs  (research)  2026-09-05
  shipping  1 docs  (research)  2026-09-05

vaultspec-core vault feature archive billing

Next action:
  Verify your vault remains completely clean after archiving
    vaultspec-core vault check all
Archived 1 documents.
  .vault\_archive\research\2026-09-05-billing-research.md

The hint prints above the result rather than below it, which reads oddly and is what the tool does. The documents move to .vault/_archive/ rather than being removed, and the feature drops out of the list:

vaultspec-core vault feature list

  shipping  1 docs  (research)  2026-09-05

To undo it, unarchive the same tag. It reverses exactly, and this half prints no hint at all:

vaultspec-core vault feature unarchive billing

Unarchived 1 documents.
  .vault\research\2026-09-05-billing-research.md

Archiving is reversible and deleting is not, so reach for this first. It is also the only undo here: nothing restores a document the filesystem no longer has, and vault archive restore recovers only what was archived rather than removed. Captured on 0.1.73; that run was made on Windows, where the tool prints \.

Gate a pipeline on itLink to Gate a pipeline on it

Check out the repository and install vaultspec-core on PATH before running these steps. For the optional gates, install Bash and jq.

Run the vault checks as a pipeline step. Errors fail the step; warnings pass.

- name: Check the vault
  run: vaultspec-core vault check all

To reject code-boundary and modified-stamp findings, add this gate:

- name: Check source boundaries and record stamps
  shell: bash
  run: |
    set -euo pipefail
    for check in code-boundary modified-stamp; do
      vaultspec-core vault check "$check" --json |
        jq -e --arg check "$check" '
          .schema == ("vaultspec.vault.check." + $check + ".v2")
          and .status == "unchanged"
          and .data.diagnostics.total == 0'
    done

The gate checks the response schema and total findings, not one page of results. It deliberately rejects warnings. code-boundary is excluded from all; modified-stamp runs in all but reports advisory findings. A stamp mismatch flags a record for inspection; it doesn’t prove whether the record was approved. See the check reference for details.

To validate every plan, add:

- name: Check plan conventions
  shell: bash
  run: |
    set -euo pipefail
    shopt -s nullglob
    for plan in .vault/plan/*.md; do
      vaultspec-core vault plan check "$plan"
    done

When .vault/plan/ contains no Markdown files, this step skips cleanly.

Apply corrections locally, review the diff, and recheck. Keep --fix out of the pipeline so it checks the committed files.

Get JSON outputLink to Get JSON output

Request status as JSON:

vaultspec-core status --json

See the JSON output reference for response fields.

The --json flag is command-specific. Check a command’s --help output to see whether it supports JSON.

When a command refusesLink to When a command refuses

Five refusals cover most of what stops you, and each names its own way out.

vaultspec is already installed at ... comes from a second install in a project that has one. It names three ways forward - --upgrade to re-seed the bundled rules and skills, --force to overwrite, uninstall to start over - and exits 1.

error: L1 plans do not support Phase headings; promote first means the plan has no container above its Steps. Scaffold with --tier L2, or run vaultspec-core vault plan tier promote, which wants the new container’s title and intent as flags.

'vaultspec-core vault check orphans' has no auto-fix capabilities means the check rejects --fix. Run it without that flag and resolve the findings manually. See the check reference for supported fixes.

Step canonical identifier 'S02' appears 2 times in document order comes from vaultspec-core vault plan check, and it is the one thing a hand-edited plan can break that nothing repairs. Its fix is marked manual because the tool cannot know which row the execution records naming S02 were written against. vault check all does not run the plan conventions, so a duplicate survives a clean run of it.

For an unresolved related document, run vaultspec-core vault list and use the existing document’s filename or stem in --related.

Where to go nextLink to Where to go next

If you’d rather your agent called these operations directly than shelled out, read reaching Vaultspec from your agent.

Use the command line#Link to Use the command line

Check progress#Link to Check progress

Create documents#Link to Create documents

Edit a plan#Link to Edit a plan

Reach a tier above L2#Link to Reach a tier above L2

Keep it healthy#Link to Keep it healthy

Rename a feature without breaking its trail#Link to Rename a feature without breaking its trail

Retire a feature without deleting it#Link to Retire a feature without deleting it

Gate a pipeline on it#Link to Gate a pipeline on it

Get JSON output#Link to Get JSON output

When a command refuses#Link to When a command refuses

Where to go next#Link to Where to go next