@ps-inc/opencode-obsidian

An OpenCode plugin that turns your Obsidian vault into an AI-managed project workspace. Track work items, search and update notes, audit link hygiene, generate roadmaps, assess technical feasibility, and keep your vault tidy — all from your OpenCode session.

Prerequisites

• OpenCode CLI installed
• Obsidian installed (running recommended for live sync)
• ob CLI optional but recommended for headless vault sync and link-aware renames

Install

Copy opencode.json.example to opencode.json in your project root (or merge into your existing OpenCode config):

// opencode.json
{
	"$schema": "https://opencode.ai/config.json",
	"default_agent": "vault-orchestrator",
	"plugin": ["@ps-inc/opencode-obsidian"],
}

default_agent makes vault-orchestrator the session entry point for general vault work. PM slash commands still route to pm-creator, pm-analyst, and pm-implement as needed.

Setup

Create .opencode/vault-assistant.json in your project root (copy from .opencode/vault-assistant.json.example):

{
	"vault": "/absolute/path/to/your/obsidian/vault",
	"main-model": "anthropic/claude-sonnet-4-20250514",
	"explorer-model": "google/gemini-2.0-flash",
	"executor-model": "openai/gpt-4o-mini",
	"worker-model": "google/gemini-2.0-flash",
	"modules": {
		"core": { "enabled": true },
		"pm": {
			"enabled": true,
			"project": "project - Your Project Name"
		}
	}
}

On first load the plugin also writes:

