obsidian-vault

name

obsidian-vault

description

Generate a comprehensive, ground-truth-anchored Obsidian Vault for any repository. The vault covers codebase understanding, execution planning, Architecture Decision Records (ADRs), session reasoning logs, and design tracking — structured for both human navigation and AI consumption. Creates the full folder skeleton, note templates, .obsidian/ config (plugin manifest, graph settings, CSS color snippets), tag taxonomy, AI context file, and a starter architecture canvas. Idempotent: detects an existing vault and offers update vs fresh create. Global and project-agnostic. Trigger when the user says "create obsidian vault", "set up obsidian vault", "init vault", "scaffold vault for this repo", "obsidian-vault", or "create vault". SKIP when the user is asking about an existing vault they manage manually or wants only a specific part (e.g. just a template).

Generate an Obsidian Vault for a repository

Project-agnostic, global skill. It scans a repository, then writes a complete Obsidian Vault that acts as the single knowledge base for understanding the codebase, tracking decisions, planning execution, and logging reasoning — usable by both the developer and AI tools without re-deriving context each session.

The vault is always anchored to ground truth: it references the codebase; it does not paraphrase it. Any note that describes code should link to the actual file path rather than duplicate its content.

Vault layout (target output)

<vault-root>/                    default: <repo>/.obsidian-vault/
├── .obsidian/
│   ├── app.json                 core settings (preview mode, line numbers off)
│   ├── community-plugins.json   plugin enable list
│   ├── graph.json               graph layout + folder color groups
│   └── snippets/
│       └── graph-colors.css     CSS variables driving graph node colors by folder
├── _templates/                  Templater source folder
│   ├── TPL-ADR.md
│   ├── TPL-Architecture.md
│   ├── TPL-ExecutionPlan.md
│   ├── TPL-Research.md
│   ├── TPL-Reference.md
│   └── TPL-SessionLog.md
├── 00-Home/
│   └── Home.md                  root MOC + live Dataview dashboards
├── 01-Architecture/
│   └── Overview.md              stub seeded from scan
├── 02-ADRs/
│   └── _ADR-Index.md            Dataview index of all ADRs
├── 03-Plans/
│   └── _Plans-Index.md          Dataview index of all plans + open tasks
├── 04-Research/
├── 05-Sessions/
├── 06-Reference/
├── Architecture.canvas          starter canvas from discovered repo structure
├── _AI-CONTEXT.md               machine-readable vault guide for AI tools
└── _TAG-TAXONOMY.md             canonical tag list; never add tags outside this file

Universal frontmatter convention

Every note and template must open with this YAML block (Templater variables in templates):

---
title: <human title>
date: <YYYY-MM-DD>          # creation date; templates use <% tp.date.now("YYYY-MM-DD") %>
type: adr | plan | session | research | reference | architecture | moc
status: draft | active | deprecated | superseded
tags: []
related: []                 # [[wikilinks]] to related notes
---

The type and status fields drive Dataview queries and graph CSS coloring. Never omit them.

Procedure

1. Orient

• Identify the repo root (ask if ambiguous — monorepos, submodules).
• Check whether <vault-root>/ already exists.
  • Exists: list what's already there, confirm whether to update (add missing files only) or regenerate (overwrite everything). Default: update.
  • Does not exist: confirm the vault root path before creating anything.
• Confirm or override the default vault placement (<repo>/.obsidian-vault/).

2. Scan (via Explore agent)

Spawn the built-in Explore agent (read-only, no context pollution) with this task:

"Scan this repository and return: (1) project name and one-line purpose, (2) tech stack (languages, frameworks, build tools), (3) top-level source components/modules (folder names, packages, services), (4) key files worth referencing in the vault (README, architecture docs, main entrypoints, CI config). Return a structured summary — no file dumps."

Use the summary to seed: project name, component list for tags and canvas, stack for architecture overview, key file paths for Reference notes.

3. Propose and pause for approval

Present to the user:

• Vault root path
• Folder structure (from layout above)
• Plugin list (see step 4a)
• Template list
• Gitignore strategy (.obsidian/ settings gitignored; vault content tracked)
• Any update-vs-regenerate decision from step 1

Do NOT create any files before the user approves. Show what will be created, not just "I'll create a vault."

4. Generate vault files

4a. .obsidian/ config files

Write .obsidian/app.json:

{
  "defaultViewMode": "preview",
  "foldIndent": true,
  "showLineNumber": false,
  "livePreview": true,
  "strictLineBreaks": false,
  "showFrontmatter": false
}

Write .obsidian/community-plugins.json (these must be installed manually in Obsidian, but listing them here makes the intent declarative):

[
  "dataview",
  "templater-obsidian",
  "obsidian-git",
  "obsidian-excalidraw-plugin",
  "quickadd",
  "tag-wrangler",
  "obsidian-tasks-plugin",
  "obsidian-kanban"
]

Write .obsidian/graph.json — configure color groups by folder path so each section is visually distinct in the graph view. Use these RGB values (decimal):

• 00-Home → gold #E6AC00 (15117312 decimal)
• 01-Architecture → blue #4488FF (4491519)
• 02-ADRs → orange #FF6600 (16744448)
• 03-Plans → green #44AA44 (4433476)
• 04-Research → violet #AA44FF (11157759)
• 05-Sessions → cyan #00CCCC (52428)
• 06-Reference → gray #888888 (8947848)

Also set: "showOrphans": false, "showTags": true, "showAttachments": false.

Write .obsidian/snippets/graph-colors.css:

