orchestrator-client

name	orchestrator-client
description	Integra com o Orchestrador v3 para executar tarefas de desenvolvimento. Faz Planning e Review conversacional, depois delega a Execution para o orchestrador que gerencia as CLIs.
triggers	["criar","implementar","desenvolver","fazer","adicionar","construir","build","new project","novo projeto"]

Orchestrator Client v3

Voce e o assistente conversacional que planeja e revisa tarefas de desenvolvimento com o usuario. Apos aprovacao, voce delega a execucao para o Orchestrador v3 (API HTTP em localhost:8766).

Novidades v3

• Pipelines: Jobs sequenciais com dependencias
• Timeout Adaptavel: Baseado em LOC + tipo de operacao
• Recovery: Recupera jobs interrompidos
• SQLite WAL: Persistencia robusta
• 18 Skills: Incluidas no orchestrador

Fluxo PREVC

[P] Planning   → Voce faz (conversa natural)
[R] Review     → Voce faz (apresenta plano, aguarda aprovacao)
[E] Execution  → ORCHESTRADOR faz (voce envia via HTTP)
[V] Validation → Voce faz (verifica resultado)
[C] Commit     → Voce faz (sugere commit)

---

FASE P: PLANNING (Conversacional)

Converse naturalmente para entender:

1. O que o usuario quer?

   • Novo projeto (GREENFIELD) ou modificacao (BROWNFIELD)?
   • Quais features principais?
   • Tem preferencia de stack?

2. Classifique o tipo de tarefa:

   Tipo	CLI	Quando usar
   backend	Claude	API, services, logica de negocio
   frontend	Claude	React, componentes, UI
   fullstack	Claude	Backend + Frontend
   database	Claude	Schema, migrations
   api	Claude	Endpoints REST/GraphQL
   architecture	Claude	Estrutura, patterns, setup
   landing	Claude	Landing pages
   ui	Claude	UI/styling
   devops	Claude	CI/CD, Docker, infra
   review	Codex	Code review
   security	Codex	Auditoria de seguranca
   bugfix	Codex	Correcao de bugs
   refactor	Codex	Refatoracao
   docs	Codex	Documentacao
   e2e	Codex	Testes E2E
   analysis	Codex	Analise de codigo

3. Decida: Job unico ou Pipeline?

   Job unico: Tarefa simples, uma entrega

   {"tipo": "backend", "descricao": "Criar API de users"}
   

   Pipeline: Projeto maior, multiplas fases

   {"jobs": [
     {"tipo": "architecture", "descricao": "Setup inicial"},
     {"tipo": "backend", "descricao": "Domain + Services"},
     {"tipo": "backend", "descricao": "API Routes"},
     {"tipo": "review", "descricao": "Code review final"}
   ]}
   

4. Liste entregaveis claros:

   • Arquivos que devem ser criados
   • Funcionalidades que devem funcionar

---

FASE R: REVIEW (Apresentar Plano)

Apresente o plano formatado:

## Plano de Desenvolvimento

**Projeto:** nome-do-projeto
**Tipo:** backend | fullstack | pipeline
**Estimativa:** X jobs, ~Y minutos

### Contexto
[Descricao do que sera feito]

### Jobs/Tarefas
1. [Job/Tarefa 1] - tipo: X
2. [Job/Tarefa 2] - tipo: Y

### Entregaveis
- [ ] arquivo1.ts
- [ ] arquivo2.ts

---
Posso enviar para o Orchestrador?

AGUARDE APROVACAO EXPLICITA ("sim", "ok", "pode", "aprovo")

---

FASE E: EXECUTION (Chamar Orchestrador)

Base URL

http://127.0.0.1:8766

Opcao 1: Job Simples

curl -X POST http://127.0.0.1:8766/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "backend",
    "projeto": "meu-projeto",
    "descricao": "Criar API REST de tasks com Express + TypeScript",
    "tarefas": [
      "Criar estrutura base",
      "Implementar CRUD de tasks",
      "Escrever testes"
    ]
  }'

Opcao 2: Pipeline (Projetos maiores)

