Run the Vaultspec workflowLink to Run the Vaultspec workflow
Start from a configured project, then describe your task to the coding agent. You don’t need to create a complete set of documents before work begins. This guide covers choosing the route, authorizing work, and continuing it across sessions.
Commands here use vaultspec-core; keep the uvx or uv run prefix if that is how you
installed it.
Choose the route for your taskLink to Choose the route for your task
Describe the outcome and use a feature tag to group its records, as in the README example. The agent assesses two separate needs:
Decision coverage: does the work depend on a costly-to-reverse choice? Reuse an accepted architecture decision record (ADR), or gather evidence and propose a new or amended decision.
Planning: does scope or progress need to survive sessions or handoff? If so, write a plan; otherwise work directly.
A typo fix can proceed directly. A multi-session cleanup within settled design choices can need a plan but no new ADR. Changing a persisted data format needs a decision even if the implementation is short. File count alone does not determine the route.
Search for existing decisions across features, not only under the current tag, and list the ADRs as well: a search can miss a lower-ranked record. Reuse applicable evidence and accepted ADRs instead of creating equivalent records. See Find a feature’s documents for the search routes.
Workflow stagesLink to Workflow stages
Use these skills when you want to request a particular part of the workflow:
Need |
Skill |
Record |
|---|---|---|
Weigh options using evidence |
|
Research: findings and sources |
Understand how real code works |
|
Reference: implementation patterns |
Record a costly decision |
|
ADR: the choice, rationale, and consequences |
Preserve scope and work order |
|
Plan: cohesive, verifiable Steps |
Carry out an approved plan |
|
Ledger: changed files and verification per Step |
Review planned work |
|
Audit: findings and their resolutions |
These are skill names for your agent, not shell commands. Research, code References, and Audit findings can supply decision evidence; you don’t need all three. Each record has one job. Keep evidence in its source record and link to it rather than copying it into decisions and plans.
Orient: see what is in flightLink to Orient: see what is in flight
From your repository, check current plan progress, next open steps, and recent changes:
Command
vaultspec-core status
Once a feature has a plan, use its feature tag to trace its plans, steps, and recorded
execution evidence. Replace search-api with your feature tag:
Command
vaultspec-core status search-api
To narrow the view to one plan, supply its stem or path instead.
The > marker identifies the next open step. If an open step shows no rows, it lacks
recorded execution evidence; that doesn’t prove no work occurred.
See the status reference for output details and options.
Approve the scope, not every editLink to Approve the scope, not every edit
Approve new or changed decisions before implementation relies on them, and approve a plan before its Steps execute. Review the proposed scope and choices, not only the document’s status label.
Explicit prior authorization can cover later work within that scope. The agent records its basis and proceeds with ordinary implementation details and in-scope corrections. Material scope changes, uncovered costly decisions, and actions needing new external authority require your input. Not every correction needs another approval turn.
Find a feature’s documentsLink to Find a feature’s documents
List a feature’s records:
Command
vaultspec-core vault list --feature search-api
See the list reference for type filters and pagination.
To ask the vault a question, use vaultspec-core vault search (MCP: search). It
returns the passage that answers, with its line range, and says when nothing in the
vault answers. It needs a TypeSafe key in VAULTSPEC_CORE_TYPESAFE_API_KEY and sends
vault text to the TypeSafe API:
Command
vaultspec-core vault search "why do pages use opaque cursors" --feature search-api
When no key is set, or the hosted service fails, the reply returns no partial results
and names the next step instead: a vaultspec-rag vault search over the requested record
types when the workspace provisions RAG, otherwise vaultspec-core vault list (MCP:
find) and grep over .vault/. Listing, the feature
graph, and grep always work. See the
vaultspec-core vault search reference and the
search tool for the reply fields.
To search code with semantic retrieval, install RAG and index your project first. RAG is a separate package; Core doesn’t install it. Hosted vault search doesn’t search code.
Command
vaultspec-rag search "full-text ranking and tokenizer" --type code
Find and amend an ADRLink to Find and amend an ADR
List the current feature’s ADRs with:
Command
vaultspec-core vault list adr --feature search-api
Omit --feature to inspect decisions recorded elsewhere in the project.
Reuse an accepted ADR when it already covers the decision. Extend a section or amend that record for refinements, narrower scope, or parameter changes; create a separate ADR for a distinct costly decision. For prose edits, follow editing safely. Keep the accepted content intact while presenting a proposed amendment separately; apply it after approval.
If the direction reverses or the rationale no longer applies, create a replacement ADR. The replacement must be accepted before superseding the old ADR.
The ADR author proposes any necessary edits to conflicting older wording alongside the decision. Links alone do not reconcile contradictory rulings. Keep enough context to explain the decision and cite detailed evidence in its source record. Research gathers evidence; the ADR records the resulting commitment.
With VAULTSPEC_CORE_TYPESAFE_API_KEY configured, the author uses
crossref on the populated draft and reads
the relevant full records before presenting it. Proposed amendments use --body-file
(MCP: body) without replacing accepted text. Reuse judgments while the draft and
relevant corpus remain unchanged. Results are advisory and report bounded coverage; they
do not certify the absence of conflict. Without a key, use local discovery; a service
failure names a fallback and does not block authoring.
Acceptance establishes the decision’s authority, not implementation completion. Implementation hypotheses can adapt within its binding commitments. If evidence invalidates a commitment or its rationale, propose an authorized revision; code divergence alone does not rewrite the ruling.
Superseding doesn’t revise plans or retarget their authorizing links. Review affected active plans and links, revise them where necessary, and establish decision coverage before continuing implementation. Completed plans retain their historical links; reopening work requires reassessment.
Make a planLink to Make a plan
When the work needs durable sequencing, ask for a plan:
Use vaultspec-write to plan the search-api work. Reuse applicable decisions and keep the plan to a few major, verifiable Steps.
Before approving the plan, review its scope, work order, affected files, and verification steps. If it doesn’t match the approved scope, ask for revisions before execution.
A Step describes a cohesive change, which may span several files. Start with a flat L1 plan; add Phases, Waves, or an Epic only when those groups help coordinate the work. Link governing ADRs and inherit their evidence through those links. If none governs, record why no costly decision is involved in the plan’s Description.
For parallel work, name each worker’s assignment and keep write ownership separate. Sharing a working tree requires coordination of shared metadata and commits. More workers do not, by themselves, require a higher plan tier.
For the plan’s structure and Step syntax, see tiers and row format.
Change a plan safelyLink to Change a plan safely
Use vaultspec-core vault plan to add, move, or remove Steps and their containers. Keep
structural edits out of your text editor.
Before reorganizing existing work, review the identifier rules. See plan commands for arguments and examples.
Execute a planLink to Execute a plan
After approving the plan, ask your agent to use vaultspec-execute. It starts from the
next open Step. For each Step, it implements, runs relevant tests and checks, logs the
changed files and verification results, marks the Step complete, and commits.
Before adding code, the agent checks for an existing implementation it can reuse and follows the project’s typing, lint, formatting, and style conventions. Verification covers the changed behavior and affected interfaces. Successful checks are repeated when changes, failures, or unresolved concerns justify another run; Step completion does not require a separate formal review. Workers verify their assigned scope, while the orchestrator coordinates shared checks and integrated review.
Give shared or expensive checks one owner and pass their status and results to reviewers. The review guide explains evidence reuse and incomplete verification.
To resume interrupted work, ask the agent to continue or specify a Step. Use status to check progress and the next open Step.
If a closed Step is incomplete, reopen it with vaultspec-core vault plan step uncheck
and keep its execution records. See the
plan commands for arguments and other state changes.
Review the resultLink to Review the result
Ask your agent to use vaultspec-code-review to compare the implementation with the
plan and any governing decisions. Review the integrated result, not individual files as
separate approval gates. The review guide covers when review is due,
how findings are recorded, and how fixes are verified.
Check records and project healthLink to Check records and project health
Use the verification guide to check installation, validate records, and review repairs. These checks validate the workspace and records; they don’t replace implementation tests or review.
To inspect a feature’s document links, replace search-api with its feature tag:
Command
vaultspec-core vault graph --feature search-api
See the graph reference for filtering and output options.
Curate an existing vaultLink to Curate an existing vault
Ask for vaultspec-curate to review an existing feature, decision cluster, or corpus.
This is user-started maintenance, independent of the implementation pipeline. Specify
review-only work when you want findings without repairs to the reviewed records.
The curator compares decisions, relevant code, and supporting evidence. It applies authorized, content-preserving repairs and records unresolved choices in a reconciliation audit. Historical recommendations remain evidence even when a later decision chose another option. Implementation gaps do not automatically change accepted authority.
With TypeSafe configured, a bounded cross-reference batch helps select relevant pairs. The audit distinguishes records inventoried, model-scored, and actually reviewed, and records incomplete coverage and continuation. Verification follows the affected scope; unrelated vault warnings do not require an open-ended cleanup before the audit finishes.
Coordinate several active workstreamsLink to Coordinate several active workstreams
Ask for vaultspec-projectmanager when you need a roadmap, cross-worktree triage,
coordination of an epic and its project board, or a developer workday across several
in-flight features. Routine branch comparisons, worktree operations, and single-PR tasks
use the ordinary tools directly.
The coordinator gathers relevant local and remote state, connects dependencies and ownership, and recommends an actionable sequence. Each assignment identifies its outcome, owner, target, prerequisites, and completion evidence. It updates the context affected by completed actions and preserves a compact handoff. GitHub access is needed only for the remote facts and actions that depend on it.
Implementation plans remain the source of execution order and progress. At L4, the coordinator tracks the external association named in Epic intent alongside that plan. Priorities do not confer implementation or remote-action authority. Hosted vault search and ADR cross-referencing can supply governing context when configured; project coordination does not depend on them.
For a bounded starting snapshot, run:
Command
vaultspec-core project context "Prepare the release across active features" --json
vaultspec-core project context "Prepare the release" --repo OWNER/REPO --json
The command reads local branches and worktrees, tracked-change status and latest commit
subjects. --repo explicitly adds open GitHub issues and PRs, including assignees,
labels, review and CI signals, through an authenticated gh installation. Collection
has a shared ten-second budget and reports source failures and truncated windows.
Boards, milestones, dependency edges, vault plans and untracked files are not collected.
Local branches are not joined to PRs by name, since forks can reuse branch names.
The default reply contains five attention items (--limit accepts 1–10). Observed
blocker and shared-branch signals come first, then tracked changes, with objective fit
and recent activity breaking ties. This order guides investigation; it does not
establish execution dependencies, merge readiness, ownership availability or permission
to act.
With VAULTSPEC_CORE_TYPESAFE_API_KEY configured, the backend sends at most twelve
shortlisted summaries in one TypeSafe request with a five-second budget. It sends no
file contents or issue bodies. Without a key, or on service failure, ordering uses local
signals and lexical objective overlap. --no-hosted disables hosted ranking. The normal
credential precedence applies, including a workspace .env only when Core’s running
interpreter lives inside that workspace and Core’s resolved install mode there is
dependency or dev.
Save --json output when continuity is useful and supply it as
--previous result.json. The backend refreshes observations and reuses matching
judgments for up to one hour; it never restores old facts as current state. Replies
report source coverage, command counts, hosted usage, reuse and timings. The command
writes no repository or tracker state and is discoverable through the existing MCP
gateway as vaultspec-core project context.
Customize the policyLink to Customize the policy
Add a project rule with its instructions:
Command
vaultspec-core spec rules add enforce-newline --body "All workspace source files must end with a single trailing newline."
Edit .vaultspec/rules/enforce-newline.md to change the instructions. Then update the
enabled coding-agent integrations:
Command
vaultspec-core sync
Review and commit the policy changes. For skills, agents, and other rule operations, see the resource commands.
For setup and upgrades, see installation options. To remove Core from a project, follow the uninstall reference.
Installation optionsLink to Installation options
The quickstart uses uvx vaultspec-core install. When using this route, keep the uvx
prefix for later commands.
To install the CLI once and run it from any project:
Command
uv tool install vaultspec-core
vaultspec-core install
To manage it as a project dependency:
Command
uv add vaultspec-core
uv run vaultspec-core install
Contributors then use uv sync to install dependencies and uv run vaultspec-core to
run the CLI. Configure generated launchers under
project integrations. For release binaries that need
neither a separate Python install nor a network, see Homebrew and Scoop.
After updating the package, run vaultspec-core install --upgrade in each project to
update its bundled rules, skills, and agents. Use uvx or uv run as appropriate for
your installation route.
Configure project integrationsLink to Configure project integrations
Install mode. Choose how generated hooks and MCP configuration launch Core with
vaultspec-core install --mode. See the install reference for modes
and selection rules.
Pre-commit hooks. Generated configuration doesn’t activate a Git hook. If you use
pre-commit or prek, run pre-commit install or prek install to activate it. The
generated configuration has one hook, commit-gate. It checks
only the staged vault documents, blocks only on errors the commit introduces, and never
modifies documents. It doesn’t check the vault as a whole: run
vaultspec-core vault check all in CI for orphans, feature coverage, and cross-document
references.
Use the pre-commit controls to enable or disable configuration generation. These settings don’t remove an existing configuration or deactivate an installed hook.
MCP clients. Check enrollment with vaultspec-core spec mcps status --json. See the
MCP tool reference for the available tools.
Agent-runtime hooks. Write a hook once and Core renders it for every coding agent you have installed. See agent-runtime hooks.
Agent-runtime hooksLink to Agent-runtime hooks
Claude Code, Codex, the Antigravity CLI and the Gemini CLI can each run a shell command
when something happens in a session: before a tool runs, after it returns, when a
session starts. Each one spells the events differently and keeps them in a different
file. Write the hook once in .vaultspec/hooks/, and vaultspec-core sync renders it
into whichever of those agents this project has installed.
These are the agent’s events, not Core’s. A hook here fires inside the coding agent
while you work. It has nothing to do with the
pre-commit hooks Core scaffolds for Git, nor with the
lifecycle triggers in .vaultspec/triggers/, which fire inside Core’s own CLI. Each
directory has one owner, so a file in the wrong one is reported rather than silently
ignored.
The two systems are approved separately, and both vaultspec-core spec hooks status and
vaultspec-core spec triggers status report a hooks_dir and a triggers_dir
respectively in --json. Same shape, different directory: read the command, not just
the key.
Write a hookLink to Agent-runtime hooks, Write a hook
One YAML file per hook, in .vaultspec/hooks/. The filename stem is the hook’s name.
There’s no command that scaffolds one; create the file yourself.
Install creates the directory empty and Core ships no example in it, deliberately. A file here is a shell command, and anything bundled would arrive in every install of every project — disabled or not, one edit away from running.
File contents
# .vaultspec/hooks/guard-commands.yaml
event: pre_tool_use
matcher: Bash
command: "./scripts/audit-command.sh"
timeout: 30
enabled: true
Key |
Required |
Meaning |
|---|---|---|
|
yes |
One of the canonical events below |
|
yes |
The shell command the agent runs |
|
no |
Tool-name pattern to filter on; empty matches every tool |
|
no |
Seconds, always. Core converts to each provider’s unit |
|
no |
Defaults to |
This directory holds agent-runtime hooks only. Core’s own lifecycle triggers live in
.vaultspec/triggers/, and a file whose event isn’t one of the canonical names below
doesn’t belong here.
Canonical eventsLink to Agent-runtime hooks, Canonical events
Write the canonical name. Core translates it to each provider’s own spelling. The table below is Core’s mapping: a dash means Core renders nothing for that provider, and the hook is skipped there with a warning naming the hook and the provider.
Canonical event |
claude |
codex |
antigravity |
gemini |
|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
- |
|
|
|
|
- |
|
|
|
|
|
- |
|
|
|
- |
- |
|
|
- |
- |
|
A dash is not a statement about the provider. It says only that Core has no mapping, and in some cases the provider does have an equivalent Core doesn’t use yet. Treat the table as what Core does, and each provider’s own hooks documentation as what that provider supports.
pre_tool_use and post_tool_use are the only two events every provider runs. Bind a
hook that has to work everywhere to one of those.
Antigravity fires five events and Core maps three of them. Its other two,
PreInvocation and PostInvocation, are the nearest thing it has to a session
boundary, but they expect a different response shape, so Core leaves them unmapped
rather than render something the agent would fail to parse. If you previously bound a
hook to session_start or session_end expecting it to reach Antigravity, it never
did: those names exist nowhere in the agy binary, so the hook rendered and was never
called.
Gemini expresses hook timeouts in milliseconds and every other provider in seconds. Write seconds; Core multiplies where it has to.
Where they landLink to Agent-runtime hooks, Where they land
Provider |
Rendered into |
Render report or owned hookset |
|---|---|---|
claude |
|
|
codex |
|
|
antigravity |
|
The |
gemini |
|
|
Core reads and writes .codex/hooks.json only. Codex also accepts an inline [hooks]
table in .codex/config.toml; Core neither reads that nor reports it, so hooks you put
there are invisible to vaultspec-core spec hooks status.
Under --target, hooks and triggers resolve differently, and it isn’t an oversight.
Hooks are source content, like rules and skills: they’re read from the workspace you run
the command in and written into the target. Triggers are read from the target, because a
trigger reacts to something that happened to that workspace.
Hooks you wrote into those files by hand are preserved, including groups identical to the current render. The sidecar beside each flat provider config describes the last render for status reporting. It grants no authority to remove hooks. Native files stay free of ownership fields because some providers reject unknown keys.
Deletion authority lives in ~/.vaultspec/hook-ownership/<native-path-hash>.json,
outside the workspace. Each record binds groups Core actually inserted to the canonical
native path and a digest of the complete native hooks mapping. Sync replaces or
removes those groups only while that mapping still matches. Changes to unrelated
settings do not invalidate ownership. If hooks have been edited, or the host record is
missing or invalid, existing groups remain external and are preserved. Review and remove
obsolete groups manually in that case. Legacy workspace sidecars are never imported as
authority.
Antigravity needs no sidecar: it groups hooks under named hooksets, and Core owns the
one called vaultspec.
Deleting a workspace sidecar affects status reporting; the next sync rebuilds it. Deleting a host ownership record makes Core forget what it inserted. Sync never adopts an existing equal group solely because it matches the current render.
Approve before they renderLink to Agent-runtime hooks, Approve before they render
A hook file travels with the repository, and rendering one writes a command into your agent’s own configuration, where it runs as you on every matching tool call rather than once per sync. So Core renders nothing until you have approved it on this machine.
You are asked before any sync that would render, and before
vaultspec-core install --upgrade. Not on a fresh install, which has nothing to render
yet, and never under --skip hooks. For each unapproved hook you see its name, its
path, the event, the matcher, and the command exactly as written, then a single prompt
that defaults to no.
Declining costs only the hooks. The sync itself completes, the hook isn’t rendered, and stderr names the files it skipped and the command that approves them.
Approval is recorded outside the workspace, in ~/.vaultspec/hook-trust.json, and
pinned to each file’s current contents. Editing an approved hook, or pulling a change to
one, withdraws the approval until you grant it again. Nothing a clone or an archive
carries can add an entry there.
Where there is no operator to ask, nothing renders. --json output, CI, a redirected
stream, VAULTSPEC_NON_INTERACTIVE, and MCP tool calls all skip the prompt, skip the
rendering, and write nothing to the ledger. There’s no flag that approves on your
behalf, because a flag a script can pass is a flag a repository can talk a script into
passing. The refusal lives in the renderer rather than in the prompt, so a route that
never reaches a prompt still cannot render an unapproved hook.
To withdraw approval, run vaultspec-core spec hooks trust --revoke and sync: the next
sync removes the entries it had written, so the hook leaves the provider’s config rather
than lingering there unapproved.
Triggers are approved separately, with
vaultspec-core spec triggers trust. Approving
one system never approves the other.
Turn it offLink to Agent-runtime hooks, Turn it off
vaultspec-core sync --skip hooks runs every other sync pass and leaves hook rendering
alone. It doesn’t remove hooks an earlier sync already rendered; it declines to
reconcile them. vaultspec-core install --skip hooks does the same during install.
Removing a source file and syncing is the way to withdraw a rendered hook. A config file that held nothing but hooks Core wrote is removed along with them rather than left behind empty; one that carries your own settings keeps them and loses only the hooks.
Manage generated filesLink to Manage generated files
Commit your feature documents in .vault/ and your project rules, skills, agents, and
workspace policy in .vaultspec/. Include .vaultspec/workspace.json so the policy
travels with the project. The managed .gitignore entries exclude local caches, logs,
and state.
Use the Gitignore, Gitattributes, and Precommit controls to set project policy for those files.
Enabling or disabling changes only workspace policy; it doesn’t edit or remove existing files. Disabling Precommit also leaves any active Git hook installed.
Deleting a managed Git block or the pre-commit YAML stops ordinary sync from managing that output locally. Install or upgrade can recreate it unless project policy disables generation.
For Model Context Protocol (MCP), edit the canonical JSON server definitions. Core merges Vaultspec-owned entries into enabled provider configurations and preserves unrelated entries.
Per-account runtime stateLink to Per-account runtime state
~/.vaultspec/ stores per-account runtime state shared across repositories. Project
policy stays in the repository’s .vaultspec/ directory.
To diagnose runtime state, run:
Command
vaultspec-core spec doctor --json
The process-registry check reports records in ~/.vaultspec/procs/ whose processes no
longer run. It doesn’t modify those records. Don’t delete runtime records by hand. If
the check reports a stale record, include the JSON output in a
bug report.