atlas-workflow 0.9.2 → 0.9.3

package/plugins/atlas-workflow-orchestrator/orchestrator/references/host-adapters.md

@@ -11,7 +11,7 @@ Tools nativas do cliente (`Agent()`, `TodoWrite`, `tasks`, `$skill`) vivem no ho
 1. **Runtime:** `atlas_capabilities` (MCP) — detecta host por env e retorna o descritor. Preferir sempre.
 2. **Estático:** esta tabela — fallback de leitura/documentação quando o MCP não está disponível.
 
-Os dois devem permanecer consistentes. O descritor em código vive em `packages/mcp-server/server.js` (`HOST_ADAPTERS`).
+Os dois devem permanecer consistentes. O descritor em código vive em `packages/mcp-server/server.js` (`HOST_ADAPTERS`). ZCode usa o mesmo formato de agentes que Claude (`.md` com frontmatter) por ser Claude Agent SDK compat.
 
 ## Detecção de host
 
@@ -21,6 +21,7 @@ Os dois devem permanecer consistentes. O descritor em código vive em `packages/
 | env `ATLAS_HOST` | o valor da env |
 | env `CLAUDE_PLUGIN_ROOT` presente | `claude` |
 | env `CODEX_HOME` / `CODEX_PLUGIN_ROOT` | `codex` |
+| env `ZCODE_PLUGIN_ROOT` (injetado pelo `.zcode-plugin` do host) | `zcode` |
 | env `ATLAS_HOST=opencode` (injetado por `opencode.json`) | `opencode` |
 | env `ATLAS_HOST=pi` (injetado pela config do `pi-mcp-adapter`) | `pi` |
 | env `ATLAS_HOST=antigravity` (injetado por `mcp_config.json`) | `antigravity` |
@@ -28,15 +29,15 @@ Os dois devem permanecer consistentes. O descritor em código vive em `packages/
 
 ## Matriz de adapters
 