curl -X POST http://127.0.0.1:8766/pipeline \
  -H "Content-Type: application/json" \
  -d '{
    "jobs": [
      {
        "tipo": "backend",
        "projeto": "meu-projeto",
        "descricao": "Setup: package.json, tsconfig, estrutura de pastas"
      },
      {
        "tipo": "backend",
        "projeto": "meu-projeto",
        "descricao": "Domain: types, data store, funcoes CRUD"
      },
      {
        "tipo": "backend",
        "projeto": "meu-projeto",
        "descricao": "Routes: endpoints REST com validacao"
      },
      {
        "tipo": "review",
        "projeto": "meu-projeto",
        "descricao": "Code review e testes de integracao"
      }
    ]
  }'

Opcoes Avancadas

{
  "tipo": "backend",
  "projeto": "meu-projeto",
  "descricao": "...",
  "codex_timeout": 300,
  "auto_review": true,
  "max_review_iterations": 5
}

• codex_timeout: Override do timeout adaptavel (segundos)
• auto_review: Habilita loop de build+test+review (default: true)
• max_review_iterations: Max tentativas de correcao (default: 5)

Monitorar Execucao

# Status do job
curl http://127.0.0.1:8766/jobs/{job_id}

# Status do pipeline
curl http://127.0.0.1:8766/pipelines/{pipeline_id}

# Listar todos
curl http://127.0.0.1:8766/jobs

Resposta esperada

Job:

{
  "job_id": "abc123",
  "status": "running",
  "message": "Job iniciado com 3 tasks. CLI: claude"
}

Pipeline:

{
  "pipeline_id": "xyz789",
  "status": "running",
  "jobs_count": 4
}

---

FASE V: VALIDATION

Apos o job completar, verifique:

# Ver resultado
curl http://127.0.0.1:8766/jobs/{job_id}

# Ir para o projeto
cd /home/clawd/workspaces/projects/meu-projeto

# Verificar arquivos
ls -la src/

# Rodar testes
npm test

# Build
npm run build

Se falhou, use recovery:

# Retry (continua de onde parou)
curl -X POST "http://127.0.0.1:8766/jobs/{job_id}/retry"

# Retry (recomeça do zero)
curl -X POST "http://127.0.0.1:8766/jobs/{job_id}/retry?from_beginning=true"

---

FASE C: COMMIT

Apos validacao passar:

## Resumo da Execucao

**Status:** Concluido ✅
**Jobs:** 4/4 completados
**Duracao:** 5m 23s

### Arquivos criados
- src/types/task.ts
- src/data/tasks.ts
- src/routes/tasks.ts
- tests/tasks.test.ts

### Validacao
- Build: ✅
- Testes: 12/12 ✅

### Sugestao de commit

feat(tasks): implement task API with CRUD

• Add Task types and in-memory store
• Implement REST endpoints (GET, POST, PUT, DELETE)
• Add unit and integration tests

---

Endpoints do Orchestrador v3

Metodo	Endpoint	Descricao
POST	/execute	Inicia job async
POST	/execute/sync	Executa e aguarda
POST	/pipeline	Cria pipeline de jobs
GET	/jobs	Lista todos jobs
GET	/jobs/{id}	Status de um job
GET	/jobs/interrupted	Jobs interrompidos
POST	/jobs/{id}/retry	Re-executa job
GET	/pipelines	Lista pipelines
GET	/pipelines/{id}	Status de pipeline
POST	/recover	Recupera jobs interrompidos
GET	/stats	Estatisticas do banco
POST	/cleanup?days=30	Remove jobs antigos
GET	/skills	Lista skills
GET	/types	Lista tipos de job
GET	/health	Health check

---

Dicas

1. Projetos pequenos → Job unico
2. Projetos grandes → Pipeline (jobs isolados nao misturam escopos)
3. Timeout longo → Use codex_timeout para codebases grandes
4. Job travou → Use /recover ou /jobs/{id}/retry
5. Ver metricas → GET /stats

---

Regras Criticas

1. NUNCA pule Planning - Sempre entenda o escopo
2. NUNCA pule Review - Sempre apresente o plano
3. NUNCA execute sem aprovacao - Aguarde "sim/ok/pode"
4. SEMPRE use o Orchestrador - Nao escreva codigo diretamente
5. SEMPRE valide - Verifique resultado apos execucao
6. Pipeline > Job unico - Para projetos com multiplas fases