pantheon-opencode 1.0.0

package/docs/mcp-user-guide.md

@@ -0,0 +1,204 @@
+# MCP User Guide: Adding Custom Servers & Agent Awareness
+
+This guide explains how to add your own MCP servers to Pantheon and make agents aware of them.
+
+---
+
+## Quick Start
+
+Add an MCP server to your platform config. All examples below use a fictional `my-tools` server:
+
+**OpenCode** (`opencode.json`):
+```json
+{
+  "mcp": {
+    "my-tools": {
+      "type": "local",
+      "command": ["node", "my-mcp-server.js"],
+      "enabled": true
+    }
+  }
+}
+```
+
+**** (`.mcp.json`):
+```json
+{
+  "mcpServers": {
+    "my-tools": {
+      "command": "node",
+      "args": ["my-mcp-server.js"]
+    }
+  }
+}
+```
+
+** / ** (`.vscode/mcp.json` or `./mcp.json`):
+```json
+{
+  "servers": {
+    "my-tools": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["my-mcp-server.js"]
+    }
+  }
+}
+```
+
+**** (`_mcp_settings.json`):
+```json
+{
+  "mcpServers": {
+    "my-tools": {
+      "command": "node",
+      "args": ["my-mcp-server.js"]
+    }
+  }
+}
+```
+
+After adding, restart your MCP client. Verify the server connects.
+
+---
+
+## Making Agents Aware of Custom MCPs
+
+Adding a server to config is only half the work. **Agents don't auto-discover MCP tools** — you must declare them in the agent's `.agent.md` file.
+
+### Step 1: Add `mcp_tools:` to Frontmatter
+
+In the agent's YAML frontmatter, add an `mcp_tools:` block listing which tools from which server the agent can use:
+
+```yaml
+---
+name: hermes
+mcp_tools:
+  my-tools:
+    - analyze_dependency
+    - scan_vulnerabilities
+---
+```
+
+This tells the platform to inject these tool definitions into the agent's context.
+
+### Step 2: Document Tools in the Agent Body
+
+Add a `## Custom MCP Tools` section in the agent's body so the agent understands *when* and *how* to use each tool:
+
+```markdown
+## Custom MCP Tools
+
+| Server | Tool | Signature | When to use |
+|--------|------|-----------|-------------|
+| **my-tools** | `analyze_dependency(package, depth?)` | Check a dependency for known vulnerabilities |
+| **my-tools** | `scan_vulnerabilities(path)` | Scan a directory for security issues |
+```
+
+### Step 3: Set Access Control
+
+**OpenCode** (`opencode.json`):
+```json
+{
+  "permission": {
+    "mcp": {
+      "my-tools": "ask"
+    }
+  }
+}
+```
+
+Values: `allow` (auto-approve), `ask` (prompt user), `deny` (block).
+
+---
+
+## Full Example: GitHub MCP
+
+### 1. Install & Configure
+
+**OpenCode** (`opencode.json`):
+```json
+{
+  "mcp": {
+    "github": {
+      "type": "local",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "{env:GITHUB_TOKEN}"
+      },
+      "enabled": true
+    }
+  }
+}
+```
+
+### 2. Declare in Agent Frontmatter
+
+```yaml
+---
+name: iris
+mcp_tools:
+  github:
+    - create_issue
+    - list_pull_requests
+    - search_code
+---
+```
+
+### 3. Document in Agent Body
+
+```markdown
+## Custom MCP Tools
+
+| Server | Tool | Signature | What it does |
+|--------|------|-----------|-------------|
+| **github** | `create_issue(title, body, labels?)` | Create a GitHub issue in the current repo |
+| **github** | `list_pull_requests(state?: "open")` | List PRs with optional state filter |
+| **github** | `search_code(query)` | Search code across the repository |
+```
+
+### 4. Configure Permissions
+
+```json
+{
+  "permission": {
+    "mcp": {
+      "github": "ask"
+    }
+  }
+}
+```
+
+---
+
+## Best Practices
+
+| Practice | Recommendation |
+|----------|---------------|
+| **Server names** | Short, descriptive, lowercase (e.g., `github`, `postgres`, `slack`). They become the prefix. |
+| **Tool declarations** | Only declare tools the agent actually needs. |
+| **Documentation** | Always add a `## Custom MCP Tools` table with signature + purpose. |
+| **Permission** | Start with `ask` for new MCPs. Only downgrade to `allow` after verifying read-only safety. |
+| **Max MCPs** | Follow the 3-7 rule: 3 core + up to 4 custom. Beyond 7, accuracy degrades. |
+| **Naming** | Match `mcp_tools:` keys to the server name in your config. They must be identical. |
+| **Environment variables** | Use `{env:VAR}` interpolation for secrets. Never inline tokens in config. |
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Agent says "I don't have that tool" | MCP not declared in frontmatter | Add `mcp_tools:` entry |
+| Tool exists but agent doesn't use it | No body documentation | Add `## Custom MCP Tools` section |
+| "Server not found" | Config typo | Check server name matches config |
+| "Tool call failed" | Permission denied | Set to `allow` or `ask` in config |
+| Agent uses wrong tool | Too many MCPs | Reduce to ≤5 per agent |
+| Changes not taking effect | Client cache | Restart the MCP client |
+
+---
+
+## Reference
+
+- [MCP Tool Registry](mcp-tools.md) — Canonical reference of built-in Pantheon MCP tools
+- [MCP Security](skill: mcp-security) — Security hardening rules