-| Concern | `claude` (Claude Code) | `codex` (Codex App) | `opencode` | `pi` (pi cli) | `antigravity` (Gemini) | `generic` |
-|---------|------------------------|---------------------|------------|---------------|------------------------|-----------|
-| Disparo de subagente | `Agent(subagent_type: "<name>", prompt: "<state_path>")` | `spawn_agent(agent_type: "<name>", items: [{ type: "text", text: "<state_path>" }])` | `@<name>` (ou auto) com `<state_path>` | tool `subagent({ agent: "<name>", task: "<state_path>", context: "fresh" })` (pi-subagents) | `define_subagent` + `invoke_subagent` com `<state_path>` | subagente nativo do host, passando só `<state_path>` |
-| Registro do subagente | `agents/<name>.md` na raiz do plugin | `CODEX_HOME/agents/<name>.toml` via `init codex` (`.codex/agents/` no bundle é fonte gerada; custom agent nativo; `developer_instructions` carrega o `SKILL.md`; `atlas-task-validator` pinado em `model="gpt-5.4"` + `model_reasoning_effort="high"`) | `.opencode/agents/<name>.md` (`mode: subagent`) | `.pi/agents/<name>.md` (pi-subagents; frontmatter `name`+`description`+`tools`; **`SKILL.md` canônico embutido no corpo** porque o pi não tem skill loader no sub-agente — fonte única segue `packages/skills/<name>/SKILL.md`, agente é cópia gerada por `build/gen-host-agent.mjs`) | dinâmico via `define_subagent` da skill do orquestrador | mecanismo nativo equivalente |
-| Topologia do validador frio (G4) | **`sibling`** | **`sibling`** | **`sibling`** | **`sibling`** | **`sibling`** | **`sibling`** |
-| Join síncrono (gate JOIN) | `self_evident` (`Agent()` bloqueante) | `self_evident` (confirmado em produção) | `self_evident` (`@<name>` bloqueante) | `must_report` (depende de `pi-subagents`; hard-fail sem report) | `self_evident` (`invoke_subagent` bloqueante) | `must_report` (indeterminado; hard-fail sem report) |
-| Todo nativo | `TodoWrite` | `tasks` | `todowrite` | nenhum (segue sem mirror) | nenhum (segue sem mirror) | nenhum (segue sem mirror) |
-| Config MCP | `plugin.json` `mcpServers` | `.mcp.json` | `opencode.json` `mcp.<name>` (`type:"local"`, `environment.ATLAS_HOST=opencode`) | `.mcp.json` no root (`pi-mcp-adapter`; `env.ATLAS_HOST=pi`); tools chegam proxiadas/prefixadas `atlas_workflow_<tool>` | `mcp_config.json` (`env.ATLAS_HOST=antigravity`) | host MCP-capaz |
-| Deps externas obrigatórias | — | — | — | **`pi-mcp-adapter` + `pi-subagents`** (DEC-005) | — | — |
+| Concern | `claude` (Claude Code) | `codex` (Codex App) | `opencode` | `pi` (pi cli) | `antigravity` (Gemini) | `zcode` (ZCode) | `generic` |
+|---------|------------------------|---------------------|------------|---------------|------------------------|-----------|-----------|
+| Disparo de subagente | `Agent(subagent_type: "<name>", prompt: "<state_path>")` | `spawn_agent(agent_type: "<name>", items: [{ type: "text", text: "<state_path>" }])` | `@<name>` (ou auto) com `<state_path>` | tool `subagent({ agent: "<name>", task: "<state_path>", context: "fresh" })` (pi-subagents) | `define_subagent` + `invoke_subagent` com `<state_path>` | `Agent(subagent_type: "<name>", prompt: "<state_path>")` | subagente nativo do host, passando só `<state_path>` |
+| Registro do subagente | `agents/<name>.md` na raiz do plugin | `CODEX_HOME/agents/<name>.toml` via `init codex` (`.codex/agents/` no bundle é fonte gerada; custom agent nativo; `developer_instructions` carrega o `SKILL.md`; `atlas-task-validator` pinado em `model="gpt-5.4"` + `model_reasoning_effort="high"`) | `.opencode/agents/<name>.md` (`mode: subagent`) | `.pi/agents/<name>.md` (pi-subagents; frontmatter `name`+`description`+`tools`; **`SKILL.md` canônico embutido no corpo** porque o pi não tem skill loader no sub-agente — fonte única segue `packages/skills/<name>/SKILL.md`, agente é cópia gerada por `build/gen-host-agent.mjs`) | dinâmico via `define_subagent` da skill do orquestrador | `agents/<name>.md` na raiz do plugin (.zcode-plugin) — mesmo formato claude (Claude Agent SDK) | mecanismo nativo equivalente |
+| Topologia do validador frio (G4) | **`sibling`** | **`sibling`** | **`sibling`** | **`sibling`** | **`sibling`** | **`sibling`** | **`sibling`** |
+| Join síncrono (gate JOIN) | `self_evident` (`Agent()` bloqueante) | `self_evident` (confirmado em produção) | `self_evident` (`@<name>` bloqueante) | `must_report` (depende de `pi-subagents`; hard-fail sem report) | `self_evident` (`invoke_subagent` bloqueante) | `self_evident` (`Agent()` bloqueante; Claude Agent SDK) | `must_report` (indeterminado; hard-fail sem report) |
+| Todo nativo | `TodoWrite` | `tasks` | `todowrite` | nenhum (segue sem mirror) | nenhum (segue sem mirror) | `TodoWrite` | nenhum (segue sem mirror) |
+| Config MCP | `plugin.json` `mcpServers` | `.mcp.json` | `opencode.json` `mcp.<name>` (`type:"local"`, `environment.ATLAS_HOST=opencode`) | `.mcp.json` no root (`pi-mcp-adapter`; `env.ATLAS_HOST=pi`; tools chegam proxiadas/prefixadas `atlas_workflow_<tool>`) | `mcp_config.json` (`env.ATLAS_HOST=antigravity`) | `.zcode-plugin/plugin.json` `mcpServers` (stdio; `ZCODE_PLUGIN_ROOT` injetado pelo host) | host MCP-capaz |
+| Deps externas obrigatórias | — | — | — | **`pi-mcp-adapter` + `pi-subagents`** (DEC-005) | — | — | — |
 | Estado de run | `atlas_run_state` (MCP) | `atlas_run_state` (MCP) | `atlas_run_state` (MCP) | `atlas_run_state` (MCP) | `atlas_run_state` (MCP) | `atlas_run_state` (MCP) |
 | Escrita de plano | `.atlas/plans/` | `.atlas/plans/` | `.atlas/plans/` | `.atlas/plans/` | `.atlas/plans/` | `.atlas/plans/` |
 | Leitura de plano (ordem) | `.atlas/plans/` → `.cursor/plans/` → `.codex/plans/` | idem | idem | idem | idem | idem |
@@ -92,7 +93,7 @@ Campos retornados (DEC-007):
 1. Adicionar entrada em `HOST_ADAPTERS` (`packages/mcp-server/server.js`).
 2. Adicionar regra de detecção em `detectHost` se houver env próprio.
 3. Adicionar linha na matriz de adapters.