/* Obsidian graph node colors by folder — matches graph.json colorGroups */
.graph-view.color-fill-tag { color: #E6AC00; }

/* Node label sizes */
.graph-view.color-text { opacity: 0.8; }

4b. Folder skeleton + index MOCs

Create each folder. Write index MOCs for 00-Home/Home.md, 02-ADRs/_ADR-Index.md, and 03-Plans/_Plans-Index.md.

00-Home/Home.md must include:

• Frontmatter: type: moc, status: active
• A one-line project description (from scan)
• A Dataview block listing all active ADRs:

  TABLE status, date FROM "02-ADRs" WHERE type = "adr" SORT date DESC
  

• A Dataview block listing all in-progress plans:

  TABLE status, date FROM "03-Plans" WHERE type = "plan" AND status != "deprecated" SORT date DESC
  

• A Dataview block listing all session notes from the last 30 days:

  TABLE date FROM "05-Sessions" SORT date DESC LIMIT 10
  

• Links to [[Architecture.canvas]], [[01-Architecture/Overview]], [[_TAG-TAXONOMY]], [[_AI-CONTEXT]]

02-ADRs/_ADR-Index.md and 03-Plans/_Plans-Index.md: frontmatter + a Dataview table of all files in their folder sorted by date.

01-Architecture/Overview.md: seed with project name, stack summary, and a bullet list of top-level components discovered in step 2 — each linking to a [[06-Reference/ <component>]] stub.

4c. Templates (in _templates/)

All templates use Templater syntax (<% tp.* %>). Each must open with the universal frontmatter from the convention section above. Section headers for each:

TPL-ADR.md — type: adr Sections: ## Context, ## Decision, ## Status, ## Consequences, ## Alternatives Considered, ## Related (Dataview: list notes tagged same component)

TPL-Architecture.md — type: architecture Sections: ## Purpose, ## Components, ## Key Files (link to actual paths), ## Interfaces / Contracts, ## Known Constraints, ## Open Questions

TPL-ExecutionPlan.md — type: plan Sections: ## Goal, ## Success Criteria, ## Tasks (Tasks plugin checklist), ## Related ADRs (Dataview: FROM "02-ADRs" WHERE contains(related, this.file.link)), ## Session Log (links to sessions for this plan), ## Notes

TPL-SessionLog.md — type: session Sections: ## Goal for This Session, ## Decisions Made (link to ADRs), ## Code Changed (file paths), ## Open Questions, ## Next Session

TPL-Research.md — type: research Sections: ## Question, ## Sources, ## Findings, ## Conclusion, ## Impact on Architecture (link to ADR if decision follows)

TPL-Reference.md — type: reference Sections: ## Source (file path or URL), ## Key Excerpts, ## How This Is Used, ## Last Verified (date — critical for keeping reference notes honest)

4d. _AI-CONTEXT.md

Write a structured file at vault root explaining the vault to an AI tool reading it for the first time. Must include:

• What each folder contains and when to use it
• The frontmatter convention and how type/status fields work
• How to interpret related: [] links
• Where to find architectural ground truth (links to actual repo paths, not vault copies)
• The tag taxonomy (or link to [[_TAG-TAXONOMY]])
• What the AI should NOT do: do not treat vault notes as authoritative over the actual codebase; always verify against the real files before acting

4e. _TAG-TAXONOMY.md

Define the canonical tag hierarchy. Seed with:

#status/draft  #status/active  #status/deprecated  #status/superseded
#type/adr  #type/plan  #type/session  #type/research  #type/reference  #type/architecture
#priority/high  #priority/medium  #priority/low
#component/<name>   ← one tag per component discovered in step 2

Include a rule: only add tags here first, then use them in notes. Tags not in this file are considered typos.

4f. Architecture.canvas

Write a JSON canvas file with one text node per top-level component discovered in step 2, arranged in a grid layout (300px × 150px nodes, 400px horizontal spacing, 300px vertical). Add edges only where a clear dependency is obvious from the scan. Canvas JSON format:

{
  "nodes": [
    {"id": "1", "type": "text", "text": "ComponentName", "x": 0, "y": 0, "width": 300, "height": 150}
  ],
  "edges": []
}

If the repo has a clear layered structure (e.g. frontend/backend/db), arrange top to bottom to reflect the dependency direction.

5. Offer .gitignore update

Offer to append to <repo>/.gitignore:

# Obsidian vault settings (machine-local, not shared)
.obsidian-vault/.obsidian/workspace.json
.obsidian-vault/.obsidian/workspace-mobile.json

Do NOT ignore the full .obsidian/ directory — plugin config (community-plugins.json, graph.json, app.json) is intentional and should be shared. Only ignore workspace state files that record window positions and open tabs.

6. Hand off

• List every file created (or skipped if updating).
• Remind the user to open the vault root in Obsidian, then install plugins via Settings → Community Plugins → Browse (the community-plugins.json lists them but does not auto-install — Obsidian requires a manual install step).
• Note that Templater must be configured to use _templates/ as its template folder (Settings → Templater → Template folder location).
• Suggest opening 00-Home/Home.md as the default starting note and pinning it.

Guardrails

• Pause for approval after step 3; never generate files without user confirmation.
• Idempotent on update: skip files that already exist unless the user explicitly chose regenerate; never silently overwrite a note that may contain the user's own content.
• Never copy-paste source code into the vault — reference file paths instead. The vault complements the codebase; it does not duplicate it.
• All generated content must be grounded in what the Explore agent actually found; never fabricate component names, file paths, or architectural claims.
• Keep _AI-CONTEXT.md honest: it must warn AI readers to verify against the live codebase, not treat vault notes as authoritative.
• If the vault root is inside the repo, ensure it will not break existing tooling (e.g. test runners that glob all .md files — flag this risk if detected).