jpporta/ndots
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

docs: expand WORKFLOW.md with tool interaction guide

Browse Source 
- 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
This commit is contained in:
hermes
2026-08-04 18:26:08 -03:00
parent 6d861958ce
commit c53a7f278b
1 changed files with 151 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tooling/WORKFLOW.md
+151 -110
View File
@@ -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,179 +65,169 @@ 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
│ ├── design.md │ ├── design.md
│ └── tasks.md │ └── tasks.md
├── .gitignore # inclui .worktrees/ ├── .gitignore # inclui .worktrees/
└── ... └── ...
../.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`.