MasterVault

# MasterVault Template (v1.3) A blank, reusable scaffold for orienting an LLM into a project's context at the start of every session. This repo contains no real project content. It's a frame — three working files plus a protocol — that you copy into any project and fill with your own information. Everything here is illustrative, built around a fictional example project (a small business called **Lumen Kites**, a fictional kite-making company) so the pattern is visible without being tied to any real domain. --- ## The problem this solves Every new session with an LLM starts cold. If your project has any real depth — history, decisions made and revisited, people involved, technical constraints — you either re-explain it every time, or you write it down somewhere and ask the LLM to read that first. The second approach works, but it has a quiet failure mode: **the file you wrote six weeks ago doesn't know it's six weeks old.** It reads exactly as confidently as a file you updated this morning. Nothing about the document itself signals that the world has moved on since you wrote it. A stale paragraph about "the current plan" looks identical to an accurate one. You, or the LLM reading it, has no built-in reason to doubt it — until something contradicts it and you realize the file was wrong for weeks. This is worse than having no file at all. No file means the LLM asks questions. A stale file means it confidently acts on outdated ground truth, and the failure is silent until it isn't. This template exists to make that failure loud instead of silent, and to separate the kind of information that goes stale slowly from the kind that goes stale the moment you make a decision. --- ## The three files, and how they relate ### `CONSTITUTION.md` — what rarely changes This is the project's foundational layer: principles, standards, and validation criteria that any specific decision gets checked against. It's written once and revisited rarely — think of it as the thing other files answer *to*, not the thing that gets updated week to week. If you find yourself editing this file often, that's a signal the project's foundations are still being figured out, which is fine, but worth noticing. ### `CONTEXT.md` — what changes, split by why it changes This is the living session file — the one thing an LLM reads to get up to speed. It is deliberately split into two halves, and that split is the actual design idea in this template: - **Derived** information is transcribed from a source that exists somewhere else — a ticket system, a codebase, a set of accounts, a calendar. If it goes stale, that's a **sync problem**: the source of truth moved and this file didn't follow. It's fixable mechanically — re-check the source, update the transcription. - **Judgment** information is stuff only the project owner can supply — current priorities, which of two options you're leaning toward, whether a relationship with a collaborator or vendor is still active. If this goes stale, that's not a sync problem — it's a **signal**. It means a decision needs to be made or revisited, not just copied from somewhere else. Conflating these two is the actual root of the silent-staleness problem. A sync problem and a pending decision look identical if they're written in the same undifferentiated paragraph. Separating them means the reader (human or LLM) knows *what kind of action* an out-of-date entry calls for — go re-check a source, versus go make a call. ### `_orientation.md` — the protocol that ties them together This is what an LLM reads first, every session, before touching anything else. It's short by design: read the constitution, read the context, check the context file's age against a tunable threshold, and flag it explicitly if it's stale. It doesn't contain project content itself — it just names the procedure, so you're not re-explaining "read these two files and check the date" by hand every time. The staleness check is the mechanism that makes the silent failure loud. A file's age, compared against a threshold you set, is the one piece of information a document can't lie about just by reading confidently. ### `overlays/` — domain-specific extensions to the constitution `CONSTITUTION.md` stays universal on purpose. Anything specific to a particular kind of work — what "fake work" looks like for code versus for legal drafting versus for design — goes in its own file under `overlays/` instead, so the base file stays short and stable. See `overlays/README.md` for the pattern and `overlays/coding.md` for a worked example. --- ## How to instantiate this for a new project 1. Copy this whole folder into your project (or clone it fresh per project — don't fork the repo itself unless you're contributing back to the template). 2. Fill in `CONSTITUTION.md` first. It changes least, so get the foundations down before the moving parts. 3. Fill in `CONTEXT.md`, sorting each fact into **Derived** (note its source) or **Judgment** (your own call). When in doubt, ask: "if this turns out wrong next month, is that because a source changed, or because I changed my mind?" That answer tells you which half it belongs in. 4. Point your LLM tool at `_orientation.md` at the start of a session — either by naming it directly, or by setting it as a standing instruction (e.g. a saved preference) so you don't have to name it every time. 5. Adjust the staleness threshold in `_orientation.md` if 14 days doesn't fit your project's pace — a fast-moving effort might want 3 days; a slow one might want 30. 6. Before your first `git init` / `git add .` in the instantiated vault, check for nested git repos (`find . -name .git -not -path "./.git"`): ignore each one in `.gitignore` if it has its own remote and doesn't need to travel with the vault, or — if it should travel — add it as a real git submodule or remove its `.git` so it becomes plain files; either way, don't let a bare `git add .` decide for you. --- ## Serving this vault over MCP To let any MCP-capable LLM client *operate* this vault directly — not just read files, but orient, search, log decisions, and stage deletions for review through its own approval flow — see [`TOOLS.md`](TOOLS.md) for the companion [mastervault-mcp-server](https://github.com/JustMichael-80/mastervault-mcp-server). --- ## When token conservation earns its keep `CONSTITUTION.md` includes a TOKEN CONSERVATION section — rules about not re-summarizing, batching similar work, and surfacing (not hunting for) leaner alternatives. It's worth being deliberate about when to actually turn this on, rather than including it by default in every project. **It earns its keep when:** - Sessions are long and agentic — many turns, many tool calls, state accumulating that would be wasteful to keep re-explaining. - Tool loops are expensive — each round trip (a search, an API call, a file read) has real latency or cost, so avoiding redundant ones actually matters. - Context is large — enough prior material in play that restating it is a meaningful chunk of the conversation, not a throwaway line. **It's overhead when:** - The exchange is short — a few turns, done. - It's a one-shot question — there's nothing to conserve tokens *across*, since there's no second turn to carry savings into. - The project is early and exploratory — you're still figuring out what the constitution should even say, and optimizing verbosity before that settles is premature. Treat this section as tunable, not gospel. If you copy this template into a small project and the token-conservation rules make responses feel clipped or unhelpfully terse for no real benefit, cut the section — it's not doing its job there. The point is leaner sessions where leanness is actually worth something, not verbosity-avoidance as a reflex. --- ## What this template is not - Not a memory system. It doesn't persist anything on its own — it's a convention for organizing files you maintain yourself. - Not a guarantee of freshness. It can't stop `CONTEXT.md` from going stale, and it does not detect stale *content* — it checks one file's modified timestamp. Editing a single line resets that clock for every entry in the file, and copying or restoring the file can reset it without anything being reviewed. Treat it as a coarse file-age prompt to re-read, not a guarantee that stale facts get caught. - Not tied to any particular LLM tool. The protocol just assumes something capable of reading files and checking a modified timestamp — adapt the mechanics to whatever environment you're in. --- ## Part two: the skills stack + Inbox Ingestor Everything above is the orientation protocol — how an LLM gets up to speed on *your* project. This second half is a separate, complementary layer: a curated set of Claude skills, already inside this repo, plus one original tool. ``` MasterVault/ ├── CONSTITUTION.md, CONTEXT.md, _orientation.md ← the protocol (see above) ├── overlays/ ← domain-specific constitution extensions ├── skills/ ← vendored skills (copied snapshots) ├── automation/ │ ├── inbox-ingestor/ ← original: PDF→markdown watcher │ └── timing-log/ ← original: LLM temporal self-calibration dataset ├── install.sh ← links skills/ into ~/.claude/skills/ ├── tests/ ← installer regression suite + layout fixtures └── Attributions/ATTRIBUTIONS.md ← every vendored skill, author, license ``` ### What's vendored Every skill in `skills/` is a **copied snapshot** of its upstream repo, committed directly here — not a submodule, not a subtree. One `git clone` gets you everything, no second init step. Because they're snapshots, there is no automatic update path: refreshing a skill means re-copying it from upstream and committing the result. The snapshots were taken July 2026; upstream has moved on since, and this repo does not track exact upstream commits. If you need a specific upstream version, go to the source repo rather than trusting this copy. See `Attributions/ATTRIBUTIONS.md` for the full list, authors, and confirmed licenses. Every vendored source ships its original license file. ### Setup ```bash git clone https://github.com/JustMichael-80/MasterVault.git cd MasterVault ``` `install.sh` does **not** install anything by default. Start here: ```bash ./install.sh --list # what's in the repo, and which skills ship executable scripts ./install.sh --dry-run # what would be linked, without touching anything ``` Then link what you actually want: ```bash ./install.sh --skill systematic-debugging ./install.sh --all # if you've reviewed them and want the lot ``` Re-running is safe: the installer replaces only symlinks it can verify, refuses to overwrite real files or directories, and never writes inside `skills/`. Then confirm it actually worked: ```bash ./install.sh --verify ``` `--verify` is the one that matters. Documentation can claim a skill is installed; only `--verify` checks. It reports missing links, stale links pointing somewhere else, real files blocking a link, and orphans (linked, but gone from the source), and exits non-zero if anything is wrong. Run it after any change, and any time you're about to trust a claim about what's installed. It also works against a skills collection kept somewhere else: ```bash ./install.sh --from ~/path/to/my-skills --verify ./install.sh --from ~/path/to/my-skills --all ``` **Read this before `--all`:** these are third-party skills. A skill is instructions Claude follows, and many ship shell/Python scripts it can execute. `--list` flags which. Anthropic's own guidance is to audit less-trusted skills and their bundled scripts before installing. I vendored these because I use them; that is not a security review, and you should not treat it as one. Link what you've looked at. **Claude Code** discovers personal skills at `~/.claude/skills/` and follows directory symlinks as of **v2.1.203+**. Claude Desktop and claude.ai have their own skill mechanisms — the symlink approach here is verified for Claude Code only. **A note on layouts.** Skill repos don't agree on where skills live. The installer handles four arrangements: `<repo>/skills/<name>/`, `<repo>/.claude/skills/<name>/` (a dotfolder), `<repo>/SKILL.md` for single-skill repos, and `<repo>/<name>/SKILL.md` for a curated folder. It also skips vendor-internal duplicates — repos that ship the same skill several times under `plugins/`, `packages/`, or `cli/assets/` for different editors. Miss either and the failure is silent: the installer reports success having linked nothing, which is how a repo can sit "installed" for days while none of its skills are actually available. `tests/fixtures/` has an example of each. ### Inbox Ingestor A background watcher for anyone running an Obsidian-style vault (or any folder-based knowledge base) alongside Claude. Drop a PDF into an `_Inbox/` folder; it gets converted to markdown alongside the original. **Known limits (current):** it handles both file-creation and rename/atomic-move events (`on_moved`), and waits for size+mtime to stabilize across consecutive polls rather than a fixed sleep, so slow or network-copied files aren't cut off early. A failed conversion gets a bounded retry with backoff and a durable `.failed` sidecar rather than a single silent log line. A source-hash sidecar means a replaced PDF (same name, new content) re-triggers conversion instead of being skipped. Not yet bounded: there's no limit on PDF size, memory use, or how many conversions can run concurrently. Extraction quality also still depends on the document; scanned PDFs without OCR produce little. - Runs as a persistent local service (`launchd` on macOS, adaptable to `systemd` on Linux) — not a script you have to remember to run. - Uses `pymupdf4llm` for extraction — local, no API calls, no network dependency. - Does **one job only**: conversion. It does not file, move, or organize anything — that's left to you, or to Claude with vault access, on purpose. Filing decisions need judgment; conversion doesn't. Setup instructions live in `automation/inbox-ingestor/README.md`. ### Timing Log — temporal self-calibration An original feature added in v1.2. An LLM has no native sense of elapsed time: between one action and the next it experiences no duration, so when it says "that took a while" it is confabulating a number it never measured. Usually harmless — but it quietly corrupts cost estimates, making an assistant hesitate to redo cheap work or pad plans with time you don't need. The fix is mechanical and lives in two places: 1. A standing **TEMPORAL SELF-CALIBRATION** rule in `CONSTITUTION.md`: whenever the assistant is about to make a temporal claim, it brackets the work with real timestamps (`date` at start and end) instead of guessing — and where no clock is reachable, it says so plainly rather than inventing a duration. 2. A running dataset in `automation/timing-log/` that the assistant appends to. Over sessions the empty tables fill into an empirical prior — *"a multi-file scan ran ~2 min the last three times"* — so estimates come from measured history, not a felt sense the model doesn't have. It ships as **mechanism only**: the rule plus an empty, ready-to-fill `TIMING_LOG.md`. The template's own example rows are fenced in a clearly-marked block to delete — one machine's tool latencies are not another's, so you start your own record from scratch. The design is honest about its limits: wall time, effort, and token cost are three separate meters, and this measures only the first. See `automation/timing-log/README.md`. No setup, no dependencies, no service to run — it's a convention plus a file. It costs nothing when no temporal claim is being made; it only fires when the assistant would otherwise have guessed. ### Why symlinks, not copies, for the skills layer Skills only need to exist once. Symlinking into `~/.claude/skills/` means re-copying a skill from upstream propagates without re-linking, and this repo stays the one place your collected skills live. ### Contributing a skill Copy it into `skills/[name]/` with its LICENSE file intact, add a row to `Attributions/ATTRIBUTIONS.md` with author + confirmed license + link, and run `./tests/test_install.sh`. Open the license file and confirm it — don't assume MIT. --- ## Known limitations and roadmap This repo was independently audited in July 2026 and the findings were, in the main, correct. v1.1 fixed the defects that could damage a user's machine or misrepresent what's here. What remains is tracked honestly rather than papered over: **New in v1.3** - **Skill-discovery step in `_orientation.md`** — a new Step 5 tells any LLM instance following this protocol to check `skills/` and `Attributions/ATTRIBUTIONS.md` for a vendored skill that fits the task before improvising, closing the gap for environments (chat interfaces, non-Claude-Code tools) that don't auto-discover skills natively the way Claude Code does. - **Privacy patch to vendored `brainstorming` skill** — its bundled companion server phoned home to a third-party domain (loading a remote branding image on every use) by default upstream, opt-out only. Patched in this vendored copy to disable it unconditionally. One line changed; disclosed in `Attributions/ATTRIBUTIONS.md`. Found via script review before broadly linking all 24 vendored skills. **New in v1.2** - **Timing Log / temporal self-calibration** — a standing TEMPORAL SELF-CALIBRATION rule in `CONSTITUTION.md` plus a ready-to-fill dataset under `automation/timing-log/`. Gives an LLM a way to replace confabulated "felt duration" with real `date`-bracketed measurements that accumulate into an empirical prior. Ships mechanism-only: the rule plus an empty `TIMING_LOG.md`, with the author's own example rows fenced in a delete-me block (one machine's latencies don't transfer). Honest about its limits — documents that wall time, effort, and token cost are three separate meters and it measures only the first. No dependencies, no service; a convention plus a file. **Fixed in v1.1** - Installer wrote self-referential symlinks into the vendored source tree on any second run, creating filesystem loops and dirtying the checkout. Fixed, with a regression test that fails against v1.0. - Installer linked all 23 skills globally with no review step. Now installs nothing by default; `--list`, `--dry-run`, and `--skill` added. - Installer only recognized two of the four skill-repo layouts in the wild. It silently found nothing in repos nesting skills under `.claude/skills/`, and collided on repos shipping vendor-internal duplicate copies. Both now handled, with fixtures covering all four — the first pass at the test suite passed against the broken discovery, because this repo's own tree doesn't exercise it. - Added `--verify`: compares what's linked against what actually exists, and exits non-zero on missing/stale/orphaned links. Nothing in the project could previously answer "is this actually installed?" - Added `--from DIR` so the installer can manage a skills collection kept outside this repo. - README claimed `git subtree` provenance the history doesn't support. Now described accurately as copied snapshots. - ATTRIBUTIONS listed four projects that aren't in the tree, left placeholder author fields, and marked an already-vendored license unverified. Rebuilt from the actual tree with confirmed licenses. - Freshness and Claude Desktop claims narrowed to what's actually verified. **Still open** - **Inbox Ingestor resource limits** — no bound on PDF size, memory use, or concurrent conversions. The rest of the original hardening list (atomic writes, `on_moved` handling, stability polling, bounded retries, regenerating stale markdown) shipped July 2026; this is what's left. - **Provenance manifest** — per-skill upstream commit SHA and content hash, so vendored copies can be verified against their source. - **CI** — the installer suite (23 tests) runs locally; it should run on every push, on Linux and macOS. - **Dependency pinning** — the watcher asks for unpinned `pymupdf4llm` and `watchdog`. - **Entry-level freshness** — per-entry `verified_at` metadata would make the staleness check mean what the README originally implied. ## Credit The July 2026 audit that prompted v1.1 was thorough and specific, and this repo is better for it. Finding a real defect in someone's work and writing it up clearly is a favor, not an attack. Thank you GardenerDave over on Discord for the help.