pantheon-opencode 2.1.5 → 2.1.6

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.
package/README.pt-BR.md CHANGED
@@ -1,254 +1,98 @@
1
1
  <!-- synced-from: README.md -->
2
2
  # Pantheon
3
3
 
4
- **Uma forma mais clara, rápida e eficiente de trabalhar com OpenCode em projetos de software reais.**
5
- O Pantheon reúne planejamento, implementação, revisão e documentação numa experiência guiada e otimizada para tokens. É um plugin e instalador para OpenCode feito para desenvolvedores e equipes que querem estrutura útil sem abrir mão de velocidade ou do controle sobre seu código.
6
-
7
- [English](README.md) ·
8
- [Repositório](https://github.com/ils15/pantheon-opencode) · [Licença MIT](LICENSE)
9
-
10
- [![Versão](https://img.shields.io/github/v/release/ils15/pantheon-opencode?label=version)](https://github.com/ils15/pantheon-opencode/releases/latest)
11
- [![Documentação](https://img.shields.io/badge/documenta%C3%A7%C3%A3o-portal-indigo)](https://ils15.github.io/pantheon-opencode/)
12
- [![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)
13
- [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22650136.svg)](https://doi.org/10.5281/zenodo.22650136)
14
-
15
- ## O que é?
16
-
17
- O Pantheon é um companheiro do [OpenCode](https://opencode.ai/) que ajuda você a ir de uma ideia até uma alteração revisada e verificada. Quatorze agentes especializados compartilham um fluxo direto e consistente: planejar, implementar, checar, revisar e registrar o que foi importante. Você permanece no controle de cada decisão e de cada merge.
18
-
19
- ```mermaid
20
- flowchart LR
21
- U["Você"] --> Z["Zeus<br/>orquestrador"]
22
- Z -->|"delega"| S["14 especialistas<br/>hermes · aphrodite · demeter · themis …"]
23
- Z -->|"rota ambígua"| J["Jev decision router<br/>tipado · com budget · reversível"]
24
- J -->|"ordena · classifica · verifica"| S
25
- S -->|"último recurso"| M["MCP nativo<br/>memória · persistência · visão<br/>code-mode · recursos"]
26
- Z --> G["J1 risk gate<br/>off / shadow / warn / enforce"]
27
- G -->|"alto risco"| H["Aprovação humana"]
28
- ```
29
-
30
- **A escada de escalonamento que todo agente segue**: contexto da sessão primeiro → seletor local gratuito → uma decisão Jev tipada quando genuinamente ambíguo → chamada a MCP nativo apenas como último recurso para estado que a sessão não puder reconstruir.
31
-
32
- ```mermaid
33
- flowchart LR
34
- R["pedido inicial"] --> T0{"claro e<br/>delimitado?"}
35
- T0 -->|sim| X["executar diretamente"]
36
- T0 -->|"vago /<br/>múltiplos tópicos"| T1["Tier 1 — interno<br/>ajuste mínimo ≤15 linhas<br/>(silencioso, sem aprovação)"]
37
- T1 --> T2q{">> fornecido?"}
38
- T2q -->|sim| T2["Tier 2 — contrato completo<br/>6 seções, confirmar-ou-ajustar"]
39
- T2q -->|não| X
40
- ```
4
+ Plugin de orquestração multiagente para o OpenCode que leva um pedido do plano até a
5
+ alteração revisada com 14 agentes especializados, TDD obrigatório e gates de aprovação
6
+ humana — para desenvolvedores e equipes que querem estrutura sem abrir mão do controle
7
+ do código.
41
8
 
42
- **A descoberta de skills segue uma cascata de confiança** — canônicas primeiro, popularidade nunca compensa proveniência:
9
+ [English](README.md) · [Repositório](https://github.com/ils15/pantheon-opencode) · [Licença MIT](LICENSE)
43
10
 
44
- ```mermaid
45
- flowchart LR
46
- L["pool instalado<br/>(sempre primeiro)"] -->|"lacuna"| C1["anthropics/skills<br/>canônica"]
47
- C1 -->|"sem ajuste"| C2["skills.sh<br/>sinal por instalações"]
48
- C2 -->|"sem ajuste"| C3["GitHub raw<br/>mais ampla, menor confiança"]
49
- C3 --> J["Jev ordena<br/>os candidatos"]
50
- J --> P["VOCÊ revisa<br/>e roda o install"]
51
- ```
11
+ [![Licença](https://img.shields.io/badge/licen%C3%A7a-MIT-blue)](LICENSE)
12
+ [![Node](https://img.shields.io/badge/node-%E2%89%A526.4.0-339933)](package.json)
13
+ [![OpenCode](https://img.shields.io/badge/opencode-2.x-black)](https://opencode.ai/)
14
+ [![Docs](https://img.shields.io/badge/docs-portal-indigo)](https://ils15.github.io/pantheon-opencode/pt-BR/)
52
15
 
53
- ## Por que usar?
16
+ ## O que é
54
17
 
55
- - **Execução Fast-Track:** Micro-edições delimitadas (<= 2 arquivos, <= 50 linhas) pulam cerimônias pesadas e validam em < 10 segundos.
56
- - **Fatiamento mandatório de testes (test slicing):** Execução direcionada em submissegundos em vez de rodar suites lentas do repositório inteiro durante loops de desenvolvimento.
57
- - **Recibos de execução comprováveis:** Assinatura criptográfica SHA-256 sobre arquivos modificados e fatias de teste elimina relatórios falsos-positivos de conclusão.
58
- - **Otimização de prefixo de cache KV:** Estruturação estrita de prompts invariantes maximiza reaproveitamento de cache em modelos modernos.
59
- - **Barramento reativo de eventos sem polling:** Event bus em memória distribui atualizações de jobs e agentes em tempo real com latência zero.
60
- - **Loops de reflexo local Themis:** Auto-remediação direta de falhas isoladas de lint ou fatias de teste antes de escalar para o Zeus.
61
- - **Conselho assertivo (`/pantheon`):** Consultas paralelas entre especialistas resolvidas decisivamente via autoridade de domínio e decisões multi-critério JEV sem loops infinitos de debate.
62
- - **Você no comando:** O Pantheon apoia seu julgamento; ele nunca altera permissões silenciosamente nem executa ações destrutivas sem aprovação.
63
- - **Atualizações não-destrutivas:** Atualizar o Pantheon (`pantheon-opencode update`) renova skills, MCPs e instruções preservando rigorosamente todos os modelos do usuário, presets ativos, permissões e regras customizadas no `AGENTS.md`.
18
+ Um agente único planejando, escrevendo, testando, revisando e documentando ao mesmo tempo
19
+ produz contexto fragmentado e testes pulados. O Pantheon divide esse trabalho entre
20
+ especialistas que compartilham um fluxo único: Zeus orquestra, Athena planeja, os agentes
21
+ de implementação escrevem, Themis revisa, e cada fase para esperando sua aprovação.
22
+ Micro-edições limitadas pulam a cerimônia e verificam em segundos; trabalho pesado de
23
+ várias fases roda como plano com checkpoints, retomável entre sessões. É um plugin do
24
+ OpenCode mais um instalador — sem runtime separado, sem auto-merge, sem mudança silenciosa
25
+ de permissões.
64
26
 
65
- ## Comece em 2 minutos
27
+ Cada despacho carrega um handoff brief conciso — objetivo, escopo limitado, entradas
28
+ relevantes, restrições, formato de retorno esperado e verificação — e o trabalho é roteado
29
+ **qualitativamente**, por incerteza, domínio, dependências, risco e verificação, não por
30
+ limites fixos de arquivos ou linhas.
66
31
 
67
- Requisitos: [OpenCode](https://opencode.ai/docs/) **2.x** e Node.js **>=26.4.0**. (Veja [Compatibilidade](docs/COMPATIBILITY.md)).
32
+ ## Instalação
68
33
 
69
- ### 1. Instalação
34
+ Requisitos: [OpenCode](https://opencode.ai/docs/) **2.x** e Node.js **≥ 26.4.0**
35
+ ([compatibilidade](docs/COMPATIBILITY.md)).
70
36
 
71
- **Opção A — Adição Rápida de Plugin (Global ou no Projeto):**
72
37
  ```bash
38
+ # Opção A — como plugin do OpenCode (global ou do projeto)
73
39
  opencode plugin add pantheon-opencode
74
- # Ou fixe uma versão específica:
75
- opencode plugin add pantheon-opencode@2.0.0-rc.1
76
- ```
77
40
 
78
- **Opção B — Instalação Global via CLI com Tooling MCP Completo:**
79
- ```bash
41
+ # Opção B — instalação global via CLI com todo o ferramental MCP
80
42
  npm install -g pantheon-opencode@beta
81
43
  pantheon-opencode init --yes
82
- ```
83
44
 
84
- ### 2. Verificação de Saúde
85
- ```bash
45
+ # Verificar a instalação
86
46
  pantheon-opencode doctor
87
- ```
88
- Executa um diagnóstico de 28 pontos checando inicialização de MCPs, ambientes virtuais Python, versão do Node, permissões e integridade de configuração.
89
47
 
90
- ### 3. Atualizando o Pantheon sem Sobrescrever Configurações
91
- Quando uma nova versão for lançada:
92
- ```bash
48
+ # Depois: atualizar sem perder modelos, presets ou permissões
93
49
  pantheon-opencode update
94
50
  ```
95
- O atualizador valida a identidade do pacote, baixa a versão mais recente e executa uma atualização de configuração totalmente não-destrutiva. **Seus modelos personalizados, preset ativo, permissões customizadas, opções de plugins e seções próprias no AGENTS.md são preservados sem alterações.**
96
51
 
97
- ---
52
+ ## Uso
98
53
 
99
- ## Modos de Execução & Fluxo Ótimo
54
+ Dentro do OpenCode, acione o orquestrador ou um fluxo:
100
55
 
101
- O Pantheon equilibra velocidade e rigor através de três modos de execução:
102
-
103
- ```mermaid
104
- flowchart TD
105
- Req["Pedido do Usuário"] --> Size{"Escopo / Risco"}
106
- Size -->|"≤ 2 arquivos · ≤ 50 linhas<br/>correção / typo / CSS"| Fast["Fast-Track<br/>(Sub-10s · Test Slicing Inline)"]
107
- Size -->|"Arquitetura / Escolha técnica<br/>Segurança / Multi-stakeholders"| Council["Síntese do Conselho (/pantheon)<br/>(2-3 Especialistas em Paralelo · Autoridade de Domínio)"]
108
- Size -->|"Feature multi-fases<br/>Refatoração pesada · Breaking change"| Deep["Deepwork (/pantheon-deepwork)<br/>(Plano da Athena · Gates de Fase · Checkpoints)"]
109
- ```
110
-
111
- ### 1. Fast-Track & Test Slicing (Micro-Edições < 10s)
112
- Para correções de bugs pontuais, ajustes de estilo ou refatorações localizadas:
113
- - **Sem cerimônia de planejamento:** Executa diretamente as alterações delimitadas.
114
- - **Fatiamento direcionado de testes:** Executa APENAS a fatia de testes correspondente ao arquivo modificado (ex: `node --test tests/foo.test.mjs` ou `pytest -k <func>`). Suites completas são reservadas para CI e release gates.
115
- - **Entrega em turno único:** Valida e finaliza em menos de 10 segundos.
116
-
117
- ### 2. Síntese Assertiva do Conselho (`/pantheon`)
118
- Ao enfrentar encruzilhadas arquiteturais, avaliações tecnológicas ou trade-offs de segurança:
119
- ```text
120
- /pantheon Devemos usar WebSockets ou Server-Sent Events para notificações push em tempo real?
121
- ```
122
- - **Despacho Paralelo:** Dispara 2 a 3 especialistas simultaneamente com prompts independentes.
123
- - **Arbitragem Assertiva:** Em vez de travar em rodadas repetitivas de debate, divergências são resolvidas de imediato via **Precedência de Autoridade de Domínio**:
124
- - **Segurança / Auth:** `@themis` tem poder de veto sobre propostas vulneráveis.
125
- - **Banco de Dados / Schema:** `@demeter` tem autoridade técnica sobre consultas e integridade transacional.
126
- - **Frontend / UX / A11y:** `@aphrodite` rege acessibilidade e ergonomia visual.
127
- - **Infraestrutura / CI:** `@prometheus` rege limites de runtime, containers e pipelines.
128
- - **API / Protocolos:** `@hermes` rege conformidade contratual e esquemas de transporte.
129
- - **Arquitetura / Modularidade:** `@athena` rege desacoplamento e manutenibilidade a longo prazo.
130
- - **Decisões Multi-Critério JEV:** Se os trade-offs equilibrarem demandas concorrentes de mesmo peso, Zeus invoca `pantheon_jev_decide` (ou a matriz de decisão local) para ordenar as opções deterministicamente em uma única chamada.
131
-
132
- ### 3. Deepwork com Checkpoints (`/pantheon-deepwork`)
133
- Para tarefas complexas com mais de 10 turnos ou distribuídas em várias sessões:
134
56
  ```text
135
- /pantheon-deepwork "Implementar autenticação OAuth2 PKCE"
57
+ @zeus: Adicione exportação CSV na página de relatórios
58
+ /pantheon-deepwork "Implemente o fluxo de autenticação OAuth2 PKCE"
136
59
  ```
137
- - **O Plano é o Artefato:** O estado canônico é salvo em `.pantheon/deepwork/<slug>/plan.json` acompanhado do log append-only de eventos (`journal.ndjson`) para recuperação resiliente contra falhas.
138
- - **Gates Nativos do OpenCode (Sem HTML):** Aprovações (Portão 1) e resoluções de decisão utilizam a ferramenta interativa nativa `question` do OpenCode diretamente no chat.
139
- - **Grafo de Dependências (DAG):** Projeção automática das tarefas em diagrama Mermaid vivo (`flowchart LR`) dentro do `PLAN.md` e nos resumos de status do chat.
140
- - **Critérios de Aceite Fail-First:** Cada tarefa define verificações concretas (`kind: test|command|file|manual`, `fails_now: true`) validadas com recibos criptográficos de execução.
141
- - **Automação via Ferramenta (`pantheon_deepwork`):** Ferramenta estruturada para `init`, `status`, `update_task`, `verify_acceptance` e `resolve_decision`.
142
- - **Resumibilidade:** Progresso salvo em `.pantheon/deepwork/<slug>/`. Retome a qualquer momento com `/pantheon-deepwork --resume <slug>`.
143
-
144
- ---
145
-
146
- ## Os 14 Agentes Especializados
147
-
148
- Para uma matriz detalhada de permissões, ferramentas, acesso a MCPs e restrições absolutas de cada agente, consulte a [Matriz de Capacidades dos Agentes](docs/AGENT-CAPABILITY-MATRIX.md).
149
-
150
- Toda delegação raiz carrega um brief conciso — objetivo, escopo delimitado, entradas relevantes, restrições, formato de retorno esperado e critérios de verificação. O trabalho é roteado de forma qualitativa — incerteza, especialidade de domínio, dependências, risco e verificação — nunca por limites arbitrários de linhas. Os contratos de retorno são específicos por papel: implementação usa `## subtask_summary`, investigações retornam achados estruturados, Athena entrega o plano completo e respostas ao conselho usam `## specialist_response`.
151
-
152
- | Agente | Autoridade de Domínio | Responsabilidades Principais |
153
- |---|---|---|
154
- | **@zeus** | Orquestrador Central | Direciona o fluxo, delega tarefas, arbitra decisões do conselho e garante economia de tokens. Nunca implementa código diretamente. |
155
- | **@athena** | Arquitetura e Planejamento | Planejamento research-first, fronteiras de sistema, LTS e análise de dependências. Plan-only; nunca implementa. |
156
- | **@hermes** | Backend e APIs | FastAPI, Python assíncrono, backends Node/TypeScript, contratos de API e conformidade de protocolos. |
157
- | **@aphrodite** | Frontend e UX | React 19, TypeScript estrito, design responsivo, acessibilidade WCAG e CSS moderno. |
158
- | **@demeter** | Banco de Dados e Persistência | Migrações de schema, otimização de queries, prevenção de queries N+1 e integridade transacional. |
159
- | **@themis** | Gate de Qualidade e Segurança | Auditorias OWASP, análise estática (Biome/ruff), autorização e limpeza de código legado. Revisa mudanças materiais. |
160
- | **@prometheus** | DevOps e Infraestrutura | Docker, pipelines CI/CD, configuração de runtime, abstração de provedores e infra de telemetria. |
161
- | **@talos** | Linha Rápida de Hotfixes | Correções rápidas e autônomas para bugs pequenos, typos e lógica simples sem sobrecarga de subagentes. |
162
- | **@apollo** | Batedor de Investigação | Descoberta somente-leitura: buscas paralelas no código e na documentação. Retorna achados estruturados. |
163
- | **@hephaestus**| Pipelines de IA e RAG | Embeddings, vector stores, engenharia de prompt e pipelines de agentes. |
164
- | **@gaia** | Sensoriamento e Geoespacial | Sensoriamento remoto, SAR, análise geoespacial e classificação raster ML/DL (somente-leitura). |
165
- | **@iris** | Operações Git e Release | Branches, PRs, triagem de issues e notas de lançamento. Nunca faz push ou merge sem aprovação humana explícita. |
166
- | **@mnemosyne** | Banco de Memória do Projeto | Mantém o `.pantheon/memory-bank/` e registra ADRs quando explicitamente solicitado. |
167
- | **@nyx** | Observabilidade e Telemetria| Rastreamento OpenTelemetry, monitoramento de tokens/custos e profiling de execução. |
168
60
 
169
- ---
61
+ `@zeus` roteia para os especialistas; `/pantheon` arbitra escolhas de arquitetura entre
62
+ especialistas; `/pantheon-deepwork` executa um plano multifase com checkpoints e gates.
63
+ Você aprova cada gate e executa cada commit.
170
64
 
171
- ## Skills & Ferramental MCP
65
+ ## Estrutura
172
66
 
173
- - **Busca de Skills In-Process (`pantheon_skill_search`) e Instalação Proativa:** Encontra rapidamente skills locais e do ecossistema aberto; ao detectar lacunas de capacidade, Zeus abre proativamente a ferramenta interativa `question` para instalação em 1 clique isolada no projeto em `.agents/skills/` (via `npx skills add <skill> -a opencode -y`), delegando a execução a especialistas sem exigir comandos manuais no terminal.
174
- - **25 Skills de Produção:** Inclui `test-slicing`, `fast-path-execution`, `tdd-with-agents`, `instruction-forge` e `incremental-implementation`.
175
- - **5 Servidores MCP Locais:**
176
- - `pantheon-memory`: Memória compartilhada com travas atômicas SQLite.
177
- - `pantheon-persistence`: Persistência de contexto e arquivos de projeto.
178
- - `pantheon-resources`: Disponibilização de documentação e recursos locais.
179
- - `pantheon-code-mode`: Execução confinada de scripts Python.
180
- - `pantheon-vision`: Análise e inspeção visual diagnóstica de imagens.
181
- - **Roteador Consultivo de Decisões JEV:** Avalia candidatos (`pantheon_jev_decide`), ordena trade-offs e fornece suporte a decisões multi-critério sem modificar permissões.
182
-
183
- ---
184
-
185
- ## Configurações & Janela TUI (`/pantheon-settings`)
186
-
187
- Execute `/pantheon-settings` (ou `Pantheon: Settings` na paleta de comandos) para abrir o painel de configurações:
188
-
189
- - **Gates & Overrides:** Habilite ou desabilite comportamentos nomeados em tempo real (salvo em `pantheon-overrides.json`).
190
- - **Presets de Modelos:** Alterne o tier de modelos ativo globalmente ou no projeto.
191
- - **Seletor de Modelo de Decisão:** Alterne interativamente entre os modelos remotos de decisão (`openrouter-jev`, `typesafe-jev`, `openai-decisions`, etc.) diretamente na interface.
192
- - **Suporte Multilíngue (PT-BR / EN):** Tradução visual completa das abas Decisões, Autonomia e Segurança, com detecção automática da linguagem do sistema e troca manual na aba TUI.
193
- - **Atualizações:** Verifique o canal do registro (`beta` / `stable`) e dispare upgrades.
194
- - **Doctor:** Execute o diagnóstico de saúde do sistema diretamente na interface.
195
- - **Personalização da TUI:** Ajuste espaçamento (`comfortable` vs `compact`), separadores, estilo das barras de progresso, linhas de contexto e idioma.
196
- - **Overlay Não-Destrutivo e Navegação por Clique:** Abre como diálogo flutuante sobre a sessão ativa mantendo a TUI visível (configurável entre `dialog` e `fullscreen`), com suporte completo a cliques de mouse em abas, menu lateral, linhas, seletores e botões de ação.
197
- - **Janela de Novidades Modernizada:** Layout em card com bordas arredondadas, paginação visual e botão dedicado `[OK, Entendido]` com confirmação via mouse ou teclado (`Enter`/`Esc`/`Q`).
198
-
199
- ---
200
-
201
- ## Documentação & Tutoriais
202
-
203
- > 📖 **Portal Oficial de Documentação:** Explore guias completos com pesquisa instantânea, diagramas interativos em Mermaid e histórico de versões em **[https://ils15.github.io/pantheon-opencode/](https://ils15.github.io/pantheon-opencode/)**.
204
-
205
- | Guias & Tutoriais | Arquitetura e Aprofundamento | Referência e Operações |
206
- |---|---|---|
207
- | [Primeiro Projeto (End-to-End)](docs/guides/first-project.md) | [Arquitetura](docs/ARCHITECTURE.md) | [Ferramentas MCP](docs/mcp-tools.md) |
208
- | [Matriz de Agentes](docs/AGENT-CAPABILITY-MATRIX.md) | [Delegação & Gates](docs/PERMISSIONS-QUALITY-DELEGATION.md) | [Decisões Nativas (Jev)](docs/reference/native-decisions.md) |
209
- | [Guia do Deepwork](docs/guides/deepwork.md) | [Sistema de Memória](docs/MEMORY.md) | [Roteamento de Modelos](docs/reference/model-routing.md) |
210
- | [Pantheon Vision](docs/guides/vision.md) | [Integração OpenCode](docs/opencode.md) | [Changelog](CHANGELOG.md) |
211
- | [Cookbook de Receitas](docs/guides/cookbook.md) | [Compatibilidade](docs/COMPATIBILITY.md) | [Wiki](wiki/Home.md) |
212
-
213
- ---
214
-
215
- ## Exemplos Práticos do Mundo Real
216
-
217
- Projetos funcionais demonstrando a orquestração do Pantheon na prática:
218
-
219
- * **[SaaS Performance Dashboard](examples/saas-dashboard/) (`examples/saas-dashboard`):** Aplicação fullstack completa com React 19, backend Fastify, streaming de CSV, testes automatizados e plano Deepwork real com evidências (`plan.json`, `journal.ndjson`, `PLAN.md`).
220
- * **[Repo Health CLI](examples/cli-tool/) (`examples/cli-tool`):** Ferramenta de linha de comando para diagnóstico de repositórios em menos de 1 segundo, demonstrando o fluxo fast-path do `@talos` e `@hermes`.
221
-
222
- ---
223
-
224
- ## O Que Há de Novo na v2.0.1
225
-
226
- - **Configurações TUI Bilíngues (PT-BR / EN):** Localização visual para o Assistente de Decisão Jev, Autonomia & Orçamentos e Portão de Segurança J1, com detecção inteligente da linguagem do ambiente (`LANG` / `LC_ALL`) e seleção manual (`auto`, `pt-BR`, `en`).
227
- - **Seletor Interativo de Modelos Jev:** Linha de seleção sempre visível em `/pantheon-settings` para alternar entre os 6 modelos remotos suportados sem editar arquivos JSON manualmente.
228
- - **Síntese do Conselho Modernizada (`/pantheon`):** Artefatos com Autoridade por Domínio, diagrama visual de arbitragem em Mermaid e checklist de ações imediatas.
229
- - **Planejamento Estratégico Modernizado (`/pantheon-deepwork`):** Planos da Athena com fluxo visual em Mermaid, fatiamento rigoroso de testes (< 10s), análise de raio de impacto e plano de rollback.
230
- - **Desmistificação da Escala de Segurança J1:** Descrições claras dos modos de execução (`shadow`, `enforce`, `off`), eliminando ambiguidades sobre bloqueio e telemetria.
231
-
232
- ---
233
-
234
- ## O Que Há de Novo na v2.0.0-rc.1
235
-
236
- - **Inauguração da Série Release Candidate:** Orquestração multi-agente pronta para produção no OpenCode 2.x.
237
- - **Compactação de Tokens dos Agentes (-44.3%):** Remoção de código duplicado no Apollo/Prometheus, economizando 8.150 tokens por turno (~29,3M tokens/mês).
238
- - **Diretiva de Pragmatismo e Anti-Pedantismo:** Diagnósticos seguros autorizados sem burocracia excessiva, eliminando lentidão e morosidade.
239
- - **TDD em Lote (Batched Suite) e Test-Slicing:** Implementação coesa de módulos completos e execução de testes em menos de 100ms.
240
- - **Descoberta Proativa de Skills com Cache:** Buscas de skills cacheadas (TTL 24h) e recomendação proativa de ferramentas pelo Zeus.
241
- - **Scorecard JEV ao Vivo e App Web no Sandbox:** 16/16 cenários aprovados ($0,0000238/decisão) validados com app real no sandbox.
242
-
243
- Consulte o [CHANGELOG.md](CHANGELOG.md) para o histórico completo de lançamentos.
67
+ ```
68
+ src/agents/ 14 definições canônicas de agentes
69
+ src/skills/ skills carregadas sob demanda
70
+ src/mcp/ servidores MCP locais (memory, persistence, resources, code-mode, vision)
71
+ src/plugins/ plugin do OpenCode + TUI
72
+ scripts/ instalador, doctor, test-slice, ferramental de release
73
+ bin/ CLI pantheon-opencode
74
+ docs/ documentação (também publicada como portal de docs)
75
+ examples/ projetos de referência executáveis
76
+ tests/ suítes de teste em Node e TypeScript
77
+ ```
244
78
 
245
- ## Contribuição
79
+ ## Documentação
246
80
 
247
- Ideias, relatórios de bugs e contribuições de código são muito bem-vindos! Por favor, leia [CONTRIBUTING.md](CONTRIBUTING.md) antes de abrir um PR.
81
+ | Comece por | Aprofunde |
82
+ |---|---|
83
+ | [Portal de docs](https://ils15.github.io/pantheon-opencode/pt-BR/) | [Arquitetura](docs/pt-BR/ARCHITECTURE.md) |
84
+ | [Início rápido](docs/pt-BR/QUICKSTART.md) | [Visão geral e escadas de roteamento](docs/OVERVIEW.md) |
85
+ | [Instalação](docs/pt-BR/INSTALLATION.md) | [Modos de execução](docs/guides/execution-modes.md) |
86
+ | [Primeiro projeto ponta a ponta](docs/pt-BR/guides/first-project.md) | [Matriz de capacidade dos agentes](docs/pt-BR/AGENT-CAPABILITY-MATRIX.md) |
87
+ | [Configurações e janela TUI](docs/SETTINGS.md) | [Permissões, gates e delegação](docs/PERMISSIONS-QUALITY-DELEGATION.md) |
88
+ | [Novidades da v2.x](docs/releases/v2-highlights.md) | [CHANGELOG](CHANGELOG.md) |
248
89
 
249
- ## Citação e Licença
90
+ Exemplos executáveis: [dashboard SaaS](examples/saas-dashboard/) e
91
+ [CLI de saúde do repositório](examples/cli-tool/). Contribuição:
92
+ [CONTRIBUTING.md](CONTRIBUTING.md).
250
93
 
251
- O Pantheon é software de código aberto sob a [Licença MIT](LICENSE).
252
- Cite via Zenodo concept DOI: [10.5281/zenodo.22650136](https://doi.org/10.5281/zenodo.22650136). Metadados de citação disponíveis em [CITATION.cff](CITATION.cff).
94
+ ## Licença
253
95
 
254
- Repositório canônico: <https://github.com/ils15/pantheon-opencode>
96
+ MIT — veja [LICENSE](LICENSE). Citação via DOI de conceito Zenodo
97
+ [10.5281/zenodo.22650136](https://doi.org/10.5281/zenodo.22650136)
98
+ ([CITATION.cff](CITATION.cff)).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pantheon-opencode",
3
- "version": "2.1.5",
3
+ "version": "2.1.6",
4
4
  "description": "Multi-agent orchestration for OpenCode \u2014 14 specialized agents, TDD, Themis review gates.",
5
5
  "type": "module",
6
6
  "workspaces": [
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pantheon",
3
3
  "publisher": "ils15",
4
- "version": "2.1.5",
4
+ "version": "2.1.6",
5
5
  "displayName": "Pantheon",
6
6
  "description": "Conductor-Delegate orchestration platform with 14 specialized agents, 25 skills, and OpenCode support.",
7
7
  "agents": "./src/agents",
package/pyproject.toml CHANGED
@@ -4,7 +4,7 @@ build-backend = "setuptools.backends._legacy:_Backend"
4
4
 
5
5
  [project]
6
6
  name = "pantheon"
7
- version = "2.1.5"
7
+ version = "2.1.6"
8
8
  description = "Multi-agent orchestration framework"
9
9
  requires-python = ">=3.11"
10
10
  # Python sources under src/mcp/ import fastmcp/pydantic at runtime, but those
@@ -3290,6 +3290,18 @@ async function installPass(
3290
3290
  markAppliedWrite()
3291
3291
  stateStep(true)
3292
3292
  advancePhase()
3293
+
3294
+ if (opts.isProject && !existsSync(join(target, '.git'))) {
3295
+ try {
3296
+ const { spawnSync } = await import('node:child_process')
3297
+ const gitProbe = spawnSync('git', ['--version'], { stdio: 'ignore' })
3298
+ if (gitProbe.status === 0) {
3299
+ spawnSync('git', ['init', '-q'], { cwd: target, stdio: 'ignore' })
3300
+ }
3301
+ } catch {
3302
+ // git probe or initialization failed; harmless
3303
+ }
3304
+ }
3293
3305
  }
3294
3306
 
3295
3307
  // Fail closed only after the degraded state is persisted. The caller records
@@ -126,7 +126,7 @@ These rules are economic, measured against the 2026-11-05 usage audit. They appl
126
126
  * Recommended choice: `"(Recomendado) Instalar skills prioritárias no projeto (.agents/skills/)"` (curated candidates).
127
127
  * Granular choice: `"Selecionar skills específicas para instalar"` (or checkbox list if multiselect).
128
128
  * Skip choice: `"Prosseguir sem instalar skills adicionais"`.
129
- - Automated Specialist Execution & Batching: When the user approves in the question prompt, do NOT require them to run commands. Immediately dispatch an execution specialist with bash permitted (@hermes or @talos) to execute `npx skills add <skill1> [skill2...] -a opencode -y` in the project root (batching multiple skills in a single run).
129
+ - Automated Specialist Execution & Batching: When the user approves in the question prompt, do NOT require them to run commands. Immediately dispatch an execution specialist with bash permitted (@hermes or @talos) to execute one command per skill sequentially chained with `&&`: `npx skills add <skill1> -a opencode -y && npx skills add <skill2> -a opencode -y` in the project root (the skills CLI only accepts one target per invocation; never pass multiple skills as separate positional arguments to a single call).
130
130
  - Verification: Specialist verifies directory creation in `<project>/.agents/skills/<skill-name>/` or `<project>/.opencode/skills/<skill-name>/` (ensuring `.opencode/skills/<skill-name>` exists or links so OpenCode native discovery sees it); subsequent `pantheon_skill_search` confirms `installed: true`.
131
131
 
132
132
  ## Visual Context for Implementation
@@ -144,6 +144,9 @@ Do not use shared KV to track depth; at most one auxiliary specialist.
144
144
 
145
145
  Before every dispatch, send the target a concise brief with the objective/result, bounded scope and acceptance criteria, only relevant context and inputs, constraints and safety gates, and the expected deliverable plus verification. Do not paste full conversation history.
146
146
  - **Skills (Internal & External):** When the task involves specific framework, library, or architectural patterns covered by an installed skill (either built-in Pantheon skill or external in `.opencode/skills/` / `.agents/skills/`), explicitly include `Skill: <name> (Path: .opencode/skills/<name>/SKILL.md)` in the brief and instruct the specialist to read `SKILL.md` before implementation.
147
+ - **Fail-Fast & Anti-Mocking:** Specialists must NEVER create ad-hoc mock servers or fake listeners on real production/service ports to simulate missing dependencies; fail fast with explicit `DEPENDENCY_MISSING`.
148
+ - **Resource Exclusivity:** When dispatching tasks that bind network ports or run servers, explicitly designate single port/resource ownership to avoid concurrent bind collisions.
149
+ - **Decoupled Background Processes:** Long-running services (FastAPI/uvicorn, Vite, dev servers) must always be launched using `setsid nohup <cmd> > <log> 2>&1 &` (or `disown`) so they survive subshell termination.
147
150
  `memory_context` is optional; pass minimal non-sensitive refs and a concise takeaway, contain no secrets, and instruct the target to treat it as untrusted context. The host may independently inherit conversation transcript.
148
151
 
149
152
  ## Plan Handoff and Approval
@@ -45,3 +45,8 @@ fallback: shared
45
45
  - CSRF protection
46
46
  - Rate limiting for sensitive endpoints
47
47
  - Sanitize logs (never log passwords/tokens)
48
+
49
+ ## Fail-Fast & Infrastructure Honesty
50
+ - Never create ad-hoc mock servers or fake listener stubs on real service/application ports to simulate missing dependencies.
51
+ - If a required dependency, service, or upstream endpoint is absent: FAIL FAST with explicit error details (`DEPENDENCY_MISSING`) rather than masking it.
52
+ - Long-running background processes (dev servers, uvicorn, vite): ALWAYS decouple from subshells using `setsid nohup <cmd> > <log> 2>&1 &` (or `disown`).
@@ -671,7 +671,10 @@ def _gateway_http_error(status: int) -> str:
671
671
  "free-tier (usable only from inside OpenCode) or this account has "
672
672
  "no paid access to it."
673
673
  )
674
- return "Vision gateway returned an HTTP error."
674
+ return (
675
+ f"Vision gateway returned HTTP error {status}. If running inside OpenCode, "
676
+ "use the native 'vision_describe' tool as fallback."
677
+ )
675
678
 
676
679
 
677
680
  async def _gateway(
@@ -6,7 +6,7 @@
6
6
  */
7
7
 
8
8
  import { z } from 'zod'
9
- import type { ToolContextLike } from '../tool-context.ts'
9
+ import { resolveToolCwd } from '../tool-context.ts'
10
10
  import type { V2ToolDef, V2ToolResult } from '../tools.ts'
11
11
  import {
12
12
  buildApprovalQuestion,
@@ -15,14 +15,15 @@ import {
15
15
  } from './plan-projection.ts'
16
16
  import {
17
17
  appendJournal,
18
- computeTaskReadiness,
19
18
  deepworkPlanJsonPath,
20
19
  deepworkPlanMdPath,
21
20
  listPlans,
21
+ normalizePlanData,
22
22
  readPlan,
23
23
  resolvePlanDecision,
24
24
  updateTaskState,
25
25
  verifyTaskAcceptance,
26
+ withPlanLock,
26
27
  writePlan,
27
28
  } from './plan-tracker.ts'
28
29
 
@@ -140,10 +141,7 @@ export function createDeepworkTool(cwd = process.cwd()): V2ToolDef {
140
141
  output: {},
141
142
  async execute(input: Record<string, unknown>, context: unknown): Promise<V2ToolResult> {
142
143
  const parsed = DeepworkToolInputSchema.parse(input)
143
- const effectiveCwd =
144
- typeof (context as ToolContextLike)?.directory === 'string'
145
- ? (context as ToolContextLike).directory
146
- : cwd
144
+ const effectiveCwd = resolveToolCwd(context, cwd)
147
145
 
148
146
  if (parsed.action === 'list') {
149
147
  const plans = await listPlans(effectiveCwd)
@@ -175,81 +173,31 @@ export function createDeepworkTool(cwd = process.cwd()): V2ToolDef {
175
173
  }
176
174
 
177
175
  if (parsed.action === 'init') {
178
- const title = parsed.title?.trim() || slug
179
- const intent = parsed.intent?.trim() || 'Plano de deepwork estruturado.'
180
- const rawTasks = parsed.tasks ?? []
181
- const rawDecisions = parsed.decisions ?? []
182
- const doneWhen = parsed.done_when ?? []
183
-
184
- const tasks = rawTasks.map((t, idx) => ({
185
- id: typeof t.id === 'string' ? t.id : `T${String(idx + 1).padStart(2, '0')}`,
186
- title: typeof t.title === 'string' ? t.title : `Task ${idx + 1}`,
187
- description: typeof t.description === 'string' ? t.description : undefined,
188
- agent: typeof t.agent === 'string' ? t.agent : 'zeus',
189
- phase: typeof t.phase === 'number' ? t.phase : 1,
190
- state: (typeof t.state === 'string' ? t.state : 'pending') as
191
- | 'pending'
192
- | 'ready'
193
- | 'in_progress'
194
- | 'done'
195
- | 'failed'
196
- | 'blocked',
197
- depends_on: Array.isArray(t.depends_on) ? (t.depends_on as string[]) : [],
198
- parallel_safe: Boolean(t.parallel_safe),
199
- acceptance: Array.isArray(t.acceptance)
200
- ? (
201
- t.acceptance as Array<{
202
- kind: 'test' | 'command' | 'file' | 'manual'
203
- check: string
204
- fails_now?: boolean
205
- verified?: boolean
206
- proof?: string
207
- }>
208
- ).map((a) => ({
209
- kind: a.kind || 'command',
210
- check: a.check || 'verify',
211
- fails_now: a.fails_now ?? true,
212
- verified: a.verified ?? false,
213
- proof: a.proof,
214
- }))
215
- : [],
216
- }))
217
-
218
- const decisions = rawDecisions.map((d, idx) => ({
219
- id: typeof d.id === 'string' ? d.id : `D${String(idx + 1).padStart(2, '0')}`,
220
- question: typeof d.question === 'string' ? d.question : 'Decisão necessária',
221
- options: Array.isArray(d.options) ? (d.options as string[]) : ['Sim', 'Não'],
222
- chosen: typeof d.chosen === 'string' ? d.chosen : undefined,
223
- status: (d.chosen ? 'resolved' : 'pending') as 'pending' | 'resolved',
224
- }))
225
-
226
- const initialPlan = computeTaskReadiness({
227
- plan_id: slug,
228
- title,
229
- intent,
230
- done_when: doneWhen,
231
- decisions_needed: decisions,
232
- risks: [],
233
- out_of_scope: [],
234
- tasks,
235
- metadata: {
236
- created_at: new Date().toISOString(),
237
- updated_at: new Date().toISOString(),
238
- version: 1,
176
+ const initialPlan = normalizePlanData(
177
+ {
178
+ plan_id: slug,
179
+ title: parsed.title,
180
+ intent: parsed.intent,
181
+ done_when: parsed.done_when,
182
+ decisions_needed: parsed.decisions,
183
+ tasks: parsed.tasks,
239
184
  },
240
- })
185
+ slug,
186
+ )
241
187
 
242
- await writePlan(effectiveCwd, initialPlan)
243
- await appendJournal(effectiveCwd, slug, {
244
- type: 'plan_created',
245
- timestamp: new Date().toISOString(),
246
- payload: { slug, title, tasks_count: tasks.length },
188
+ await withPlanLock(effectiveCwd, slug, async () => {
189
+ await writePlan(effectiveCwd, initialPlan)
190
+ await appendJournal(effectiveCwd, slug, {
191
+ type: 'plan_created',
192
+ timestamp: new Date().toISOString(),
193
+ payload: { slug, title: initialPlan.title, tasks_count: initialPlan.tasks.length },
194
+ })
247
195
  })
248
196
 
249
197
  const projection = generateChatProjection(initialPlan, effectiveCwd)
250
198
  const approvalQ = buildApprovalQuestion(initialPlan)
251
199
  const todoPayload = {
252
- todos: tasks.map((t) => ({
200
+ todos: initialPlan.tasks.map((t) => ({
253
201
  content: `[${t.id}] ${t.title}`,
254
202
  status:
255
203
  t.state === 'done'
@@ -262,7 +210,7 @@ export function createDeepworkTool(cwd = process.cwd()): V2ToolDef {
262
210
 
263
211
  return {
264
212
  output: [
265
- `✅ Plano de Deepwork '${title}' inicializado com sucesso em \`.pantheon/deepwork/${slug}/\`!`,
213
+ `✅ Plano de Deepwork '${initialPlan.title}' inicializado com sucesso em \`.pantheon/deepwork/${slug}/\`!`,
266
214
  `- 🔗 **Deeplink PLAN.md:** [Abrir PLAN.md](file://${deepworkPlanMdPath(effectiveCwd, slug)})`,
267
215
  `- 🔗 **Deeplink plan.json:** [Abrir plan.json](file://${deepworkPlanJsonPath(effectiveCwd, slug)})`,
268
216
  '',
@@ -55,9 +55,11 @@ export type DecisionStatus = z.infer<typeof DecisionStatusSchema>
55
55
  export const PlanDecisionSchema = z.object({
56
56
  id: z.string().min(1),
57
57
  question: z.string().min(1),
58
- options: z.array(z.string()).min(2),
58
+ options: z.array(z.string()).default([]),
59
59
  chosen: z.string().optional(),
60
+ choice: z.string().optional(),
60
61
  status: DecisionStatusSchema.default('pending'),
62
+ resolved_at: z.string().optional(),
61
63
  })
62
64
  export type PlanDecision = z.infer<typeof PlanDecisionSchema>
63
65
 
@@ -78,7 +80,7 @@ export type PlanMetadata = z.infer<typeof PlanMetadataSchema>
78
80
  export const DeepworkPlanSchema = z.object({
79
81
  plan_id: z.string().min(1),
80
82
  title: z.string().min(1),
81
- intent: z.string().min(1),
83
+ intent: z.string().default('Plano de deepwork estruturado.'),
82
84
  done_when: z.array(z.string()).default([]),
83
85
  decisions_needed: z.array(PlanDecisionSchema).default([]),
84
86
  risks: z.array(PlanRiskSchema).default([]),