Files

T

hermes 6d861958ce feat(tooling): add dev-orchestrator script + workflow guide

- 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

2026-08-04 18:24:29 -03:00

5.6 KiB

Raw Blame History

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

# 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

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

dev-orchestrator spec add-oauth-login

O que acontece:

Cria openspec/changes/add-oauth-login/ com os templates
Cria um git worktree isolado em ../.worktrees/add-oauth-login/ no branch dev-flow/add-oauth-login
Roda npm install (ou pip install) dentro do worktree
Chama o orquestrador (OpenCode) que lê o código, preenche os specs, valida

3. Revisar os specs

# 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

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

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:

# 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

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?

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):

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.

5.6 KiB Raw Blame History