diff --git a/tooling/WORKFLOW.md b/tooling/WORKFLOW.md index 02bb0ec..c50a912 100644 --- a/tooling/WORKFLOW.md +++ b/tooling/WORKFLOW.md @@ -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,179 +65,169 @@ 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 ` | Cria spec OpenSpec + worktree isolado + preenche spec via IA | -| `dev-orchestrator build ` | 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 ` | Remove worktree + branch (para features abandonadas) | +| `dev-orchestrator init` | Configura repo (OpenSpec + .gitignore) — 1x por projeto | +| `dev-orchestrator spec ` | Cria spec + worktree isolado + preenche spec via IA | +| `dev-orchestrator build ` | Loop dev→QA (3 tentativas), merge automático se passar | +| `dev-orchestrator status` | Dashboard de features em andamento | +| `dev-orchestrator clean ` | Remove worktree + branch (abortar feature) | --- ## Fluxo Completo -### 1. Inicializar o projeto +``` +┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ +│ init │───→│ spec │───→│ [review] │───→│ build │ +│ (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) -│ └── changes/ # specs ativos +│ ├── specs/ # specs arquivados +│ └── changes/ # specs ativos │ └── add-oauth/ │ ├── spec.md │ ├── design.md │ └── tasks.md -├── .gitignore # inclui .worktrees/ +├── .gitignore # inclui .worktrees/ └── ... ../.worktrees/ -└── add-oauth/ # worktree isolado - ├── .git # branch: dev-flow/add-oauth - ├── src/ # cópia do código - ├── node_modules/ # instalado localmente +└── add-oauth/ # worktree isolado + ├── .git # branch: dev-flow/add-oauth + ├── 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`. \ No newline at end of file