pantheon-opencode 2.1.5 → 2.2.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/AGENTS.global.md +1 -1
  2. package/AGENTS.md +1 -1
  3. package/CHANGELOG.md +58 -0
  4. package/README.md +60 -242
  5. package/README.pt-BR.md +64 -220
  6. package/package.json +7 -1
  7. package/plugin.json +1 -1
  8. package/pyproject.toml +1 -1
  9. package/scripts/build-plugin.mjs +1 -1
  10. package/scripts/install/opencode.mjs +12 -0
  11. package/scripts/install-mcp.mjs +55 -27
  12. package/src/agents/roster.json +562 -0
  13. package/src/agents/zeus.md +4 -1
  14. package/src/instructions/backend-standards.instructions.md +5 -0
  15. package/src/mcp/pantheon-mcp-server.mjs +508 -0
  16. package/src/mcp/pantheon_vision.py +4 -1
  17. package/src/pantheon/deepwork/deepwork-tool.ts +23 -75
  18. package/src/pantheon/deepwork/plan-schema.ts +4 -2
  19. package/src/pantheon/deepwork/plan-tracker.ts +380 -90
  20. package/src/pantheon/jev-decision-tool.ts +1 -7
  21. package/src/pantheon/local-decision-tool.ts +1 -1
  22. package/src/pantheon/native-vision.ts +1 -1
  23. package/src/pantheon/skill-search-tool.ts +118 -44
  24. package/src/pantheon/tool-context.ts +23 -0
  25. package/src/pantheon/tools.ts +46 -42
  26. package/src/plugin/index.js +9008 -361
  27. package/src/plugin/index.ts +42 -14
  28. package/src/plugin.ts +53 -1
  29. package/src/plugins/tui/dist/tui.d.ts +73 -6
  30. package/src/plugins/tui/dist/tui.d.ts.map +1 -1
  31. package/src/plugins/tui/dist/tui.js +1201 -444
  32. package/src/plugins/tui/dist/tui.js.map +1 -1
  33. package/src/plugins/tui/package-lock.json +2 -2
  34. package/src/plugins/tui/package.json +1 -1
  35. package/src/plugins/tui/src/index.tsx +639 -116
  36. package/src/plugins/tui/src/pantheon-settings.tsx +64 -13
  37. package/src/plugins/tui/src/quota-state.ts +128 -0
  38. package/src/plugins/tui/src/tui-prefs.ts +164 -21
package/AGENTS.global.md CHANGED
@@ -1,7 +1,7 @@
1
1
  <!-- pantheon:generated:begin — Pantheon-managed region; regenerated on install/upgrade, never edit inside -->
2
2
  <!-- Generated by scripts/build-agents-md.mjs — do not edit directly. -->
