---

name: obsidian-workspace-skill description: Development conventions and architecture guide for the Obsidian plugin monorepo.

Obsidian Workspace — Repository Skill

Project Overview

A monorepo of Obsidian community plugins sharing a common architecture enforced by a boiler-template sync engine. All plugins follow a strict 4-layer architecture with ESLint-enforced layer boundaries.

Codebase: 7 plugin submodules + 1 boiler-template, TypeScript under src/.

Tech Stack

| Component | Technology | |-----------|-----------| | Language | TypeScript (strict mode, ES modules) | | Runtime | Node.js via Obsidian's Electron | | UI Framework | Obsidian API (Views, Modals, Settings) | | Build | esbuild (esbuild.config.mjs) | | Package Manager | pnpm (workspace) | | Linter | ESLint flat config (eslint.config.mts) | | Commit Lint | commitlint + Husky hooks | | Release | Automated via scripts/release.mjs | | CI/CD | GitHub Actions (generated by boiler-template) | | Template Sync | Custom sync engine (tooling/sync/index.mjs) |

Architecture

Directory Map (per plugin src/)

| Directory | Purpose | obsidian import? | |-----------|---------|-------------------| | main.ts | Composition root — wires everything | Yes | | domain/ | Business logic, pure functions | No | | ui/ | Views, modals, settings, commands, adapters with I/O | Yes | | types/ | Pure type definitions | No | | utils/ | Pure functions, zero state | No | | shared/ | Boiler-template synced modules | Yes |

Dependency Direction

utils/ ──┐
types/ ──┼── domain/ ── ui/ ── main.ts
shared/ ─┘               │
                          └── shared/

Monorepo Layout

| Submodule | Purpose | Default Branch | |-----------|---------|----------------| | obsidian-eagle-plugin | Image upload to Eagle app | main | | open-connections | Semantic note connections via embeddings | main | | Metadata-Auto-Classifier | AI-powered metadata classification | master | | obsidian-boiler-template | Source-of-truth seed template | master | | obsidian-bible-search | Bible verse search (private) | main | | obsidian-qmd | QMD semantic search integration | main | | youtube-note-playlist | YouTube music player via yt-dlp | main |

Key Files (per plugin)

| File | Role | |------|------| | src/main.ts | Plugin entry point, onload() / onunload() | | src/ui/settings*.ts | Plugin settings tab | | src/shared/plugin-logger.ts | Structured logger (synced) | | src/shared/plugin-notices.ts | Catalog-driven notice system (synced) | | src/shared/settings-migration.ts | Settings version migration (synced) | | boiler.config.mjs | Per-plugin sync overrides | | eslint.config.mts | ESLint config (synced from boiler-template) |

Boiler-Template Key Files

| File | Role | |------|------| | tooling/sync/index.mjs | Sync engine core | | tooling/sync/targets.json | Managed plugin list | | scripts/release.mjs | Release pipeline (CI -> version bump -> tag) | | scripts/sync-to-plugins.mjs | CLI for sync operations | | tooling/shared/ | Shared source modules, scripts, infra |

Patterns & Conventions

Plugin Entry Point

Every plugin extends Plugin and uses onload() as the composition root:

// src/main.ts
import { Plugin } from 'obsidian';

export default class MyPlugin extends Plugin {
  async onload() {
    // Register commands, views, settings, event handlers
    this.addCommand({ ... });
    this.registerView(VIEW_TYPE, (leaf) => new MyView(leaf));
    this.addSettingTab(new MySettingTab(this.app, this));
    this.registerEvent(this.app.vault.on('modify', handler));
  }
  onunload() { /* cleanup */ }
}

Layer Boundary Enforcement

ESLint no-restricted-imports prevents domain/, types/, and utils/ from importing obsidian. Verified with:

rg "import.*from 'obsidian'" */src/domain/   # should return zero

Obsidian Types in Domain Code

Define shim interfaces in types/ instead of importing from obsidian:

// types/index.ts
export interface FileRef { path: string; }
export interface NoteMetadata { frontmatter?: Record<string, unknown>; }

main.ts passes real Obsidian objects which satisfy these via structural typing.

Shared Module Pattern

Modules in src/shared/ are synced from boiler-template. Never edit directly in downstream plugins — change in boiler-template, then propagate.

Naming Conventions

| Element | Convention | Example | |---------|-----------|---------| | Files | kebab-case | qmd-process-adapter.ts, query-builder.ts | | Classes | PascalCase | QmdProcessAdapter, EmbedStore | | Types/Interfaces | PascalCase | FileRef, EmbedState, PluginSettings | | Constants | SCREAMING_SNAKE_CASE | CACHE_MAX_SIZE, DEFAULT_DELAY_MS | | Functions | camelCase | parseCollectionList, sanitizeForVec | | Directories | kebab-case | domain/, ui/, shared/ |

Available Skills

| Skill | Trigger | Purpose | |-------|---------|---------| | obsidian-propagate | "sync", "propagate", "push template changes" | Sync boiler-template to downstream plugins | | obsidian-runtime-debug | Runtime errors, plugin state reset, profiling | Debug plugins in live vault with obsidian-cli | | frontend-design | Build web components, UI design | Production-grade frontend interfaces |

Agent Team

| Agent | Role | Owns | |-------|------|------| | obsidian-developer | Implementation — domain logic, infrastructure | main.ts, domain/, types/, utils/, shared/, test/ | | obsidian-ui | UX design + visual implementation | ui/settings*, ui/connections/, ui/views/, styles.css | | obsidian-qa | Runtime verification + static code review | All files (read), fixes where needed |

Mandatory Rules

1. index.ts is an entry point — re-exports and wiring only, no business logic
2. No catch-all files — utils.ts, helpers.ts, service.ts are banned
3. Single Responsibility — one file = one responsibility
4. 200 LOC hard limit — files exceeding this must be split

Release Workflow

pnpm run ci                    # build + lint + test (must pass)
pnpm release:patch|minor|major # CI -> version bump -> auto-push tag
# GitHub Actions handles the rest

git tag, git push --tags, gh release, npm publish are DENIED by settings.json.

Configuration

| Setting | Location | |---------|----------| | Plugin settings | <vault>/.obsidian/plugins/<id>/data.json | | Claude Code permissions | .claude/settings.json | | Agent definitions | .claude/agents/*.md | | Skill definitions | .claude/skills/*/SKILL.md | | ESLint config | eslint.config.mts (synced) | | Per-plugin sync | boiler.config.mjs | | Sync targets | obsidian-boiler-template/tooling/sync/targets.json |

Documentation

Detailed guides in docs/:

| Guide | Purpose | |-------|---------| | Architecture | Layer structure, dependency rules, data flow | | Exploration Guide | Study paths, grep patterns, feature-to-file mapping | | Rules | Mandatory code rules with enforcement grep commands | | Patterns | 8 proven patterns with code examples | | Gotchas | 7 known pitfalls with fixes | | Obsidian API | API quirks and workarounds | | Collaboration | Agent roles, handoff protocol, Definition of Done |

Guidelines

1. Read relevant source files before making changes — understand existing patterns first.
2. Follow the 4-layer architecture. If it needs obsidian, it belongs in ui/.
3. Keep edits minimal and focused — avoid unnecessary refactoring.
4. Never edit src/shared/ in downstream plugins — change in boiler-template, then propagate.
5. Always dry-run before syncing: node scripts/sync-to-plugins.mjs --dry-run.
6. Run pnpm run ci before declaring work complete.
7. Respect the branch strategy — never commit directly to main/master.
8. Update docs/ as project conventions evolve.