docs: expand WORKFLOW.md with tool interaction guide

- Added per-tool usage: when to use OpenCode/OpenSpec directly vs orchestrator - Direct interaction patterns for manual work - Clear gate: you review specs before build — critical step - When to step out of the orchestrator workflow - Smoother flow diagram
2026-08-04 18:26:08 -03:00
parent 6d861958ce
commit c53a7f278b
1 changed files with 151 additions and 110 deletions
@@ -1,12 +1,63 @@
 # Dev Orchestrator — AI Workflow Guide

-Workflow de desenvolvimento com IA usando **OpenCode** + **OpenSpec** + **git worktrees**, com orquestração automática do loop dev→QA.
+Toolchain de desenvolvimento com IA: **OpenCode** (agente) + **OpenSpec** (spec-driven dev) + **Dev Orchestrator** (loop dev→QA automático).
+
+---
+
+## Ferramentas — Quando Usar Cada Uma
+
+### OpenCode — O Agente
+
+Executa tarefas de código. Use **diretamente** quando:
+
+- Explorar uma codebase nova: `opencode` (TUI interativo)
+- Fazer uma mudança pontual: `opencode run "corrige typo no header"`
+- Debugar um erro específico: `opencode run "por que esse teste falha?" --thinking`
+- Revisar um PR manualmente: `opencode pr 42`
+
+Use via **orquestrador** quando:
+- Implementar uma feature completa com spec (`dev-orchestrator build`)
+- Precisar de QA automático depois do dev
+- Quiser loop dev→QA sem babysitting
+
+```bash
+# Modos do OpenCode
+opencode                          # TUI interativo (exploração)
+opencode run "tarefa"             # one-shot (automação)
+opencode run "..." --thinking     # vê o raciocínio do modelo
+opencode run "..." -f arquivo.ts  # anexa contexto
+```
+
+### OpenSpec — O Spec Engine
+
+Gerencia specs como source of truth. Use **diretamente** quando:
+
+- Criar spec manualmente: `openspec new change minha-feature`
+- Validar um spec existente: `openspec validate minha-feature --strict`
+- Ver status de todos os changes: `openspec list --json`
+- Arquivar spec concluído: `openspec archive minha-feature --yes`
+
+Use via **orquestrador** quando:
+- Quiser que a IA preencha o spec automaticamente (`dev-orchestrator spec`)
+- O archive deve acontecer automático pós-QA-pass (`dev-orchestrator build`)
+
+```bash
+# Comandos OpenSpec que você mais usa
+openspec list                          # o que está ativo?
+openspec show minha-feature            # ler um spec
+openspec validate minha-feature        # check pré-implementação
+openspec status --change minha-feature # progresso dos artefatos
+openspec instructions --change minha-feature  # o que o agente deve fazer
+```
+
+### Dev Orchestrator — O Script
+
+Automatiza o loop completo. **Substitui** os comandos manuais acima no fluxo principal.

 ```
-Você (review specs)  →  Orquestrador (specs)  →  Dev Agent (implementa)  →  QA Agent (revisa)
-                              ↑                                                    │
-                              └─────────────────── FAIL ──────────────────────────┘
-                                                          PASS → merge → archive
+você tem ideia → spec → review → build → PR pronto
+                     ↑        ↑        ↑
+                orquestrador  você    automático
 ```

 ---
@@ -14,109 +65,139 @@ Você (review specs)  →  Orquestrador (specs)  →  Dev Agent (implementa)
 ## Pré-requisitos

 ```bash
-# Instalar as 2 dependências
 npm install -g opencode-ai@latest
 npm install -g @fission-ai/openspec@latest
-
-# Configurar provedor (OpenRouter, Anthropic, etc.)
-opencode auth login
+opencode auth login          # configura provider (OpenRouter, Anthropic, etc.)
 ```

 ---

-## Comandos
+## Comandos do Orquestrador

 | Comando | O que faz |
 |---|---|
-| `dev-orchestrator init` | Configura o repo com OpenSpec (roda 1x por projeto) |
-| `dev-orchestrator spec <nome>` | Cria spec OpenSpec + worktree isolado + preenche spec via IA |
-| `dev-orchestrator build <nome>` | Roda dev→QA loop no worktree, merge automático no main se QA passar |
-| `dev-orchestrator status` | Visão kanban dos features ativos |
-| `dev-orchestrator clean <nome>` | Remove worktree + branch (para features abandonadas) |
+| `dev-orchestrator init` | Configura repo (OpenSpec + .gitignore) — 1x por projeto |
+| `dev-orchestrator spec <nome>` | Cria spec + worktree isolado + preenche spec via IA |
+| `dev-orchestrator build <nome>` | Loop dev→QA (3 tentativas), merge automático se passar |
+| `dev-orchestrator status` | Dashboard de features em andamento |
+| `dev-orchestrator clean <nome>` | Remove worktree + branch (abortar feature) |

 ---

 ## Fluxo Completo

