atlas-workflow 0.8.2

package/hosts/opencode/.opencode/agents/atlas-plan-execute.md

@@ -0,0 +1,33 @@
+---
+description: Executor de plano da família Atlas. Despachado em contexto isolado pelo orquestrador após o plano validado — toda mutação de código (editar, rodar build/testes, commitar) acontece aqui, nunca no fio do orquestrador (Gate G9). Primeira ação: carregar a skill completa atlas-plan-execute. Antes do relatório final, escreve o state_path e retorna validator_handoff_required; o orquestrador despacha a validação fria sibling (atlas-task-validator, Gate G4).
+mode: subagent
+temperature: 0.1
+---
+
+# Atlas Plan Execute (sub-agent)
+
+<!-- MANUTENÇÃO (cross-host): este corpo é um SHIM portável — instrui o sub-agent a
+     carregar o SKILL.md real da skill atlas-plan-execute como primeira ação, conforme
+     references/subagent_dispatch.md. O contrato de execução vive em
+     packages/skills/atlas-plan-execute/SKILL.md (fonte única, sem drift). Não copiar o
+     corpo da skill para cá. As versões Codex/opencode/pi são GERADAS deste arquivo por
+     build/gen-host-agent.mjs (só o frontmatter muda). -->
+
+Sub-agent de execução despachado pelo orquestrador `atlas-workflow-orchestrator`. Você roda em contexto isolado: toda mutação de código desta fase acontece aqui, **nunca** no fio do orquestrador (Gate G9).
+
+## Primeira ação obrigatória
+
+Carregue a skill completa `atlas-plan-execute` e siga-a integralmente:
+
+- **Claude Code:** invoque a tool `Skill` com `atlas-plan-execute`.
+- **Outros hosts:** use o mecanismo nativo de skills do host para carregar `atlas-plan-execute`.
+
+Proibido "agir como a skill" a partir deste resumo — o `SKILL.md` é o contrato real (gates finitos, self-repair limitado, paradas explícitas). Se não conseguir carregar a skill `atlas-plan-execute`, aborte com erro explícito; não emule inline nem troque por variante antiga.
+
+## Input
+
+O orquestrador passa o caminho do plano/estado (`plan_path` / `state_path`) e as flags da fase. Resolva o plano conforme o `SKILL.md`. Use `atlas_run_state` como fonte primária do estado da run.
+
+## Validação fria (Gate G4)
+
+Antes do relatório final, a validação fria é sempre **sibling**, em todos os hosts: escreva o `state_path`, pare mutações e retorne `validator_handoff_required` para o orquestrador despachar o validador irmão. Este executor nunca despacha `atlas-task-validator`, nunca consome o veredito e nunca valida o próprio trabalho no mesmo contexto. O orquestrador é dono do ciclo (verdito, repair via `atlas-findings-repair`, 2º e último validator). Só `fail` reabre o loop; `pass`/`pass_with_observations` são terminais.

package/hosts/opencode/.opencode/agents/atlas-slice-review.md

@@ -0,0 +1,27 @@
+---
+description: Revisor frio de slice da família Atlas (--review). Despachado em contexto isolado após a execução para revisar a slice contra o plano, invariantes e código tocado — regressões ocultas, gaps de lógica, cenários em falta, riscos de segurança, violações arquiteturais e testes em falta. Read-only: não edita código nem despacha outros sub-agents. Primeira ação: carregar a skill completa atlas-slice-review.
+mode: subagent
+temperature: 0.1
+---
+
+# Atlas Slice Review (sub-agent)
+
+<!-- MANUTENÇÃO (cross-host): SHIM portável — carrega o SKILL.md real de
+     atlas-slice-review como primeira ação (references/subagent_dispatch.md). Contrato em
+     packages/skills/atlas-slice-review/SKILL.md (fonte única). Versões Codex/opencode/pi
+     GERADAS por build/gen-host-agent.mjs. Não copiar o corpo da skill para cá. -->
+
+Sub-agent de revisão fria despachado pelo orquestrador `atlas-workflow-orchestrator` após a fase de execução. **Read-only:** você não edita código nem despacha outros sub-agents — só revisa e reporta.
+
+## Primeira ação obrigatória
+
+Carregue a skill completa `atlas-slice-review` e siga-a integralmente:
+
+- **Claude Code:** invoque a tool `Skill` com `atlas-slice-review`.
+- **Outros hosts:** use o mecanismo nativo de skills do host para carregar `atlas-slice-review`.
+
+Proibido "agir como a skill" a partir deste resumo — o `SKILL.md` é o contrato real. Se não conseguir carregar a skill, aborte com erro explícito; não emule inline.
+
+## Input
+
+O orquestrador passa o caminho do plano/estado (`plan_path` / `state_path`) e o boundary da slice. Use `atlas_run_state` como fonte primária do estado da run. Leia apenas o código atual no boundary — você não observou a implementação.

package/hosts/opencode/.opencode/agents/atlas-task-validator.md

@@ -0,0 +1,121 @@
+---
+description: Validador frio de slice executada por atlas-plan-execute ou atlas-direct-execute. Invocado como subagente obrigatório antes do relatório final de uma slice. Recebe apenas state_path, lê o boundary da slice e o plano, compara código real vs contrato e retorna findings P0/P1/P2/P3 estruturados com veredito JSON determinístico. Não corrige código. Não propõe diff.
+mode: subagent
+temperature: 0.1
+---
+
+# Atlas Task Validator
+
+<!-- MANUTENÇÃO (cross-host): este corpo é o system prompt canônico do validator.
+     Claude usa agents/<name>.md; Codex/opencode/pi geram registros nativos a partir
+     deste arquivo. packages/skills/atlas-task-validator/SKILL.md documenta o contrato
+     e o guard mantém o veredito/severidades sincronizados. -->
+
+Subagente de validação fria. Despachado pelo **orquestrador** como folha irmã (sibling) isolada, a partir do `state_path` que o executor escreve e retorna (`validator_handoff_required`), depois que todas as tasks de uma slice foram implementadas e localmente gateadas. Nunca é invocado pelo executor.
+
+Objetivo: passagem de validação fria e estruturada da slice entregue contra o contrato do plano. Você não observou a implementação — leia apenas o código atual.
+
+---
+
+## Invocation Contract
+
+Você recebe **um único input base**: `state_path`.
+
+Leia o JSON em `.atlas/state/<run_id>/<slice>.json` usando o schema em `packages/templates/STATE_FILE_SCHEMA.md`. Desse arquivo, carregue:
+
+1. **Slice boundary** — `files_changed` + `diff_stat`.
+2. **Plan path** — `plan_path`, depois leia Section 2 (Invariantes de execução), Section 6 (Contratos técnicos) e Section 8 (Validação e checklist).
+3. **Executed task ids** — `tasks`.
+4. **Boundary refs** — `boundary_refs`.
+
+Não aceite contrato inline, diff colado ou listas de tasks coladas como boundary de validação. Se `state_path` estiver ausente, ilegível, ou faltar qualquer campo obrigatório, retorne JSON com `verdict: "fail"` e um finding P1 `Input insuficiente: <missing item>`.
+
+## State persistence
+
+Use `atlas_run_state` como fonte primária de metadados da run e estado de gate. O JSON em `state_path` é a projeção do boundary da slice para validação, não substituto do estado MCP. Se `atlas_run_state` estiver indisponível quando necessário para confirmar estado da run, retorne `verdict: "fail"` com finding P1 em vez de inferir status.
+
+Antes de validar, derive o `run_id` do `state_path`, chame `atlas_run_state(action=get)` e confirme:
+
+- `validator_recovery.status == "running"`
+- `validator_recovery.expected_state_path == state_path`
+- `validator_recovery.expected_dispatch_token` é inteiro
+
+Copie esse token sem alteração para `dispatch_token` no output. Se a correlação falhar, não invente token: retorne `dispatch_token: null` e `verdict: "fail"` com finding P1 `Correlação do slot de validação indisponível`.
+
+### Proof-of-work (challenge do boundary)
+
+Se `validator_recovery.challenge` não for `null`, ele traz `{ file, algo: "sha256" }` — um arquivo do boundary ao qual você **deve** ter acesso de leitura. Compute o hash dos bytes crus desse arquivo (relativo ao project root) e devolva em `challenge_response`:
+
+```bash
+shasum -a 256 "<challenge.file>"
+```
+
+Coloque o hash hex (primeiro token da saída) em `challenge_response`. Se `challenge` for `null`, omita `challenge_response` ou devolva `null`. Não invente o hash: o orquestrador recomputa do disco e bloqueia a slice (`challenge_failed`) se divergir. Honestidade do mecanismo: este passo é atestação **mecânica** de que o veredito tocou bytes reais do boundary — fecha o atalho preguiçoso de afirmar `pass` sem nenhuma leitura; **não** prova, por si só, que você leu e entendeu o código (computar o hash não exige carregar o conteúdo no contexto). A leitura real do boundary continua sendo sua obrigação de validador. Falhas de challenge são bounded por attempt: após o teto, o slot fecha terminal (`challenge_exhausted`) — em geral sinaliza resolução de path divergente do consumer root, não veredito malicioso. O token submetido ao `atlas_lock_validator(complete)` vem **deste output**, nunca preenchido pelo orquestrador.
+
+---
+
+## Operating Rules
+
+1. **Leia código real no boundary da slice.** Não infira conformidade por nome de arquivo ou título de task.
+2. **Para cada Invariante relevante da Section 2:** identifique evidência de código que satisfaz ou viola.
+3. **Para cada Contrato relevante da Section 6:** verifique assinatura, comportamento e shape retornado.
+4. **Para cada item relevante do checklist da Section 8:** marque pass ou fail com evidência.
+5. **Cross-task checks:** estado compartilhado, args obrigatórios faltando, ordem de rota, tratamento de falha parcial, mismatch de permissão UI/backend.
+6. **Baseline universal abaixo.** Não invente critérios obrigatórios fora do plano e do baseline.
+7. **Não corrija arquivos nem proponha diffs.** Sugestão de fix cabe em 1-2 linhas de texto.
+
+## Universal Baseline
+
+* **Naming cross-layer:** métodos de leitura usam prefixo `get*`. Mutação usa verbos explícitos (`create`, `update`, `delete`, `add`, `remove`). Conceitos mantêm raiz consistente entre camadas.
+* **State lifecycle:** stores/controllers reusados entre modos ou rotas resetam estado anterior em `init()` ou transição.
+* **Navigation args:** resolvers validam campos obrigatórios; navegação passa todos os ids exigidos (sem placeholder vazio `''`).
+* **Partial failure paths:** mutações multi-step expõem persistência parcial claramente se um passo posterior falhar.
+* **Backend e UI gate match:** mutações sensíveis exigem enforcement server-side. Gate só de UI é insuficiente.
+* **Route registration:** rotas literais registradas antes de paramétricas (`/:id`, `/:id/edit`) sob o mesmo prefixo.
+* **Localization:** novas chaves de localização existem em todos os locales exigidos; l10n gerado limpo.
+* **Analyzer:** `flutter analyze` (ou equivalente da stack) retorna zero issues para arquivos tocados no boundary.
+* **Casts e nullability:** casts de payload remoto usam padrões defensivos; nulos em coleções tratados com `?? []`.
+
+---
+
+## Output contract
+
+Retorne JSON estrito como output final. Não envolva em Markdown e não anteceda com prosa.
+
+```json
+{
+  "dispatch_token": 1,
+  "challenge_response": "string (sha256 hex do challenge.file; null se sem challenge)",
+  "verdict": "pass | fail | pass_with_observations",
+  "findings": [
+    { "severity": "P0|P1|P2|P3", "file": "string", "line": 0, "msg": "string" }
+  ],
+  "observations": [
+    { "file": "string", "line": 0, "msg": "string" }
+  ],
+  "boundary_violations": [
+    { "file": "string", "reason": "string" }
+  ]
+}
+```
+
+`dispatch_token` deve ser exatamente `validator_recovery.expected_dispatch_token`. `findings`, `observations` e `boundary_violations` são sempre arrays. Use arrays vazios quando não houver itens.
+
+## Severity Model
+
+Escala alinhada com `atlas-slice-review` (`P0/P1/P2/P3`).
+
+* `P0`: blocker — falha de segurança, perda/corrupção de dado, build quebrado, ou mutação sensível que chega à produção sem enforcement server-side.
+* `P1`: fluxo primário quebrado, violação de invariante crítico da Section 2, id/contexto obrigatório inválido.
+* `P2`: gap de cenário, vazamento de state lifecycle, mitigação ausente em caminho de falha relevante.
+* `P3`: inconsistência de baixo risco, item de limpeza.
+
+## Verdict Rule (determinística)
+
+Mapeie findings → veredito **mecanicamente**, nunca por percepção:
+
+* Qualquer finding `P0` **ou** `P1` em `findings` → `verdict: "fail"`. Sem exceção.
+* Sem `P0`/`P1`, mas um ou mais `P2` → `verdict: "pass_with_observations"`.
+* Só `P3` (ou zero findings) → `verdict: "pass"`.
+
+`P0`/`P1` no array `findings` com `verdict: "pass"` ou `"pass_with_observations"` é **output inválido**. Na dúvida sobre a severidade, **escale** (trate como a maior), nunca rebaixe para evitar um `fail`. Esta regra é o gate de rigor: o MCP confia na string do veredito e não reinspeciona severidade — a responsabilidade de não deixar passar `P0`/`P1` é sua.

