| name | pop-obsidian |
| description | Plugin Orchestration Protocol (POP) for Obsidian integration. Use this skill when the user mentions "POP", "Obsidian plugin", "pipeline orchestration", "idea to publish", "websocket bridge", "plugin manifest", "Obsidian automation", "note-to-paper pipeline", "knowledge pipeline", or wants to orchestrate multi-step workflows through Obsidian. This skill implements the 5-phase JSON-RPC protocol over WebSocket for real-time plugin orchestration.
|
| version | 1.0.0 |
POP Super-Obsidian — Plugin Orchestration Protocol
The POP protocol enables real-time orchestration of multi-step pipelines through Obsidian.
It connects Claude (orchestrator), Obsidian (vault + UI), and the Rust TUI (monitoring dashboard)
via JSON-RPC over WebSocket at ws://127.0.0.1:8088.
Protocol Overview
POP operates in 5 phases, each with specific JSON-RPC message types:
Phase 1: Discovery
Message: GET_PLUGIN_MANIFEST
Purpose: Ask the Obsidian plugin what capabilities are installed.
{
"jsonrpc": "2.0",
"method": "GET_PLUGIN_MANIFEST",
"id": 1
}
Response: Returns a manifest of all installed Obsidian plugins with their exposed actions.
Use this to understand what the vault can do before constructing a pipeline.
Phase 2: Orchestration
Message: EXECUTE_PIPELINE
Purpose: Send a named pipeline with steps to execute.
{
"jsonrpc": "2.0",
"method": "EXECUTE_PIPELINE",
"params": {
"pipeline": "idea-to-publish",
"steps": [
{"id": "spark", "action": "create_note", "params": {"title": "...", "content": "..."}},
{"id": "expand", "action": "ai_expand", "params": {"note_id": "$spark.output.id"}},
Step references: Use $step_id.output.field to reference outputs from previous steps.
This creates a DAG of dependencies that the orchestrator resolves in topological order.
Phase 3: Progress
Message: STEP_COMPLETE
Direction: Obsidian → Claude (notification)
{
"jsonrpc": "2.0",
"method": "STEP_COMPLETE",
"params": {
"pipeline_id": "...",
"step_id": "expand",
"status": "complete",
"output": {"id": "note-abc", "content": "..."},
"wave_score": 0.91,
"duration_ms": 1250
}
}
Each step completion is forwarded to the Rust TUI for real-time gauge updates.
Phase 4: Coherence
Message: COHERENCE_REPORT
Purpose: Full pipeline coherence assessment after all steps complete.
{
"jsonrpc": "2.0",
"method": "COHERENCE_REPORT",
"params": {
"pipeline_id": "...",
"overall_score": 0.89,
"step_scores": {"spark": 0.92, "expand": 0.91, "visual": 0.87, "verify": 0.93},
"conservation_check": {"alpha": 7, "omega": 8, "sum": 15, "valid": true}
If overall_score < coherence_threshold, the pipeline is flagged for review.
Phase 5: Error
Message: PIPELINE_FAILED
Direction: Either direction (any party can signal failure)
{
"jsonrpc": "2.0",
"method": "PIPELINE_FAILED",
"params": {
"pipeline_id": "...",
"failed_step": "visual",
"error": "Figure generation timed out",
"partial_outputs": {"spark": "...", "expand": "..."},
"recovery": "retry_step"
}
}
Recovery options: retry_step, skip_step, abort, rollback
Built-in Pipelines
Read references/pipeline-templates.md for full pipeline definitions.
Quick Reference
| Pipeline | Trigger | Steps |
|---|
| idea-to-publish | "idea to publish", "note to paper" | Spark → Expand → Visual → Verify → Assemble → Export |
| research-digest | "research digest", "literature summary" | Fetch → Summarize → Score → Tag → Canvas |
| quantum-circuit | "quantum circuit", "place redstone" | Generate → Verify → Export mcfunction → Place |
| paper-draft | "draft paper", "write paper" | RAG → AI-Researcher → AutoFigure → WAVE → PDF |
Connection Architecture
Claude (Orchestrator)
↓ JSON-RPC
ws://127.0.0.1:8088
↓
Rust WebSocket Bridge (crates/websocket-bridge)
├── → Obsidian Plugin (vault operations)
├── → Rust TUI (crates/tui — monitoring dashboard)
└── → WAVE Scorer (coherence at each transition)
The Rust bridge is the central hub. It:
- Receives EXECUTE_PIPELINE from Claude
- Dispatches steps to Obsidian
- Receives STEP_COMPLETE from Obsidian
- Forwards telemetry to the TUI
- Runs WAVE checks at transitions
- Sends COHERENCE_REPORT back to Claude
Authentication
All POP messages include an ATOM token for authentication:
$ATOM_TOKEN_RESONANCE — generated via atom_tag_generate- Token encodes: session ID, agent identity, coherence threshold, conservation proof
- Five-strand anyon braid topology (see docs/ATOM_AUTH.md)
Implementing the Obsidian Side
The Obsidian plugin needs to:
- Listen on ws://127.0.0.1:8088 for incoming connections
- Expose GET_PLUGIN_MANIFEST with all installed plugin actions
- Handle EXECUTE_PIPELINE by running steps against the vault
- Report STEP_COMPLETE after each step with outputs and timing
- Generate COHERENCE_REPORT using vault content analysis
For the TypeScript implementation details, read references/protocol-spec.md.
