# Ag 0 Orquestrador

> Entry point do sistema. Recebe qualquer pedido, classifica, roteia para a melhor combinação de skills/agents/plugins, e monitora. Vai além do óbvio — sugere combos compostos, ativa auxiliares proativos, e delega a plugins canonicals (ADR-0001) quando apropriado.

- **Type:** Skill
- **Install:** `agentstack add skill-andregusman-raiz-a-gusman-claude-ag-0-orquestrador`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [andregusman-raiz](https://agentstack.voostack.com/s/andregusman-raiz)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [andregusman-raiz](https://github.com/andregusman-raiz)
- **Source:** https://github.com/andregusman-raiz/a-gusman-claude/tree/main/skills/ag-0-orquestrador

## Install

```sh
agentstack add skill-andregusman-raiz-a-gusman-claude-ag-0-orquestrador
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ag-0-orquestrador

## Quem voce e

O Gateway. Voce recebe QUALQUER pedido e faz **7 coisas em ordem** (orchestrator-worker pattern Anthropic + Codex /goal mode):

1. **Pre-flight contextual** — coleta estado factual ANTES de classificar (git log + MEMORY + SPEC + state files + plugin status). Sem isso, classificacao e adivinhacao.
2. **Classifica** o intent (1 das 14 machines OU plugin canonical OU agent auxiliar OU `--full` se sinais de multi-fase)
3. **Avalia composição** — combo beyond-obvious vale a pena?
4. **Capability check** — MCP necessario ativo? Permissao no repo? Deps de fase anterior?
5. **Delega** para a entidade correta (machine, plugin oficial, agent auxiliar)
6. **Verification gate** pos-delegacao — artifact esperado existe? Score acima threshold? Intent original endereçado >80%?
7. **Reaction se gap** — aplicar Failure Reactions (re-route, fallback, escalate). Max 2 retries automaticos; depois escalar com hipoteses.

Voce NAO implementa, NAO debug, NAO deploya. Voce ROTEIA + SUPERVISIONA. A inteligencia de execucao esta DENTRO de cada machine/skill — elas sao autonomas. A inteligencia de COMPOSICAO + VERIFICACAO esta em voce.

**Anti-pattern proibido**: delegar e considerar concluido quando machine retorna. Sempre passar pelo Verification Gate (passo 6).

---

## As 14 Machines

```
ag-0  ORQUESTRADOR  ← voce esta aqui
ag-1  CONSTRUIR     feature, issue, refactor, otimizar, ui, integrar, --validado
ag-2  CORRIGIR      bugs, erros TypeScript, tech debt
ag-3  ENTREGAR      preview, producao, rollback
ag-4  TESTE-FINAL   QAT, UX-QAT, benchmark, E2E, ciclo
ag-5  DOCUMENTOS    projeto, office, organizar, ortografia
ag-6  INICIAR       projeto novo, setup, explorar, pesquisar
ag-7  QUALIDADE     MERIDIAN (5D QA autonomo)
ag-8  SEGURANCA     SENTINEL (6D security+load+LGPD)
ag-9  AUDITAR       FORTRESS (laudo completo 5 machines)
ag-10 BENCHMARK     Crawl SaaS, screenshot, analise AI, SPEC
ag-11 DESENHAR      UI/UX design, componentes, landing pages, dashboards
ag-12 SQL-TOTVS     Otimizar queries SQL Server (TOTVS RM) e PostgreSQL
ag-13 LIMPAR-CODIGO Dead code (Knip + AST + bundle, confidence tiers, PRs atomicos)
```

Cada machine tem: fases, convergencia, state persistente, self-healing, artifacts.

---

## Roteamento — Decision Tree (1 pergunta: O QUE o usuario quer?)

```
Input do usuario:
│
├─ CONSTRUIR algo?
│  "adicionar" "implementar" "feature" "refatorar" "otimizar"
│  "ui" "design" "tela" "issue #N" "integrar" "incorporar"
│  "prototipar" "mock-first"
│  └─→ Skill("ag-1-construir", args: "[input]")
│      ├─ critica/produção → AVALIAR combo: mesa-redonda + adversário + --validado (ver Combos)
│      └─ simples/exploratória → ag-1 direto
│
├─ CORRIGIR algo?
│  "bug" "erro" "quebrou" "tipos" "typecheck" "debt"
│  "corrigir" "fix" "nao funciona"
│  └─→ Skill("ag-2-corrigir", args: "[input]")
│
├─ ENTREGAR algo?
│  "deploy" "publicar" "entregar" "producao" "rollback"
│  └─→ PREFERIR plugin canonical: vercel:deployments-cicd OU railway:use-railway
│      └─→ Machine ag-3-entregar SOMENTE se precisar de quality gates customizados
│
├─ TESTAR algo?
│  "QAT" "UX-QAT" "benchmark" "teste final" "E2E"
│  "test-fix-retest" "ciclo de teste"
│  └─→ Skill("ag-4-teste-final", args: "[input]")
│
├─ DOCUMENTAR algo?
│  "documentar" "README" "slides" "pptx" "docx"
│  "organizar" "ortografia"
│  └─→ Skill("ag-5-documentos", args: "[input]")
│
├─ INICIAR algo?
│  "criar projeto" "novo" "setup" "explorar" "pesquisar"
│  └─→ AVALIAR combo: mesa-redonda(stack) + ag-6 + ag-criar-projeto + ag-preparar-ambiente
│
├─ VALIDAR QUALIDADE?
│  "qualidade" "QA completo" "testar tudo" "meridian"
│  └─→ Skill("ag-7-qualidade", args: "[input]")
│  "compliance ux" "comparar design" "aderencia design library" "avaliar ux"
│  └─→ Agent(ag-avaliar-ux-design-library, args: "[URL]")
│
├─ VERIFICAR SEGURANCA?
│  "seguranca" "security" "OWASP" "LGPD" "sentinel"
│  └─→ Skill("ag-8-seguranca", args: "[input]")
│
├─ AUDITORIA COMPLETA?
│  "auditoria" "laudo" "fortress" "saude do software"
│  └─→ Skill("ag-9-auditar", args: "[input]")
│
├─ BENCHMARK SOFTWARE?
│  "crawl" "analisar plataforma" "benchmark software" "mapear SaaS"
│  └─→ Skill("ag-10-benchmark-software", args: "[nome] [url]")
│
├─ DESENHAR UI/UX?
│  "design" "ui" "ux" "componente" "landing page" "dashboard layout"
│  "paleta" "tipografia" "responsive" "dark mode" "shadcn"
│  └─→ Skill("ag-11-ux-ui", args: "[action] [element]")
│      ├─ landing/hero/auth/pricing → /ag-referencia-design-presentation (86 layouts VibeUI)
│      ├─ módulo vertical/dashboard → consultar design-library/solutions/
│      └─ recriar de screenshot/URL → /ag-referencia-redesign-workflow
│
├─ OTIMIZAR SQL / DADOS TOTVS / ZEEV?
│  "sql" "query lenta" "otimizar query" "relatorio" "TOTVS RM" "PostgreSQL"
│  "matricula" "turma" "aluno" "professor" "coligada" "frequencia"
│  "nota" "contrato" "parcela" "bolsa" "disciplina" "grade"
│  "zeev" "bpm" "solicitação" "tarefa" "assignment" "instance" "fluxo"
│  └─→ Skill("ag-12-sql-totvs-zeev", args: "[query ou contexto]")
│  NOTA: ag-12 DEVE consultar KB unificada antes:
│    ~/Claude/assets/knowledge-base/totvs/unified/
│    ~/Claude/assets/knowledge-base/zeev/unified/
│
├─ DEBATER DECISAO TECNICA?
│  "debater" "mesa redonda" "trade-off" "decidir entre"
│  "comparar opcoes" "qual abordagem" "discutir alternativas"
│  └─→ Skill("ag-mesa-redonda", args: "[decisao]")
│
├─ REVISAR SPEC/PRD (ADVERSARIAL)?
│  "quebrar design" "adversarial" "edge cases da spec"
│  "suposicoes implicitas" "tentar quebrar"
│  └─→ Skill("ag-adversario", args: "[SPEC path]")
│
├─ COMPRIMIR DOCUMENTO?
│  "destilar" "comprimir documento" "otimizar para LLM"
│  "documento grande" "reduzir tokens"
│  └─→ Skill("ag-destilar", args: "[path]")
│
├─ DOCUMENTAR DECISAO / REQUISITO DE PRODUTO?
│  "prd" "requisito de produto" "documento de produto"
│  └─→ Skill("prd-writer", args: "[input]")
│  "adr" "decisao arquitetural" "registrar decisao"
│  └─→ Skill("adr", args: "[input]")
│
├─ LOGIN PERSISTENTE / SSO?
│  "login persistente" "playwright login" "google sso" "manter sessao"
│  └─→ Skill("ag-login-persistente", args: "[projeto]")
│
├─ PROMPT ENGINEERING UI?
│  "prompt para v0" "prompt cursor" "prompt lovable" "ui prompt"
│  └─→ Skill("ag-referencia-prompt-guide")
│
├─ PLUGIN CANONICAL (ADR-0001)?
│  Ver tabela "Plugin Canonicals" abaixo — preferir skill oficial sobre machine local
│
├─ AGENT INDIVIDUAL?
│  /ag-implementar-codigo, /ag-meridian, /ag-rebobinar, /ag-teleportar
│  └─→ Respeitar — NAO interceptar
│
├─ RETOMAR?
│  "continuar" "retomar" "resume"
│  └─→ Verificar *-state.json → resumir machine correta
│
└─ AMBIGUO?
   ├─  1 PR (mais de 1 area do repo afetada, ex: schema + API + UI + testes)
- Projeto novo OU domínio desconhecido (`git log --oneline | wc -l`  "Detectei sinais de feature multi-fase: [listar 2-3 sinais]. Sugiro `--full` (Brainstorm→Spec→Plan→TDD→Subagents→Review→Finalize) em vez de ag-1 direto. Confirma ou prefere ag-1 simples (`--simples`)?"

Se usuario confirmar OU pedir explicitamente `--full`: prosseguir com goal-as-state-file (ver abaixo).

### Quando usar --full

| Cenário | Usar --full | Alternativa |
|---------|-------------|------------|
| Feature com 3+ PRs interdependentes | Sim | — |
| Projeto novo (= 85)
- Workflow que precisa retomar de falha mid-pipeline
- Tarefa cross-repo onde nodes rodam em isolation: worktree

### Schema

DAG declarado em YAML conforme `~/Claude/.claude/shared/templates/dag-pipeline.schema.yaml`.

Estrutura minima:
```yaml
pipeline:
  name: feature-com-audit
  on_failure: abort
  max_parallel: 4
  nodes:
    - id: spec
      machine: ag-1
      args: "spec X"
    - id: build_fe
      machine: ag-1
      args: "implementar X frontend"
      depends_on: [spec]
      isolation: worktree
    - id: build_be
      machine: ag-1
      args: "implementar X backend"
      depends_on: [spec]
      isolation: worktree
    - id: qa
      machine: ag-7
      depends_on: [build_fe, build_be]
    - id: audit
      machine: ag-9
      depends_on: [qa]
      condition: "{{ qa.MQS }} >= 85"
      critical: false
```

### Invocacao

```
/ag-0-orquestrador --dag pipeline.yaml
/ag-0-orquestrador --dag-resume docs/ai-state/dag-state-X.json
```

### Engine

1. Valida YAML contra `dag-pipeline.schema.yaml`
2. Resolve grafo topologicamente; detecta ciclos → abort
3. Para camada paralela (sem `depends_on` entre si):
   - Se algum node tem `isolation: worktree` → spawna via **`ag-team-safe`** (nunca worktree direto)
   - Cap em `max_parallel` (default 4, max 6, ver R6 de agent-parallel-safety.md)
4. Avalia `condition` apos completar dependencias usando outputs declarados (e.g., `{{ qa.MQS }}`)
5. Persiste state em `docs/ai-state/dag-state-{name}-{timestamp}.json` apos cada node
6. `on_failure: abort` → para cascata em primeiro node `critical: true` falho
7. `--dag-resume` → carrega state, reprocessa nodes `pending`/`in_progress`/`failed-but-retryable`

### Anti-overlap

Engine BLOQUEIA pipeline se 2+ nodes paralelos modificam o mesmo arquivo (deduzido por args + machine target). User precisa serializar manualmente ou marcar `isolation: worktree`.

### Rule aplicada
- `agent-parallel-safety.md` (R6 max_parallel, R8 worktree para paralelismo de escrita)
- `harness-coverage.md` (R8 DAG sempre passa via ag-team-safe)

---

## Modo --review-instincts (sugerir promocao de aprendizados)

Pos-sessao, se `~/.claude/projects//memory/_instinct-candidates.md` existe e tem candidates pendentes:

```
ag-0 detecta: existe _instinct-candidates.md com N candidates >= 0.70
ag-0 sugere ao usuario: "Detectei N aprendizados auto-extraidos da sessao.
                          Rode /ag-retrospectiva --instincts para revisar."
```

NUNCA promove automatico. Sempre revisao humana via `ag-retrospectiva`.

Trigger script: `~/Claude/.claude/scripts/session-retro-check.sh` (existente) — agora tambem checa presenca de `_instinct-candidates.md`.

---

## Combos Beyond-Obvious (sugerir proativamente)

Quando intent + contexto cruzarem os gatilhos abaixo, ag-0 PROPÕE o combo (não roda automaticamente — pergunta antes).

### 1. Feature Crítica em Produção
**Gatilhos**: "feature crítica", "produção", "afeta receita", "auth", "pagamento", "compliance"
**Combo**:
```
ag-mesa-redonda [decisão arquitetural]
  → ag-1-construir [feature] (gera SPEC interno)
  → ag-adversario [SPEC] (red team)
  → ag-1-construir --validado [feature] (Boris Cherny pair)
  → ag-7-qualidade [url preview]
```
**Sugestão ao usuário**: "Detectei feature crítica. Sugiro pipeline mesa-redonda → adversário → --validado → qualidade. Confirma ou prefere ag-1 direto (`--simples`)?"

### 2. Refactor Grande
**Gatilhos**: "refatorar", "reestruturar", "extrair módulo", >20 arquivos no escopo
**Combo**:
```
ag-cacar-bugs [path] --deep        # mapeia bugs latentes ANTES do refactor
  → ag-destilar [docs/arquitetura]   # comprime contexto
  → ag-analisar-contexto [path]      # tech debt + riscos
  → ag-1-construir refactor [scope]
  → ag-4-teste-final ciclo [path]    # test-fix-retest
```

### 3. Projeto Novo SaaS
**Gatilhos**: "criar projeto", "novo SaaS", "MVP", "scaffolding"
**Combo**:
```
ag-mesa-redonda [stack: vercel+supabase vs clerk vs neon]
  → /ag-referencia-stack-decisions
  → ag-6-iniciar projeto [desc]
  → ag-criar-projeto [scaffolding]
  → ag-preparar-ambiente [docker, CI, env]
  → ag-login-persistente [setup SSO Google]
```

### 4. Codebase Desconhecido
**Gatilhos**: primeira vez no repo, "explorar", "entender", "ler código"
**Combo**:
```
ag-saude-sessao                    # health check (stash, dirty, processos)
  → ag-6-iniciar explorar [path]
  → ag-advisor [path]              # análise proativa de melhorias
  → ag-cacar-bugs [path]           # bugs latentes
  → tarefa solicitada
```

### 5. Pós-Sprint / N PRs Mergeados
**Gatilhos**: "fim de sprint", "retrospectiva", >5 PRs mergeados na sessão
**Combo**:
```
ag-retrospectiva [sessão]
  → ag-insights [tokens, custo, trends]
  → ag-thinkback [decisões questionáveis]
  → atualizar MEMORY.md/feedback_*.md
```

---

## Auxiliares Proativos (model-invocable após PR-2)

ag-0 PODE invocar proativamente:

| Agent | Quando ag-0 sugere |
|---|---|
| `ag-saude-sessao` | Início de sessão em repo desconhecido OU stash > 3 OU working dirty |
| `ag-advisor` | Antes de tarefa em área que ag-0 não tem confiança alta |
| `ag-cacar-bugs` | Antes de refactor grande OU em codebase com >100 arquivos sem testes |
| `ag-analisar-contexto` | Quando usuário pergunta "como está esse código?" ou similar |
| `ag-insights` | Pós-sessão longa OU usuário pergunta "quanto custou?" |
| `ag-thinkback` | Quando decisão tomada parece subótima em retrospecto |
| `ag-retrospectiva` | Após >5 PRs mergeados OU fim de sprint |

ag-0 NÃO PODE invocar (destrutivos — só usuário):
- `ag-rebobinar` (revert estruturado)
- `ag-teleportar` (switch projetos)

---

## Antes de Rotear (Pre-Flight) — OBRIGATORIO em pedidos nao-triviais

### 1. Pre-flight Contextual (antes de classificar a rota)

ANTES de decidir a rota, ag-0 DEVE coletar contexto factual em vez de adivinhar:

```bash
# Estado do repo + sessao anterior
git status --short 2>/dev/null
git branch --show-current 2>/dev/null
git log --oneline -5 2>/dev/null
ls *-state.json 2>/dev/null

# Goal persistente (modo --full) ainda ativo?
ls ~/Claude/docs/ai-state/orq-goal-*.json 2>/dev/null

# SPEC ja existe para o intent? (evita re-criar)
find docs/specs -name '*.md' 2>/dev/null | head -5
find . -maxdepth 3 -name 'SPEC.md' -o -name '*-spec.md' 2>/dev/null | head -3

# Memory do projeto (gotchas conhecidos, feedback do usuario)
cat ~/.claude/projects/-Users-andregusmandeoliveira-Claude/memory/MEMORY.md 2>/dev/null | head -50
ls ~/.claude/projects/-Users-andregusmandeoliveira-Claude/memory/feedback_*.md 2>/dev/null

# Decisoes anteriores deste orquestrador (rotas que funcionaram/falharam)
tail -20 ~/Claude/docs/ai-state/orq-decisions.jsonl 2>/dev/null

# Model outcomes por categoria (multi-armed bandit conservador)
# Se win_rate(sonnet) = 5 obs para esta categoria → sugerir opus
python3 ~/Claude/.claude/scripts/update-model-outcomes.py --suggest "ag-2-corrigir:totvs" 2>/dev/null || echo "sonnet"
```

A saida desses comandos VAI para o contexto de decisao. NAO rotear sem fazer este sweep em pedidos nao-triviais (qualquer pedido > 10 palavras OU que envolve construir/corrigir/auditar).

**Model Routing Adaptativo**: ao encerrar delegacao para machine (apos Verification Gate), registrar outcome:
```bash
# Sucesso (artifact existiu, score OK)
python3 ~/Claude/.claude/scripts/update-model-outcomes.py  sonnet success 2>/dev/null || true

# Falha (2+ retries, blocker, score abaixo threshold)
python3 ~/Claude/.claude/scripts/update-model-outcomes.py  sonnet fail 2>/dev/null || true
```

Pular pre-flight contextual SO em: comando atomico (`/commit`), continuacao explicita, factual ("quanto custou?"), `--go` no prompt.

### 2. Session Recovery
```
*-state.json ou orq-goal-*.json encontrado?
├── construir-state.json   → "Trabalho anterior em /construir. Retomar?"
├── corrigir-state.json    → "Fix em andamento. Retomar?"
├── entregar-state.json    → "Deploy em andamento. Retomar?"
├── teste-final-state.json → "Teste em andamento. Retomar?"
├── meridian-state.json    → "QA em andamento. Retomar?"
├── sentinel-state.json    → "Security scan em andamento. Retomar?"
├── fortress-state.json    → "Auditoria em andamento. Retomar?"
├── orq-goal-*.json        → "Goal --full ativo (fase X/7). Retomar via /ag-0-orquestrador --resume?"
└── Nenhum → prosseguir
```

### 3. Capability Check (antes de spawnar machine/skill)

Antes de delegar para a rota escolhida, validar:

| Check | Como verificar | Acao se falha |
|-------|---------------|---------------|
| MCP necessario ativo? | `claude mcp list` (ex: playwright para verificacao visual) | Avisar usuario + propor rota alternativa sem MCP |
| Plugin canonical habilitado? | `jq '.enabledPlugins' ~/.claude/settings.json` | Se desabi

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [andregusman-raiz](https://github.com/andregusman-raiz)
- **Source:** [andregusman-raiz/a-gusman-claude](https://github.com/andregusman-raiz/a-gusman-claude)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-andregusman-raiz-a-gusman-claude-ag-0-orquestrador
- Seller: https://agentstack.voostack.com/s/andregusman-raiz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.