-### 1. Inicializar o projeto
+```
+┌──────────┐    ┌──────────────┐    ┌──────────────┐    ┌─────────────┐
+│   init   │───→│  spec <nome> │───→│   [review]    │───→│ build <nome> │
+│ (1x/proj)│    │ (orquestrador│    │ (você aprova) │    │ (dev→QA loop)│
+└──────────┘    │   preenche)  │    └──────────────┘    └──────┬──────┘
+                └──────────────┘                               │
+                                          ┌────────────────────┘
+                                          │ QA PASS → merge + archive
+                                          │ QA FAIL → retry (3x max)
+                                          └────────────────────────
+```
+
+### 1. Inicializar

 ```bash
 cd ~/projetos/meu-app
 dev-orchestrator init
 ```

-Isso cria a pasta `openspec/`, configura o OpenCode, e adiciona `.worktrees/` ao `.gitignore`.
-
-### 2. Criar spec de uma feature
+### 2. Especificar feature

 ```bash
-dev-orchestrator spec add-oauth-login
+dev-orchestrator spec add-oauth
 ```

-O que acontece:
-1. Cria `openspec/changes/add-oauth-login/` com os templates
-2. Cria um **git worktree** isolado em `../.worktrees/add-oauth-login/` no branch `dev-flow/add-oauth-login`
-3. Roda `npm install` (ou `pip install`) dentro do worktree
-4. Chama o **orquestrador** (OpenCode) que lê o código, preenche os specs, valida
+O que acontece internamente:
+1. `openspec new change add-oauth --json` → cria templates
+2. `git worktree add -b dev-flow/add-oauth ../.worktrees/add-oauth/ HEAD`
+3. `npm install` dentro do worktree
+4. `opencode run "preenche os specs lendo a codebase"` → orquestrador preenche spec.md, design.md, tasks.md

-### 3. Revisar os specs
+### 3. Revisar os specs (MOMENTO CRÍTICO)

 ```bash
-# Ver arquivos gerados
-ls openspec/changes/add-oauth-login/
-cat openspec/changes/add-oauth-login/spec.md
+# Ler o spec gerado
+cat openspec/changes/add-oauth/spec.md
+cat openspec/changes/add-oauth/design.md

 # Validar
-openspec validate add-oauth-login --strict
+openspec validate add-oauth --strict
+
+# Ajustar manualmente se quiser — edite os arquivos
+vim openspec/changes/add-oauth/spec.md
 ```

-**Aqui você está no controle.** Revise os specs, ajuste o que quiser.  
-Só prossiga quando estiver satisfeito.
+> **Você é o gatekeeper aqui.** Se o spec não está certo, o build vai sair errado.  
+> Gaste tempo revisando os specs — é o investimento mais rentável do fluxo.

-### 4. Disparar o build
+### 4. Build (dev→QA loop)

 ```bash
-dev-orchestrator build add-oauth-login
+dev-orchestrator build add-oauth
 ```

-O que acontece:
+Loop:
 ```
-── Dev Phase (attempt 1/3) ──
-  → OpenCode implementa no worktree
-  → Roda testes
-
-── QA Review ──
-  → OpenCode revisa: spec compliance, testes, regressões, edge cases
-
-PASS → merge no main, archive spec, remove worktree
-FAIL → volta pro dev (até 3 tentativas)
+Dev Phase ──→ OpenCode implementa + testa + commita
+    │
+    ▼
+QA Phase ──→ OpenCode revisa: spec compliance, testes, regressões
+    │
+    ├── PASS → merge no main, archive spec, remove worktree ✅
+    │
+    └── FAIL → volta pro Dev (até 3 tentativas)
+               falhou 3x → worktree mantido pra correção manual
 ```

-Se o QA falhar 3 vezes, o worktree é mantido pra você inspecionar e corrigir manualmente.
-
-### 5. Ver status de tudo
+### 5. Status dashboard

 ```bash
 dev-orchestrator status
 ```

