pantheon-opencode 1.0.1 → 1.0.6

package/docs/INSTALLATION.md

@@ -1,217 +0,0 @@
-# Pantheon Installation Guide — v1.0 (OpenCode)
-
-Pantheon v1.0 is **OpenCode-only**. It installs globally via `npx pantheon init` and works across all your projects.
-
-## Prerequisites
-
-- **OpenCode v1.18.4+** — [Install OpenCode](https://opencode.ai/docs/install)
-- **Node.js 18+** — for `npx pantheon init`
-- **Python 3.11+** — for MCP servers (optional, `npm run install`)
-- **Git** — for version detection in TUI sidebar
-
-## Quick Install
-
-```bash
-# 1. Install Pantheon agents globally
-npx pantheon init
-
-# 2. (Optional) Install MCP servers + skills + TUI plugin
-npm run install
-
-# 3. Enable background subagents
-# Add to ~/.zshrc or ~/.bashrc:
-export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
-
-# 4. Launch OpenCode with background subagents
-opencode
-```
-
-## Install Modes
-
-| Mode | Command | Installs | Time | Dependencies |
-|------|---------|----------|------|-------------|
-| **Agents only** 🟢 | `npx pantheon init` | agents + commands | ~2s | None |
-| **Full** 🔵 | `npx pantheon init && npm run install` | agents + MCPs + skills + TUI | ~60s | Python 3.11+ |
-| **Runtime** 🟡 | `npm run install` | MCP servers + venv | ~30s | Python 3.11+ |
-
-```bash
-# Agents only — just the agent rules, no Python dependencies
-npx pantheon init
-
-# Full setup — agents + MCP servers (memory, persistence, resources)
-npx pantheon init
-npm run install
-
-# Add MCP servers to an existing agents-only install
-npm run install
-```
-
-## Global vs Project-Local
-
-By default, `npx pantheon init` installs agents **globally** to `~/.config/opencode/agents/`. This makes Pantheon available in all your projects.
-
-For project-local installation (e.g., team-shared config):
-
-```bash
-npx pantheon init --project
-```
-
-This installs to `.opencode/agents/` in the current project directory.
-
-## Background Subagents
-
-Pantheon v1.0 supports **native OpenCode background delegation**. This allows dispatching up to 5 agents in parallel.
-
-**Requirement:** Set the environment variable before launching OpenCode:
-
-```bash
-export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
-opencode
-```
-
-Or use the provided npm script:
-
-```bash
-npm run start
-```
-
-**How it works:**
-
-```javascript
-// Dispatch a background task — returns immediately
-task(background=true, subagent_type="apollo", prompt="...")
-// → { task_id: "ses_xxx", state: "running" }
-
-// Collect results later
-task_status(task_id="ses_xxx", wait=true)
-// → { state: "completed", task_result: "..." }
-```
-
-**Which agents run in background:**
-
-| Agent | Background? | Why |
-|-------|------------|-----|
-| Apollo, Hermes, Aphrodite, Demeter, Hephaestus, Prometheus | ✅ Yes | Independent, long-running work |
-| Athena, Themis | ❌ No | Need full session context |
-| Talos, Iris, Nyx, Mnemosyne, Gaia | ❌ No | Quick operations |
-
-## TUI Sidebar Plugin
-
-Pantheon includes a TUI sidebar plugin showing:
-
-```
-Pantheon v1.0.0
-⎇ main
-▶ Sessions (N total)
-▶ Commands (11)
-▶ Agents (14)
-▶ Config — MCPs, Compaction
-▶ Memory — Entry count
-```
-
-The plugin is installed automatically during `npm run install`. It appears in the right sidebar of OpenCode TUI.
-
-## Commands
-
-Type these in the OpenCode chat:
-
-| Command | Description |
-|---------|-------------|
-| `/pantheon` | Council synthesis |
-| `/pantheon-status` | System status |
-| `/pantheon-audit` | Full audit |
-| `/pantheon-bg` | List background tasks |
-| `/pantheon-deepwork` | Deep work mode |
-| `/pantheon-focus` | Focus on scope |
-| `/pantheon-optimize` | Optimize memory bank |
-| `/pantheon-doc` | Generate docs |
-| `/pantheon-remember` | Memory store/recall |
-| `/pantheon-search` | Memory search |
-| `/pantheon-forget` | Compress memories |
-
-## Verification
-
-After installation, verify everything works:
-
-```bash
-# 1. Check agents are installed
-ls ~/.config/opencode/agents/
-# Should show 14 .md files
-
-# 2. Check MCP servers
-ls ~/.config/opencode/scripts/
-
-# 3. Launch OpenCode with background subagents
-export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
-opencode
-
-# 4. Test background delegation
-# Type: @zeus, task(background=true, subagent_type="apollo", prompt="test")
-```
-
-## Troubleshooting
-
-| Problem | Solution |
-|---------|----------|
-| Agents not found | Run `npx pantheon init` again |
-| MCP servers not starting | Check Python 3.11+, run `npm run install` |
-| Background delegation not available | Set `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` before launching OpenCode |
-| TUI sidebar not showing | Check `~/.config/opencode/tui.json` has `"plugins/pantheon-tui"` |
-| Plugin not loading | Ensure `~/.config/opencode/plugins/pantheon-tui/dist/tui.tsx` exists |
-
-## Installation Flow
-
-```mermaid
-flowchart LR
-    A["npx pantheon init"] --> B{"--project?"}
-    B -->|No| C["~/.config/opencode/agents/ (global)"]
-    B -->|Yes| D[".opencode/agents/ (project-local)"]
-    C --> E["npm run install"]
-    D --> E
-    E --> F["MCP servers + skills + TUI"]
-    F --> G["export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true"]
-    G --> H["opencode"]
-    H --> I["🚀 Pantheon v1.0 ready"]
-```
-
-## Background Delegation Flow
-
-```mermaid
-sequenceDiagram
-    participant Z as Zeus
-    participant A as Apollo (bg)
-    participant D as Demeter (bg)
-    participant T as Themis (sync)
-
-    Z->>+A: task(background=true, "discover")
-    Z->>+D: task(background=true, "schema")
-    Note over Z: Max 5 concurrent
-    
-    A-->>Z: task_status(wait=true) → result
-    D-->>Z: task_status(wait=true) → result
-    
-    Z->>+T: task("review")
-    Note over T: Athena/Themis NEVER background
-    T-->>-Z: review complete
-```
-
-## TUI Sidebar Layout
-
-```mermaid
-block-beta
-    columns 1
-    block["Pantheon v1.0.0"]
-        block("⎇ main")
-        end
-        block Sessions["▶ Sessions (N total)"]
-        end
-        block Commands["▶ Commands (11)"]
-        end
-        block Agents["▶ Agents (14)"]
-        end
-        block Config["▶ Config"]
-        end
-        block Memory["▶ Memory"]
-        end
-    end
-```

package/docs/MCP.md

@@ -1,238 +0,0 @@
-# Pantheon MCP Servers
-
-Pantheon provides 3 built-in MCP (Model Context Protocol) servers that enhance
-AI agent capabilities with persistent memory, resource discovery, and
-confined script execution. All three are local Python servers that auto-start
-with OpenCode.
-
----
-
-## Server Comparison
-
-| Server | Tools | Resources | Purpose |
-|--------|-------|-----------|---------|
-| **pantheon-resources** | — | 3 static + 5 templates | Agent discovery, skills, routing, deepwork plans, memory-bank |
-| **pantheon-code-mode** | 1 | 1 static + 1 template | Confined script execution from `.pantheon/code-mode/` |
-| **pantheon-memory** | 14 | 2 static | Persistent memory with semantic search, recall, knowledge graph |
-
----
-
-## Quick Start
-
-Add to your platform config (e.g., `opencode.json` or `.mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "pantheon-resources": {
-      "command": "python3",
-      "args": ["scripts/mcp_resources_server.py"]
-    },
-    "pantheon-code-mode": {
-      "command": "python3",
-      "args": ["scripts/code_mode_server.py"]
-    },
-    "pantheon-memory": {
-      "command": "python3",
-      "args": ["scripts/memory_mcp_server.py"]
-    }
-  }
-}
-```
-
-Restart your MCP client. The servers auto-start and connect.
-
-### Permission Tiers
-
-In `opencode.json`, set auto-approve levels:
-
-```json
-"permission": {
-  "mcp": {
-    "pantheon-resources": "allow",
-    "pantheon-code-mode": "ask",
-    "pantheon-memory": "allow"
-  }
-}
-```
-
-- **pantheon-resources** → `allow` (read-only, same trust boundary as repo)
-- **pantheon-code-mode** → `ask` (script execution needs explicit confirmation)
-- **pantheon-memory** → `allow` (read/write within agent sandbox)
-
----
-
-## pantheon-resources
-
-**Script:** `scripts/mcp_resources_server.py`
-
-Read-only resource server exposing Pantheon framework metadata. No tools, only
-resources and resource templates accessible via `pantheon://` URIs.
-
-### Static Resources
-
-| URI | Description |
-|-----|-------------|
-| `pantheon://routing` | Full content of `routing.yml` — canonical delegation rules, handoff contracts, agent registry |
-| `pantheon://agents` | List of all 14 Pantheon agents with roles from YAML frontmatter |
-| `pantheon://skills` | List of all Pantheon skills with descriptions |
-
-### Resource Templates (Parameterized URIs)
-
-| URI Template | Description |
-|-------------|-------------|
-| `pantheon://agents/{agent_name}` | Content of a single agent file by name (case-insensitive) |
-| `pantheon://deepwork/{slug}` | `PLAN.md` content for a deepwork task slug |
-| `pantheon://deepwork/{slug}/status` | `STATUS.md` content for a deepwork task (or default IN_PROGRESS) |
-| `pantheon://memory-bank/{path}` | Content of a file within `.pantheon/memory-bank/` by relative path (path traversal blocked) |
-| `pantheon://skills/{name}` | Content of a skill's `SKILL.md` file by name |
-
-### Usage
-
-```python
-# Read via MCP resource URI
-read_mcp_resource(server="pantheon-resources", uri="pantheon://agents")
-read_mcp_resource(server="pantheon-resources", uri="pantheon://routing")
-read_mcp_resource(server="pantheon-resources", uri="pantheon://skills/hermes")
-```
-
-### Good For
-
-- Discovering which agents exist and their roles
-- Reading routing/delegation rules during orchestration
-- Loading skill instructions on demand
-- Checking deepwork plan status
-- Reading memory-bank files by path
-
----
-
-## pantheon-code-mode
-
-**Script:** `scripts/code_mode_server.py`
-
-Confined script execution server. Runs `.sh` and `.py` scripts from
-`.pantheon/code-mode/` with a 30-second timeout.
-
-### Tool
-
-| Tool | Description |
-|------|-------------|
-| `execute_code_script(script_name)` | Execute a script from `.pantheon/code-mode/` and return output |
-
-### Resources
-
-| URI | Description |
-|-----|-------------|
-| `pantheon://code-mode/scripts` | List all available code-mode scripts |
-| `pantheon://code-mode/scripts/{name}` | View script content by name |
-
-### Security Rules
-
-- Only `.sh` and `.py` files are allowed
-- Scripts must live in `.pantheon/code-mode/`
-- 30-second execution timeout
-- Permission tier set to `ask` (requires user confirmation)
-- Path traversal outside `.pantheon/code-mode/` is blocked
-
-### How to Create a Script
-
-Create a `.sh` or `.py` file in `.pantheon/code-mode/`:
-
-```bash
-#!/bin/bash
-# .pantheon/code-mode/deploy.sh
-echo "Deploying..."
-npm run build
-```
-
-Then run it from an agent:
-
-```
-execute_code_script("deploy.sh")
-```
-
-### Usage by Agent
-
-| Agent | Use Case |
-|-------|----------|
-| **zeus** | Automated orchestration sequences (build → test → deploy) |
-| **prometheus** | Docker builds, CI/CD pipelines, deployment scripts |
-| **hermes** | Test runner, lint automation |
-| **talos** | Hotfix automation, batch fixes |
-
----
-
-## pantheon-memory
-
-**Script:** `scripts/memory_mcp_server.py`
-
-Persistent, multi-strategy memory server using ChromaDB + sentence-transformers
-(all-MiniLM-L6-v2) for local embeddings. Provides 14 tools and 2 resources.
-
-### Tools (14)
-
-| Tool | Description |
-|------|-------------|
-| `memory_store` | Store a memory entry with metadata (category, agent, session, importance, links) |
-| `memory_search` | Search with dense vector similarity + freshness decay + importance boost |
-| `memory_recall` | Auto-recall: context → relevant memories as formatted prompt injection |
-| `memory_compress` | Compress oldest entries into summarized form (DCP-style range compression) |
-| `memory_expand` | Restore a compressed entry back to detailed form |
-| `memory_consolidate` | Merge duplicate/similar entries (cosine similarity threshold) |
-| `memory_delete` | Permanently delete a specific memory entry by ID |
-| `memory_update` | Update content and/or metadata of an existing entry |
-| `memory_link` | Create a bidirectional relationship between two entries |
-| `memory_traverse` | Walk the knowledge graph from an entry, following links up to max_depth |
-| `memory_verify` | Verify a claim: check entry exists and validate freshness |
-| `memory_sessions` | List all unique session IDs with entry count and latest timestamp |
-| `memory_export` | Export memories as formatted markdown, optionally scoped to a session |
-| `memory_cleanup` | Delete test/old sessions (prefix minimum 3 characters) |
-
-### Resources
-
-| URI | Description |
-|-----|-------------|
-| `pantheon://memory/sessions` | List all sessions with entry counts and timestamps |
-| `pantheon://memory/status` | Memory server statistics: total entries, session count, disk usage |
-
-### Tech Stack
-
-| Component | Implementation |
-|-----------|---------------|
-| Vector DB | ChromaDB `PersistentClient` → `~/.pantheon/memory/chroma.sqlite3` |
-| Embeddings | `sentence-transformers/all-MiniLM-L6-v2` (~80MB, offline, one-time download) |
-| Freshness decay | 30-day half-life (exponential, Shokunin-inspired) |
-| Compression | DCP-style range compression (deterministic, not LLM-based) |
-| Fusion scoring | Dense similarity + freshness boost + importance boost |
-
-### Full Documentation
-
-See `docs/MEMORY.md` for complete usage guide with examples for all 14 tools.
-
----
-
-## When to Use Which Server
-
-| Need | Server |
-|------|--------|
-| Read routing.yml, agent list, skill files | pantheon-resources |
-| Check deepwork plan or status | pantheon-resources (`pantheon://deepwork/{slug}`) |
-| Read memory-bank files | pantheon-resources (`pantheon://memory-bank/{path}`) |
-| Run a shell/Python script safely | pantheon-code-mode |
-| Store an important fact across sessions | pantheon-memory |
-| Find relevant past decisions | pantheon-memory |
-| Link related memories into a graph | pantheon-memory |
-| Auto-recall context at session start | pantheon-memory |
-| Export session memories as markdown | pantheon-memory |
-
----
-
-## Troubleshooting
-
-| Symptom | Likely Cause | Fix |
-|---------|-------------|-----|
-| Server not found | Not in MCP config | Add to `opencode.json` → `mcp` or `.mcp.json` |
-| Connection refused | Python env issue | Verify `python3` has required deps (`chromadb`, `sentence-transformers`, `fastmcp`) |
-| `memory_recall` returns empty | No entries stored yet | First call `memory_store` with some content |
-| Code-mode script not found | Wrong path | Script must be in `.pantheon/code-mode/` |
-| Path traversal error | Invalid URI segment | Use flat filenames for `pantheon://memory-bank/{path}` (no nested `../`) |