--- generator: "vaultspec-marketing discovery" title: "Run the Vaultspec workflow - vaultspec-core documentation" description: "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." url: "https://vaultspec.neve.md/docs/core/framework.html" component: "vaultspec-core" source_repository: "https://github.com/nevenincs/vaultspec-core" source_path: "docs/framework.md" source_commit: "20c6945c09a7503b942523bd55c76dede6c6d3bc" date_modified: "2026-10-08T14:21:04+02:00" --- [View as Markdown]() # 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 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 stages Use these skills when you want to request a particular part of the workflow: | Need | Skill | Record | | --- | --- | --- | | Weigh options using evidence | `vaultspec-research` | Research: findings and sources | | Understand how real code works | `vaultspec-code-research` | Reference: implementation patterns | | Record a costly decision | `vaultspec-adr` | ADR: the choice, rationale, and consequences | | Preserve scope and work order | `vaultspec-write` | Plan: cohesive, verifiable Steps | | Carry out an approved plan | `vaultspec-execute` | Ledger: changed files and verification per Step | | Review planned work | `vaultspec-code-review` | 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 flight From your repository, check current plan progress, next open steps, and recent changes: **Command** ```bash 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** ```bash 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 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 documents List a feature’s records: **Command** ```bash 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** ```bash 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** ```bash vaultspec-rag search "full-text ranking and tokenizer" --type code ``` ## Find and amend an ADR List the current feature’s ADRs with: **Command** ```bash 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 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 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 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 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 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** ```bash vaultspec-core vault graph --feature search-api ``` See the [graph reference]() for filtering and output options. ## 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 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** ```bash 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 policy Add a project rule with its instructions: **Command** ```bash 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** ```bash 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 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** ```bash uv tool install vaultspec-core vaultspec-core install ``` To manage it as a project dependency: **Command** ```bash 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 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 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 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** ```yaml # .vaultspec/hooks/guard-commands.yaml event: pre_tool_use matcher: Bash command: "./scripts/audit-command.sh" timeout: 30 enabled: true ``` | Key | Required | Meaning | | --- | --- | --- | | `event` | yes | One of the canonical events below | | `command` | yes | The shell command the agent runs | | `matcher` | no | Tool-name pattern to filter on; empty matches every tool | | `timeout` | no | Seconds, always. Core converts to each provider’s unit | | `enabled` | no | Defaults to `true`; `false` parses the file but renders nothing | 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 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 | | --- | --- | --- | --- | --- | | `pre_tool_use` | `PreToolUse` | `PreToolUse` | `PreToolUse` | `BeforeTool` | | `post_tool_use` | `PostToolUse` | `PostToolUse` | `PostToolUse` | `AfterTool` | | `session_start` | `SessionStart` | `SessionStart` | - | `SessionStart` | | `session_end` | `SessionEnd` | `SessionEnd` | - | `SessionEnd` | | `stop` | `Stop` | `Stop` | `Stop` | - | | `user_prompt_submit` | `UserPromptSubmit` | `UserPromptSubmit` | - | - | | `notification` | `Notification` | - | - | `Notification` | 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 land | Provider | Rendered into | Render report or owned hookset | | --- | --- | --- | | claude | `.claude/settings.json`, `hooks` key | `.claude/.vaultspec-hooks.json` | | codex | `.codex/hooks.json` | `.codex/.vaultspec-hooks.json` | | antigravity | `.agents/hooks.json` | The `vaultspec` hookset | | gemini | `.gemini/settings.json`, `hooks` key | `.gemini/.vaultspec-hooks.json` | 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/.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 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 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 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 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** ```bash 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](). ## Related documentation | Document | What it covers | | --- | --- | | [Repository README]() | What vaultspec-core is, and installing it | | [Document syntax]() | Frontmatter, tags, links, and the plan row grammar | | [Verifying a workspace and a vault]() | The health commands and what each check proves | | [Review a feature implementation]() | Review scope, findings, fixes, and test evidence | | [CLI reference]() | Every command, flag, and option | | [MCP reference]() | The MCP server tools, setup, and configuration | For bug reports and feature requests, open an issue on the [vaultspec-core issue tracker]().