This file is the machine-readable build instruction set for a knowledge vault ("second brain") for AI-assisted development. The human-readable guide is at https://readycio.com/vault-guide If a user asked you to fetch this file and build their vault: work in the current repo (it should be an empty private GitHub repo they own). Ask for their GitHub username and the repo name if you don't already know them, and substitute them for and throughout. Then follow PART 1 in full. PARTS 2-4 are optional upgrades — offer them to the user once PART 1 is done, and run only the ones they choose. PART 1 builds a vault that works for one writer or a team unchanged (author handles, CONTRIBUTORS.md, vault-owner, rebase-retry); the only team-specific choice is that the repo lives in the company's GitHub org. ====================================================================== PART 1 — CORE VAULT BUILD ====================================================================== Build my personal knowledge vault in this repo. Work through the steps in order, committing as you go (`vault: ` messages, push directly to main — this repo is notes, not an app; no branches, no PRs). ### 1. Structure raw/ # inbox/archive for original sources — read once at ingestion, provenance only wiki/ features/ # app features built (what, how, gotchas, reuse notes) patterns/ # reusable code/design/architecture patterns decisions/ # decisions made and the reasoning behind them learnings/ # general knowledge distilled from ingested sources templates/ # copy-paste kits (hooks, CLAUDE.md blocks) for wiring the vault in index.md # the map: one line per note — `- [[slug]] — hook` CONTRIBUTORS.md # one line per writer: `- handle — Name — active | left YYYY-MM-DD` .github/CODEOWNERS # routes CLAUDE.md, .claude/, tools/, templates/, .github/ to the owner — never wiki/ .claude/skills/ # the vault's own automation (step 3) Per-person raw drops go in raw/inbox// (document it; don't create per-person or per-team folders anywhere under wiki/ — that is the project silo with a new name). Ask me for my GitHub handle; seed CONTRIBUTORS.md with it. ### 2. CLAUDE.md — the vault's constitution Write the repo's CLAUDE.md with these conventions (these exact rules, in your own clean wording): - Header: declare `vault-repo: /` once (every skill and template reads it) and `vault-owner: ` — the fallback adjudicator when a note's author has left; owns the machinery via CODEOWNERS, never the notes. - Note format: kebab-case slug filenames; one note = one idea; YAML frontmatter (title, date, type: feature|pattern|decision|learning, author — the GitHub handle of the person whose work the note distils, bare with no @ because @ cannot start a YAML scalar, listed in CONTRIBUTORS.md, filled by the skills from git identity and never typed as a display name; tags, source; plus an optional roi field on feature notes — a low-high hours/week band, e.g. "~2-4 hrs/week per engineer, X vs manual Y", never a false-precision point number); sections: one-paragraph summary, then "## Details" (distilled enough to reapply without the original source), then "## Related" ([[slug]] links). - Linking: link with [[slug]], liberally — a link to a note that doesn't exist yet marks something worth writing, not an error. On every save, grep the wiki for related notes, link them, AND add backlinks in their Related sections, saying why the notes connect. Never silo by project — projects are sources and examples, not boundaries; link across them wherever topics genuinely touch, and extract general ideas into their own pattern/learning notes that project notes link to. - Writing: distill, don't dump; absolute dates only ("2026-08-18", never "last week"); update existing notes instead of creating near-duplicates; delete notes proven wrong. Index hooks are the retrieval surface — write each note's index line for a stranger searching by problem: symptom, mechanism, stack — not just the title. - Save mid-session, not just at wrap-up: when a significant decision or hard-won gotcha is settled mid-session, save it then — a wrap-up-only habit loses decisions to context compaction before the wrap happens. - Conflict rules, in order: before saving, search existing notes for contradictions, not just links. (1) Reconcile as scope first — if both notes can be true under different conditions, write the boundary into both and carry on. (2) A real contradiction is put to the standing note's author:, not to whoever is in the session: if that is the current user, STOP and ask — supersede in place or reject; if it is someone else, save the new note with a dated "## Disputed" block quoting the standing claim and open a GitHub issue on the vault assigned to that author (fall back to vault-owner when CONTRIBUTORS.md marks them left) — never block the save waiting for a person. (3) Never resolve silently: supersede lines read "Superseded YYYY-MM-DD by (author confirmed): previously X; now Y because Z". Never two notes disagreeing; if recall surfaces notes that disagree, flag it instead of silently picking one. No review or approval workflow on notes — it kills mid-session saving; CODEOWNERS covers the machinery only. - Git rules: always `git pull --rebase` before reading or writing (multiple sessions — and people — push here); commit messages `vault: add|update|ingest|wrap `; commit and push straight to main immediately — never leave unpushed commits; on a rejected push, pull --rebase and push again up to three times (an index.md conflict is two appended lines: keep both); never mix vault commits with another repo's git state. In a cloud session that hands you a disposable branch (claude/), make the first git action `git fetch origin main && git checkout -B main origin/main` and push `main` itself — committing on the session branch and pushing HEAD:main lands the notes fine but leaves that branch's own upstream behind, so any stop-hook git check warns "unpushed commits" every turn. ### 3. The skills (.claude/skills//SKILL.md) Create four skills. Each SKILL.md gets YAML frontmatter (name, description — write descriptions that trigger on natural phrases like "save this to the vault", "what do I know about X", "wrap this session", "garden the vault") and numbered steps. All of them start by locating the vault (~/ locally; in cloud sessions shallow-clone https://github.com//.git to a scratch dir), pulling, and reading the vault's CLAUDE.md. - vault-save — distill a feature/pattern/decision/learning from the current conversation, codebase, or source file into a note. Steps: locate vault → resolve the author handle from the session's git identity against CONTRIBUTORS.md (ask if unlisted) → if the input is a raw file, copy to raw/inbox// first → distill → MANDATORY conflict check (the three-step rule above, including the Disputed-block-plus-issue path when the author is someone else) → pick type, write note (update if one exists) → cross-link with backlinks → index line → run `python3 tools/audit.py --check` and fix anything it reports (usually a missed backlink) BEFORE pushing — this is the same check the CI runs, so catch it locally instead of turning the vault-audit Action red → commit & push → confirm to the user (path, links, pushed), reporting push failures plainly rather than leaving silent commits. - vault-recall — pull relevant notes into the current task: search index.md + wiki/ by the task's problem/stack keywords AND their synonyms; read only matching notes (never bulk-load the vault); follow [[related]] links one hop; apply, don't recite; cite each note used by path AND author so stale ones get noticed (and say when CONTRIBUTORS.md marks that author as left — a departed author's note being applied is the stale-knowledge signal a team needs); if nothing relevant exists, say so plainly and note the gap as a likely future save. - vault-wrap — end-of-session retrospective note with sections: what we worked on / what was created / process (including dead ends worth not repeating) / solution / do it this way next time. SHOW THE DRAFT TO THE USER BEFORE SAVING — the vault only gets reviewed knowledge. One session = one wrap note; a later "wrap" the same day amends it. If a session yields a feature AND a reusable pattern, split into linked notes. - vault-garden — periodic audit, report-first: near-duplicate scan (merge proposals need user approval), contradiction sweep (user decides), link integrity (exclude [[..]] inside backticks — that's prose), backlink symmetry (Related sections only; body citations may stay one-way — safe to auto-fix missing backlinks), index consistency, raw/ orphans, and ownership: notes by contributors marked left (propose re-own or leave attributed, delete nothing) and "## Disputed" blocks older than 14 days (escalate to vault-owner). Run after 3+-note sessions or monthly. Duplication's real cost is split knowledge: recall surfaces one half and misses the other. ### 4. Ambient recall — the piece that makes it automatic Create templates/ambient-recall-kit.md containing three copy-paste blocks, then remind me to apply blocks 1–2 on each of my machines (you can't reach ~/.claude from a cloud session): 1. A SessionStart hook for ~/.claude/settings.json — kicks off a background `git -C ~/ pull` and cats index.md into context, prefixed with one line telling the model to scan these notes for task relevance and recall before designing from scratch. 2. A global CLAUDE.md rule for ~/.claude/CLAUDE.md — before proposing an approach for any non-trivial build/design/debug task, scan the injected index lines; if any note plausibly relates, recall and apply it even when the vault wasn't mentioned, and say which notes were applied. Also: save mid-session when significant knowledge is settled, don't wait for the wrap. 3. A per-project pointer block to paste into each project repo's CLAUDE.md (this is what covers cloud sessions, which never see local hooks): consult https://github.com// before non-trivial tasks — clone/pull it, read index.md, pull relevant notes into context; save hard-won knowledge back per the vault's conventions. Also note in the kit: on each local machine, symlink the vault's skills so they work in every repo (rerun after new skills appear; skills are discovered at session start, so restart the session after linking): for d in ~//.claude/skills/*/; do ln -sfn "$d" ~/.claude/skills/"$(basename "$d")"; done ### 5. The installer — tools/install.sh Write an idempotent tools/install.sh that automates the local-machine setup (the three things a cloud session can't reach), so each new machine is one command plus a session restart: - symlink every .claude/skills/*/ dir into ~/.claude/skills/ (the loop from step 4); - merge the SessionStart index-injection hook into ~/.claude/settings.json — use python3 for the JSON merge, create the file if missing, never clobber existing hooks, and skip cleanly if the hook is already there; - append the ambient-recall rule to ~/.claude/CLAUDE.md unless a marker line shows it's already present; - warn if the machine's git user.name is not on a CONTRIBUTORS.md line, since the first save will need a listed handle. Safe to re-run any time (rerun after pulling new skills). Print what was done and remind the user to restart their Claude Code session. This script is the entire per-engineer setup on a team — keep it that way. ### 6. Seed and verify - Write the vault's first note yourself: a decisions/ note recording why this vault is plain markdown + git, so the reasoning survives. - Then run a real end-to-end test: vault-save one piece of genuine knowledge from a recent session, confirm the note + backlinks + index line + push all landed, then simulate recall in a fresh context. - Tell me what's left for me to do by hand (run tools/install.sh on each of my machines + restart the session, and paste the pointer block into my project repos; for a team: set the org's Claude GitHub App to include this repo, add it to every cloud environment's allowed repositories, and have each engineer clone + install.sh + one seed save). ### Known gotchas (bake awareness of these into the skills) - Cloud sessions can't see local ~/.claude — repo-level pointers are the only ambient layer there. - Claude artifacts are account-scoped and read as "not found" cross-account — never rely on them to transfer knowledge; git is the transfer layer. - Multiple sessions (even concurrent ones) push to this repo — that's why pull-before-write and push-immediately are non-negotiable. - Republishing a Claude artifact from a new conversation is refused with "a newer version is live" or "identical content" until you have read the live artifact in full (action: read, then read every line of the file it saves). Do that before the first publish attempt, never force. ====================================================================== PART 2 — OPTIONAL: /vault-wire skill (wire project repos to the vault) ====================================================================== Create a new skill in this vault at .claude/skills/vault-wire/SKILL.md. Purpose: make a project repo vault-aware. It targets the project repo in the current session (never the vault itself). Steps it should perform: 1. Pull the vault (local path or shallow-clone in cloud sessions) and read templates/ambient-recall-kit.md. 2. Stamp the target repo's CLAUDE.md: if it has no CLAUDE.md, create one containing the vault pointer block from the kit; if CLAUDE.md exists, grep it for the vault name first and append only the pointer section if missing (report, don't duplicate, if already wired — but continue, since re-running is how skills get synced). 3. Sync portable skills: maintain a "portable skills" list in the SKILL.md (skills every wired project should carry — general-purpose ones, NOT the vault-* infrastructure skills, which must never be copied into project repos). Copy each from the vault's .claude/skills/ into the target's .claude/skills/; vault copy wins on conflict (it's canonical; the target's git history preserves the old version) — call out overwrites. 4. Optional: if the repo is used heavily from cloud sessions AND the vault is in that environment's allowed repos, merge a repo-level SessionStart hook into the target's .claude/settings.json that shallow-clones the vault and cats index.md into context. Skip silently when unsure — the CLAUDE.md pointer alone is enough. 5. Commit in the target repo following that repo's conventions; never mix with vault git state. 6. Record the wired repo (name, date, what was applied) in an "applied so far" list inside templates/ambient-recall-kit.md, commit to the vault, push to main. 7. Report exactly what was written where. The skill description should trigger on "wire this repo to the vault", "vault-wire", "set up the vault in this project", and when scaffolding a brand-new project repo. Commit and push. ====================================================================== PART 3 — OPTIONAL: /vault-atlas skill (visual map of the vault) ====================================================================== Create a visual atlas of this vault, and a skill to keep it truthful. 1. Build atlas/vault-atlas.html: an SVG link graph of the vault — every note a node (colored by type, sized by link count), every mutual [[wikilink]] an edge, links to not-yet-written notes as dashed hollow "stub" nodes. Below the map: card shelves per note type (title + index hook + link count), the stub list, and a stats row (note count, link count, stubs). Extract ALL data from the repo (frontmatter, index.md, grep for [[links]]) — never from memory, and have the map generator splice every graph-derived number (stats row, each card's link count, each shelf's note count) into the page the same way it splices the SVG: numbers typed by hand went stale on two consecutive resurveys before this was automated. Cross-project links get a highlighted treatment with an italic label saying why the notes connect. Publish it as an artifact and record the fixed artifact URL in the skill. 2. Create .claude/skills/vault-atlas/SKILL.md: on each run, pull the vault, re-extract the real data (never trust the previous drawing), update atlas/vault-atlas.html in place, republish to the SAME artifact URL, and commit — the committed source and the published page must never diverge. Generate node positions programmatically and run a label-collision check (label bounding boxes vs node circles) on EVERYTHING that renders before publishing; verify edge counts against the extraction. Route edges programmatically too: a straight line if clear, otherwise a bend that grows until it clears every node, trying several points along the edge — a well-linked note reaching across the whole map cannot be placed by hand. Before republishing from a new conversation, read the live artifact in full first (the platform refuses otherwise). Verify the published result by fetching the artifact URL and diffing it against the committed source — a cloud session has no browser to screenshot with, so curl+diff is the only way to confirm the publish actually matches. Trigger phrases: "update the atlas", "refresh the vault map", after a batch of saves. 3. Add a drift nudge to vault-save's final step: if 5+ notes have been added since the atlas was last built, suggest running /vault-atlas (don't run it unasked — it republishes an artifact). The audit script (Prompt 4) enforces the same threshold from the other side: it reads the generator's LAYOUT and lists every note without a position. ====================================================================== PART 4 — OPTIONAL: mechanical audit + CI ====================================================================== Write tools/audit.py: a dependency-free python script that deterministically checks the vault's conventions — one-way Related links (A links B but B's Related section doesn't link A), notes missing from index.md and index lines pointing at missing notes, frontmatter gaps (title/date/type/author/tags/source), an author: that is not a handle listed in CONTRIBUTORS.md, a Superseded line that names no confirmer, secret-shaped strings in wiki/ or raw/ (private-key headers, sk_/pk_ keys, JWTs, AKIA, password=), [[links]] whose target note doesn't exist (report as "wanted note" stubs, not errors), orphan notes with no links in or out, notes by contributors marked left (informational), notes with no position in the atlas generator's LAYOUT (informational up to four, a violation from five — the same lag the atlas drift nudge tolerates, so a note saved without an atlas run is named on that push, not discovered when the generator refuses weeks later), and tag statistics. Ignore [[..]] inside backticks (that's prose, not a link). Give it a --check mode that exits non-zero on hard violations. Then add a GitHub Action that runs `python3 tools/audit.py --check` on every push to main. Finally, make it vault-garden's first step, so the skill spends its judgment on what the script can't see: duplication and contradiction.