sync-obsidian

# Sync to Obsidian — Auto-Detect Project Sync Automatically sync your Claude Code session plans and implementation reports to your Obsidian vault. Every sync produces **two files**: a detailed Markdown note + an Obsidian Canvas visual map. The project name is **auto-detected** — no per-project configuration needed. ## Configuration Only one path to set — your Obsidian vault root: ``` OBSIDIAN_VAULT = /Users/you/Documents/Obsidian Vault ``` > Update this to your actual Obsidian vault path before first use. ## Auto Project Detection The skill automatically detects the current project name (in priority order): 1. **Git repo name**: `basename $(git rev-parse --show-toplevel)` 2. **Current directory name**: `basename $PWD` (fallback if not in a git repo) Sync targets are derived from the project name: - **Markdown**: `{OBSIDIAN_VAULT}/[Project] {project_name}/` - **Canvas**: `{OBSIDIAN_VAULT}/[Project] {project_name}/canvas/` > Directories are auto-created if they don't exist (`mkdir -p`). ## Usage ``` /sync-obsidian plan # Sync the latest plan file /sync-obsidian report # Generate and sync an implementation report /sync-obsidian plan Auth Redesign # Sync plan with custom title /sync-obsidian report API Layer # Sync report with custom title ``` - `$ARGUMENTS[0]`: Type — `plan` or `report` (required) - `$ARGUMENTS[1]`: Custom title (optional — auto-inferred from content if omitted) ## Execution Flow ### Step 0: Detect Project 1. Run `basename $(git rev-parse --show-toplevel 2>/dev/null) 2>/dev/null || basename $PWD` to get project name 2. Set `PROJECT_DIR = [Project] {project_name}` 3. Set `CANVAS_DIR = [Project] {project_name}/canvas` 4. Run `mkdir -p` to ensure both directories exist ### When type = `plan` 1. Read the latest `.md` file from `.claude/plans/` 2. If no plan file found, extract plan content from the current conversation context 3. Convert to Obsidian note format (see templates below) 4. Write Markdown to `{OBSIDIAN_VAULT}/{PROJECT_DIR}/` 5. Write Canvas to `{OBSIDIAN_VAULT}/{CANVAS_DIR}/` 6. Filename: `[Plan] {title} ({YYYY-MM-DD}).md` / `.canvas` ### When type = `report` 1. Summarize the implementation work completed in the current session 2. Include: what was done, which files changed, key design decisions, follow-up TODOs 3. Convert to Obsidian note format 4. Write Markdown to `{OBSIDIAN_VAULT}/{PROJECT_DIR}/` 5. Write Canvas to `{OBSIDIAN_VAULT}/{CANVAS_DIR}/` 6. Filename: `[Report] {title} ({YYYY-MM-DD}).md` / `.canvas` ## Markdown Templates ### Plan Template ```markdown # [Plan] {title} > Date: {YYYY-MM-DD} > Source: Claude Code Session > Project: {project_name} > Status: Pending / Approved --- {Original plan content, preserved in full markdown} --- > Synced from `.claude/plans/{filename}` ``` ### Report Template ```markdown # [Report] {title} > Completed: {YYYY-MM-DD} > Source: Claude Code Session > Project: {project_name} --- ## Summary {1-3 sentence overview} ## Completed Work {Detailed list of completed work:} - Files created/modified - Key design decisions - Technical details ## File Changes | File | Action | Description | |------|--------|-------------| | ... | Created/Modified | ... | ## Design Decisions {Important architectural/technical decisions and rationale} ## Follow-up TODO - [ ] {Next steps} --- > Auto-generated by Claude Code ``` ## Canvas Sync (Dual Output) Every Markdown sync **also generates an Obsidian Canvas file** (`.canvas`) for visual exploration. ### Canvas Structure Canvas is a JSON format with `nodes` (cards/groups) and `edges` (connections). **Report Canvas layout:** - `grp_summary` (color:4 cyan) — Summary: title + date + 1-3 sentence overview - `grp_work` (color:6 pink) — Completed work: split into sub-cards (steps, rules, etc.) - `grp_files` (color:5 purple) — File changes: table of files and operations - `grp_decisions` (color:3 green) — Design decisions: architecture/tech choices and rationale - `grp_todo` (color:2 orange) — Follow-up TODO: checklist of next steps **Plan Canvas layout:** - `grp_overview` (color:4) — Plan overview and goals - `grp_steps` (color:6) — Implementation steps, one text node per step - `grp_architecture` (color:3) — Architecture/tech decisions - `grp_risks` (color:2) — Risks and considerations **Layout principles:** - Groups connected by edges showing flow direction - Top-left start: Summary → Work/Steps → Files/Architecture → TODO - Color key: 1=red, 2=orange, 3=green, 4=cyan, 5=purple, 6=pink **Sizing rules (prevent content clipping):** - Text node min width 320px, recommended 500-660px - Estimate 35px per line of text (including line spacing) - Headers (##) at 45px, code blocks at 28px per line - Text node height = line_count × 35 + 60 (top/bottom padding) - Groups add 20px padding around contained text nodes - Minimum 80px gap between groups (vertical and horizontal) - **Better too large than too small** — clipping is worse than whitespace ## Important Rules 1. **No YAML frontmatter** — use `>` quote blocks for metadata instead 2. **Quote blocks for metadata** — date, source, status, project in `>` blocks 3. **Preserve original plan content** — never trim or rewrite technical details 4. **Reports must be specific** — list actual file paths, code patterns, design rationale 5. **Always output both files** — Markdown + Canvas on every sync 6. **Report full paths** — tell the user where both files were written 7. **Auto-create directories** — use `mkdir -p` if project or canvas dir doesn't exist ## Auto-Sync Setup (Optional) Add this to your project's `CLAUDE.md` to enable the full sync lifecycle: ```markdown ## Auto Sync to Obsidian ### Plan Sync (Before Implementation) When a plan/design discussion is complete and about to move into implementation, call `/sync-obsidian plan` FIRST — so the user can review it in Obsidian before giving the green light. Trigger when: - A plan or design discussion has been finalized - User indicates approval intent ("looks good", "let's do it") - Before starting any implementation work Flow: Discuss → Sync plan → User reviews in Obsidian → Confirmed → Implement ### Report Sync (After Implementation) After completing substantive work, call `/sync-obsidian report` before the session ends. Trigger when: - Code files were created, edited, or deleted - A plan was implemented - Important architecture discussions or decisions were made ### Do NOT trigger when: - Pure Q&A / casual chat - Only read files, no modifications - User explicitly says no sync needed ```