Obsidian Vault Sync

---
name: obsidian-vault-sync
description: Audit and maintain an existing Obsidian Vault against the current state of the repository it covers. Runs two parallel read-only scans (codebase + vault), produces a structured audit report across 11 checks (missing coverage, stale notes, dead wikilinks, orphan notes, tag drift, frontmatter drift, ADR staleness, canvas freshness, _AI-CONTEXT.md drift, Dataview query health, plugin recommendations), then applies fixes only after per-item user approval. Global and project-agnostic; pairs with the obsidian-vault creation skill. Trigger when the user says "maintain obsidian vault", "sync obsidian vault", "update obsidian vault", "audit obsidian vault", "obsidian-vault-sync", "vault is out of date", "update vault", "sync vault", or "check vault". SKIP when the user is asking about creating a new vault from scratch (use obsidian-vault instead).
---

# Obsidian Vault sync / audit

Project-agnostic, global skill. It keeps an Obsidian Vault honest: scans the live
codebase and the vault in parallel, diffs their states across 11 checks, and applies
fixes only after the user approves each finding. The vault is always a mirror of ground
truth — this skill is the sync mechanism that maintains that property over time.

Pairs with `/obsidian-vault` (which creates the vault). If no vault exists yet, stop
and direct the user there.

## Scope flags (parsed from invocation text)

| Flag | Limits audit to |
|---|---|
| `--tags` | Tag drift and taxonomy checks only |
| `--content` | Note staleness, dead links, orphans, ADR staleness |
| `--structure` | Folder structure, canvas, _AI-CONTEXT.md drift |
| `--plugins` | Plugin/settings recommendations only |
| `--all` | All checks (default when no flag is given) |

## Procedure

### 1. Orient
- Locate the vault root: check `<repo>/.obsidian-vault/` by default; ask if not found.
- If the vault root does not exist: stop, explain, suggest running `/obsidian-vault` first.
- Parse any scope flag from the invocation (default `--all`).
- Show the user: vault path, scope, and the list of checks that will run. Confirm before
  scanning.

### 2. Scan (two agents in parallel)

Spawn both simultaneously and wait for both to return before proceeding:

**Agent A — Codebase scan (built-in `Explore` agent, read-only):**
> "Scan this repository and return a structured summary: (1) all top-level
> components/modules (folder names, package names from manifests), (2) key file paths
> (README, entrypoints, CI config, any architecture docs), (3) recent git activity —
> files added, deleted, or renamed in the last 60 commits (run `git log --diff-filter=ADR
> --name-status --oneline -60`), (4) any file paths that were deleted or renamed. Return
> a structured plain-text report — no file dumps, no code excerpts."

**Agent B — Vault scan (`vault-scanner` custom agent):**
Spawn the `vault-scanner` agent (defined in this repo under `global/claude/agents/vault-scanner.md`)
against the vault root. It returns a structured vault state report covering: all notes
with their frontmatter, wikilinks, and sizes; all tags in use; tags defined in
`_TAG-TAXONOMY.md`; folder structure; orphan candidates; dead wikilinks; `.obsidian/`
config contents; template frontmatter schemas; and all Dataview query blocks.

### 3. Diff → audit report

Cross-reference Agent A and Agent B outputs to evaluate every active check. For each
check, produce a finding entry:

```text
[CHECK NAME]  severity: high | medium | low
Summary: <one sentence>
Affected: <list of file paths or note titles>
Action: <add note | update frontmatter | fix wikilink | update canvas | skip | manual>
```

The 11 checks and their logic:

1. **Missing coverage** — components in Agent A output with no matching note in
   `01-Architecture/` or `06-Reference/`. Severity: high if component has >5 source files.

2. **Stale content** — notes containing file paths (from Agent B) that appear in Agent A's
   deleted/renamed list. Severity: high if the note is an active ADR or architecture note.

3. **Dead wikilinks** — wikilinks and `related:` values from Agent B that don't resolve to
   any note path in Agent B's inventory. Severity: medium.