-4. Registrar o subagente no formato nativo do host (ex.: `agents/<name>.md` ou equivalente).
+4. Registrar o subagente no formato nativo do host (ex.: `agents/<name>.md` ou equivalente). ZCode reusa o formato Claude (`agents/<name>.md`) — mesmo formato, sem geração extra.
 
 Sem tocar nas skills — elas já consomem o descritor.
 
@@ -102,4 +103,4 @@ Sem tocar nas skills — elas já consomem o descritor.
 
 ## Status multi-host
 
-Todos os hosts-alvo do survey S01 estão implementados na matriz acima: `claude`, `codex`, `cursor` (carona no manifest claude), `opencode` (S06), `pi` (S07) e `generic`. Nenhum exige HTTP/SSE → stdio único (DEC-006/S05). Survey completo + fontes: `PRD_S01_host_survey.md`.
+Todos os hosts-alvo do survey S01 estão implementados na matriz acima: `claude`, `codex`, `cursor` (carona no manifest claude), `opencode` (S06), `pi` (S07), `zcode` (Claude Agent SDK compat) e `generic`. Nenhum exige HTTP/SSE → stdio único (DEC-006/S05). Survey completo + fontes: `PRD_S01_host_survey.md`.

package/plugins/atlas-workflow-orchestrator/orchestrator/skills/atlas-workflow-orchestrator/SKILL.md

@@ -122,6 +122,7 @@ O pipeline é **fire-and-continue**: uma vez iniciado, o orquestrador avança fa
 
 A única interação legítima com o usuário é **dentro de uma fase** — o mecanismo estruturado `question_prompt` devolvido por `atlas_capabilities`, usado pela entrevista para resolver ambiguidade de produto. Resolver ambiguidade ≠ pedir permissão pra avançar. Terminada a fase, respostas são persistidas no PRD, gates são reexecutados e o pipeline segue sozinho.
 
+
 ## Papel do orquestrador (fronteira de determinismo pela mutação de código)
 
 O orquestrador **coordena a execução**, não implementa código — maestro que aponta cada sub-agent na ordem e espera terminar, **nunca pega o instrumento de código**. A fronteira de determinismo é a **mutação de código** (PRD D10), com **duas fases**:
