pantheon-opencode 1.0.1 → 1.0.6

package/docs/ARCHITECTURE.md

@@ -1,384 +0,0 @@
-# 🏛️ Pantheon Architecture
-
-> **Audience:** Developers extending the framework, platform integrators, and anyone who
-> wants to understand why Pantheon works the way it does.
->
-> **Scope:** Architectural rationale and design patterns — not agent behavior or setup.
-
----
-
-## Table of Contents
-
-1. [Conductor-Delegate Pattern](#1-conductor-delegate-pattern)
-2. [Canonical → Adapter → Sync](#2-canonical--adapter--sync)
-3. [DAG Wave Execution](#3-dag-wave-execution)
-4. [Two-Tier Memory Strategy](#4-two-tier-memory-strategy)
-5. [Platform Adapter Design Pattern](#5-platform-adapter-design-pattern)
-6. [Model Configuration](#6-model-configuration)
-7. [Summary: Why This Architecture](#7-summary-why-this-architecture)
-
----
-
-## 1. Conductor-Delegate Pattern
-
-### Problem
-
-Traditional single-agent coding forces one agent to plan, implement, test, review, and
-document simultaneously. This produces context fragmentation (80%+ on logistics, ~20% on
-reasoning), skipped tests, generic code, and no quality accountability.
-
-### Solution
-
-**Zeus orchestrates but never implements.** Zeus has a `premium` model assignment and
-a restricted tool set (no `edit/editFiles`). His only job is routing work to the right
-specialist agent at the right time, managing the 3 approval gates, and conserving context.
-
-```
-User Request
-     │
-     ▼
-┌─────────┐
-│  ZEUS   │  Orchestrator — delegates, never edits
-└────┬────┘
-     │
-     ├──► Athena (planning, research)
-     ├──► Hermes (backend, FastAPI)
-     ├──► Aphrodite (frontend, React)
-     ├──► Demeter (database, SQLAlchemy)
-     ├──► Themis (quality gate, mandatory review)
-     └──► ...
-```
-
-### Why this matters
-
-| Metric | Single Agent | Conductor-Delegate (Pantheon) |
-|--------|-------------|-------------------------------|
-| Reasoning-to-logistics ratio | 10–20% reasoning | 70–80% reasoning |
-| Test coverage | 65–75% | **92%** |
-| TDD enforcement | Optional | **Enforced RED→GREEN→REFACTOR** |
-| Bugs reaching production | 3–5 per feature | **Near zero** |
-| Code review cadence | End of feature | **After every phase** |
-
-The key insight: **specialization beats generalization at every layer.** Hermes knows
-FastAPI async patterns and nothing about React. Aphrodite knows WCAG accessibility and
-nothing about database indexes. Gaia knows remote sensing and nothing about Docker.
-The result is expert-quality code at each layer, assembled by Zeus into a coherent
-feature.
-
-### Delegation decisions
-
-Zeus uses explicit rules to decide whether to delegate or not:
-
-| Agent | Delegate when | Don't delegate when |
-|-------|--------------|---------------------|
-| Athena | Feature >3 components, unknown codebase | Simple single-file change |
-| Apollo | Needs >3 parallel searches | Single known file location |
-| Themis | After any implementation phase | Hotfix (no code change) |
-
----
-
-## 2. Canonical → Adapter → Sync
-
-### Problem (before v3.4.0)
-
-Each platform (OpenCode, , , , , Continue) had its own agent
-format with different field capabilities, different tool naming conventions, and different
-configuration patterns. A single change required editing 6 files — and they were never quite
-identical. Bugs like `temis_delegate` (missing the "h") propagated across platforms because
-there was no single source of truth.
-
-### Solution
-
-A three-layer architecture:
-
-```
-┌─────────────────────────────────────────────────────┐
-│                  1. CANONICAL                        │
-│  agents/*.agent.md — single source of truth          │
-│  Rich YAML frontmatter + full body text              │
-│  Fields: name, description, tools, model, skills,     │
-│          handoffs, permission, hooks, mcpServers,      │
-│          temperature, steps, globs                    │
-└──────────────────────┬──────────────────────────────┘
-                       │ read by
-                       ▼
-┌─────────────────────────────────────────────────────┐
-│                  2. ADAPTER                           │
-│  platform/*/adapter.json — translation rules         │
-│  Defines: include, exclude, transform, toolMap,      │
-│           bodyFilters, handoffStrategy, skillsOutput  │
-│                                                       │
-│  Example (OpenCode adapter):                          │
-│  - Canonical "execute/runInTerminal" → "bash"         │
-│  - Canonical "agent" → "createAndRunTask"             │
-│  - Excluded: handoffs, disable-model-invocation       │
-└──────────────────────┬──────────────────────────────┘
-                       │ consumed by
-                       ▼
-┌─────────────────────────────────────────────────────┐
-│                  3. SYNC ENGINE                       │
-│  scripts/sync-platforms.mjs — generates outputs      │
-│  - Reads canonical agents                            │
-│  - Applies adapter translation rules                 │
-│  - Generates platform-native files                   │
-│  - Validates body tool references                    │
-│  - Deploys skills in platform format                 │
-│  - Reports validation warnings                       │
-└─────────────────────────────────────────────────────┘
-```
-
-### What the sync engine does
-
-- **Parses frontmatter** — Extracts YAML from `---` blocks
-- **Applies adapter rules** — Includes/excludes fields per platform, transforms values
-- **Maps tools** — Converts canonical tool names to platform equivalents (e.g.,
-  `execute/runInTerminal` → `bash` for OpenCode)
-- **Transforms body references** — Rewrites tool references in agent body text to
-  platform-correct equivalents
-- **Deploys skills** — Copies skill files to platform-specific skill directories
-- **Validates** — Checks that every tool mentioned in body text exists in the agent's
-  tool list (catching stale references at sync time, not at runtime)
-- **Reports warnings** — Missing skills, deprecated fields, unmapped tools
-
-### Deduplication
-
-The sync engine uses composite dedup keys (`${tool}:${mapped}`) to correctly handle
-platforms where the same canonical tool maps to different platform tools. This prevents
-false duplicates while ensuring no tool appears twice.
-
-### Real-world impact (v3.4.0)
-
-- **416 files changed** — 119 modified + 297 new skill deployment files
-- **`temis_delegate` fixed** — 11 occurrences across canonical source, generated files,
-  and stale deployment copies
-- **174 skills deployed** — 29 skills × 6 platforms, each in the format their runtime
-  expects
-- **Zero manual platform editing** required for the entire v3.4.0 migration
-
----
-
-## 3. DAG Wave Execution
-
-### Problem
-
-Sequential phase execution (plan → implement backend → implement frontend → review →
-deploy) wastes agent idle time. Backend and frontend have no interdependencies — they
-could execute in parallel.
-
-### Solution
-
-Instead of a flat sequential list, Zeus organizes work into **DAG waves** — groups of
-tasks that have no interdependencies and can execute simultaneously. Waves flow
-sequentially only where dependencies exist.
-
-```
-Wave 1: [demeter: schema] + [apollo: research]        ← parallel (no deps)
-                    │
-Wave 2: [hermes: backend] + [aphrodite: frontend]     ← parallel (both use Wave 1 schema)
-                    │
-Wave 3: [themis: review]                              ← sequential (depends on Waves 1+2)
-                    │
-Wave 4: [prometheus: deploy]                          ← sequential (depends on approval)
-```
-
-### Wave declaration format
-
-When Zeus dispatches a wave, it announces the parallel execution explicitly:
-
-```
-🔀 WAVE 2 — Parallel Execution
-Tasks in this wave (no interdependencies):
-  ├─ @hermes   → POST /reviews endpoint + tests
-  └─ @aphrodite → ReviewCard component with mocked data
-Both execute simultaneously. Wave 3 starts after both complete.
-```
-
-### Benefits
-
-| Aspect | Sequential | DAG Wave |
-|--------|-----------|----------|
-| Total time | Sum of all phases | **Longest path only** |
-| Idle agents | Waiting for previous to finish | **Always busy** |
-| Context reuse | One agent at a time | **Parallel specialized agents** |
-| Risk detection | Late (at integration) | **Early (per wave)** |
-| Feedback loop | End of each phase | **End of each wave** |
-
-### When DAG is not used
-
-- **Simple features** (single implementation agent) — no parallelization needed
-- **Hotfixes** (Talos) — express lane bypasses orchestration entirely
-- **Sequential dependencies** — must chain (e.g., Themis always waits for implementation)
-
----
-
-## 4. Two-Tier Memory Strategy
-
-### Problem
-
-Project memory was a single bucket: everything went into `.pantheon/memory-bank/`. But not all
-knowledge has the same access pattern. Permanent facts (stack, commands) should always be
-available at zero token cost. Sprint narratives should be read only when needed.
-
-### Solution
-
-Three tiers with distinct storage, loading policies, and update frequency:
-
-```
-Tier 1: Native Memory (Facts)
-  Location:  /memories/repo/                ← auto-managed by 
-  Content:   Stack, test commands, directory structure, immutable truths
-  Access:    ✅ Auto-loaded — zero token cost
-  Updated:   Rarely (when stack changes)
-  Written by: Any agent, automatically
-
-Tier 2: Reference Memory (Narrative)
-  Location:  .pantheon/memory-bank/              ← committed to repo
-  Content:   Project overview (00), architecture (01), components (02),
-             tech context (03), active sprint (04), progress log (05),
-             ADRs (_notes/), task records (_tasks/)
-  Access:    ❌ Loaded on demand — read cost per file
-  Updated:   Sprint boundaries, decision milestones
-  Written by: Mnemosyne (on explicit request)
-
-Tier 3: Session Memory (Ephemeral)
-  Location:  /memories/session/             ← auto-managed by 
-  Content:   Current conversation plans, work-in-progress, temporary findings
-  Access:    One read per conversation session
-  Updated:   Continuously within session
-  Written by: Any agent, automatically
-```
-
-### Learning Routing Triple
-
-Knowledge is categorized to prevent duplication:
-
-| Category | Where | Auto-loaded? | Example |
-|----------|-------|-------------|---------|
-| **Facts** | `/memories/repo/` | ✅ Yes | "Project uses FastAPI + SQLAlchemy" |
-| **Patterns** | `skills/` | ❌ On demand | "How to create a new API endpoint with TDD" |
-| **Conventions** | `.github/-instructions.md` | ✅ Yes | "Use snake_case for Python" |
-
-**Rule:** If content belongs in a different category, **move it — don't duplicate**.
-
----
-
-## 5. Platform Adapter Design Pattern
-
-### Problem
-
-Seven platforms (, OpenCode, , , , , Continue),
-each with different agent file formats, tool naming conventions, and configuration
-patterns. A design without abstraction would require maintaining 7 parallel copies of
-every agent.
-
-### Solution
-
-A **platform adapter** is a JSON configuration file (`platform/<name>/adapter.json`)
-that defines how to translate the canonical agent format into a platform-specific
-format:
-
-```jsonc
-{
-  "name": "opencode",
-  "outputDir": "agents",
-  "fileExtension": ".md",
-
-  // What frontmatter fields to include/exclude/transform
-  "frontmatter": {
-    "include": ["name", "description", "tools", "skills", "instructions"],
-    "exclude": ["handoffs", "disable-model-invocation", "permission",
-                "hooks", "mcpServers", "temperature", "steps", "globs"],
-    "transform": {
-      "tools": { "strategy": "identity" },
-      "model": { "strategy": "omit" }
-    }
-  },
-
-  // Canonical tool name → platform tool name mapping
-  "toolMap": {
-    "search/codebase": "search/codebase",
-    "edit/editFiles": "edit/editFiles",
-    "execute/runInTerminal": "bash"         // <-- renamed for OpenCode
-  },
-
-  // Body text filters (omit sections that don't apply)
-  "bodyFilters": [
-    { "pattern": " Workflow", "action": "omit-section" }
-  ],
-
-  // Skill deployment configuration
-  "skillsOutputDir": "skills",
-  "deploySkills": true,
-  "handoffStrategy": "exclude",
-  "ensureAgentTool": false
-}
-```
-
-### Adapter fields in detail
-
-| Field | Purpose | Example values |
-|-------|---------|---------------|
-| `frontmatter.include` | Fields to include in output | `["name", "tools", "skills"]` |
-| `frontmatter.exclude` | Fields to strip | `["handoffs", "hooks"]` |
-| `frontmatter.transform` | Field-level transformations | `{tools: {strategy: "map"}}` |
-| `toolMap` | Canonical → platform tool mapping | `"execute/runInTerminal": "bash"` |
-| `bodyFilters` | Section-level body text filtering | Omit " Workflow" section |
-| `skillsOutputDir` | Where to deploy skill files | `"skills"` |
-| `deploySkills` | Whether to sync skills | `true` / `false` |
-| `handoffStrategy` | How to handle handoff YAML | `"exclude"` / `"include"` / `"body-only"` |
-| `ensureAgentTool` | Add `agent` tool if missing | `true` / `false` |
-
-### Platform capability matrix
-
-| Feature |  | OpenCode |  |  |  |  | Continue |
-|---------|:-------:|:--------:|:-----------:|:-----:|:--------:|:-----:|:--------:|
-| Parallel subagents | ✅ | ✅ | ⚠️ | ✅ | ❌ | ⚠️ | ⚠️ |
-| Handoff UI | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Agent hooks | ✅ | ⚠️ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| MCP servers | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
-| Skills system | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-
-### Template for new platforms
-
-A template adapter is at `platform/_template/adapter.json`. To add a new platform:
-1. Create `platform/<name>/adapter.json` with translation rules
-2. Add a setup guide to `docs/platforms/<name>.md`
-3. Extend `scripts/install.mjs` and `scripts/sync-platforms.mjs` for the new platform
-4. Run `node scripts/sync-platforms.mjs <name>` to generate the first set of files
-
----
-
-## 6. Model Configuration
-
-Pantheon does NOT hardcode models by default. Each agent uses your
-platform's account default model.
-
-### Provider prefix
-
-The model ID prefix determines which provider OpenCode uses:
-- `opencode-go/...` → OpenCode Go provider (recommended)
-- `openai/...` → OpenAI provider
-
-### Reference configs
-
-Example model configurations are in `platform/examples/`.
-These are documentation only — not used at runtime.
-
----
-
-## 7. Summary: Why This Architecture
-
-| Decision | Problem it solves | Key benefit |
-|----------|------------------|-------------|
-| **Conductor-Delegate** | Context fragmentation in single-agent coding | 70-80% reasoning, 92% coverage |
-| **Canonical → Adapter → Sync** | 6 copies of every agent, divergent formats | Change once, deploy to all platforms |
-| **DAG Wave Execution** | Sequential idle time, slow feedback | Total time = critical path only |
-| **Two-Tier Memory** | Mixed knowledge with wrong access patterns | Facts free, narrative on demand |
-| **Platform Adapter** | 7 different agent runtimes to support | Pluggable architecture, easy to extend |
-| **Model Configuration** | Hardcoded model names across subscriptions | Any provider, no config needed |
-
-> **Design philosophy:** Pantheon is configuration, not code. There are zero framework
-> Python/TypeScript source files. The entire system is `.agent.md` (agent definitions),
-> `adapter.json` (translation rules), `.instructions.md` (quality gates), and
-> `SKILL.md` (domain expertise). This makes it trivially extensible — adding an agent is
-> creating a markdown file, not writing a class.

package/docs/BRANCH-PROTECTION.md

@@ -1,142 +0,0 @@
-# Branch Protection: `main`
-
-> **Why this matters:** Branch protection prevents force-pushes, requires passing
-> CI checks before merge, enforces linear history, and ensures no one (not even
-> admins) can bypass the pipeline. Without it, the agent orchestration pipeline
-> (Iris → Themis → merge) is just a suggestion, not a guarantee.
-
----
-
-## Enable Protection via GitHub UI
-
-1. Go to your repo on github.com → **Settings** → **Branches** (sidebar).
-2. Click **Add branch protection rule** (or **Add rule**).
-3. In **Branch name pattern**, enter: `main`
-4. Enable the following checkboxes:
-
-### ✅ Required Settings
-
-| Setting | Checkbox label | Why |
-|---|---|---|
-| ✅ | **Require a pull request before merging** | All changes go through a PR reviewed by Themis/Iris |
-| ✅ | **Require approvals** — set to `1` | At least one reviewer must approve |
-| ✅ | **Dismiss stale pull request approvals when new commits are pushed** | Re-review after changes |
-| ✅ | **Require status checks to pass before merging** | Block merge if CI fails |
-| ✅ | **Require branches to be up to date** | Prevents merge skew |
-
-### 🔍 Required Status Checks
-
-Add these exact check names (they match the Pantheon CI workflows):
-
-- `CI / validate`
-- `PR Checks / label-by-title`
-- `PR Checks / recommend-version`
-
-> **Tip:** Type each name in the search box and select it. GitHub will auto-suggest
-> matching check names once the workflow has run at least once on `main`.
-
-### 🔒 Additional Protections
-
-| Setting | Checkbox label | Value |
-|---|---|---|
-| ✅ | **Require linear history** | — (on) — Prevents merge commits, keeps history clean |
-| ✅ | **Include administrators** | — (on) — Even admins must follow the rules |
-| ❌ | **Allow force pushes** | — (off) — Never allow force pushes |
-| ❌ | **Allow deletions** | — (off) — Never allow branch deletion |
-
-### 🚀 Apply Rule
-
-Click **Create** (or **Save changes**).
-
----
-
-## Alternative: `gh` CLI
-
-If you prefer the command line, use the GitHub CLI to apply the same settings:
-
-```bash
-gh api repos/:owner/:owner/branches/main/protection \
-  --method PUT \
-  --field required_status_checks='{
-    "strict": true,
-    "checks": [
-      {"context": "CI / validate"},
-      {"context": "PR Checks / label-by-title"},
-      {"context": "PR Checks / recommend-version"}
-    ]
-  }' \
-  --field enforce_admins=true \
-  --field required_pull_request_reviews='{
-    "required_approving_review_count": 1,
-    "dismiss_stale_reviews": true
-  }' \
-  --field required_linear_history=true \
-  --field allow_force_pushes=false \
-  --field allow_deletions=false
-```
-
-> **Note:** Replace `:owner` with your GitHub username or org (`ils15`).
-> You need `admin` or `write` permissions on the repo to run this command.
-
----
-
-## Verification
-
-After enabling protection, verify it's active:
-
-```bash
-gh api repos/ils15/pantheon/branches/main/protection --jq '.required_status_checks.contexts'
-```
-
-Expected output:
-```json
-[
-  "CI / validate",
-  "PR Checks / label-by-title",
-  "PR Checks / recommend-version"
-]
-```
-
-You can also check the GitHub UI: **Settings → Branches → `main` rule** shows
-a green "Protection enabled" badge.
-
----
-
-## How This Enforces the Agent Pipeline
-
-```
-                              ┌─────────────────────────────┐
-                              │  User pushes to feature/    │
-                              │  branch                     │
-                              └──────────┬──────────────────┘
-                                         │
-                                         ▼
-                              ┌─────────────────────────────┐
-                              │  Iris opens Draft PR        │
-                              │  → CI / validate runs       │
-                              │  → PR Checks / label,       │
-                              │    version-recommend        │
-                              └──────────┬──────────────────┘
-                                         │
-                                         ▼
-                              ┌─────────────────────────────┐
-                              │  All status checks pass?    │
-                              │  ─── NO ───→ Fix & re-push  │
-                              │  ─── YES ───↓               │
-                              └──────────┬──────────────────┘
-                                         │
-                                         ▼
-                              ┌─────────────────────────────┐
-                              │  Themis reviews & approves  │
-                              └──────────┬──────────────────┘
-                                         │
-                                         ▼
-                              ┌─────────────────────────────┐
-                              │  User says "merge"          │
-                              │  → Iris merges (squash)     │
-                              │  → Linear history preserved │
-                              └─────────────────────────────┘
-```
-
-Without branch protection, any of these steps can be skipped by a force-push
-or a direct commit to `main`. Enable it once and never worry about it again.

package/docs/INDEX.md

@@ -1,81 +0,0 @@
-# Pantheon Documentation Index
-
-> **A multi-agent orchestration framework** — 14 specialized agents, OpenCode, 40 skills.
-
----
-
-## Quick Navigation
-
-| If you need... | Go here |
-|---|---|
-| **What is Pantheon?** | [README.md](../README.md) |
-| **Quick start / Install** | [INSTALLATION.md](INSTALLATION.md) |
-| **Which platform to pick** | [PLATFORMS.md](PLATFORMS.md) |
-| **Agent reference** | [AGENTS.md](../AGENTS.md) |
-| **MCP tiers & tools** | [mcp-tools.md](mcp-tools.md), [mcp-user-guide.md](mcp-user-guide.md) |
-| **Release process** | [RELEASING.md](RELEASING.md) |
-| **Contributing** | [CONTRIBUTING.md](../CONTRIBUTING.md) |
-| **Changelog** | [CHANGELOG.md](../CHANGELOG.md) |
-| **MCP Tool Registry** | [mcp-tools.md](mcp-tools.md) |
-| **MCP User Guide** | [mcp-user-guide.md](mcp-user-guide.md) |
-| **MCP Tiers** | `.pantheon/tiers.json` |
-
----
-
-## Architecture at a Glance
-
-**Pantheon** replaces the single-agent coding trap with **specialized agents**:
-- **Zeus** orchestrates the workflow (plan → implement → review → deploy)
-- **Athena** plans architecture; **Apollo** discovers code; **Hermes/Aphrodite/Demeter/Prometheus** implement
-- **Themis** reviews every phase (mandatory quality gate); **Mnemosyne** documents decisions
-- **Iris** manages GitHub; **Talos** handles hotfixes; **Gaia** analyzes remote sensing
-
-All agents live as **canonical `.agent.md` files** in `agents/` and are auto-generated into platform-specific formats via the [sync engine](../scripts/sync-platforms.mjs).
-
----
-
-## Platform Support Matrix
-
-| Platform | Format | Status | Install Method |
-|---|---|---|---|
-| ** ** | `.agent.md` | ✅ Active | Plugin marketplace, `/pantheon-install`, or `./sync-platform.sh copilot` |
-| **OpenCode** | `.md` + `opencode.json` | ✅ Active | `/pantheon-install` or `./sync-platform.sh opencode` |
-| **** | `.md` (comma-separated tools) | ✅ Active | `node scripts/install.mjs claude` or `./sync-platform.sh claude` |
-| **** | `.mdc` rules | ✅ Active | `node scripts/install.mjs cursor` or `./sync-platform.sh cursor` |
-| **** | `.md` (stub) | ✅ Active | `node scripts/install.mjs windsurf` or `./sync-platform.sh windsurf` |
-| **** | `.md` | ✅ Active | `node scripts/install.mjs cline` or `./sync-platform.sh cline` |
-| **** | `.md` rules | ✅ Active | `node scripts/install.mjs continue` or `./sync-platform.sh continue` |
-
----
-
-## Where to Find What
-
-| Concern | Location |
-|---|---|
-| Agent definitions (edit here) | `agents/*.agent.md` |
-| Platform configs (auto-generated) | `platform/<name>/agents/` |
-| Shared skills | `skills/<name>/SKILL.md` |
-| Standards & instructions | `instructions/*.instructions.md` |
-| Prompt templates | `prompts/*.prompt.md` |
-| GitHub Actions workflows | `.github/workflows/` |
-| CI/CD hooks | `scripts/hooks/` |
-| MCP tool registry (canonical) | [docs/mcp-tools.md](mcp-tools.md) |
-| MCP user guide (adding custom MCPs) | [docs/mcp-user-guide.md](mcp-user-guide.md) |
-| MCP tiers (none/essential/recommended/full) | `.pantheon/tiers.json` |
-| MCP recommendations per project type | [docs/mcp-recommendations.md](mcp-recommendations.md) |
-| Project memory (sprints, decisions) | `.pantheon/memory-bank/` |
-| Plugin manifests | `plugin.json`, `.github/plugin/plugin.json` |
-
----
-
-## Platform READMEs
-
-Each platform has its own README with installation notes and format details:
-
-- [OpenCode](../platform/opencode/README.md)
-- [](../platform/claude/README.md)
-- [](../platform/cursor/README.md)
-- [](../platform/windsurf/README.md)
-- [](../platform/cline/README.md) *(coming soon)*
-- [Continue](../platform/continue/README.md)
-- [Template (add new platform)](../platform/_template/README.md)