3
3
  <!-- Source of truth: src/instructions/*.instructions.md + the static sections in this script. -->
4
- <!-- pantheon:agents-md v2 artifact=global generated-at=2026-11-14T14:44:27-03:00 sha=053433e -->
4
+ <!-- pantheon:agents-md v2 artifact=global generated-at=2026-11-16T06:25:36-03:00 sha=de352bf -->
5
5
 
6
6
  # Pantheon Agent System — OpenCode
7
7
 
package/AGENTS.md CHANGED
@@ -1,7 +1,7 @@
1
1
  <!-- pantheon:generated:begin — Pantheon-managed region; regenerated on install/upgrade, never edit inside -->
2
2
  <!-- Generated by scripts/build-agents-md.mjs — do not edit directly. -->
3
3
  <!-- Source of truth: project sections in scripts/build-agents-md.mjs. -->
4
- <!-- pantheon:agents-md v2 artifact=project generated-at=2026-11-14T14:44:27-03:00 sha=053433e -->
4
+ <!-- pantheon:agents-md v2 artifact=project generated-at=2026-11-16T06:25:36-03:00 sha=de352bf -->
5
5
 
6
6
  # Pantheon — Repository Setup
7
7
 
package/CHANGELOG.md CHANGED
@@ -13,6 +13,64 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
13
13
  `node scripts/versioning.mjs apply --notes` pre-fills the generated sections from conventional commits.
14
14
  Running apply will move this section to a versioned entry and reset the template below. -->
15
15
 
16
+ ## [v2.2.0-beta.1] - 2026-11-17
17
+
18
+ ### 🆕 What's New
19
+
20
+ - **Native Node.js MCP Server**: Migrated MCP servers from Python (`.venv`) to 100% native Node.js ESM (`src/mcp/pantheon-mcp-server.mjs`).
21
+ - **Quotas & Spend Tab**: Added dedicated "Cotas & Gastos" tab in Pantheon Settings inspired by `@slkiser/opencode-quota`.
22
+ - **Dynamic Auto-Provisioning**: Automated agent provisioning via `agent.transform` from canonical roster on `opencode update`.
23
+ - **Single-Command Plugin Installation**: Supported native single-command install via `opencode plugin add pantheon-opencode`.
24
+ - **Stabilized Sidebar TUI**: Interactive `[compact]` button, color tokens, no line wrapping, docked layout, theme & accent colors.
25
+
26
+ ### Added
27
+
28
+ - **mcp** — `src/mcp/pantheon-mcp-server.mjs`: zero-dependency native Node.js MCP server with `node:sqlite` memory, persistence, resources, and code-mode.
29
+ - **tui** — `src/plugins/tui/src/quota-state.ts`: Quota & spend tracking store with provider window limits, alerts, and cost projections.
30
+ - **tui** — `buildQuotaTab` in `src/plugins/tui/src/pantheon-settings.tsx`: settings tab displaying live API quotas, token limits, and spend.
31
+ - **plugin** — `src/plugin.ts`: automated `agent.transform` provisioning of Zeus, Athena, Hermes, Aphrodite, and specialists from canonical roster.
32
+ - **plugin** — package export `.` allowing native `opencode plugin add pantheon-opencode` without custom init scripts.
33
+
34
+ ## [v2.1.7] - 2026-11-16
35
+
36
+ ### 🆕 What's New
37
+
38
+ - **Native Plugin Entrypoint**: Added root exports (`"."`, `"./server"`, `"./tui"`), enabling `opencode plugin add pantheon-opencode` support.
39
+ - **Interactive Compaction**: Wired `[compact]` button with pointer events and toast feedback triggering native session compaction.
40
+ - **Semantic Theme Polish**: Vibrant colors for turn cost, cache hit, reasoning tokens, and block header icons.
41
+ - **Next-Gen TUI Layout**: Dense bilateral row layouts (`justifyContent="space-between"`) matching the Next-Gen proposal without line wrap.
42
+ - **Telemetry & Cache Speed**: Cache hit percentage paired with generation speed (`Speed: 72 t/s`) on unified rows.
43
+ - **Tools & Verification Gate**: Tool execution counter paired with active test/safety gate (`tools: 14 (0 err)` + `✓ Gate: tests pass`).
44
+
45
+ ### Added
46
+
47
+ - **plugin** — root `"."`, `"./server"`, and `"./tui"` package exports in `package.json` for unified OpenCode plugin loader support.
48
+ - **tui** — Next-Gen bilateral layouts for Context, Git status, and header metrics in `src/plugins/tui/src/index.tsx`.
49
+ - **tui** — `extractCompactionInfo`, `formatCompactionBadge`, `formatTokenAnatomySplit`, `resolveGateStatus`, and `isSessionPinned`.
50
+ - **tui** — `pinnedSessions` persistence and self-healing schema normalization in `src/plugins/tui/src/tui-prefs.ts`.
51
+ - **tests** — comprehensive unit and integration coverage in `tests/tui-sidebar.test.mjs` and `tests/tui-prefs.test.mjs`.
52
+
53
+ ## [v2.1.6] - 2026-11-16
54
+
55
+ ### 🆕 What's New
56
+
57
+ - **Deepwork Resilient Normalization**: Supported multi-decision blueprints, single-option policies, and string acceptance criteria.
58
+ - **Fail-Fast Anti-Mocking**: Prohibited fake mock servers on service ports to hide missing dependencies; fail fast with explicit errors.
59
+ - **Workspace Tool Directory**: Native shell tools dynamically resolve to the active project root rather than falling back to `$HOME`.
60
+ - **Atomic Skill Installation**: Enforced sequential `&&` chaining for `npx skills add` to prevent silent dropping of trailing targets.
61
+ - **Project Bootstrap Git Init**: `init --project` initializes an empty Git repo when absent, enabling worktree and branch support.
62
+ - **Decoupled Background Processes**: Mandated `setsid nohup <cmd> > <log> 2>&1 &` (or `disown`) for long-running service processes.
63
+
64
+ ### Fixed
65
+
66
+ - **deepwork** — fixed `readPlan` schema rejection on single-option decision policies and auto-inferred acceptance criteria kinds (`test|command|file|manual`).
67
+ - **deepwork** — added atomic plan locking and safe temp files preventing write race conditions during concurrent decision resolutions.
68
+ - **tools** — flattened JSON schema for `pantheon_jev_decide` to eliminate upstream validator rejections on top-level `oneOf`/`anyOf`.
69
+ - **tools** — bound `shellTool` fallback execution directory dynamically to `hostLocationDirectory`.
70
+ - **mcp** — improved `pantheon-vision` error reporting with status code diagnostics and actionable fallback to native `vision_describe`.
71
+ - **tui** — removed duplicate todo block from settings preferences in favor of native sidebar.
72
+ - **agents** — updated Zeus and backend instructions with Fail-Fast, resource exclusivity, and decoupled server execution standards.
73
+
16
74
  ## [v2.1.5] - 2026-11-14
17
75
 
18
76
  ### 🆕 What's New
package/README.md CHANGED
@@ -1,277 +1,95 @@
1
1
  # Pantheon
2
2
 
3
- **A clearer, faster way to work with OpenCode on real software projects.** Pantheon
4
- brings planning, implementation, review, and documentation into one guided,
5
- token-efficient experience. It is an OpenCode plugin and installer for developers
6
- and teams who want useful structure without giving up speed or control of their code.
3
+ A multi-agent orchestration plugin for OpenCode that carries a request from plan to
4
+ reviewed change with 14 specialized agents, enforced TDD and explicit human approval
5
+ gates — for developers and teams who want structure without giving up control of the code.
7
6
 
8
- [Português (Brasil)](README.pt-BR.md) ·
9
- [Repository](https://github.com/ils15/pantheon-opencode) · [MIT License](LICENSE)
7
+ [Português (Brasil)](README.pt-BR.md) · [Repository](https://github.com/ils15/pantheon-opencode) · [MIT License](LICENSE)
10
8
 
11
- [![Version](https://img.shields.io/github/v/release/ils15/pantheon-opencode?label=version)](https://github.com/ils15/pantheon-opencode/releases/latest)
9
+ [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
10
+ [![Node](https://img.shields.io/badge/node-%E2%89%A526.4.0-339933)](package.json)
11
+ [![OpenCode](https://img.shields.io/badge/opencode-2.x-black)](https://opencode.ai/)
12
12
  [![Docs](https://img.shields.io/badge/docs-portal-indigo)](https://ils15.github.io/pantheon-opencode/)
13
- [![CI](https://img.shields.io/github/actions/workflow/status/ils15/pantheon-opencode/ci.yml?branch=main&label=CI)](https://github.com/ils15/pantheon-opencode/actions)
14
- [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22650136.svg)](https://doi.org/10.5281/zenodo.22650136)
15
13
 
16
- ## What is it?
14
+ ## What it is
17
15
 
18
- Pantheon is a companion for [OpenCode](https://opencode.ai/) that helps you move
19
- from an idea to a reviewed, verified change. Fourteen specialized agents share one
20
- streamlined workflow: plan, implement, check, review, and record what mattered.
21
- You stay in charge of every decision and every merge.
16
+ One agent planning, writing, testing, reviewing and documenting at the same time gives you
17
+ fragmented context and skipped tests. Pantheon splits that work across specialists that
18
+ share a single workflow: Zeus orchestrates, Athena plans, the implementation agents write,
19
+ Themis reviews, and every phase stops for your approval. Bounded micro-edits skip the
20
+ ceremony and verify in seconds; heavy multi-phase work runs as a checkpointed plan that
21
+ resumes across sessions. It is an OpenCode plugin plus installer — no separate runtime, no
22
+ auto-merge, no silent permission changes.
22
23
 
23
- ```mermaid
24
- flowchart LR
25
- U["You"] --> Z["Zeus<br/>orchestrator"]
26
- Z -->|"delegates"| S["14 specialists<br/>hermes · aphrodite · demeter · themis …"]
27
- Z -->|"ambiguous route"| J["Jev decision router<br/>typed · budgeted · reversible"]
28
- J -->|"orders · ranks · verifies"| S
29
- S -->|"last resort"| M["Native MCP<br/>memory · persistence · vision<br/>code-mode · resources"]
30
- Z --> G["J1 risk gate<br/>off / shadow / warn / enforce"]
31
- G -->|"high risk"| H["Human approval"]
32
- ```
33
-
34
- **The escalation ladder every agent follows**: session context first → free local selector → one typed Jev decision when genuinely ambiguous → native MCP call only as the last resort for state the session cannot reconstruct.
35
-
36
- ```mermaid
37
- flowchart LR
38
- R["rough request"] --> T0{"clear &<br/>bounded?"}
39
- T0 -->|yes| X["execute directly"]
40
- T0 -->|"vague /<br/>multi-concern"| T1["Tier 1 — internal<br/>minimal adjust ≤15 lines<br/>(silent, no approval)"]
41
- T1 --> T2q{">> given?"}
42
- T2q -->|yes| T2["Tier 2 — full contract<br/>6 sections, confirm-or-adjust"]
43
- T2q -->|no| X
44
- ```
45
-
46
- **Skill discovery runs a trust cascade** — canonical first, popularity never compensates for provenance:
47
-
48
- ```mermaid
49
- flowchart LR
50
- L["installed pool<br/>(always first)"] -->|"gap"| C1["anthropics/skills<br/>canonical"]
51
- C1 -->|"no fit"| C2["skills.sh<br/>install-count signal"]
52
- C2 -->|"no fit"| C3["GitHub raw<br/>widest, weakest"]
53
- C3 --> J["Jev orders<br/>the candidates"]
54
- J --> P["YOU review<br/>and run the install"]
55
- ```
24
+ Every dispatch carries a concise handoff brief — objective, bounded scope, relevant inputs,
25
+ constraints, expected return format and verification — and work is routed **qualitatively**,
26
+ by uncertainty, domain expertise, dependencies, risk and verification, not by fixed file or
27
+ line thresholds.
56
28
 
57
- ## Why use it?
29
+ ## Installation
58
30
 
59
- - **Fast-Track execution:** Bounded micro-edits (<= 2 files, <= 50 lines) bypass all heavy ceremony and verify in < 10 seconds.
60
- - **Mandatory test slicing:** Sub-second targeted test execution instead of running sluggish repository-wide test suites during dev loops.
61
- - **Execution proof receipts:** Cryptographic SHA-256 fingerprinting on modified files and test slice exit codes prevents false-positive task reports.
62
- - **KV-cache prefix optimization:** Strict invariant-first prompt layering maximizes LLM cache hits (up to 90% cost and latency savings).
63
- - **Reactive event bus & zero polling:** Process-wide in-memory event bus delivers instant updates across jobs and agents without disk polling.
64
- - **Themis local reflex loops:** Specialist self-healing resolves isolated lint and test slice discrepancies before escalating to Zeus.
65
- - **Assertive council (`/pantheon`):** Parallel specialist consultations resolved decisively via domain authority and JEV multi-criteria decisions without endless debate turns.
66
- - **You stay in charge:** Pantheon supports your judgment; it never silently alters permissions or runs unapproved destructive actions.
67
- - **Non-destructive upgrades:** Updating Pantheon (`pantheon-opencode update`) refreshes skills, MCPs, and instructions while strictly preserving all user models, presets, permissions, and custom configs.
31
+ Requirements: [OpenCode](https://opencode.ai/docs/) **2.x** and Node.js **≥ 26.4.0**
32
+ ([compatibility](docs/COMPATIBILITY.md)).
68
33
 
69
- ## Start in 2 minutes
70
-
71
- Requirements: [OpenCode](https://opencode.ai/docs/) **2.x** and Node.js **>=26.4.0**. (See [Compatibility](docs/COMPATIBILITY.md)).
72
-
73
- ### 1. Install
74
-
75
- **Option A — Quick Plugin Add (Global or Project):**
76
34
  ```bash
35
+ # Option A — as an OpenCode plugin (global or project)
77
36
  opencode plugin add pantheon-opencode
78
- # Or pin a specific version:
79
- opencode plugin add pantheon-opencode@2.0.0-rc.1
80
- ```
81
37
 
82
- **Option B — Global CLI Install with Full MCP Tooling:**
83
- ```bash
38
+ # Option B — global CLI install with full MCP tooling
84
39
  npm install -g pantheon-opencode@beta
85
40
  pantheon-opencode init --yes
86
- ```
87
41
 
88
- ### 2. Verify Health
89
- ```bash
42
+ # Verify the install
90
43
  pantheon-opencode doctor
91
- ```
92
- Runs a diagnostic checking Decision Router & budget ledger accessibility, MCP initialization, Python virtual environments, Node version, permissions, and config integrity. In containerized or JupyterHub environments with group-writable homes, set `PANTHEON_ALLOW_GROUP_WRITABLE=1` if needed.
93
44
 
94
- ### 3. Updating Pantheon Without Overwriting Settings
95
- When a new version is released:
96
- ```bash
45
+ # Later: update without losing models, presets or permissions
97
46
  pantheon-opencode update
98
47
  ```
99
- The updater verifies package identity, pulls the latest release, and runs a non-destructive configuration refresh. **Your custom models, active preset, custom permissions, plugin options, and user-defined AGENTS.md sections are preserved verbatim.**
100
-
101
- ---
102
-
103
- ## Optimal Workflow & Execution Modes
104
-
105
- Pantheon balances speed and rigor through three distinct execution modes:
106
-
107
- ```mermaid
108
- flowchart TD
109
- Req["User Request"] --> Size{"Scope / Risk"}
110
- Size -->|"≤ 2 files · ≤ 50 lines<br/>routine fix / typo / CSS"| Fast["Fast-Track<br/>(Sub-10s · Inline Test Slicing)"]
111
- Size -->|"Architecture / Tech choice<br/>Security / Multi-stakeholder"| Council["Council Synthesis (/pantheon)<br/>(2-3 Specialists in Parallel · Domain Authority)"]
112
- Size -->|"Multi-phase feature<br/>Heavy refactor · Breaking changes"| Deep["Deepwork (/pantheon-deepwork)<br/>(Athena Plan · Phase Gates · Checkpoints)"]
113
- ```
114
48
 
115
- ### 1. Fast-Track & Test Slicing (Micro-Edits < 10s)
116
- For routine bug fixes, style adjustments, or localized refactors:
117
- - **No planning ceremony:** Directly executes bounded changes.
118
- - **Targeted test slicing:** Runs ONLY the test slice relevant to the modified file (e.g. `node --test tests/foo.test.mjs` or `pytest -k <func>`). Full repository test suites are reserved for CI and release gates.
119
- - **Single-turn delivery:** Verifies and completes in under 10 seconds.
49
+ ## Usage
120
50
 
121
- ### 2. Assertive Council Synthesis (`/pantheon`)
122
- When confronting architectural crossroads, technology evaluations, or security tradeoffs:
123
- ```text
124
- /pantheon Should we use WebSockets or Server-Sent Events for live push notifications?
125
- ```
126
- - **Parallel Dispatch:** Dispatches 2–3 specialist agents simultaneously with independent prompts.
127
- - **Assertive Arbitration:** Rather than looping in repetitive debate rounds, divergences are resolved immediately via **Domain Authority Precedence**:
128
- - **Security / Auth:** `@themis` has veto power over vulnerable designs.
129
- - **Database / Schema:** `@demeter` carries authoritative weight on query performance and transaction safety.
130
- - **Frontend / UX / A11y:** `@aphrodite` governs user interface responsiveness and accessibility.
131
- - **Infrastructure / CI:** `@prometheus` governs deployment contracts and container isolation.
132
- - **API / Protocols:** `@hermes` governs contract consistency and transport schemas.
133
- - **Architecture / Modularity:** `@athena` governs separation of concerns.
134
- - **JEV Multi-Criteria Decision:** If trade-offs balance competing requirements equally, Zeus invokes `pantheon_jev_decide` (or local decision matrix) to rank candidates deterministically in one tool call.
51
+ Inside OpenCode, dispatch the orchestrator or a workflow:
135
52
 
136
- ### 3. Checkpointed Deepwork (`/pantheon-deepwork`)
137
- For multi-phase tasks spanning 10+ turns or multiple sessions:
138
53
  ```text
54
+ @zeus: Add CSV export to the reports page
139
55
  /pantheon-deepwork "Implement OAuth2 PKCE authentication flow"
140
56
  ```
141
- - **The Plan is the Artifact:** The canonical ground truth is stored in `.pantheon/deepwork/<slug>/plan.json` with an append-only event log (`journal.ndjson`) for resilient crash recovery.
142
- - **Native OpenCode Gates (Strictly No HTML):** Approvals (Gate 1) and decision resolutions use OpenCode's native interactive `question` tool directly in the chat UI.
143
- - **Dependency DAG:** Automatically projects task dependencies into live Mermaid diagrams (`flowchart LR`) inside `PLAN.md` and chat status.
144
- - **Fail-First Acceptance:** Every task defines concrete acceptance criteria (`kind: test|command|file|manual`, `fails_now: true`) verified with cryptographic receipts.
145
- - **Tool Automation (`pantheon_deepwork`):** Structured tool for `init`, `status`, `update_task`, `verify_acceptance`, and `resolve_decision`.
146
- - **Resumability:** Checkpoints persisted to `.pantheon/deepwork/<slug>/`. Resume anytime with `/pantheon-deepwork --resume <slug>`.
147
-
148
- ---
149
-
150
- ## The 14 Specialized Agents
151
-
152
- For a complete breakdown of permissions, tools, MCP access, and boundary constraints per agent, see the [Agent Capability Matrix](docs/AGENT-CAPABILITY-MATRIX.md).
153
-
154
- Every root dispatch carries a concise handoff brief — objective, bounded scope, relevant inputs, constraints, expected return format, and verification. Work is routed qualitatively — uncertainty, domain expertise, dependencies, risk, and verification — not by fixed file or line thresholds. Return contracts are role-specific: implementation uses `## subtask_summary`, investigation returns structured findings, Athena returns the complete plan, and council responses use `## specialist_response`.
155
-
156
- | Agent | Domain Authority | Core Responsibilities |
157
- |---|---|---|
158
- | **@zeus** | Central Orchestrator | Directs workflow, manages delegations, arbitrates council decisions, enforces token efficiency. Never implements directly. |
159
- | **@athena** | Architecture & Planning | Research-first planning, system boundaries, LTS policy, dependency analysis. Plan-only; never implements. |
160
- | **@hermes** | Backend & APIs | FastAPI, Python async, Node/TypeScript backends, API contracts, protocol conformance. |
161
- | **@aphrodite** | Frontend & UX | React 19, strict TypeScript, responsive design, WCAG accessibility, CSS optimization. |
162
- | **@demeter** | Database & Persistence | Schema migrations, query optimization, N+1 query prevention, transaction integrity. |
163
- | **@themis** | Security & Quality Gate | OWASP audits, static analysis (Biome/ruff), authorization gates, dead code removal. Reviews material changes. |
164
- | **@prometheus** | DevOps & Infrastructure | Docker, CI/CD pipelines, runtime configuration, provider abstraction, telemetry infra. |
165
- | **@talos** | Hotfix Fast Lane | Rapid, standalone fixes for small bugs, typos, and minor logic without subagent overhead. |
166
- | **@apollo** | Investigation Scout | Read-only discovery: parallel codebase and web searches. Returns structured findings. |
167
- | **@hephaestus**| AI Pipelines & RAG | Embeddings, vector stores, prompt engineering, agent pipelines. |
168
- | **@gaia** | Geospatial & Sensing | Remote sensing, SAR, geospatial analysis, ML/DL raster classification (read-only). |
169
- | **@iris** | Git & Release Ops | Branching, PRs, issue triage, release notes. Never pushes or merges without human approval. |
170
- | **@mnemosyne** | Project Memory Bank | Maintains `.pantheon/memory-bank/` and records ADRs when explicitly requested. |
171
- | **@nyx** | Observability & Telemetry| OpenTelemetry tracing, token/cost monitoring, execution profiling. |
172
57
 
173
- ---
58
+ `@zeus` routes to the specialists; `/pantheon` arbitrates architectural choices across
59
+ specialists; `/pantheon-deepwork` runs a multi-phase plan with checkpoints and gates. You
60
+ approve each gate and you run every commit.
174
61
 
175
- ## Skills & MCP Tooling
62
+ ## Structure
176
63
 
177
- - **In-Process Skill Search (`pantheon_skill_search`) & Proactive Installation:** Quickly discovers local and external ecosystem skills; when gaps are identified, Zeus proactively invokes the interactive `question` tool for 1-click project-scoped installation into `.agents/skills/` (via `npx skills add <skill> -a opencode -y`), delegated to execution specialists with zero manual shell typing required.
178
- - **25 Production Skills:** Includes `test-slicing`, `fast-path-execution`, `tdd-with-agents`, `instruction-forge`, and `incremental-implementation`.
179
- - **5 Local MCP Servers:**
180
- - `pantheon-memory`: Shared project memory with atomic SQLite locking.
181
- - `pantheon-persistence`: File and context persistence.
182
- - `pantheon-resources`: Local documentation and asset serving.
183
- - `pantheon-code-mode`: Sandboxed Python execution.
184
- - `pantheon-vision`: Image analysis and diagnostic visual inspection.
185
- - **Advisory JEV Decision Router:** Evaluates candidate options (`pantheon_jev_decide`), orders trade-offs, and provides formal multi-criteria decision making without modifying permissions.
186
-
187
- ---
188
-
189
- ## Settings & TUI Window (`/pantheon-settings`)
190
-
191
- Run `/pantheon-settings` (or `Pantheon: Settings` in the command palette) to open the interactive settings window:
192
-
193
- - **Gates & Overrides:** Toggle named behaviors live; persists to `pantheon-overrides.json`.
194
- - **Model Presets:** Switch active model tier globally or per project.
195
- - **Decision Model Selector:** Interactive selector to cycle across all remote decision models (`openrouter-jev`, `typesafe-jev`, `openai-decisions`, `vercel-gateway-jev`, etc.) directly from the UI.
196
- - **Bilingual Settings (PT-BR / EN):** Full visual localization for Decision, Autonomy, and Safety tabs, auto-detecting environment locale with manual toggle in the TUI tab.
197
- - **Updates:** Check registry channel (`beta` / `stable`) and trigger upgrades.
198
- - **Doctor:** Run inline system health diagnostics.
199
- - **TUI Personalization:** Adjust spacing (`comfortable` vs `compact`), separators, gauge bar styles, context display rows, and language.
200
- - **Non-Destructive Overlay & Mouse Navigation:** Opens as a floating dialog overlay over the active session without blanking the workspace (configurable via `dialog` vs `fullscreen`), with full mouse click support for tabs, sidebar, rows, value cyclers, and actions.
201
- - **Modernized What's New Window:** Card layout with rounded border, pagination buttons, and a dedicated `[OK, Entendido]` button with keyboard (`Enter`/`Esc`/`Q`) and mouse click support.
202
-
203
- ---
204
-
205
- ## Documentation & Tutorials
206
-
207
- > 📖 **Official Documentation Portal:** Explore full searchable guides, interactive Mermaid diagrams, and versioned releases at **[https://ils15.github.io/pantheon-opencode/](https://ils15.github.io/pantheon-opencode/)**.
208
-
209
- | Guides & Tutorials | Architecture & Deep Dives | Reference & Operations |
210
- |---|---|---|
211
- | [First Project (End-to-End)](docs/guides/first-project.md) | [Architecture](docs/ARCHITECTURE.md) | [MCP Tools](docs/mcp-tools.md) |
212
- | [Agent Capability Matrix](docs/AGENT-CAPABILITY-MATRIX.md) | [Delegation & Gates](docs/PERMISSIONS-QUALITY-DELEGATION.md) | [Native Decisions (Jev)](docs/reference/native-decisions.md) |
213
- | [Deepwork Blueprint](docs/guides/deepwork.md) | [Memory System](docs/MEMORY.md) | [Model Routing](docs/reference/model-routing.md) |
214
- | [Pantheon Vision](docs/guides/vision.md) | [OpenCode Integration](docs/opencode.md) | [Changelog](CHANGELOG.md) |
215
- | [Cookbook](docs/guides/cookbook.md) | [Compatibility](docs/COMPATIBILITY.md) | [Wiki](wiki/Home.md) |
216
-
217
- ---
218
-
219
- ## Real-World Examples
220
-
221
- Working runnable reference projects demonstrating Pantheon orchestration in practice:
222
-
223
- * **[SaaS Performance Dashboard](examples/saas-dashboard/) (`examples/saas-dashboard`):** Fullstack web application with React 19, Fastify backend, streaming CSV export, automated tests, and a real Deepwork execution plan (`plan.json`, `journal.ndjson`, `PLAN.md`).
224
- * **[Repo Health CLI](examples/cli-tool/) (`examples/cli-tool`):** Sub-second diagnostic CLI tool demonstrating the fast-path execution of `@talos` and `@hermes`.
225
-
226
- ---
227
-
228
- ## What's New in v2.1.5
229
-
230
- - **Risk-Based Validation Protocol (#444):** Explicit multi-tier protocol distinguishing focused test slices (<10s), package integration suites, and mandatory repository CI gates. Escalation to broad suites requires explicit triggers (cross-module, breaking contracts, auth, DB migrations).
231
- - **Tool Execution Resilience & Fallback:** Added `execute` fallback tool alias executing commands directly in `/bin/bash`, preventing `SyntaxError: Assigning to rvalue` when models call `execute` with CLI commands or scripts.
232
- - **CLI Execution Mandate:** Enforced CLI execution via `shell`/`bash` for binaries like `opencode-quota` with an anti-panic ban on speculative recursive `glob`/`grep` in `~/.config`.
233
- - **Validation Scope Transparency (#444):** `subtask_summary` observable receipts report `validation_scope` and deferred `pending_validation` repository CI pipeline gates.
234
-
235
- ---
236
-
237
- ## What's New in v2.1.4
238
-
239
- - **Global Install Shadowing & PATH Hygiene (#424):** Doctor check (H2b) detects multiple global binaries, dangling symlinks, and prefix skew. Version skew validation prevents `_npx` from binding to older global packages.
240
- - **Strict Test Slice Ordering (#442):** Reordered `--test-name-pattern` flag ahead of the test file path in `scripts/test-slice.mjs` so Node's native test runner filters tests during failure/fix loops.
241
- - **Security Boundaries on Internal Folders (#441):** Hardened `auto-permissions` and `zeusReadGuard` to exclude `.git/` and `node_modules/` from autonomous reads.
242
- - **Universal Session Todo Tool Availability (#439):** Granted `todowrite` and `todoread` across all 14 specialist agent manifests.
243
- - **Session Auto-Discovery for Zen Vision (#440):** Automated active session discovery from environment (`OPENCODE_SESSION_ID`) and SQLite `opencode.db` (`session_v2`) for `vision_describe`.
244
-
245
- ---
246
-
247
- ## What's New in v2.0.1
248
-
249
- - **Bilingual TUI Settings (PT-BR / EN):** Visual localization for Decision Router, Autonomy & Budgets, and J1 Safety Gate tabs, with intelligent system locale auto-detection (`LANG` / `LC_ALL`) and manual preference cycling (`auto`, `pt-BR`, `en`).
250
- - **Interactive Decision Model Selector:** Permanently accessible selector row in `/pantheon-settings` to cycle across all 6 remote decision models without manual JSON configuration.
251
- - **Modernized Council Synthesis (`/pantheon`):** Rich synthesis artifacts featuring Domain Authority breakdown, Mermaid arbitration diagrams, and immediate action checklists.
252
- - **Modernized Strategic Planning (`/pantheon-deepwork`):** Athena plans now enforce mandatory sub-10s test slicing, execution dependency diagrams, blast radius impact matrix, and rollback blueprints.
253
- - **Demystified J1 Safety Ladder:** Plain-language descriptions for J1 execution modes (`shadow`, `enforce`, `off`), making telemetry and protection gates clear.
254
-
255
- ---
256
-
257
- ## What's New in v2.0.0-rc.1
258
-
259
- - **Release Candidate Series Inauguration:** Production-ready multi-agent orchestration for OpenCode 2.x.
260
- - **Agent Token Compaction (-44.3%):** Removed duplicated backend code in Apollo/Prometheus, saving 8,150 tokens per turn (~29.3M tokens/month).
261
- - **Pragmatism & Anti-Pedantry Directive:** Safe diagnostic operations are authorized without bureaucratic gates, ending agent sluggishness.
262
- - **Batched Suite TDD & Test-Slicing:** Cohesive multi-endpoint testing and sub-100ms targeted test execution.
263
- - **Proactive Skill Discovery & Query Caching:** Cached skill lookups (24h TTL) and automated recommendation for external tools.
264
- - **Live JEV Scorecard & Sandbox Web App:** 16/16 pass rate ($0.0000238/decision) verified with an end-to-end sandbox application.
265
-
266
- See [CHANGELOG.md](CHANGELOG.md) for full historical release notes.
64
+ ```
65
+ src/agents/ 14 canonical agent definitions
66
+ src/skills/ skills loaded on demand
67
+ src/mcp/ local MCP servers (memory, persistence, resources, code-mode, vision)
68
+ src/plugins/ OpenCode plugin + TUI
69
+ scripts/ installer, doctor, test-slice, release tooling
70
+ bin/ pantheon-opencode CLI
71
+ docs/ documentation (also published as the docs portal)
72
+ examples/ runnable reference projects
73
+ tests/ Node and TypeScript test suites
74
+ ```
267
75
 
268
- ## Contributing
76
+ ## Documentation
269
77
 
270
- Ideas, bug reports, and contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a PR.
78
+ | Start here | Go deeper |
79
+ |---|---|
80
+ | [Docs portal](https://ils15.github.io/pantheon-opencode/) | [Architecture](docs/ARCHITECTURE.md) |
81
+ | [Quick Start](docs/QUICKSTART.md) | [Overview and routing ladders](docs/OVERVIEW.md) |
82
+ | [Installation](docs/INSTALLATION.md) | [Execution modes](docs/guides/execution-modes.md) |
83
+ | [First project end-to-end](docs/guides/first-project.md) | [Agent Capability Matrix](docs/AGENT-CAPABILITY-MATRIX.md) |
84
+ | [Settings & TUI window](docs/SETTINGS.md) | [Permissions, gates & delegation](docs/PERMISSIONS-QUALITY-DELEGATION.md) |
85
+ | [v2.x highlights](docs/releases/v2-highlights.md) | [CHANGELOG](CHANGELOG.md) |
271
86
 
272
- ## Citation and License
87
+ Runnable examples: [SaaS performance dashboard](examples/saas-dashboard/) and
88
+ [repo health CLI](examples/cli-tool/). Contributing:
89
+ [CONTRIBUTING.md](CONTRIBUTING.md).
273
90
 
274
- Pantheon is open-source software licensed under the [MIT License](LICENSE).
275
- Cite via Zenodo concept DOI: [10.5281/zenodo.22650136](https://doi.org/10.5281/zenodo.22650136). Citation metadata is available in [CITATION.cff](CITATION.cff).
91
+ ## License
276
92
 
277
- Canonical repository: <https://github.com/ils15/pantheon-opencode>
93
+ MIT — see [LICENSE](LICENSE). Cite via Zenodo concept DOI
94
+ [10.5281/zenodo.22650136](https://doi.org/10.5281/zenodo.22650136)
95
+ ([CITATION.cff](CITATION.cff)).