4. **Orphan notes** — notes from Agent B with no outgoing wikilinks in body and not
   referenced by any other note's `related:` field. Severity: low (may be intentional stubs).

5. **Tag drift** — two sub-checks:
   - Tags used in notes (Agent B) absent from `_TAG-TAXONOMY.md` → severity: medium
   - Tags in `_TAG-TAXONOMY.md` never used in any note → severity: low

6. **Frontmatter drift** — notes missing fields required by the current template for their
   `type:` value. Derive required fields by reading `_templates/TPL-<type>.md` frontmatter.
   Severity: medium (breaks Dataview queries).

7. **ADR staleness** — notes with `type: adr` and `status: active` that contain file paths
   appearing in Agent A's deleted/renamed list. Severity: high.

8. **Canvas freshness** — compare nodes in `Architecture.canvas` against components in
   Agent A output: nodes for deleted components (remove), missing nodes for new ones (add).
   Severity: medium.

9. **`_AI-CONTEXT.md` drift** — Agent B's folder list differs from what `_AI-CONTEXT.md`
   describes, or new tag conventions exist that aren't documented there. Severity: medium.

10. **Dataview query health** — Dataview blocks from Agent B that query a `FROM` path or
    filter on a `type:`/`status:` value that doesn't appear in Agent B's folder structure
    or note inventory. Severity: medium.

11. **Plugin/settings recommendations** — compare Agent B's `community-plugins.json` against
    vault usage patterns (e.g., Tasks plugin listed but no task syntax found in notes →
    flag as unused). Use `WebFetch` for one targeted lookup only if clearly useful (e.g.,
    checking whether a listed plugin has been deprecated). Severity: low.

### 4. Present the full audit report

Show all findings before touching anything. Group by severity (high → medium → low).
For each finding, show the check name, severity, affected files, and recommended action.
Finish with a summary: `N high / M medium / P low findings. Nothing changed yet.`

If no findings: report "vault is fully in sync — nothing to update" and stop.

### 5. Apply fixes (approval-gated, per section or per item)

Ask the user: approve all high-severity findings, or go item by item?

For each approved finding, apply using this decision tree:

**Safe to apply directly (no user content at risk):**
- Add missing frontmatter fields to a note (append only; never rewrite existing fields)
- Add missing `#component/<name>` tags to `_TAG-TAXONOMY.md`
- Remove unused taxonomy tags (after confirming none are used)
- Update `Architecture.canvas` nodes (add/remove nodes for new/deleted components)
- Fix a dead `related:` wikilink if the correct target is unambiguous
- Update `_AI-CONTEXT.md` folder list / tag conventions section

**Requires diff review before applying:**
- Any note whose line count is significantly larger than its template stub — show a
  side-by-side diff of proposed changes vs current content; user chooses apply / skip /
  manual-merge.

**Never apply automatically (always manual):**
- ADR body content (user's decision text)
- Session log entries
- Research findings
- Any note with `status: active` where the proposed change rewrites meaning, not just metadata

### 6. Hand off
- List every file changed and every finding skipped.
- If any findings were skipped, offer to save the unresolved list to
  `<vault-root>/00-Home/_Sync-Backlog.md` for follow-up.
- Remind the user that re-running `obsidian-vault-sync` on an up-to-date vault should
  produce zero findings.

## Guardrails
- Never start applying changes before presenting the full audit report (step 4 before 5).
- Never overwrite user-written note content without showing a diff and getting explicit
  approval. User content is irreplaceable; vault structure is not.
- Never delete notes — only flag orphans for the user to decide.
- Treat any note larger than ~2× its template stub as user-owned content; use diff review.
- If the vault root is not found, stop immediately — do not create directories or guess paths.
- Never fabricate findings: every reported issue must be traceable to something Agent A or
  Agent B actually returned.
- Keep the two scans strictly parallel; do not use one agent's output to guide the other.