@@ -143,6 +144,7 @@ O **mecanismo** varia por host — leia `subagent_dispatch.mechanism`, `.example
 
 > Ausência de "Agent tool" (host ≠ Claude) **não** é licença pra executar inline — é sinal pra usar o verbo daquele host (Gate G9, qualquer host). Host sem mecanismo de sub-agent já abortou em PREREQ; você nunca chega aqui sem isolamento.
 
+
 ## Protocolo de banner (única comunicação de progresso)
 
 O orquestrador comunica progresso **apenas** por **banner de fase de linha única** no formato `▸ atlas: <fase> · <ação> [· <detalhe>]` (PRD D7/D8). Regras:

package/plugins/atlas-workflow-orchestrator/packages/mcp-server/README.md

@@ -1,6 +1,6 @@
 # Atlas Workflow MCP Server
 
-Servidor MCP do plugin Atlas Workflow v0.9.1.
+Servidor MCP do plugin Atlas Workflow v0.9.3.
 
 ## Tools
 

package/plugins/atlas-workflow-orchestrator/packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlas-workflow/mcp-server",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "private": true,
   "type": "module",
   "bin": {

package/plugins/atlas-workflow-orchestrator/packages/mcp-server/server.js

@@ -283,23 +283,81 @@ const HOST_ADAPTERS = {
   },
   antigravity: {
     label: 'Antigravity',
+    // Antigravity não tem skill loader nativo em subagentes — o SKILL.md completo
+    // DEVE ser embutido no Prompt de cada invoke_subagent (via define_subagent como
+    // system_prompt ou diretamente no Prompt). Nunca despachar subagente sem SKILL.md
+    // injetado, pois o subagente não carregará o contrato e o pipeline vai impasse.
+    //
+    // Fluxo para fases de execução/validação (executor, validator, repair, review):
+    //   1. define_subagent(name: "<atlas-exec>", system_prompt: "<SKILL.MD completo>")
+    //   2. invoke_subagent(Subagents: [{TypeName: "<atlas-exec>", Role: "<papel>",
+    //                                   Prompt: "<state_path ou plan_path>",
+    //                                   Workspace: "branch"}])
+    //   — invoke_subagent é BLOQUEANTE por design: não polling, não background.
+    //   — Workspace: "branch" garante isolamento de contexto (fronteira G4/G9).
+    //
+    // Fases documentais (PRD, entrevista, plano) NÃO usam subagente — o orquestrador
+    // conduz no fio principal; define_subagent não é chamado para essas fases.
     subagent_dispatch: {
-      mechanism: 'define_subagent(name, system_prompt) + invoke_subagent(Subagents)',
-      example: 'define_subagent(name: "atlas-task-validator", system_prompt: "<SKILL_MD>") e invoke_subagent(Subagents: [{TypeName: "atlas-task-validator", Role: "Validator", Prompt: "<state_path>"}])',
-      registration: 'Mapeamento de skills e agents via define_subagent dinâmico',
+      mechanism: 'define_subagent(name, system_prompt) + invoke_subagent(Subagents: [{TypeName, Role, Prompt, Workspace}])',
+      example: 'define_subagent(name: "atlas-task-validator", system_prompt: "<SKILL.MD completo do atlas-task-validator>") seguido de invoke_subagent(Subagents: [{TypeName: "atlas-task-validator", Role: "Validador frio", Prompt: "<state_path>", Workspace: "branch"}])',
+      registration: 'define_subagent dinâmico por sessão — o SKILL.md canônico é passado como system_prompt; sem pré-registro persistente',
+      // Sem loader nativo: o SKILL.md DEVE ser embutido no system_prompt do define_subagent.
+      // Não usar TypeName: "self" sem injetar o SKILL.md — o subagente herdaria o contexto
+      // do orquestrador e violaria o isolamento frio (G4/G9).
+      skill_loading: 'embed_in_system_prompt',
     },
     validator_dispatch: {
       dispatcher: 'orchestrator',
       join: {
         sync: 'self_evident',
         confidence: 'high',
-        mechanism: 'invoke_subagent bloqueante por design do host',
+        mechanism: 'invoke_subagent bloqueante por design do host — sem polling, sem callback',
       },
     },
-    question_prompt: { mechanism: 'notify_user', mode: 'structured', max_questions: 4, options_per_question: 3, persistence: 'prd_after_each_round' },
+    // question_prompt: usado pela atlas-prd-interview para fazer perguntas ao usuário.
+    // No Antigravity, usar ask_question (ferramenta nativa de perguntas interativas).
+    // IMPORTANTE — resume_after_interview: após receber respostas via ask_question,
+    // persistir no PRD e RETOMAR O PIPELINE IMEDIATAMENTE sem nova confirmação.
+    // Nunca aguardar input adicional do usuário entre fases — viola fire-and-continue.
+    question_prompt: {
+      mechanism: 'ask_question',
+      mode: 'structured',
+      max_questions: 4,
+      options_per_question: 3,
+      persistence: 'prd_after_each_round',
+      resume_after_interview: 'automatic',
+    },
     todo_tool: null,
     hooks: { supported: false, mechanism: null },
     capabilities_flags: { subagent_available: true, mcp_available: true, todo_available: false },
+    // self_evident: MCP nativo + invoke_subagent bloqueante provados pelo boot do host.
+    // Não exige host_capabilities report (igual claude/codex/opencode).
+    prereq_policy: 'self_evident',
+  },
+  zcode: {
+    label: 'ZCode',
+    subagent_dispatch: {
+      // ZCode roda no Claude Agent SDK: Agent(subagent_type) nativo e bloqueante.
+      // Skills/agents do plugin vivem no bundle (.zcode-plugin) carregado pelo host.
+      mechanism: 'Agent(subagent_type)',
+      example: 'Agent(subagent_type: "atlas-task-validator", prompt: "<state_path>")',
+      registration: 'agents/<name>.md na raiz do plugin (descoberto via .zcode-plugin/plugin.json)',
+    },
+    validator_dispatch: {
+      dispatcher: 'orchestrator',
+      join: {
+        sync: 'self_evident',
+        confidence: 'presumed',
+        mechanism: 'Agent(subagent_type) bloqueante por design do host (Claude Agent SDK)',
+      },
+    },
+    question_prompt: { mechanism: 'AskUserQuestion', mode: 'structured', max_questions: 4, options_per_question: 3, persistence: 'prd_after_each_round' },
+    todo_tool: 'TodoWrite',
+    hooks: { supported: true, mechanism: '.zcode-plugin/plugin.json (hooks)' },
+    // ZCode é clone estrutural do Claude Code (Claude Agent SDK): subagente +
+    // MCP-local + TodoWrite nativos. Perfil self_evident — passa PREREQ/JOIN sem report.
+    capabilities_flags: { subagent_available: true, mcp_available: true, todo_available: true },
   },
   generic: {
     label: 'Host genérico',
@@ -367,6 +425,10 @@ const HOST_NAMES = Object.keys(HOST_ADAPTERS);
 const HOST_DETECTORS = [
   { via: 'env:CLAUDE_PLUGIN_ROOT', detect: (env) => (env.CLAUDE_PLUGIN_ROOT ? 'claude' : null) },
   { via: 'env:CODEX', detect: (env) => (env.CODEX_HOME || env.CODEX_PLUGIN_ROOT ? 'codex' : null) },
+  // ZCode (app Electron no Claude Agent SDK) injeta ZCODE_PLUGIN_ROOT ao spawnar o
+  // subprocesso MCP do plugin (comprovado no bundle zcode.cjs: interpolação análoga a
+  // CLAUDE_PLUGIN_ROOT). Sinal próprio e determinístico — precedência sobre ATLAS_HOST.
+  { via: 'env:ZCODE_PLUGIN_ROOT', detect: (env) => (env.ZCODE_PLUGIN_ROOT ? 'zcode' : null) },
   // opencode/pi não expõem env distintivo garantido no subprocesso MCP (S01).
   // Detecção determinística: o packaging injeta ATLAS_HOST no env do MCP —
   //   opencode: opencode.json → mcp.<name>.environment.ATLAS_HOST = "opencode"
@@ -419,7 +481,7 @@ function capabilities(args = {}) {
 // do host com a disponibilidade real reportada pelo caller (`host_capabilities`).
 //
 // Política por host (`prereq_policy`):
-//   - 'self_evident' (claude/codex/opencode, default): runtime nativo. Flag essencial
+//   - 'self_evident' (claude/codex/opencode/zcode, default): runtime nativo. Flag essencial
 //     vem do report quando presente, senão do perfil (otimista justificado: MCP-vivo
 //     prova-se no boot; subagente é nativo do host/plugin instalado).
 //   - 'must_report' (pi/generic): essencial depende de dep externa (pi) ou de host
@@ -469,7 +531,7 @@ function checkPrerequisites(args = {}) {
 
 // Gate JOIN (DEC-SIB-003, SPEC_JOIN_CAPABILITY_S03 §3/§5). Espelha checkPrerequisites:
 // lê validator_dispatch.join do adapter e decide hard-fail por política.
-//   - join.sync === 'self_evident' (claude/codex/opencode): host nativo conhecido;
+//   - join.sync === 'self_evident' (claude/codex/opencode/zcode): host nativo conhecido;
 //     o runtime presume join disponível e NÃO exige report. confidence 'presumed'
 //     (claude/opencode) passa, mas é registrado para observabilidade (smoke S13).
 //   - join.sync === 'must_report' (pi/generic): fail-closed. Só passa se o caller

package/plugins/atlas-workflow-orchestrator/skills/atlas-workflow-orchestrator/SKILL.md

@@ -122,6 +122,7 @@ O pipeline é **fire-and-continue**: uma vez iniciado, o orquestrador avança fa
 
 A única interação legítima com o usuário é **dentro de uma fase** — o mecanismo estruturado `question_prompt` devolvido por `atlas_capabilities`, usado pela entrevista para resolver ambiguidade de produto. Resolver ambiguidade ≠ pedir permissão pra avançar. Terminada a fase, respostas são persistidas no PRD, gates são reexecutados e o pipeline segue sozinho.
 
+
 ## Papel do orquestrador (fronteira de determinismo pela mutação de código)
 
 O orquestrador **coordena a execução**, não implementa código — maestro que aponta cada sub-agent na ordem e espera terminar, **nunca pega o instrumento de código**. A fronteira de determinismo é a **mutação de código** (PRD D10), com **duas fases**:
@@ -143,6 +144,7 @@ O **mecanismo** varia por host — leia `subagent_dispatch.mechanism`, `.example
 
 > Ausência de "Agent tool" (host ≠ Claude) **não** é licença pra executar inline — é sinal pra usar o verbo daquele host (Gate G9, qualquer host). Host sem mecanismo de sub-agent já abortou em PREREQ; você nunca chega aqui sem isolamento.
 
+
 ## Protocolo de banner (única comunicação de progresso)
 
 O orquestrador comunica progresso **apenas** por **banner de fase de linha única** no formato `▸ atlas: <fase> · <ação> [· <detalhe>]` (PRD D7/D8). Regras: