feat(tooling): dev-orchestrator — OpenSpec + OpenCode dev→QA loop #5
+147
-106
@@ -1,12 +1,63 @@
|
|||||||
# Dev Orchestrator — AI Workflow Guide
|
# 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)
|
você tem ideia → spec → review → build → PR pronto
|
||||||
↑ │
|
↑ ↑ ↑
|
||||||
└─────────────────── FAIL ──────────────────────────┘
|
orquestrador você automático
|
||||||
PASS → merge → archive
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -14,109 +65,139 @@ Você (review specs) → Orquestrador (specs) → Dev Agent (implementa)
|
|||||||
## Pré-requisitos
|
## Pré-requisitos
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Instalar as 2 dependências
|
|
||||||
npm install -g opencode-ai@latest
|
npm install -g opencode-ai@latest
|
||||||
npm install -g @fission-ai/openspec@latest
|
npm install -g @fission-ai/openspec@latest
|
||||||
|
opencode auth login # configura provider (OpenRouter, Anthropic, etc.)
|
||||||
# Configurar provedor (OpenRouter, Anthropic, etc.)
|
|
||||||
opencode auth login
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Comandos
|
## Comandos do Orquestrador
|
||||||
|
|
||||||
| Comando | O que faz |
|
| Comando | O que faz |
|
||||||
|---|---|
|
|---|---|
|
||||||
| `dev-orchestrator init` | Configura o repo com OpenSpec (roda 1x por projeto) |
|
| `dev-orchestrator init` | Configura repo (OpenSpec + .gitignore) — 1x por projeto |
|
||||||
| `dev-orchestrator spec <nome>` | Cria spec OpenSpec + worktree isolado + preenche spec via IA |
|
| `dev-orchestrator spec <nome>` | Cria spec + 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 build <nome>` | Loop dev→QA (3 tentativas), merge automático se passar |
|
||||||
| `dev-orchestrator status` | Visão kanban dos features ativos |
|
| `dev-orchestrator status` | Dashboard de features em andamento |
|
||||||
| `dev-orchestrator clean <nome>` | Remove worktree + branch (para features abandonadas) |
|
| `dev-orchestrator clean <nome>` | Remove worktree + branch (abortar feature) |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Fluxo Completo
|
## 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
|
```bash
|
||||||
cd ~/projetos/meu-app
|
cd ~/projetos/meu-app
|
||||||
dev-orchestrator init
|
dev-orchestrator init
|
||||||
```
|
```
|
||||||
|
|
||||||
Isso cria a pasta `openspec/`, configura o OpenCode, e adiciona `.worktrees/` ao `.gitignore`.
|
### 2. Especificar feature
|
||||||
|
|
||||||
### 2. Criar spec de uma feature
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
dev-orchestrator spec add-oauth-login
|
dev-orchestrator spec add-oauth
|
||||||
```
|
```
|
||||||
|
|
||||||
O que acontece:
|
O que acontece internamente:
|
||||||
1. Cria `openspec/changes/add-oauth-login/` com os templates
|
1. `openspec new change add-oauth --json` → cria templates
|
||||||
2. Cria um **git worktree** isolado em `../.worktrees/add-oauth-login/` no branch `dev-flow/add-oauth-login`
|
2. `git worktree add -b dev-flow/add-oauth ../.worktrees/add-oauth/ HEAD`
|
||||||
3. Roda `npm install` (ou `pip install`) dentro do worktree
|
3. `npm install` dentro do worktree
|
||||||
4. Chama o **orquestrador** (OpenCode) que lê o código, preenche os specs, valida
|
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
|
```bash
|
||||||
# Ver arquivos gerados
|
# Ler o spec gerado
|
||||||
ls openspec/changes/add-oauth-login/
|
cat openspec/changes/add-oauth/spec.md
|
||||||
cat openspec/changes/add-oauth-login/spec.md
|
cat openspec/changes/add-oauth/design.md
|
||||||
|
|
||||||
# Validar
|
# 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.
|
> **Você é o gatekeeper aqui.** Se o spec não está certo, o build vai sair errado.
|
||||||
Só prossiga quando estiver satisfeito.
|
> Gaste tempo revisando os specs — é o investimento mais rentável do fluxo.
|
||||||
|
|
||||||
### 4. Disparar o build
|
### 4. Build (dev→QA loop)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
dev-orchestrator build add-oauth-login
|
dev-orchestrator build add-oauth
|
||||||
```
|
```
|
||||||
|
|
||||||
O que acontece:
|
Loop:
|
||||||
```
|
```
|
||||||
── Dev Phase (attempt 1/3) ──
|
Dev Phase ──→ OpenCode implementa + testa + commita
|
||||||
→ OpenCode implementa no worktree
|
│
|
||||||
→ Roda testes
|
▼
|
||||||
|
QA Phase ──→ OpenCode revisa: spec compliance, testes, regressões
|
||||||
── QA Review ──
|
│
|
||||||
→ OpenCode revisa: spec compliance, testes, regressões, edge cases
|
├── PASS → merge no main, archive spec, remove worktree ✅
|
||||||
|
│
|
||||||
PASS → merge no main, archive spec, remove worktree
|
└── FAIL → volta pro Dev (até 3 tentativas)
|
||||||
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. Status dashboard
|
||||||
|
|
||||||
### 5. Ver status de tudo
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
dev-orchestrator status
|
dev-orchestrator status
|
||||||
```
|
```
|
||||||
|
|
||||||
Exemplo de output:
|
---
|
||||||
```
|
|
||||||
# FEATURE COMMITS SPEC WORKTREE
|
## Quando Sair do Orquestrador
|
||||||
─── ───────────────────────────── ───────── ───────── ──────────────
|
|
||||||
1. add-oauth-login 3 2/4 ../.worktrees/add-oauth-login/
|
O script cobre 90% dos casos. Saia dele quando:
|
||||||
2. fix-payment-timeout 1 active ../.worktrees/fix-payment-timeout/
|
|
||||||
```
|
| 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/
|
~/projetos/meu-app/
|
||||||
├── src/ # código principal
|
├── src/
|
||||||
├── openspec/
|
├── openspec/
|
||||||
│ ├── specs/ # specs arquivados (source of truth)
|
│ ├── specs/ # specs arquivados
|
||||||
│ └── changes/ # specs ativos
|
│ └── changes/ # specs ativos
|
||||||
│ └── add-oauth/
|
│ └── add-oauth/
|
||||||
│ ├── spec.md
|
│ ├── spec.md
|
||||||
@@ -128,65 +209,25 @@ Exemplo de output:
|
|||||||
../.worktrees/
|
../.worktrees/
|
||||||
└── add-oauth/ # worktree isolado
|
└── add-oauth/ # worktree isolado
|
||||||
├── .git # branch: dev-flow/add-oauth
|
├── .git # branch: dev-flow/add-oauth
|
||||||
├── src/ # cópia do código
|
├── src/
|
||||||
├── node_modules/ # instalado localmente
|
├── node_modules/
|
||||||
└── ...
|
└── ...
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## FAQ
|
## Opcional: Swarm Tools + .hive
|
||||||
|
|
||||||
### Posso rodar múltiplos features em paralelo?
|
Kanban mais visual, sem servidor:
|
||||||
|
|
||||||
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):
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install -g opencode-swarm-plugin
|
npm install -g opencode-swarm-plugin
|
||||||
swarm setup
|
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`.
|
||||||
Reference in New Issue
Block a user