obsidian-bridge

obsidian-bridge

Overview

Store the docs Claude produces (specs, plans, impl notes, best-practices, testing standards) in ONE central Obsidian vault, and implement any plan by naming its note. Docs are vault-native: written straight into the vault, not the code repo. Every note records source_repo so implementation knows which codebase to edit.

The deterministic mechanics are a Python CLI. Run it from the skill directory: python -m obsidian_bridge <command> --help. You supply the judgment: classifying docs, curating standards, and injecting them into implementation.

Capabilities

setup

Find the vault: python -m obsidian_bridge setup --vault "<path>". Detect <path> by reading ~/Library/Application Support/obsidian/obsidian.json (the CLI's vault module exposes find_vault). If no vault exists, create the directory first, then run setup. Setup scaffolds folders, installs Dataview, and writes the dashboard. If Dataview install warns (offline), tell the user the dashboard will render once they install Dataview from Obsidian's community plugins.

register + write

When you produce a spec or plan, write it into the vault with write_doc:

from obsidian_bridge import projects
projects.write_doc(vault_path, project="<repo-basename>", doc_type="spec",
                   topic="<slug>", date="<YYYY-MM-DD today>",
                   source_repo="<absolute repo path>", status="draft",
                   body="<full markdown body>")

doc_type ∈ spec|plan|impl. topic is a kebab-case slug derived from the doc title (lowercase, spaces→hyphens, drop punctuation) — it becomes the filename <date>-<topic>.md. write_doc auto-registers the project if needed.

This OVERRIDES the default superpowers spec/plan location — set the spec-location preference to the vault so brainstorming and writing-plans output land here automatically.

import (first run AND re-runs, opt-in)

Re-runnable any time — running it again re-scans the project for new docs. Steps:

1. importer.scan_docs(repo) lists candidate docs. It already excludes agent/instruction files (CLAUDE.md, AGENTS.md, GEMINI.md, SKILL.md) and noise dirs (build/deps, .claude, .cursor, .obsidian).
2. CLASSIFY in parallel to save context and time. REQUIRED SUB-SKILL: superpowers:dispatching-parallel-agents. Dispatch one subagent per doc (or per small batch) on a small model (haiku) with model: "haiku"; each reads its file and returns ONLY structured JSON {type, topic, status, confidence} where type ∈ spec|plan|impl|best-practice|tests. The main agent never reads the doc bodies. Drop low-confidence results and report them as "needs manual classification".
3. Skip already-imported docs: for each candidate compute its repo-relative path and call importer.find_existing_copy(vault, rel_path). If a copy already exists, do NOT re-import it (avoids duplicates).
4. Split the remaining docs by git status with importer.is_git_tracked:
   • Untracked → action: "move" (relocate into the vault).
   • Git-tracked → ask the user ONCE, as a single bulk choice covering ALL git-tracked docs (never per file): (a) copy + remember + refresh — action: "copy", which records source_file so future re-imports can refresh it; (b) move into the vault — action: "move"; (c) keep as-is — action: "skip" (default). Apply the one chosen action to every git-tracked doc.
5. Present the full plan, get confirmation, then importer.apply_migration(vault, decisions) (each decision carries its action). For existing copies whose source file changed and where the user chose copy+refresh, call importer.refresh_copy(note, file).

consolidate

For bulk reorganizing/deduping notes already in the vault, also fan out to haiku subagents (one per note or per cluster) that return compact structured summaries/decisions; the main agent merges the results. Same principle: keep large-document reading off the main context.

dashboard

00-Dashboard.md uses live Dataview queries — no maintenance needed.

implement

Triggered by "implement ":

1. notes.resolve_note(vault, name). If multiple, ASK which.
2. Read the note; get source_repo from frontmatter. If missing, ask the user and backfill it.
3. notes.load_necessities(vault, project) and read each standard.
4. Hand off to REQUIRED SUB-SKILL superpowers:executing-plans (or superpowers:subagent-driven-development), writing code into source_repo, enforcing the loaded standards as constraints.
5. notes.set_status(note, "in-progress") then "done".

Standards & necessities (auto-curate, report after)

Best-practices and testing notes live in Standards/ (shared) or Projects/<p>/standards/ (project-specific). Each project hub note has a necessities: list of the standards that govern it.

On register and during implement: assess the codebase, then UPDATE the hub's necessities — add applicable standards, author new reusable ones, prune irrelevant ones — and REPORT what you changed. Decide autonomously; do not ask first, but always tell the user the diff.

Frontmatter schema

project, type, topic, created, status, source_repo, related, tags (+ scope for standards). source_repo is mandatory on every spec/plan/impl note — it is the only link back to the code.

Common mistakes

• Writing docs into the repo instead of the vault (docs are vault-native).
• Moving git-tracked docs during import without asking (default is leave).
• Implementing without loading necessities (standards must constrain the work).
• Forgetting source_repo, leaving a note that cannot be implemented.