hermes
6d861958ce
- dev-orchestrator: OpenSpec + OpenCode dev→QA loop with git worktrees - WORKFLOW.md: complete usage guide and architecture documentation Commands: init, spec, build, status, clean Zero heavy dependencies — only git, opencode, openspec
193 lines
5.6 KiB
Markdown
193 lines
5.6 KiB
Markdown
# Dev Orchestrator — AI Workflow Guide
|
|
|
|
Workflow de desenvolvimento com IA usando **OpenCode** + **OpenSpec** + **git worktrees**, com orquestração automática do loop dev→QA.
|
|
|
|
```
|
|
Você (review specs) → Orquestrador (specs) → Dev Agent (implementa) → QA Agent (revisa)
|
|
↑ │
|
|
└─────────────────── FAIL ──────────────────────────┘
|
|
PASS → merge → archive
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|
|
```
|
|
|
|
---
|
|
|
|
## Comandos
|
|
|
|
| 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) |
|
|
|
|
---
|
|
|
|
## Fluxo Completo
|
|
|
|
### 1. Inicializar o projeto
|
|
|
|
```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
|
|
|
|
```bash
|
|
dev-orchestrator spec add-oauth-login
|
|
```
|
|
|
|
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
|
|
|
|
### 3. Revisar os specs
|
|
|
|
```bash
|
|
# Ver arquivos gerados
|
|
ls openspec/changes/add-oauth-login/
|
|
cat openspec/changes/add-oauth-login/spec.md
|
|
|
|
# Validar
|
|
openspec validate add-oauth-login --strict
|
|
```
|
|
|
|
**Aqui você está no controle.** Revise os specs, ajuste o que quiser.
|
|
Só prossiga quando estiver satisfeito.
|
|
|
|
### 4. Disparar o build
|
|
|
|
```bash
|
|
dev-orchestrator build add-oauth-login
|
|
```
|
|
|
|
O que acontece:
|
|
```
|
|
── 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)
|
|
```
|
|
|
|
Se o QA falhar 3 vezes, o worktree é mantido pra você inspecionar e corrigir manualmente.
|
|
|
|
### 5. Ver status de tudo
|
|
|
|
```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/
|
|
```
|
|
|
|
---
|
|
|
|
## Estrutura de diretórios
|
|
|
|
```
|
|
~/projetos/meu-app/
|
|
├── src/ # código principal
|
|
├── openspec/
|
|
│ ├── specs/ # specs arquivados (source of truth)
|
|
│ └── changes/ # specs ativos
|
|
│ └── add-oauth/
|
|
│ ├── spec.md
|
|
│ ├── design.md
|
|
│ └── tasks.md
|
|
├── .gitignore # inclui .worktrees/
|
|
└── ...
|
|
|
|
../.worktrees/
|
|
└── add-oauth/ # worktree isolado
|
|
├── .git # branch: dev-flow/add-oauth
|
|
├── src/ # cópia do código
|
|
├── node_modules/ # instalado localmente
|
|
└── ...
|
|
```
|
|
|
|
---
|
|
|
|
## FAQ
|
|
|
|
### 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):
|
|
|
|
```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.
|
|
|
|
O script `dev-orchestrator` funciona com ou sem Swarm Tools. São independentes.
|