# 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.