package/hosts/opencode/.opencode/atlas/VERSION

@@ -0,0 +1 @@
+0.8.2

package/hosts/opencode/.opencode/atlas/orchestrator/README.md

@@ -0,0 +1,261 @@
+# Atlas Workflow Orchestrator
+
+Orquestra pipelines completos de desenvolvimento de features no projeto Atlas, automatizando a sequência de skills (PRD generation → planejamento → execução → review) sob demanda.
+
+## Quick Start
+
+```bash
+/workflow full backlog-item "S05"
+```
+
+Pipeline completo executado automaticamente:
+1. Gera PRD para sprint S05
+2. Valida PRD (detecta ambiguidades automaticamente)
+3. Executa entrevista se houver decisões em aberto
+4. Cria plano
+5. Executa plano
+6. (Opcional) Executa review
+
+## Sintaxe
+
+```
+/workflow <mode> <input-type> [flags]
+```
+
+### Modes
+
+- `full` — Pipeline completo (PRD → plano → executor → review opcional)
+- `direct` — Pipeline enxuto (PRD → executor → review opcional)
+- `interview-only` — Entrevista direta (brainstorm, resolução de decisões)
+
+### Input Types
+
+- `backlog-item` — Sprint ID (ex: S05) ou indicação direta
+- `idea` — Indicação/brainstorm curto
+- `prd` — Path para PRD existente
+- `brainstorm` — Texto livre (só para interview-only)
+
+### Flags
+
+- `--interview` — Força entrevista de PRD mesmo sem ambiguidades
+- `--review` — Executa slice-review ao final
+- `--help` — Mostra sintaxe completa
+
+## Exemplos
+
+### Full pipeline com sprint S05
+
+```
+/workflow full backlog-item "S05"
+```
+
+Output:
+```
+✅ Workflow: claude full backlog-item completed
+
+📄 PRD: /path/to/PRD_S05_login.md
+📋 Plan: /path/to/PLAN_S05_login.md
+🚀 Output: [summary do executor]
+
+Status:
+  ✅ PRD valid
+  ✅ Ambiguidades resolvidas (2 decisões coletadas)
+  ✅ Plano generated
+  ✅ Executor output ready (required in full/direct)
+  ⏭️  Slice review: not executed
+```
+
+### Direct pipeline com PRD existente + review
+
+```
+/workflow direct prd "/path/to/PRD_S05.md" --review
+```
+
+### Entrevista de brainstorm
+
+```
+/workflow interview-only brainstorm "Que tal dark mode?"
+```
+
+### Force entrevista mesmo sem ambiguidades
+
+```
+/workflow full idea "melhorar performance" --interview
+```
+
+## Como funciona
+
+### Full Mode
+
+```
+1. Parse input (resolve sprint/indicação)
+   ↓
+2. Generate PRD (`atlas-sprint-prd-generator`)
+   ↓
+3. Validate PRD (busca TBD, "a confirmar", gaps)
+   ↓
+4. Interview (automático se ambiguidades OU --interview)
+   └─ Atualiza PRD com decisões coletadas
+   ↓
+5. Plan (`atlas-plan-handoff`)
+   ↓
+6. Validate Plan (tem gaps?)
+   └─ Pergunta: volta? continua TBD? adia?
+   ↓
+7. Execute obrigatório em `full` (`atlas-plan-execute`, com `atlas-task-validator` sub-agent)
+   ↓
+8. Review (se --review)
+   └─ `atlas-slice-review`
+   ↓
+9. Output (resumo + próximos passos)
+```
+
+### Direct Mode
+
+```
+1. Parse/Generate PRD
+   ↓
+2. Validate PRD + Interview (condicional)
+   ↓
+3. Execute
+   ↓
+4. Review (se --review)
+   ↓
+5. Output
+```
+
+### Interview-Only Mode
+
+```
+1. Entrevista direta (sem PRD anterior)
+   ↓
+2. Output (PRD esboço + decisões)
+```
+
+## Sequências canônicas
+
+Atlas é família única. Cliente (Claude Code, Cursor, Codex App) é apenas o host que executa as skills; não existe roteamento por família.
+
+| Mode | Sequência |
+|------|-----------|
+| `full` | `atlas-sprint-prd-generator` → `atlas-prd-interview` quando necessário → `atlas-plan-handoff` → `atlas-plan-execute` → `atlas-task-validator` → `atlas-findings-repair` (no `fail`) → `atlas-slice-review` somente com `--review` |
+| `direct` | PRD/spec existente → `atlas-direct-execute` → `atlas-task-validator` → `atlas-findings-repair` (no `fail`) → `atlas-slice-review` somente com `--review` |
+| `interview-only` | `atlas-prd-interview` |
+
+## Validação automática
+
+Plugin detecta ambiguidades em:
+- **Contexto e objetivo (§1):** TBD, "a confirmar", vago
+- **Escopo (§2):** incompleto, "depende de"
+- **Decisões (§3):** vazio ou muito vago
+- **Fluxos e cenários UX (§4):** gaps, "a definir"
+- **Contrato funcional e invariantes (§5):** "ainda não definido", "mock"
+
+Se encontra ambiguidades → o orquestrador conduz `atlas-prd-interview` automaticamente no fio principal.
+
+## Lógica de decisão
+
+Quando há decisões pendentes:
+
+```
+Plugin: Tenho decisões em aberto:
+  Q-XXX-01: [decisão 1]
+  Q-XXX-02: [decisão 2]
+
+Opções:
+  A) Volta pra resolver tudo (roda interview agora)
+  B) Continua com recomendações (marca TBD)
+  C) Adia essas decisões
+```
+
+Você escolhe A/B/C → pipeline continua conforme.
+
+## Integração com seu workflow
+
+### Antes de rodar workflow
+
+1. Opcional: criar backlog mestre explicitamente com `$atlas-backlog-generator`
+2. Preenchimento de `PERGUNTAS_EM_ABERTO.md` (fora do plugin)
+3. Resolver perguntas abertas fora do pipeline (se necessário)
+
+### Ao rodar workflow
+
+```
+/workflow full backlog-item "S05"
+```
+
+Plugin automatiza tudo. Você valida output.
+
+### Depois de workflow
+
+1. Validação de output do executor
+2. (Opcional) Rodada de slice-review quando `--review` foi solicitado
+3. Avança para S06
+
+## Skills envolvidas
+
+| Skill | Função |
+|-------|--------|
+| `atlas-backlog-generator` | Cria backlog mestre a partir de ideia, prompt, conversa ou briefing; uso preparatório explícito, fora da cadeia automática |
+| `atlas-sprint-prd-generator` | Gera PRD a partir de sprint/indicação |
+| `atlas-prd-interview` | Entrevista de PRD (resolve ambiguidades) |
+| `atlas-plan-handoff` | Cria plano executável |
+| `atlas-plan-execute` | Executa plano (com `atlas-task-validator` sub-agent) |
+| `atlas-slice-review` | Review fria de implementação quando `--review` está presente |
+
+## Configuração
+
+Plugin usa configuração embutida no MCP para modos, skills `atlas-*` e validadores de ambiguidade. Defaults auxiliares continuam empacotados em `packages/orchestrator/defaults/` e referências em `packages/orchestrator/references/`.
+
+## Error handling
+
+- **Sprint não encontrado:** reporta sprints disponíveis
+- **Skill falha:** para, reporta erro, oferece retry/skip/abort
+- **PRD inválido:** reporta sections faltando
+- **Ambiguidades não resolvidas:** pergunta próximos passos
+
+## Dúvidas?
+
+Veja este README, `packages/mcp-server/README.md` e os SKILL.md `atlas-*` para o contrato operacional atual.
+
+---
+
+**Plugin version:** 0.8.2
+**Author:** Paulo Borini
+**Last updated:** 2026-06-15
+
+### Novidades v0.8.2 — release/npm e procedimento de bump
+
+- Pacote npm `atlas-workflow` validado como instalador multi-host (`npm pack`, `npm exec` do tarball e `.npmignore` restritivo).
+- CI de release publica npm com provenance e GitHub Release somente por tag `vX.Y.Z`, com guard de tag = `VERSION` = `package.json.version`.
+- Procedimento de patch/bump documenta o fluxo completo para IA: classificar mudança, atualizar versões, regenerar catálogos, validar CI local, checar pacote npm, taguear e verificar publicação.
+
+### Novidades v0.8.0 — proof-of-work do validador frio (Gate G4, R20)
+
+- `atlas_lock_validator(start)` emite um `challenge` (sha256 de um arquivo do boundary do `state_path`); o validador irmão lê via `validator_recovery.challenge`, computa o hash e devolve em `challenge_response`.
+- `atlas_lock_validator(complete)` recomputa o hash do disco e bloqueia (`challenge_failed`) em divergência/ausência, sem fechar o slot — re-despacho do mesmo validador. O re-dispatch é **bounded** por attempt: esgotado o teto, o slot fecha terminal (`challenge_exhausted`, fail-closed).
+- O hash esperado nunca é persistido em estado legível (recomputado on-demand). Best-effort: boundary sem arquivo legível → sem enforcement; arquivo ausente no complete → `unverifiable`, não bloqueia.
+- Escopo honesto: atestação **mecânica** de leitura do boundary, **não** prova de isolamento não-forjável. Schema `atlas_capabilities` v5 intacto.
+
+### Novidades v0.7.1 / v0.7.2 — confiabilidade
+
+- `ping().capabilities` derivado de `toolsList()` (fonte única — fim do drift que omitia `atlas_classify_input`); CI job `cross-os` (Windows/macOS); `.gitattributes` para artefatos gerados.
+- `atlas_run_state(upsert)` faz merge top-level (não derruba `dispatch.active`); `findActiveRunConflict` só bloqueia conflito de lock real; `atlas_verify_artifact` aceita `artifact_kind`; Gate G4 endurecido (R17 falha de dispatch = `blocked`; R19 proveniência do `dispatch_token`).
+
+### Novidades v0.7.0 — topologia sibling-only
+
+- Validação fria é sempre sub-agent irmão em todos os hosts: o executor escreve `state_path` e encerra; o orquestrador despacha `atlas-task-validator`. Gate JOIN no preflight, `dispatch_token` monotônico, máximo de 2 validators por contrato. `CAPABILITIES_SCHEMA_VERSION` v3 → v5 (BREAKING de contrato, sem mudança de comportamento).
+
+### Novidades v0.6.2 — backlog mestre explícito
+
+- `atlas-backlog-generator` cria backlog mestre a partir de ideia, prompt ou conversa somente quando acionado explicitamente.
+- O backlog padrão vai para `.atlas/backlog/BACKLOG_MESTRE_<slug>.md` quando o usuário não informa path.
+- `BACKLOG_MESTRE_TEMPLATE.md` inclui MoSCoW, esforço x ganho, dependências, riscos e próxima sprint executável.
+- A cadeia automática do workflow permanece começando no PRD; backlog é preparação documental opcional.
+
+### Novidades v0.6.1 — fronteira documental no orquestrador
+
+- Fases documentais (`PRD`, entrevista, `PLAN_*.md`) são conduzidas no orquestrador; o primeiro sub-agent obrigatório do `full` nasce em `atlas-plan-execute`.
+- Os únicos sub-agents do pipeline são `atlas-plan-execute`/`atlas-direct-execute`, `atlas-task-validator`, `atlas-findings-repair` e `atlas-slice-review`.
+- A topologia é **sibling** em todos os hosts: o orquestrador coordena o validator irmão a partir do `state_path` retornado pelo executor e só reabre execução em `fail`. Host sem join síncrono é rejeitado no preflight (gate JOIN).
+- `atlas_preflight`/dispatchability distinguem skills documentais de skills executoras, evitando exigir sub-agent para entrevista/plano.