• Skill files to ~/.config/opencode/skills/ — vault conventions, PM workflows, and tool references
• Project rules to .opencode/rules/*.md — lazy-loaded workflow guides
• .opencode/AGENTS.md — index of agents, commands, and when to load rules/skills (only created if missing)

Skill and rule lifecycle

The plugin uses a safe-overwrite manifest to keep your customisations intact across upgrades:

• On each load the plugin compares each shipped skill/rule against the on-disk file using a sha256 hash recorded in a sidecar manifest (~/.config/opencode/skills/.opencode-obsidian-manifest.json and .opencode/rules/.opencode-obsidian-manifest.json).
• Unmodified files (on-disk hash matches manifest) are silently updated when the shipped content changes.
• User-modified files (on-disk hash differs from manifest) are never overwritten. The plugin logs them and surfaces them via doctor.
• Pre-manifest files whose content already matches the latest shipped version are silently adopted into the manifest on first contact.
• .opencode/AGENTS.md keeps its legacy never-overwrite semantics on first install so you can customise it freely.

To overwrite a customised skill or rule on purpose, use:

bunx opencode-obsidian update-skills --force <skill-name>
bunx opencode-obsidian update-rules  --force <rule-filename>
# or to overwrite EVERY customised entry in one shot:
bunx opencode-obsidian update-skills --force-all
bunx opencode-obsidian update-rules  --force-all
# preview what would change:
bunx opencode-obsidian update-skills --dry-run

bunx opencode-obsidian doctor reports any user-modified or untracked skill/rule files so you know when an upgrade is being skipped.

Tiered models

Assign cheaper/faster models to worker roles via vault-assistant.json or environment variables:

| Config field | Env fallback | Used by | | ---------------- | ------------------------- | --------------------------------------------------- | | main-model | OPENCODE_MODEL_MAIN | vault-orchestrator, PM agents | | explorer-model | OPENCODE_MODEL_EXPLORER | note-explorer, link-auditor, bases-inspector | | worker-model | OPENCODE_MODEL_WORKER | note-updater, note-compressor, batch-executor | | executor-model | OPENCODE_MODEL_EXECUTOR | vault-executor |

Leave a field empty to fall back to your OpenCode default model.

How It Works

The plugin registers vault() and pm() tools plus a tiered agent hierarchy:

vault-orchestrator (primary) ──Task──► note-explorer, note-updater, vault-executor, …
pm-creator / pm-analyst / pm-implement ──Task──► core subagents for vault I/O
                                      └──pm()──► PM intelligence (create, status, roadmap, …)

• vault-orchestrator — default entry point for general vault work; delegates to specialized subagents
• Core subagents — narrow roles with JSON handoff schemas (search, mutate, compress, audit, execute)
• PM agents — project-management reasoning via pm(); vault reads/writes go through Task delegation (no direct vault() access)

Use /vault-* commands for general vault operations and /pm-* commands for project management.

Choosing an agent

| Use case | Agent / command | | ---------------------------------- | ------------------------------------------------------------------------------- | | General vault search, read, update | /vault-search, /vault-read, /vault-update → vault-orchestrator | | PM work items | /pm-create, /pm-status, … → pm-creator or specialists | | Ad-hoc session | Set primary agent to vault-orchestrator in OpenCode, or invoke slash commands |

Vault Commands

| Command | What it does | | -------------------- | ------------------------------------------------- | | /vault-search | Search vault notes by query | | /vault-read | Read note(s) with structured JSON output | | /vault-update | Apply structured mutations to notes | | /vault-lint | Audit broken links, orphans, and hygiene | | /vault-summarize | Compress notes into token-efficient digests | | /vault-connections | Show backlinks, outgoing links, and graph context |

All vault commands delegate to vault-orchestrator, which routes work to the appropriate core subagent.

PM Commands

| Command | What it does | | ----------------- | ----------------------------------------------------------------------------------- | | /pm-create | Create a new work item (Epic, Feature, Story, Task, or Bug) | | /pm-status | Get a health summary for a project or specific item | | /pm-next | Get 2–4 recommended backlog items to pick up next | | /pm-roadmap | Generate an ordered roadmap view; optionally write it to your vault | | /pm-assess | Technical feasibility analysis — approaches, risks, effort estimate | | /pm-code-status | Check acceptance criteria against the current codebase | | /pm-implement | Generate a structured implementation plan (read-only — plans only, no code written) | | /pm-tidy | Audit all PM notes for issues; auto-fix safe ones | | /pm-audit | Detect drift between PM items and the codebase; interactive update with approval | | /pm-recommend | Recommend new items + improvements to existing items; interactive review | | /pm-groom | Single-project grooming session — audit + recommend + improve, with one approval |

PM commands use pm-creator, pm-analyst, or pm-implement depending on the workflow. These agents call pm() for PM logic and Task core subagents for vault I/O.

Grooming workflow

The audit, recommend, and groom operations follow a deterministic discover → review → apply pipeline:

1. Discover — pm({ operation: "groom" }) returns kind-only diagnostics (drift entries, improvement proposals, new-item proposals).
2. Polish split — pm-creator polishes new-item proposals; pm-analyst polishes improvement proposals; both return JSON.
3. Review — agent emits a PendingApproval JSON payload (or numbered caveman bullets); user approves with 1,3,5 | all | all drift | all gaps | all improvements | none.
4. Apply — coordinator builds a GroomApplyPlan and calls pm({ operation: "apply", plan }) to atomically execute every approved write.

The pure plan layer (buildGroomPlan) plus the deterministic apply tool means the agent decides what to propose, but how writes happen is fully predictable and testable.

Vault Structure

The plugin expects (and creates) this structure inside your vault:

<vault>/
└── _Projects/
    └── <Project Name>/
        ├── project - <Project Name>.md    ← project root note
        ├── _epics/                        ← epic - *.md
        ├── _features/                     ← feature - *.md
        └── _stories/                      ← story - *.md, task - *.md, bug - *.md

Work Item Frontmatter

Every PM note carries structured frontmatter that the plugin reads and writes:

---
PM_Type: Story # Epic | Feature | Story | Task | Bug
PM_Status: Backlog # see Status Chain below
PM_Project: project - My Project
PM_Parent: feature - Login with OAuth # optional, no .md extension
PM_Created: 2026-05-21
PM_DepsInternal: story - Auth session, task - DB schema # optional
---

Status Chain

Backlog → In Progress → Development → Code Review → QC → Stage → Done / Completed
                                                                   Cancelled (any state)

Terminal states (Done, Completed, Cancelled) cannot transition further.

Naming Convention

Files follow <type-lower> - <description>.md:

epic - User Authentication System.md
feature - Login with OAuth.md
story - User can reset password.md
task - Add bcrypt hashing.md
bug - Login fails on special chars.md

Roadmap

Running /pm-roadmap with write mode creates two files in your project directory:

• <Project> Roadmap.base — a live Obsidian Bases view that automatically updates as note frontmatter changes. Shows In Progress, Backlog, and Done columns filtered to your project. Created once; customise it freely via the Obsidian UI.
• roadmap.md — a document combining the live Bases views with agent-managed sections. On subsequent runs, the plugin refreshes only Up Next (unblocked backlog suggestions) and Blocked (items with unresolved dependencies). Your Focus Notes section is never touched.

Tidy

/pm-tidy scans all PM notes and reports issues:

| Issue | Auto-fixable | | -------------------------------------------------- | -------------- | | Deprecated frontmatter fields | ✅ | | PM_Type casing errors | ✅ | | Resolved deps still listed in PM_DepsInternal | ✅ | | Missing required fields | — agent review | | Broken PM_Parent references | — agent review | | Orphaned items (no parent, no children) | — agent review | | Parent Done but child still open | — agent review | | Stale "In Progress" (>21 days unchanged) | — agent review | | Missing Description / Acceptance Criteria sections | — agent review | | Naming convention mismatches | — agent review |

Run pm({ operation: "tidy", fix: true }) (or /pm-tidy) to apply safe fixes automatically, then let the agent work through the flagged items.

Connections & Context

Before acting on a work item, agents call pm({ operation: "connections", path }) to surface:

• Parent chain — up to 3 levels up (Story → Feature → Epic)
• Children — direct child items
• Backlinks — other vault notes that link to this item (daily notes, wiki articles, related stories)
• Outgoing links — wiki links referenced in the item body

Daily notes mentioning a story, or wiki articles linked from a feature, are automatically surfaced when work begins.

Agents

| Agent | Mode | Role | | -------------------- | -------- | ------------------------------ | | vault-orchestrator | primary | Routes vault work to subagents | | note-explorer | subagent | Search, read, connections | | note-updater | subagent | Structured note mutations | | vault-executor | subagent | Exact vault() calls | | note-compressor | subagent | Token-efficient digests | | link-auditor | subagent | Broken links, orphans | | batch-executor | subagent | Multi-step vault batches | | bases-inspector | subagent | Obsidian Bases queries (CLI) | | pm-creator | subagent | Create and manage work items | | pm-analyst | subagent | Feasibility and code status | | pm-implement | subagent | Implementation planning |

Skill Files

On first load, the plugin writes these files to ~/.config/opencode/skills/:

| Skill | Purpose | | ------------------ | ------------------------------------------------------------------------------------- | | obsidian-vault | Vault conventions, sync protocol, .base file rules | | obsidian-bases | How to query Obsidian Bases views | | vault-search | Search and read workflow | | vault-update | Structured mutation workflow | | vault-lint | Link hygiene audit workflow | | vault-summarize | Compression workflow | | pm-conventions | Type hierarchy, naming, frontmatter — generated with your vault path and project list | | pm-tool-guide | Complete pm() tool reference with examples | | pm-implement | Implementation planning workflow and plan format | | wiki-curator | Wiki ingestion and maintenance (future module) | | code-scribe | Code pattern documentation (future module) | | daily-summarizer | Daily note review (future module) |

Agents load skills on demand — see .opencode/AGENTS.md and .opencode/rules/ for the lazy-load index.

Module flags

Enable or disable modules in vault-assistant.json:

"modules": {
  "core": { "enabled": true },
  "pm": { "enabled": true, "project": "project - My Project" },
  "wiki": { "enabled": false },
  "code": { "enabled": false },
  "daily": { "enabled": false }
}

When a module is disabled, its agents, commands, and tools are not registered.

Integrations

Opt-in cross-cutting integrations enabled in vault-assistant.json:

"integrations": {
  "serena":   { "enabled": true },
  "caveman":  { "enabled": true, "mode": "full" },
  "subtask2": { "enabled": true },
  "spotme":   { "enabled": true, "defaultDifficulty": "medium", "defaultEvery": 2 }
}

| Integration | Purpose | | ----------- | ------------------------------------------------------------------------------------------------------------------ | | Serena | Symbol-level code intelligence via MCP for code_status / assess ops | | Caveman | Token-efficient agent response style (short, dense, no preamble) | | Subtask2 | Agentic loop primitives — parallel execution, prompt chaining | | SpotMe | Gym mode — pm-implement / code-scribe / wiki-curator scaffold work and hand off to you instead of completing |

Missing external dependencies (Serena MCP server, Subtask2 plugin, SpotMe plugin) are surfaced via bunx opencode-obsidian doctor, which enumerates configured integrations and reports which prerequisites are present.

Provider seams (future-pluggable)

The plugin is structured around two pluggable interfaces so backends can be swapped without rewriting domain logic:

• PmStore — abstracts where PM items live. Ships with ObsidianPmStore (filesystem). Future adapters can target Azure DevOps, GitHub Issues, or GitLab without changing auditProject / recommendProject / groomProject.
• AgentHarness — abstracts which agent runtime registers agents/commands/hooks. Ships with createOpenCodeHarness. Future adapters can target Claude Code, Cursor, or Codex.

Both interfaces have a shared contract test suite (runPmStoreContract, runAgentHarnessContract) so new adapters can prove compliance with a one-line wiring file.

See ARCHITECTURE.md and docs/providers.md for the adapter-authoring guide.

Coming Soon

The following modules are registered as stubs (skills are written so agents learn the conventions; commands are not yet implemented).

| Module | Commands (planned) | | ------ | ------------------------------------------- | | Wiki | /wiki-ingest, /wiki-query, /wiki-lint | | Code | /code-pattern, /code-summarize | | Daily | /daily-summarize, /daily-review |

Documentation

| Document | Audience | | -------------------------------------- | ---------------------------------------------------- | | README.md | Users — installation, configuration, commands | | ARCHITECTURE.md | Contributors — layers, seams, extension points | | CONTRIBUTING.md | Contributors — dev setup, gates, conventions | | docs/TESTING.md | Contributors — test-utils, contract suites, patterns | | docs/providers.md | Adapter authors — adding a PmStore / AgentHarness | | AGENTS.md | AI agents working in this repo — caveman quickref | | CHANGELOG.md | Release notes (semantic-release generated) |

License

MIT