Obsidian sync

Obsidian Sync

Write extracted knowledge back into the Obsidian vault. Create new notes, update existing ones, add links, and enforce deduplication.

Configuration

Read config.json from the ai-dev-os skill directory. If configured is false or the file is missing, STOP and tell the user:

"Please run /configure-ai-dev-os to set up your Obsidian vault path and Linear team."

• Obsidian vault: Use the obsidian_vault_path value from config.
• Templates folder: templates/

Input

Concept extraction report from knowledge-extract stage, containing per-concept dispositions (new/update/weak).

Pre-flight Check

Call mcp__obsidian__obsidian_list_notes on the vault root. If it fails, STOP and tell the user: "Obsidian MCP is not connected. Please open Obsidian and ensure the MCP server is running."

Procedure

Step 1: Process "new" concepts

For each concept with disposition "new":

1. Dedup check: Before creating, search one more time:

   • mcp__obsidian__obsidian_global_search with the concept name
   • mcp__obsidian__obsidian_global_search with common aliases
   • If a note with >80% title overlap is found, change disposition to "update" and proceed to Step 2 instead.

2. Read template: Call mcp__obsidian__obsidian_read_note on templates/concept.md.

3. Populate template: Replace placeholders:

   • {{Concept Name}} -> concept name
   • Fill in: Definition, Why It Matters, Mental Model
   • Fill in: Example in This Codebase (File, Lines, Explanation from the diff)
   • Fill in: Related Concepts with [[links]] to other detected concepts

4. Write note: Call mcp__obsidian__obsidian_update_note to create concepts/<concept-slug>.md with the populated content. Use mode: "overwrite" since it's a new file.

5. Set frontmatter: Call mcp__obsidian__obsidian_manage_frontmatter to set:

   • created = today (ISO 8601)
   • updated = today
   • source_ticket = ticket ID
   • confidence = 0.2 (new concept, just encountered)
   • difficulty = estimated 1-5
   • related_files = file paths from the diff
   • related_lines = line ranges from the diff
   • tags = relevant tags

Step 2: Process "update" concepts

For each concept with disposition "update":

1. Read existing note: Call mcp__obsidian__obsidian_read_note on the existing concept note.

2. Append code example: Use mcp__obsidian__obsidian_search_replace to add a new example under "## Example in This Codebase":

   • New file path and lines from the current diff
   • Explanation of how the concept appears in this change

3. Update links: If the concept is now related to new concepts not previously linked, use mcp__obsidian__obsidian_search_replace to add new [[links]] under "## Related Concepts".

4. Update frontmatter: Call mcp__obsidian__obsidian_manage_frontmatter to:

   • Update updated = today
   • Append to related_files if new files involved
   • Append to related_lines if new lines involved
   • Optionally add aliases if the concept was found under a different name

Step 3: Process architecture decisions

If the architecture-analysis stage produced an ADR:

1. Verify it exists in decision_logs/ (it should have been created during architecture-analysis).
2. If not, create it now using the same procedure as architecture-analysis Step 4.
3. Add [[links]] from the ADR to related concept notes.

Step 4: Add bidirectional links

For each pair of related concepts:

1. Check if concept A links to concept B.
2. If not, use mcp__obsidian__obsidian_search_replace to add - [[Concept B]] under concept A's "## Related Concepts".
3. Check the reverse direction and add if missing.

Step 5: Cleanup

If any notes were created in inbox/ during the process that have now been properly categorized:

• Call mcp__obsidian__obsidian_delete_note to remove the inbox copy.

Gotchas

• The dedup check uses title overlap — concepts with different names but same meaning may still create duplicates.
• Template files must exist in the Obsidian vault's templates/ folder. If missing, the skill fails at template read.
• obsidian_update_note with mode "overwrite" destroys existing content. Only use for genuinely new files.

Output

Summary of notes created and updated:

## Obsidian Sync Summary

### Notes Created
| Note | Type | Path |
|------|------|------|

### Notes Updated
| Note | Type | Path | What Changed |
|------|------|------|-------------|

### Links Added
| From | To |
|------|----|