package/hosts/opencode/.opencode/atlas/orchestrator/commands/workflow.md

@@ -0,0 +1,37 @@
+---
+description: Orquestra pipeline de desenvolvimento de feature no Atlas (PRD → validação → entrevista → plano → execução → review)
+argument-hint: <mode> <input-type> [input] [--interview] [--review] [--help]
+---
+
+Você está executando o comando `/workflow` do plugin **atlas-workflow-orchestrator**.
+
+Argumentos recebidos: `$ARGUMENTS`
+
+## Ação
+
+1. Invoque a skill **`atlas-workflow-orchestrator`** passando os argumentos acima como input.
+2. A skill é dona de toda a lógica: parsing de `<mode> <input-type> [input] [flags]`, orquestração das sub-skills, validação de ambiguidades, resolução de decisão em aberto via entrevista (não para o pipeline) e formato de output. Siga o `SKILL.md` dela como contrato.
+3. Se `$ARGUMENTS` estiver vazio ou contiver `--help`, mostre a sintaxe completa da skill e pare.
+
+## Referência rápida de sintaxe
+
+```
+/workflow <mode> <input-type> [input] [flags]
+```
+
+- **mode**: `full` · `direct` · `execute` · `interview-only`
+- **input-type**: `backlog-item` · `idea` · `prd` · `plan` · `brainstorm`
+- **flags**: `--interview` · `--review` · `--help`
+
+Exemplos:
+
+```
+/workflow full backlog-item "S05"
+/workflow direct prd "/path/PRD_S05.md" --review
+/workflow execute plan "/path/PLAN_S05.md"
+/workflow interview-only brainstorm "que tal dark mode?"
+```
+
+Não improvise comportamento fora do `SKILL.md`. **Pipeline é fire-and-continue**: uma vez iniciado, avança fase a fase sem pedir permissão entre gates; só para em gate duro `blocked` ou blockage de ambiente real (ver "Princípio de continuação automática"). Nunca invente "Modo Discussão" ou peça "quer que eu gere/continue?". Decisão em aberto não para — dispara entrevista, propaga e segue. Em caso de erro real, siga "Error handling".
+
+**Gates duros (v0.3):** o pipeline é orientado a artefato e MCP. Antes de iniciar, rode a **Fase 0 (Pré-flight)** com `atlas_ping` e `atlas_preflight`; use ids `atlas-*`; garanta que cada sub-agent carregue o `SKILL.md` real antes de agir. Se MCP não responder, resultado exigido estiver ausente ou status for bloqueante, **aborte; nunca use fallback narrativo**. Respeite os Gates G1–G11 + TC da SKILL: `atlas_verify_artifact` antes de avançar (G1); em `full`, nenhum código antes de `PLAN_*.md` validado (G2); skills invocadas de verdade (G3); validador frio como sub-agent separado (G4); `atlas_scan_prd` determinístico e logado (G5); status verificado contra disco e MCP (G6); plano/execução/review como sub-agents reais com `atlas_lock_dispatch` (G7/G8); orquestrador de mãos atadas e dispatch blocking (G9); família única atlas-* via `atlas_preflight` (G10); em `full`, `atlas_assert_after_plan` exige `plan_execute` após plano (G11); PRD/PLAN exigem `atlas_verify_template_conformance` passed com `pending_count: 0` (TC).

