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)

```text
<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):

```yaml
---
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`:
```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):
```json
[
  "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`:
```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:
  ```dataview
  TABLE status, date FROM "02-ADRs" WHERE type = "adr" SORT date DESC
  ```
- A **Dataview** block listing all in-progress plans:
  ```dataview
  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:
  ```dataview
  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:
```text
#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:
```json
{
  "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`:
```text
# 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).