🔧 OMP

The core specification and architectural blueprint for the OMP (Oh My Pi) AI agent framework.

---

1. 🎯 Concept Map

  [Profile] ──> [Agent] ──> [Task] ──> [Todo (Sequential)] OR [Task (Subagents Parallel)]
                  │
        ┌─────────┴─────────┐
        ▼                   ▼
  [Extensions]         [Skills / Rules]
  (Host Hooks & Tools) (Agent Prompt Context)

---

2. 💡 Core Terms

📦 Extension

• Definition: Host-side executable TypeScript/JavaScript modules loaded dynamically by the OMP core using loaders like jiti.
• Role: Registers tools (pi.registerTool), slash commands (pi.registerCommand), and listens to lifecycle hooks (pi.on("session_start")).

📦 Plugin

• Definition: The packaging and CLI installation mechanism for OMP extensions.
• Role: Resolves NPM packages or local folders and maps their resources into active extensions or MCP servers under ~/.omp/plugins/.

🤖 Agent

• Definition: The active AI execution unit consisting of a reasoning LLM model and standard tools.
• Role: Executes the reasoning loop and runs tools. Spawns specialized subagents (explore, plan, oracle, etc.) for parallel tasks.

🧠 Skill

• Definition: Agent-side instruction sheets that guide the AI on tool usage, coding styles, or domain methodologies.
• Role: Written as SKILL.md with YAML frontmatter. Dynamically injected into the LLM prompt context based on query matches.

⚖️ Rule

• Definition: Guidelines and behavioral constraints governing the agent. Operates on two distinct tiers:
  • Hard Rules: Actionable memory records (confidence >= 0.85, types: avoid_pattern, prefer_pattern) stored in OmpKeep’s L2 SQLite database.
  • Domain Rules: File-based instruction sheets (e.g. .windsurf/rules/*.md) loaded based on the current workspace context.

👤 Profile

• Definition: Configurations representing identity, boundaries, and model options. Operates on two tiers:
  • Agent Profile: Synthesized persona, skills, talents, and capabilities for a specific task.
  • Project Profile: Workspace boundary scope resolved from the cwd to isolate memory and configuration records.

📋 Task

• Definition: The atomic unit of work assigned to the agent.
• Role: Managed sequentially in a phase using the todo checklist or split into sub-assignments executed concurrently by subagents.

---

3. 🔧 pi Manifest

To publish or configure a local package (a pi-package) for tinkering, the package.json must be structured as follows:

{
  "name": "my-pi-extension",
  "version": "1.0.0",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./index.ts"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

• 🚨 Gotcha: You must include "pi-package" in the keywords array to be discovered by the local loader.
• 🚨 Gotcha: OMP loads TypeScript source files directly via jiti, so explicit build compilation is not required.

---

4. 🔍 Self-Verification Checklist

Before saving, verify the cheat sheet against these rules:

• No paragraph exceeds 2 sentences.
• All commands are copy-pasteable and grouped.
• File paths are exact and absolute where required.
• No fluff words (e.g. “basically”, “essentially”, “just”, “simply”).
• Formatted correctly with appropriate markdown syntax.

---

5. 🔗 Related

• 🧠 OmpKeep — persistent memory & session indexing
• 🔀 Shared Memory — OMP ↔ Hermes memory bridge
• 🪨 Quartz 5 — static-site generator powering the SSOT wiki
• ✅ Quartz 5 Checklist — deployment checklist