package/docs/persistence-mcp.md

@@ -0,0 +1,111 @@
+# Pantheon Persistence MCP
+
+**Server:** `pantheon-persistence`
+**Script:** `scripts/mcp_persistence_server.py`
+**Dependencies:** Zero (stdlib only: sqlite3)
+
+A lightweight key-value store with SQLite + FTS5, TTL, and namespaces.
+Separate from `pantheon-memory` (vector/ChromaDB).
+
+## Purpose
+
+- **Cache entre agentes** — compartilhar descobertas rápidas sem ir pro ChromaDB
+- **Estado de execução** — steps de jobs, progresso, checkpoints
+- **Dados efêmeros com TTL** — cache que expira sozinho
+- **Dados locais** — tokens temporários, debug info (evita ir pro GitHub)
+
+## Architecture
+
+```
+pantheon-persistence MCP
+├── Global DB: ~/.config/opencode/persistence/global.db
+└── Project DB: .pantheon/persistence/project.db
+```
+
+- **Global**: dados cross-projeto (cache de agentes, preferências)
+- **Project**: dados específicos do projeto atual
+
+## Tools (6)
+
+### kv_store
+Store a key-value pair with optional TTL.
+
+`kv_store(namespace, key, value, ttl?, scope?)`
+- `ttl`: seconds. null = forever
+- `scope`: "project" (default) or "global"
+- Returns `{"status": "stored", "namespace": ns, "key": k}`
+
+### kv_get
+Retrieve a value by namespace + key.
+
+`kv_get(namespace, key, scope?)`
+- Auto-filters expired entries (SQL-level)
+- Returns value string or null
+
+### kv_delete
+Remove an entry.
+
+`kv_delete(namespace, key, scope?)`
+- Returns `{"status": "deleted"}` or `{"status": "not_found"}`
+
+### kv_list
+List entries in a namespace with optional prefix filter.
+
+`kv_list(namespace, prefix?, scope?, limit?)`
+- Returns array of `{key, value, created_at, expires_at}`
+- Respects TTL (expired items not returned)
+
+### kv_search
+Full-text search across all namespaces using SQLite FTS5.
+
+`kv_search(query, namespace?, scope?, limit?)`
+- BM25-ranked results
+- Terms are sanitized and quoted for injection safety
+- Returns array of `{namespace, key, value, created_at, score}`
+
+### purge_expired
+Remove expired entries and rotate deletelog.
+
+`purge_expired(scope?, dry_run?)`
+- Soft-delete with deletelog audit trail
+- dry_run previews without purging
+- Deletelog rotates at 1MB (keeps last 3)
+
+## TTL Lifecycle
+
+```python
+# Cache que expira em 1 hora
+kv_store(namespace="cache-apollo", key="api-response", value="...", ttl=3600)
+
+# Dado permanente (sobrescreve sem perder created_at)
+kv_store(namespace="config", key="db-url", value="postgres://...")
+
+# Busca: expirados são invisíveis automaticamente
+result = kv_get(namespace="cache-apollo", key="api-response")  # None se expirou
+
+# Limpeza manual (opcional — TTL já filtra na leitura)
+purge_expired(scope="project")
+```
+
+## Naming Conventions
+
+| Namespace | Purpose | TTL |
+|-----------|---------|-----|
+| `cache-{agent}` | Descobertas temporárias | 300-3600s |
+| `session-{id}` | Estado de sessão | 7200s |
+| `job-{id}` | Progresso de job | 86400s |
+| `config` | Config persistente | null |
+| `local-only` | Dados sensíveis | 3600s |
+
+## Comparison with pantheon-memory
+
+| Aspect | persistence (this) | memory |
+|--------|-------------------|--------|
+| Storage | SQLite KV | ChromaDB vector |
+| Search | FTS5 (exato/keyword) | Cosine similarity (semântico) |
+| TTL | ✅ Por entrada | ❌ Nenhum |
+| Namespace | ✅ Coluna + scope | ✅ Session + category |
+| Deploys | stdlib, 0 deps | chromadb + sentence-transformers |
+| Startup | <0.5s | 3-8s |
+| Tools | 6 | 14 |
+| Lines | 449 | 1,344 |

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "pantheon-opencode",
+  "version": "1.0.0",
+  "description": "Multi-agent orchestration for OpenCode \u2014 14 specialized agents, TDD, Themis review gates.",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "install": "node scripts/install.mjs",
+    "install:lite": "node scripts/install.mjs --clean --components agents,skills,instructions",
+    "doctor": "node scripts/doctor.mjs",
+    "init": "npx pantheon init",
+    "opencode": "OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode",
+    "start": "OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode"
+  },
+  "bin": {
+    "pantheon-orchestrator": "./bin/pantheon-init.mjs"
+  },
+  "files": [
+    "LICENSE",
+    "scripts/install/*.mjs",
+    "scripts/*.py",
+    "src/plugin.ts",
+    "README.md",
+    "src/mcp/*.txt",
+    "commands/*.md",
+    "src/skills/**/*.txt",
+    "src/skills/**/*.md",
+    "pantheon.schema.json",
+    "skills-lock.json",
+    "scripts/*.sh",
+    "src/agents/*.md",
+    "bin/*.mjs",
+    "AGENTS.md",
+    "src/mcp/*.py",
+    "src/instructions/*.instructions.md",
+    "src/mcp/*.mjs",
+    "scripts/*.mjs",
+    "src/plugins/tui/**",
+    "docs/*.md",
+    "src/mcp/*.sh",
+    "src/routing.yml",
+    "src/mcp/requirements*"
+  ],
+  "dependencies": {
+    "js-yaml": "^4.3.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.8.0",
+    "@commitlint/config-conventional": "^19.8.0",
+    "husky": "^9.1.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ils15/pantheon.git"
+  },
+  "keywords": [
+    "github",
+    "copilot",
+    "agents",
+    "skills",
+    "plugin",
+    "orchestration"
+  ],
+  "author": "ils15",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "preferGlobal": true
+}