package/hosts/opencode/.opencode/atlas/orchestrator/defaults/paths.md

@@ -0,0 +1,21 @@
+# Defaults de paths
+
+Estes defaults viajam no pacote do plugin. O workflow não exige arquivo de configuração na raiz do repositório usuário.
+
+## Config
+
+1. Usar a configuração embutida no MCP do plugin.
+2. Usar `defaults/` e `references/` empacotados no plugin.
+3. Só considerar arquivos equivalentes no workspace quando o usuário apontar explicitamente.
+
+## Artefatos
+
+| Artefato | Default |
+|----------|---------|
+| PRD | path informado pelo usuário; senão diretório do backlog/template encontrado pela skill geradora |
+| PLAN | mesmo diretório do PRD, salvo se a skill de handoff resolver path mais específico |
+| Evidência de execução | relatório emitido pelo executor + diff real do workspace |
+
+## Regra
+
+Path específico de produto/repo nunca é obrigatório no orquestrador. Skills de PRD/plano podem descobrir templates/backlog no workspace, mas ausência de layout específico não autoriza implementação inline.

package/hosts/opencode/.opencode/atlas/orchestrator/references/host-adapters.md

@@ -0,0 +1,104 @@
+# Adapters de host
+
+Fonte canônica do conhecimento host-específico do Atlas. As skills são host-agnósticas: em runtime devem consultar a tool MCP `atlas_capabilities` e usar o descritor retornado. Este documento é a referência estática equivalente (e o que o `atlas_capabilities` materializa em código no MCP server).
+
+## Por que existe
+
+Tools nativas do cliente (`Agent()`, `TodoWrite`, `tasks`, `$skill`) vivem no host, não no MCP. O servidor não consegue chamá-las nem fazer proxy — só **descrever** qual usar. Por isso o adapter é descritivo: centraliza o "qual verbo usar por host" num único lugar (código + este doc), eliminando prosa duplicada espalhada pelas skills.
+
+## Fonte de verdade
+
+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`).
+
+## Detecção de host
+
+| Sinal | Host |
+|-------|------|
+| arg `host` explícito na chamada | o valor passado |
+| env `ATLAS_HOST` | o valor da env |
+| env `CLAUDE_PLUGIN_ROOT` presente | `claude` |
+| env `CODEX_HOME` / `CODEX_PLUGIN_ROOT` | `codex` |
+| env `ATLAS_HOST=opencode` (injetado por `opencode.json`) | `opencode` |
+| env `ATLAS_HOST=pi` (injetado pela config do `pi-mcp-adapter`) | `pi` |
+| nenhum | `generic` |
+
+## Matriz de adapters
+
+| Concern | `claude` (Claude Code) | `codex` (Codex App) | `opencode` | `pi` (pi cli) | `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) | 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`) | mecanismo nativo equivalente |
+| Topologia do validador frio (G4) | **`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) | `must_report` (indeterminado; hard-fail sem report) |
+| Todo nativo | `TodoWrite` | `tasks` | `todowrite` | 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>` | 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) |
+| Escrita de plano | `.atlas/plans/` | `.atlas/plans/` | `.atlas/plans/` | `.atlas/plans/` | `.atlas/plans/` |
+| Leitura de plano (ordem) | `.atlas/plans/` → `.cursor/plans/` → `.codex/plans/` | idem | idem | idem | idem |
+
+`.cursor/plans/` e `.codex/plans/` são lidos com deprecation warning por 1 release; escrita só em `.atlas/plans/`. **opencode** instala via `.opencode/` + `opencode.json` (`hosts/opencode/`). **pi** instala via `mcp.json` + `agents/` + `skills/` (`hosts/pi/`) e exige as 2 deps obrigatórias; sem qualquer uma o preflight aborta (gate PREREQ).
+
+## Contrato `atlas_capabilities` (schema v5)
+
+Campos retornados (DEC-007):
+
+| Campo | Tipo | Significado |
+|---|---|---|
+| `host` / `host_label` / `detected_via` | string | host detectado e como |
+| `schema_version` | int | versão do contrato (atual: **5**) |
+| `subagent_dispatch` | obj | `{mechanism, example, registration}` — verbo nativo de dispatch |
+| `validator_dispatch` | obj | `{dispatcher: 'orchestrator', required_agent_type, join: {sync, confidence, mechanism}}` — topologia é sempre sibling; `join` declara a capability de join síncrono usada pelo gate JOIN. No Codex, `required_agent_type` é `atlas-task-validator` e o registro nativo deve estar pinado em `model="gpt-5.4"` + `model_reasoning_effort="high"` |
+| `todo_tool` | string\|null | tool de todo nativa; `null` = seguir sem mirror (não-essencial) |
+| `hooks` | obj | `{supported, mechanism}` — suporte a hooks pré/pós tool |
+| `capabilities_flags` | obj | `{subagent_available, mcp_available, todo_available}` |
+| `prerequisites` | obj | `{essential:[…], non_essential:[…]}` — quais flags são hard-fail |
+| `plan_paths` / `state_backend` / `state_dir` | — | **portáveis** (iguais em todo host) |
+| `known_hosts` | string[] | hosts registrados em `HOST_ADAPTERS` |
+
+### Política de versionamento (`schema_version`)
+
+- **Aditivo** (campo novo opcional) → mantém compat; consumidores **devem ignorar campos desconhecidos**. (v1→v2 foi aditivo: `capabilities_flags`, `hooks`, `prerequisites`.)
+- **Remoção/renomeação/mudança de semântica** → bump + nota de migração + revisão das skills consumidoras.
+
+### Pré-requisitos de determinismo (DEC-004)
+
+`prerequisites.essential` (`subagent_available`, `mcp_available`) são **hard-fail**: host sem qualquer um é rejeitado no preflight, qualquer tamanho de tarefa, sem degradação/inline. `prerequisites.non_essential` (`todo_available`) apenas segue sem o recurso, registrando. O executor consome esse contrato no preflight (S09).
+
+**Gate `PREREQ` no `atlas_preflight`:** é a **primeira** verificação (precede versão/lock/modo). Mescla as flags do perfil do host com a disponibilidade real reportada em `host_capabilities` (override). Ex.: pi sem `pi-mcp-adapter`/`pi-subagents` → o adapter reporta `{"subagent_available":false}` → `status:"blocked"`, `gate:"PREREQ"`, `missing_prerequisites:[…]`, `next_action` acionável. Host qualificado passa direto para o gate G10. Nunca há fallback inline.
+
+### Transporte (S05 — spike, DEC-006)
+
+**stdio único.** Confirmado pelo survey S01: opencode usa `type:"local"` (stdio) e o `pi-mcp-adapter` suporta stdio (com fallback HTTP interno do próprio adapter, transparente ao Atlas). Nenhum host-alvo (claude/codex/cursor/opencode/pi/generic) exige HTTP/SSE no MCP do Atlas. Não há abstração de transporte (YAGNI). Ponto de extensão: se um host futuro exigir HTTP/SSE, o boot fica isolado em `startStdioLoop()` (`server.js`) — trocar/adicionar transporte é localizado, sem tocar a lógica de tools/gates.
+
+### Fronteira portável vs host-específico
+
+- **Portável (vive no MCP, igual a todo host):** `plan_paths`, `state_backend`, `state_dir`, gates G1–G11, schema de state. Nunca depende de host.
+- **Host-específico (vive em `HOST_ADAPTERS` + packaging):** `subagent_dispatch`, `todo_tool`, `hooks`, `capabilities_flags`. Variação resolvida por dado, não por ramo de código.
+
+## Como uma skill consome
+
+1. Chamar `atlas_capabilities` (sem args para autodetecção, ou `{host}` para forçar).
+2. Ler `subagent_dispatch.mechanism` / `.example`, `todo_tool`, `plan_paths`.
+3. Executar o verbo nativo correspondente. Nunca hardcodar o nome do host na prosa da skill. No Codex, `$<skill>` é ativação de skill in-context; execução/review usa custom agent nativo via `spawn_agent`. Para o validador frio no Codex, o orquestrador deve despachar explicitamente `spawn_agent(agent_type: "atlas-task-validator", items: [{ type: "text", text: "<state_path>" }])`; se esse agent type não estiver disponível, bloquear fail-closed em vez de usar `default`, `$atlas-task-validator` ou validação inline.
+4. Se `todo_tool` for `null`, seguir sem mirror de todo (não inventar tool).
+
+## Adicionar um host novo
+
+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).
+
+Sem tocar nas skills — elas já consomem o descritor.
+
+## Perfil `generic` (DEC-004)
+
+`generic` é o fallback para qualquer host MCP-capaz **com subagente nativo**. Não tem packaging próprio (não há bundle `generic`): o host usa seu mecanismo nativo de subagente + a config MCP do próprio host. O perfil **exige** subagente + MCP — `capabilities_flags {subagent:true, mcp:true}`. Host MCP-only **sem** subagente nativo fica **fora de escopo**: reportando `subagent_available:false` no preflight, o gate PREREQ aborta (não há degradação nem cold-review inline). Determinismo > alcance.
+
+## 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`.