-Exemplo de output:
-```
-#    FEATURE                        COMMITS    SPEC       WORKTREE
-───  ─────────────────────────────  ─────────  ─────────  ──────────────
-1.   add-oauth-login                3          2/4        ../.worktrees/add-oauth-login/
-2.   fix-payment-timeout            1          active     ../.worktrees/fix-payment-timeout/
-```
+---
+
+## Quando Sair do Orquestrador
+
+O script cobre 90% dos casos. Saia dele quando:
+
+| Situação | O que fazer |
+|---|---|
+| Spec ficou ruim e quero reescrever do zero | `openspec new change X` manual, preenche na mão |
+| QA rejeitou e quero corrigir eu mesmo | `cd ../.worktrees/feature/` → edita → commita → `dev-orchestrator build feature` |
+| Feature complexa demais pra um spec só | `openspec new change feature-pt1`, `openspec new change feature-pt2` |
+| Quero iterar rápido sem spec | `opencode` TUI direto (pula o orquestrador) |
+| Bug fix trivial (1-2 linhas) | `opencode run "fix: ..."` direto, nem cria spec |

 ---

-## Estrutura de diretórios
+## Paralelismo
+
+Rode múltiplos features ao mesmo tempo:
+
+```bash
+# Terminal 1
+dev-orchestrator build feature-a
+
+# Terminal 2
+dev-orchestrator build feature-b
+```
+
+Cada um em seu worktree isolado. O merge no main serializa no final — se houver conflito, o script para e avisa.
+
+---
+
+## Estrutura de Diretórios

 ```
 ~/projetos/meu-app/
-├── src/                    # código principal
+├── src/
 ├── openspec/
-│   ├── specs/              # specs arquivados (source of truth)
+│   ├── specs/                    # specs arquivados
 │   └── changes/                  # specs ativos
 │       └── add-oauth/
 │           ├── spec.md
@@ -128,65 +209,25 @@ Exemplo de output:
 ../.worktrees/
 └── add-oauth/                    # worktree isolado
    ├── .git                      # branch: dev-flow/add-oauth
-    ├── src/                # cópia do código
-    ├── node_modules/       # instalado localmente
+    ├── src/
+    ├── node_modules/
    └── ...
 ```

 ---

-## FAQ
+## Opcional: Swarm Tools + .hive

-### Posso rodar múltiplos features em paralelo?
-
-Sim. Cada `dev-orchestrator spec` cria um worktree isolado. Rode `build` em terminais separados:
-
-```bash
-# Terminal 1
-dev-orchestrator build add-oauth
-
-# Terminal 2
-dev-orchestrator build fix-payments
-```
-
-Worktrees em branches diferentes = zero conflito. O merge no main é o único ponto de serialização.
-
-### O QA falhou e eu quero corrigir manualmente
-
-```bash
-cd ../.worktrees/fix-payments
-# ... faz as correções ...
-git add -A && git commit -m "manual fix"
-dev-orchestrator build fix-payments  # re-dispara do QA
-```
-
-### Como limpar uma feature abandonada?
-
-```bash
-dev-orchestrator clean fix-abandonada
-```
-
-Remove o worktree e o branch. O spec em `openspec/changes/` fica — delete manualmente se quiser.
-
-### Preciso commitar algo no meio do build?
-
-O Dev Agent já commita a cada tentativa. Se quiser checkpoints extras, faça manualmente no worktree — o script não interfere.
-
-### O que acontece com `node_modules`?
-
-Cada worktree tem o seu próprio `node_modules`, instalado durante o `spec`. Sem symlinks, sem compartilhamento — isolamento total. Custa espaço em disco, mas evita qualquer heisenbug de dependência.
-
---
-
-## Opcional: Kanban com .hive (Swarm Tools)
-
-Se quiser tracking mais visual, instale o Swarm Tools (leve, sem daemon, sem binário grande):
+Kanban mais visual, sem servidor:

 ```bash
 npm install -g opencode-swarm-plugin
 swarm setup
 ```

-Depois, dentro do OpenCode, use `/hive` pra ver tasks e `/swarm "tarefa"` pra decompor em paralelo. O `.hive/` é uma pasta git-tracked com markdown — nada de banco ou servidor.
+Dentro do OpenCode:
+- `/swarm "tarefa"` — decompõe e spawna workers paralelos
+- `/hive` — quadro kanban das tasks
+- `/inbox` — mensagens entre agentes

-O script `dev-orchestrator` funciona com ou sem Swarm Tools. São independentes.
+O `.hive/` é uma pasta git-tracked. Independe do `dev-orchestrator`.