package/pantheon.schema.json

@@ -0,0 +1,158 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://pantheon.orchestrator/schema.json",
+  "title": "Pantheon Configuration Schema",
+  "description": "Configuration schema for Pantheon multi-agent orchestration platform",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "Schema version — must follow semantic versioning (e.g., \"5.0.0\")",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "agents": {
+      "type": "object",
+      "description": "Per-agent configuration overrides. Keys must match registered agent names.",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "model": {
+            "type": "string",
+            "description": "Model identifier assigned to this agent (e.g., \"gpt-4o\", \"claude-sonnet-4\")"
+          },
+          "temperature": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 2,
+            "description": "Sampling temperature (0 = deterministic, 2 = maximum creativity)"
+          },
+          "disabled": {
+            "type": "boolean",
+            "description": "If true, the agent is excluded from routing"
+          },
+          "prompt": {
+            "type": "string",
+            "description": "Custom system prompt override for this agent"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "presets": {
+      "type": "object",
+      "description": "Named model presets for quick assignment to agents",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "model": {
+            "type": "string",
+            "description": "Model identifier (e.g., \"gpt-4o\", \"claude-sonnet-4-20250514\")"
+          },
+          "temperature": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 2,
+            "description": "Default sampling temperature for this preset"
+          },
+          "maxTokens": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1048576,
+            "description": "Maximum output tokens for this preset"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "disabled_agents": {
+      "type": "array",
+      "description": "List of agent names to globally disable from routing",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "disabled_skills": {
+      "type": "array",
+      "description": "List of skill names to disable from loading",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "disabled_mcps": {
+      "type": "array",
+      "description": "List of MCP server names to disable from initialization",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "skills": {
+      "type": "object",
+      "description": "Skill loading configuration",
+      "properties": {
+        "paths": {
+          "type": "array",
+          "description": "Additional filesystem paths to search for SKILL.md files",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "fallback": {
+      "type": "array",
+      "description": "Ordered model fallback chain. If primary model fails, fallback models are tried in sequence.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "model": {
+            "type": "string",
+            "description": "Fallback model identifier"
+          },
+          "provider": {
+            "type": "string",
+            "description": "Provider name (e.g., \"openai\", \"anthropic\", \"google\")"
+          }
+        },
+        "required": ["model"],
+        "additionalProperties": false
+      },
+      "minItems": 1
+    },
+    "routing": {
+      "type": "object",
+      "description": "Routing configuration — task-to-agent mapping rules",
+      "properties": {
+        "default_model": {
+          "type": "string",
+          "description": "Default model to use when no agent override or preset is matched"
+        },
+        "rules": {
+          "type": "array",
+          "description": "Route matching rules evaluated in order (first match wins)",
+          "items": {
+            "type": "object",
+            "properties": {
+              "pattern": {
+                "type": "string",
+                "description": "Task pattern to match (glob or regex)"
+              },
+              "agent": {
+                "type": "string",
+                "description": "Target agent name for matched tasks"
+              }
+            },
+            "required": ["pattern", "agent"],
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": ["version"],
+  "additionalProperties": false
+}

package/scripts/_pantheon_paths.py

@@ -0,0 +1,68 @@
+# Auto-generated: resolved symlink from ../src/mcp/_pantheon_paths.py
+#!/usr/bin/env python3
+"""Pantheon path resolution — global install + project root detection.
+
+Provides two functions used by all MCP servers and utility scripts:
+
+    pantheon_home() -> Path
+        Pantheon global installation directory.
+        Priority: $PANTHEON_HOME → $XDG_CONFIG_HOME/opencode → ~/.config/opencode
+
+    pantheon_project() -> Path | None
+        Current Pantheon project root.
+        Priority: $PANTHEON_PROJECT → os.getcwd() → None (resources disabled)
+
+Usage:
+    from _pantheon_paths import pantheon_home, pantheon_project
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def pantheon_home() -> Path:
+    """Return the Pantheon global installation directory.
+
+    Resolution priority:
+    1. $PANTHEON_HOME env var (explicit user override)
+    2. $XDG_CONFIG_HOME/opencode (XDG Base Directory spec)
+    3. ~/.config/opencode (POSIX default)
+
+    Returns:
+        Absolute Path to the Pantheon global config directory.
+    """
+    env = os.environ.get("PANTHEON_HOME")
+    if env:
+        return Path(env).expanduser().resolve()
+
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        return Path(xdg).expanduser().resolve() / "opencode"
+
+    return Path.home() / ".config" / "opencode"
+
+
+def pantheon_project() -> Path | None:
+    """Return the Pantheon project root directory.
+
+    Resolution priority:
+    1. $PANTHEON_PROJECT env var (explicit override)
+    2. Current working directory (set by MCP client's cwd in opencode.json)
+
+    Returns:
+        Absolute Path to the project root, or None if neither is available
+        (project-scoped resources like deepwork/memory-bank are unavailable).
+    """
+    env = os.environ.get("PANTHEON_PROJECT")
+    if env:
+        return Path(env).expanduser().resolve()
+
+    cwd = os.getcwd()
+    if cwd:
+        return Path(cwd).resolve()
+
+    return None
+
+

package/scripts/check-version-consistency.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# check-version-consistency.sh — Verifies all 3 manifests have the same version
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(dirname "$SCRIPT_DIR")"
+
+pkg_ver=$(node -p "require('$ROOT/package.json').version")
+plugin_ver=$(node -p "require('$ROOT/plugin.json').version")
+gh_plugin_ver=$(node -p "require('$ROOT/.github/plugin/plugin.json').version")
+
+echo "package.json: $pkg_ver"
+echo "plugin.json: $plugin_ver"
+echo ".github/plugin/plugin.json: $gh_plugin_ver"
+
+if [ "$pkg_ver" != "$plugin_ver" ] || [ "$pkg_ver" != "$gh_plugin_ver" ]; then
+  echo "❌ Version mismatch across manifests!"
+  echo ""
+  echo "Fix: run 'node scripts/versioning.mjs apply' to sync all manifests"
+  exit 1
+fi
+
+echo "✅ All versions match: $pkg_ver"