Skip to content
BranchesTags

Repository files navigation

deep-orchestrator-agent-skill v4.0.0

Versão

Orquestrador autônomo multi-agente para Claude Code — planeja, divide em ondas ILIMITADAS (com recálculo dinâmico), cria worktrees isoladas, delega, revisa adversarialmente, integra via squash-merge um a um com gate em snapshot de integração (worktree efêmera int-ondaN-*, fora da seção crítica), verifica a dependência de pesquisa antes de cada onda (surf-agent-skill v8 — Brave é o único backend; sem chave válida o surf sai 78 e a onda não dispara), e commita tudo ao final sem perguntar nada ao usuário.

A única exceção — e ela só existe quando você pede — é o PORTÃO DE APROVAÇÃO DO PLANO (FASE 2.5): quando a invocação pede um plano, o plano vai para o Plannotator e você aprova ou anota. Cada anotação regera o plano e abre um Plannotator NOVO, até a aprovação — e nenhuma worktree nasce antes dela. Sem pedido de plano, a autonomia total continua exatamente como sempre foi.

Ao FIM da execução — depois de TUDO (commit, push e relatório) — a evolução vem como UMA PERGUNTA EM TEXTO no terminal (v3.9.0, nunca mais um site): cada proposta numerada com opções e escopo, e você responde com códigos (ex.: 1:b2 — opção b, fix global), ou nada para pular (tudo fica pendente, nada é aplicado). A flag no-evolve na invocação pula a pergunta e a análise do histórico.

Glossário (leia antes do resto)

Termo O que é
$SKILL_HOME A casa da skill: scripts/ e prompts/. Fica fora do projeto-alvo e é somente leitura/execução durante uma execução. Caminhos escritos como $SKILL_HOME/... são daqui; caminhos sem prefixo são do repositório-alvo.
RAIZ-DE-MUNDO ($BASE_DIR) git rev-parse --show-toplevel no diretório de invocação. Se você invocou dentro de uma git worktree vinculada, é a worktree — não o projeto principal. É a fronteira de escrita.
$BASE_BRANCH O branch em HEAD na raiz-de-mundo. É o único alvo de integração. Nunca é resolvido por convenção (main/master).
$MAIN_ROOT O checkout principal do repositório. Em MODO CONTIDO é zona proibida.
WORKTREE-FILHA Uma worktree por sub-agente, criada sob $CHILD_ROOT, com branch $BRANCH_NS/<nome>.
.deep-orchestrator-preferences/ Memória consultiva da skill e do projeto (contexto NÃO revisado, nunca política executável, gitignored). Do projeto: project-config.md + learnings.md + pending/; da skill: global-tips.md + pending/. Escrita por scripts/do-prefs.sh (validada, deduplicada) com o voto do usuário na pergunta de evolução (scripts/evolution-survey.sh); consultada pela FASE 1 antes de planejar.
prompts/evolution-guide.md Framework de decisão da evolução: o que qualifica, como classificar project vs global, e o caminho das prefs ao corpo da skill.

Instalação (o contrato)

A skill é distribuída como um repositório git; a casa da skill ($SKILL_HOME) é a raiz do repositório — o diretório que contém SKILL.md, scripts/ e prompts/. Instalação incompleta = FASE 0 aborta com PARE: do-context.sh nao encontrado.

  • O SKILL.md da raiz é um symlink para ./.claude/skills/deep-orchestrator-agent-skill/SKILL.md (padrão Claude Code). Desde a v3.5.1, scripts/ e prompts/ são espelhados por symlink dentro de .claude/skills/deep-orchestrator-agent-skill/ — assim qualquer dos dois alvos (a raiz ou a pasta .claude) é uma casa válida, e um harness que resolva SKILL_HOME para a pasta interna não fica sem scripts. templates/ existiu até a v3.6.0 e foi removido.
  • Instalar: a skill NÃO assume onde cada agente vive — crie UMA entrada onde o SEU harness descobre skills (um symlink para a raiz do repo, não a pasta interna; ex.: ln -s /caminho/do/repo <diretório-de-skills-do-seu-harness>/deep-orchestrator-agent-skill). Confira a doc do seu harness para o caminho de descoberta. Qualquer casa é válida — a FASE 0 resolve $SKILL_HOME pela localização dos próprios scripts, nunca por um caminho fixo. Depois verifique com ./scripts/check-install.sh --root <casa>.
  • Harnesses (Claude Code, DSH, pi, jcode, opencode...): cada um descobre skills à sua maneira — crie o symlink no caminho que o SEU usa (a FASE 0 testa primeiro as variáveis do harness, ex. $CLAUDE_SKILL_DIR, e depois alguns diretórios comuns apenas como última tentativa). Sem script de "publicação global": instalar é um comando seu, um symlink, e pronto.
  • Verificar uma instalação: ./scripts/check-install.sh [--root <dir>] — exit 0 = completo (SKILL.md + ferramentas executáveis + prompts), 1 = faltando itens, 2 = uso inválido. Rode depois de qualquer instalação/atualização.
  • Um clone legado por cópia (ex.: ~/.local/share/deep-orchestrator/) congela a versão do dia — prefira o symlink (recrie o link apontando para a raiz do repo).

MODO CONTIDO

Se a skill for invocada com o cwd dentro de uma git worktree vinculada, ela entra em MODO CONTIDO e trata essa worktree como raiz-de-mundo:

  • os squash-commits vão para o branch da worktree, jamais para main/master;
  • nenhum arquivo é escrito no projeto principal — do-wt.sh verify confere ao fim de cada onda o HEAD, a working tree (incluindo arquivos ignorados, para pegar um node_modules/ nascendo lá) e o config local contra o baseline da FASE 0. A prova é de autoria, não de imutabilidade: se o principal mudou mas nenhum commit desta execução é alcançável a partir do HEAD dele, é ALERTA (você trabalhando em paralelo), não violação;
  • as worktrees-filhas nascem num container irmão oculto <pai>/.<worktree>-do/<RUN_ID>/ (fallback automático para <worktree>/.deep-orchestrator/worktrees/ quando o irmão cairia dentro de outro repositório git; force com DO_FORCE_NESTED=1);
  • os branches vivem num namespace exclusivo por execução (do/<slug>/<RUN_ID>/<nome>), então duas orquestrações simultâneas não se apagam;
  • a limpeza usa allowlist (owned.tsv + lock nativo do git), nunca varredura: git worktree list e git branch --list enxergam worktrees de outras sessões, e git worktree prune é proibido;
  • a sujeira que já existia na worktree antes da execução é do usuário e nunca entra nos commits (do-wt.sh stage-delta).

O único vestígio compartilhado aceito é o registro administrativo das filhas em $GIT_COMMON_DIR/worktrees/, que o próprio git cria e é inevitável.

Em MODO NORMAL (invocação na árvore principal) valem as mesmas invariantes, com $CHILD_ROOT em <pai>/<repo>-worktrees/<RUN_ID>/.

Novidades na v3.9.0

  • EVOLUÇÃO COMO PERGUNTA NO TERMINAL (nunca mais um site): o questionário Plannotator acabou — depois de TUDO (commit, push e relatório), o orquestrador imprime uma pergunta em texto com as propostas do agente de evolução, cada uma numerada com opções e escopo: 
    1 - Toda vez que criamos uma worktree precisamos instalar as dependências
   como resolver definitivamente?
   a: usar symlinks para as dependências
   b: merge para principal e testar
   c: Não fazer nada (descartar)
   (1 = fix local · 2 = fix global — qual config você quer? ex.: 1:b2)
    Você responde na próxima mensagem com códigos (1:b2, nada para pular, config: <texto> para preferências livres). A opção escolhida vira a ação salva (a/b = salvar no escopo indicado; c = descartar). Sem resposta → tudo fica pendente, nada é aplicado (scripts/evolution-survey.sh ask/answer/apply/dismiss).
  • FLAG no-evolve: na invocação (/deep-orchestrator-agent-skill no-evolve <tarefa>), pula a pergunta e o pós-processamento — o agente de evolução que lê todo o histórico (handoffs + transcripts + TASK_PLAN.md) nem roda.
  • PUSH NO COMMIT-FINAL: o passo final agora commita e faz push do $BASE_BRANCH (nunca bloqueia; sem remote → registra e segue) — a pergunta de evolução vem depois de TUDO, incluindo o push.
  • Prefixo max-parallel=N: mp=N virou max-parallel=N na invocação (DO_MAX_PARALLEL, default 50) — mesmo cap de concorrência, nome explícito. Decisões D18–D22 em docs/decisions/2026-08-28-pergunta-evolucao-terminal.md.

Novidades na v3.8.0

  • QUESTIONÁRIO DE EVOLUÇÃO PÓS-EXECUÇÃO (substituído pela v3.9.0): ao fim de cada execução, UM sub-agente fresco analisa o histórico completo (handoffs de todas as ondas + transcripts do harness quando existem) e sobe um questionário próprio no Plannotator (só as perguntas, SEM limite de tempo): o usuário decide por proposta salvar/não salvar e o escopo projeto ou global (scripts/evolution-survey.sh round/answers/apply). Fechou sem responder → tudo fica PENDENTE e nada é aplicado.
  • PREFS POR PROJETO (.deep-orchestrator-preferences/): configs e aprendizados do projeto ficam no PRÓPRIO projeto (carregados na FASE 1, salvo quando o usuário decide salvar); dicas globais ficam na MESMA pasta dentro da skill — tudo gitignored (memória consultiva, nunca política). ensure-gitignore acrescenta a linha no .gitignore de cada projeto automaticamente.
  • LEARNINGS.md REMOVIDO DO REPO: as 59 entradas antigas foram reclassificadas — as globais migraram para global-tips.md; as de projeto específico saíram (git history preserva). evolve-skill.sh não commita mais memória (add/consolidate saem com mensagem de migração); o apply de CORPO vai sempre para branch evolve/YYYY-MM-DD + diff, nunca merge sozinho.
  • A FASE 1 consulta prefs + memória antes de planejar (do-prefs.sh load + evolve-skill.sh search) — evita repetir erros e respeita as preferências declaradas do projeto. Decisões D12–D17 em docs/decisions/2026-08-27-questionario-evolucao.md. Testes: scripts/test-evolve.sh (suíte F1–Fxx nova).

Novidades na v3.7.0

  • AUTO-EVOLUÇÃO CONTÍNUA (substituída pela v3.8.0): retrospectiva do orquestrador + evolve-skill.sh add no LEARNINGS.md commitado. Esse mecanismo foi substituído pelo questionário + prefs gitignored — o LEARNINGS.md não existe mais no repo.

Novidades na v3.6.0

  • HTML Explainer v3.6.0 (novo fluxo): o EXPLAINER.html do COMMIT-FINAL deixa de ser gerado pelo script scripts/generate-explainer.sh + template templates/html-explainer.html (ambos REMOVIDOS). Agora o orquestrador delega a um sub-agente que segue a skill html-explainer-agent-skill (brief didático: leitor, portão de complexidade, buzzwords, figuras com afirmação na legenda e arestas rotuladas, andaime dobrado) e renderiza com visual-explainer/plannotator-visual-explainer — SEM limite de tempo (a geração pode demorar o quanto precisar) e SALVANDO NO LUGAR em EXPLAINER.html na raiz da raiz-de-mundo (a UI do Plannotator é opcional e nunca substitui o arquivo). Degradação documentada: se o fluxo falhar, o orquestrador grava um EXPLAINER.html mínimo via Bash (exceção R1-c) e registra no relatório.
  • Contrato de instalação atualizado: scripts/check-install.sh não exige mais generate-explainer.sh nem templates/.
  • Plannotator como runtime do EXPLAINER (auto-instalado): o novo fluxo do EXPLAINER usa o backend de render/anotação do Plannotator — o html-explainer-agent-skill delega a renderização ao plannotator-visual-explainer (tokens de tema do Plannotator aplicados ao arquivo final). O binário é instalado automaticamente quando ausente (scripts/check-plannotator.sh --install, modo --minimal → só ~/.local/bin; mínima 0.19.1) e foi verificado na máquina de referência em v0.27.6. A entrega continua sendo o ARQUIVO EXPLAINER.html salvo no lugar — a UI de anotação é opcional e nunca substitui o arquivo.

Novidades na v3.5.1

  • Instalação à prova de alvo errado (bugfix do contrato): a pasta .claude/skills/deep-orchestrator-agent-skill/ (padrão Claude Code) passou a espelhar scripts/, prompts/ e templates/ por symlink para a raiz — antes ela continha apenas o SKILL.md, e qualquer harness que resolvesse $SKILL_HOME para ela rodava FASE 0 e abortava com PARE: do-context.sh nao encontrado (era o estado da instalação do DSH após o rebrand). Agora qualquer alvo de instalação é uma casa válida, e instalações existentes apontadas para a pasta interna passam a funcionar sem repontar symlink.
  • FASE 0 mais abrangente: a busca do do-context.sh ganhou o candidato ${DSH_HOME:-$HOME/.dsh}/skills/deep-orchestrator-agent-skill (raiz de skills do usuário no DeepSeek Harness).
  • scripts/check-install.sh: nova prova de instalação completa (SKILL.md + ferramentas executáveis + prompts + template; exit 0/1/2; --root, --json, --quiet) — detecta o estado "só SKILL.md, sem scripts" antes de qualquer execução.
  • README: nova seção "Instalação (o contrato)" com o layout aceito, o DSH (ambas as raízes) e o passo de verificação.

Novidades na v3.5.0

  • Flag no-stop (DO_NO_STOP): remove o teto de 10 ondas por execução. Quando presente, a execução dura quantas ondas forem necessárias até o REVISOR DE PLANO declarar convergência — ideal para quem quer qualidade máxima sem teto arbitrário de rodadas. A válvula anti-loop permanece ativa mesmo com no-stop: 2 REPLANs consecutivos sem novas sub-tarefas ACEITAS forçam a convergência (documentada no relatório final), então a execução nunca itera para sempre sem progresso. Invocação: /deep-orchestrator-agent-skill no-stop <tarefa>. Ausente → default 0 (teto histórico de 10 ondas preservado).
  • Validação e guarda no do-context.sh: a flag é parseada antes da FASE 0 e exportada como DO_NO_STOP (valores 0/1/on/off/yes/no/true/false; inválido → die 2 com mensagem clara), gravada no ENV_FILE, exportada, exibida no resumo da FASE 0 (NO_STOP = ON/OFF), e protegida por guarda anti-stale no caminho DO_REUSE (espelhando o guarda de DO_PLAN_APPROVAL) — reaproveitar um env com valor divergente cria execução nova em vez de inverter a flag em silêncio.

Novidades na v3.4.0

  • PORTÃO DE APROVAÇÃO DO PLANO (FASE 2.5, R10): quando a invocação pede um plano, o plano vai para o Plannotator e o usuário aprova ou anota, no navegador. Cada anotação REGERA o plano e abre um Plannotator inteiramente NOVO (processo novo, servidor novo, aba nova) — nunca um remendo na sessão anterior — até a aprovação ou até o orçamento de revisões acabar. Nenhuma worktree, branch ou commit existe antes do APROVADO, e é justamente por isso que o portão fica aqui: recusar o plano não custa rollback nenhum.
  • Ligado só quando pedido: DO_PLAN_APPROVAL é resolvido uma vez na FASE 0 (passo 0.5) por precedência — prefixo plan=on/plan=off > variável de ambiente > gatilhos negativos ("não me pergunte nada", "autônomo", "toca o barco") > gatilhos positivos ("faça um plano", "quero aprovar antes", "revisar o plano") > default OFF. Quem nunca falou em plano tem exatamente o comportamento autônomo de sempre: nenhum navegador abre.
  • Instalação automática do Plannotator: scripts/check-plannotator.sh --install resolve o executável ($DO_PLANNOTATOR_BIN → PATH → ~/.local/bin, que quase nunca está no PATH de um shell não-interativo), confere a versão (mínima 0.19.1) e sonda a capacidade rodando annotate sem argumento — que só imprime o usage, sem abrir navegador. Ausente, instala com --minimal: só o binário, sem encostar em ~/.claude, ~/.codex, ~/.gemini, ~/.kiro ou ~/.config/opencode. Uma instalação existente nunca é sobrescrita. Nunca sudo, nunca npm -g.
  • Independente do agente: o portão é uma chamada Bash — o menor denominador comum entre Claude Code, pi coding agent, jcode e opencode. Nada de hook de plan-mode, ExitPlanMode ou plugin de um agente específico, porque nada disso existe nos quatro. O harness é detectado (Claude Code > pi > jcode > opencode) só para carimbar PLANNOTATOR_ORIGIN na UI; a detecção jamais bloqueia o portão.
  • Título imutável: o Plannotator rastreia revisões do mesmo plano pelo primeiro # do documento. plan-approval.sh recusa (exit 2) a rodada cujo título mudou, com o título travado na mensagem — é a mesma regra que o próprio Plannotator impõe ("Do NOT change the plan title").
  • Decisão por exit code, nunca por texto: plan-approval.sh round devolve 0 aprovado · 10 anotado · 11 fechado · 12 timeout · 13 falha da ferramenta · 14 orçamento esgotado. Cada rodada deixa um snapshot imutável (rev-NNN.md, somente leitura), o feedback (rev-NNN.feedback.md) e uma linha no trail.tsv.
  • O plano aprovado vira restrição: o REVISOR DE PLANO da FASE 3 passa a classificar cada proposta em DENTRO ou FORA do escopo aprovado. FORA reabre o portão uma vez (consumindo do mesmo orçamento); sem orçamento, a proposta é registrada como FORA-DO-ESCOPO-NÃO-APROVADA e o escopo aprovado é respeitado.
  • O plano nunca sai da máquina sozinho — duas travas independentes, ambas ligadas por default:
    • PLANNOTATOR_SHARE=disabled impede o upload do texto do plano para o serviço de paste, que o Plannotator faria em sessão remota. Libere com DO_PLAN_SHARE=1.
    • PLANNOTATOR_REMOTE=0 mantém o servidor em 127.0.0.1. Sem isso, qualquer shell com SSH_TTY/SSH_CONNECTION no ambiente — o caso normal de um servidor de desenvolvimento — faria o Plannotator escutar em 0.0.0.0:19432; e como /api/approve não tem autenticação, qualquer pessoa que alcançasse a máquina leria o plano e poderia aprová-lo por você, levando o orquestrador a criar worktrees e commitar. Para revisar por SSH, use um túnel: ssh -L 19432:127.0.0.1:19432 <host>. DO_PLAN_REMOTE=1 expõe na rede de propósito, com aviso em voz alta.
  • Testes: scripts/test-plan-approval.sh — 133 asserções (130 PASS; 3 falhas de ambiente macOS conhecidas: timeout(1) ausente), tudo mockado (binário e instalador falsos num PATH temporário), sem rede, sem navegador e sem instalar nada.

Novidades na v3.3.0

  • Sistema de busca 3-tier (F1-03) — SUPERADO na v4.0.0: o sistema de busca interno foi REMOVIDO; a pesquisa é 100% surf-agent-skill v8 (ver docs/decisions/2026-08-29-surf-agent-skill-obrigatorio.md). Descrição histórica: scripts/search.sh — surf-agent-skill (Tier 1, multi-provider AI-powered) → Brave Search API (Tier 2, via search_brave_api() do brave-search.sh) → DuckDuckGo keyless (Tier 3, Instant Answer, cobertura limitada). Verificação de tiers antes de cada onda via scripts/check-search-credits.sh (exit 0 = Tier 1/2 disponível; exit 1 = só Tier 3, degradado; exit 2 = nada disponível) e lotes paralelos via scripts/search-parallel.sh (uma chamada por lote, nunca loop). O surf-agent-skill voltou como Tier 1 — a busca Brave interna da v3.0.0 não o substitui mais.
  • Subwaves duplas (F2-02/F2-04): TESTING (test-ondaN-*, máximo 3 worktrees de teste por onda — contam no teto DO_MAX_PARALLEL) e VALIDATION (val-ondaN-*, gate completo + revisão adversarial do diff integrado) rodam em background após cada onda e são integradas na onda seguinte (passo 3.5) ou no COMMIT-FINAL — nunca bloqueiam o disparo das ondas de feature.
  • Correções críticas da Fase 1 (F1-01 a F1-03): do-wt.sh undo seguro (reset --hard só com working tree exclusivamente untracked; o commit desfeito é arquivado em refs/do-archive/$RUN_ID/undo-<nome>), baseline de ignorados na FASE 0 + clean-ignored-delta no lugar do git clean -fdXq genérico (nunca apaga ignorados pré-existentes do usuário), stage-delta com -uall nos dois lados (arquivos novos dentro de dirs untracked do usuário entram no commit; a sujeira preexistente continua fora) e --budget-ms no Tier 1 do search.sh (--timeout em segundos vira milissegundos para o surf-search-normal — o --budget-ms do surf continua em MILISSEGUNDOS, e na v8 o --timeout também).
  • Gate em snapshot de integração (F3-01): o squash-merge é atômico e o gate (build + testes + linter) sai da seção crítica — roda em background numa worktree efêmera int-ondaN-<nome> (kind=integration, registrada no owned.tsv) criada no SHA pós-merge. Merges seguem em sequência; a limpeza de cada filha e o fim da onda aguardam o respectivo gate de snapshot (status=gate-pending no owned.tsv; o do-wt.sh sweep detecta gate-pending, avisa e sai != 0). Falha tardia: do-wt.sh undo <nome> reverte exatamente aquele squash com HEAD avançado, arquivando o commit em refs/do-archive/$RUN_ID/undo-<nome>. Decisão D1: builds duplicados (snapshot + validação + gate final) são esperados.
  • DO_MAX_PARALLEL (F3-02): prefixo max-parallel=N na invocação (/deep-orchestrator-agent-skill max-parallel=N <tarefa>) — o orquestrador exporta DO_MAX_PARALLEL antes da FASE 0; ausente, default 50. Orçamento: features por onda ≤ DO_MAX_PARALLEL; in-flight total ≤ DO_MAX_PARALLEL (features + worktrees de teste/validação das subwaves + revisores + REVISOR DE PLANO — tudo no mesmo teto); ondas maiores viram batches sequenciais com a própria barreira.
  • Gate definido uma vez (F3-03): a FASE 1 detecta e registra no TASK_PLAN.md o trio exato GATE_BUILD/GATE_TEST/GATE_LINT do projeto-alvo (package.json/Makefile/pyproject.toml/Cargo.toml/go.mod); toda invocação de gate referencia esse trio, com cwd conforme o contexto (snapshot, validação ou $BASE_DIR no gate final).
  • Lockfile como singleton (F3-04): manifesto + lockfile entram no mapa de propriedade como recurso singleton — no máximo 1 agente por onda adiciona dependências; os demais registram "deps pendentes: <pacote@versão>" no handoff e a adição acontece no COMMIT PREP da onda seguinte.
  • Tiering de modelos por papel (F3-09): quando o harness permite, agentes de teste e revisores adversariais rodam em modelo médio, REVISOR DE PLANO e síntese final em modelo forte, features no padrão; regra de escala: ≤2 sub-tarefas pequenas e independentes não geram fan-out extra.
  • Testes: scripts/test-contencao.sh — 85 asserções (A33: falha tardia de gate com undo de HEAD avançado; A34: gate-pending bloqueia o fim de onda).

Novidades na v3.2.0

  • MODO CONTIDO (acima) + FASE 0 — DELIMITAR O MUNDO: scripts/do-context.sh detecta worktree vinculada, resolve a fronteira e grava o arquivo de estado que toda chamada Bash sourceia.
  • Guardas em código, não em prosa: scripts/do-wt.sh concentra criação, merge, undo, remoção, limpeza e prova de contenção. Cada operação destrutiva recusa alvos que não estejam registrados nesta execução.
  • Regra de dependências (R9): instalação permitida se necessária, sempre com cwd na worktree-filha, em modo congelado e com HUSKY=0 (um postinstall de husky grava core.hooksPath no .git compartilhado). Cache global do usuário é permitido; escopo global de instalação é proibido.
  • Testes de regressão: scripts/test-contencao.sh — 85 asserções cobrindo detecção de modo, colocação, limpeza segura, worktrees de terceiros, preservação da sujeira do usuário, paths com acento e espaço, guarda de índice sujo, distinção entre vazamento nosso e trabalho do usuário no projeto principal, conflito e re-merge (A23), exits da FASE 0 (A28/A29), flock (A30), kind=validation (A31), falha tardia de gate (A33) e gate-pending (A34).

Novidades na v3.0.0

  • Ondas ilimitadas com recálculo dinâmico — após cada onda, um sub-agente REVISOR DE PLANO analisa os handoffs e o TASK_PLAN.md, propõe novas sub-tarefas ou declara CONVERGÊNCIA. O ciclo só termina por convergência declarada, nunca por um número fixo de ondas.
  • Busca interna Brave ($SKILL_HOME/scripts/brave-search.sh) — CLI próprio sobre a Brave Search API que substituía o surf-search-normal e não dependia mais do surf-research-skill nem do CLI surf-ai. SUPERADA na v3.3.0: o surf-agent-skill voltou como Tier 1 do sistema de busca 3-tier (search.sh); a Brave API virou o Tier 2 e o DuckDuckGo keyless o Tier 3.
  • Verificação de créditos antes de cada onda ($SKILL_HOME/scripts/check-brave-credits.sh) — sem créditos, o orquestrador para e informa o usuário (única exceção à autonomia total). SUPERADA na v3.3.0: o verificador agora é check-search-credits.sh (3 tiers; exit 2 = TODOS os tiers fora) — check-brave-credits.sh está DEPRECATED.
  • ECC Prompts integrados — 7 templates de prompt ($SKILL_HOME/prompts/ecc-prompts.md) + 7 skills portados do ECC ($SKILL_HOME/prompts/ecc-skills.md), incluindo Security Review (AgentShield), Planning Prompt (Plan First) e Prompt Defense Baseline.
  • Prompts de busca para dev ($SKILL_HOME/prompts/search-prompts.md) — 8 categorias de busca, sistema de evolução de perguntas (question evolution) e prompts por domínio.
  • HTML Explainer automático ao final de cada execução (pelo template próprio da época — removido na v3.6.0) — de-para de todas as mudanças em 6 abas, salvo como EXPLAINER.html na raiz da worktree em que a skill foi invocada (mecânica substituída na v3.6.0 — ver Novidades na v3.6.0).

Como funciona

O deep-orchestrator-agent-skill nunca escreve código. Ele atua como arquiteto-distribuidor: projeta o plano, divide o trabalho em ondas topológicas (quantas forem necessárias — o REVISOR DE PLANO recalcula após cada onda), cria e batiza worktrees isoladas do Git (uma por sub-agente), dispara os agentes em paralelo, aplica revisão adversarial, integra cada resultado via git merge --squash um a um — o gate (o trio GATE_BUILD/GATE_TEST/GATE_LINT registrado na FASE 1) roda em background numa worktree de snapshot efêmera int-ondaN-*, fora da seção crítica — remove worktree + branch + commits intermediários ao fim de cada onda (a limpeza de cada filha aguarda o verde do snapshot), e commita tudo ao final.

ANALYZE  →  PLAN  →  EXECUTE-ONDA (repeat, ILIMITADO)  →  COMMIT-FINAL

Fases

Fase Nome O que faz
0 DELIMITAR O MUNDO Roda $SKILL_HOME/scripts/do-context.sh: detecta se o cwd está numa worktree vinculada, resolve $BASE_DIR, $BASE_BRANCH, $MAIN_ROOT, $CHILD_ROOT, $BRANCH_NS e $SKILL_HOME, e captura os baselines de contenção. Aborta com mensagem acionável se não houver branch de integração
1 ANALYZE Lê o prompt, mapeia a estrutura do repositório, identifica subsistemas, classifica greenfield/brownfield, localiza golden masters e reconfirma o portão da surf (surf doctor — 0/1 = pronto, 78 = sem chave Brave válida, 127 = pacote ausente)
2 PLAN Decompõe a tarefa em sub-tarefas atômicas, identifica o grafo de dependências, organiza em ondas topológicas (número NÃO fixo — o plano é um ponto de partida), define o mapa de propriedade de arquivos, batiza cada worktree, escreve os prompts de delegação, publica o TASK_PLAN.md
2.5 APROVAR O PLANO Só quando PLAN_APPROVAL=1. Garante o Plannotator na máquina (check-plannotator.sh --install), escreve o plano legível em $PLAN_DOC e roda plan-approval.sh round: aprovado → FASE 3; anotado → regera o plano e abre um Plannotator NOVO (até DO_PLAN_MAX_REVISIONS); fechado/timeout/orçamento → para limpo, sem nenhuma worktree criada. Desligado (o default), a fase é pulada inteira
3 EXECUTE-ONDA Para cada onda: portão da surf (surf doctor) → commit prep (se necessário) → cria worktrees → dispara agentes em paralelo (escalonado) → barreira → recálculo dinâmico (REVISOR DE PLANO) → revisão adversarial → squash-merge um a um (gate em snapshot int-ondaN-*, em background; limpeza aguarda o verde de cada snapshot) → remoção APENAS das worktrees-filhas e branches desta execução, por nome registrado → prova de contenção → handoff para a próxima onda. Repete até o REVISOR DE PLANO declarar CONVERGÊNCIA
4 COMMIT-FINAL Remove o TASK_PLAN.md, roda o gate completo (o trio GATE_BUILD/GATE_TEST/GATE_LINT da FASE 1), commita apenas o que esta execução produziu (a sujeira preexistente do usuário é preservada), varredura final restrita à lista nominal registrada, gera o EXPLAINER.html pelo fluxo html-explainer-agent-skill (sub-agente delegado, sem limite de tempo, salvo em EXPLAINER.html na raiz) e produz o relatório final

Regras fundamentais

  1. Nunca escreve código — delega tudo a sub-agentes
  2. Nunca pergunta ao usuário — autonomia total, infere com confiança. Cinco exceções, e apenas estas: (a) a surf-agent-skill não está instalada (command -v surf-search-normal falha) E a tarefa ou alguma sub-tarefa exige pesquisa — instalar é npm -g, vedado por R9, então informa e aguarda; (b) qualquer comando surf saiu com 78 (sem chave Brave válida) E a tarefa ou alguma sub-tarefa exige pesquisa — é configuração, não pesquisa: retentar é inútil e não há provedor de reserva; (c) abort da FASE 0 (não é repositório, HEAD destacado, repo sem commits, índice sujo); (d) o portão de aprovação do plano está ativo (PLAN_APPROVAL=1) — aí a interação é a entrega pedida, acontece no navegador (nunca por pergunta em texto) e só na FASE 2.5; (e) o abort de contenção da FASE 0
  3. Trabalho completo, do início ao commit — nunca entrega trabalho parcial. Única saída antecipada legítima: o portão terminar sem aprovação — e aí nada foi construído, então o repositório fica exatamente como estava
  4. Worktree é a unidade de isolamento — cada sub-agente trabalha em sua própria worktree Git com nome descritivo (ex.: onda1-cache-service)
  5. Squash-merge um a um, nunca octopus — integração sequencial em $BASE_BRANCH; o gate roda em snapshot de integração int-ondaN-* (fora da seção crítica) e a limpeza de cada filha aguarda o verde do snapshot (decisão D1: builds duplicados são esperados)
  6. Worktree nasce nomeada e morre no fim da própria onda — limpeza imediata após gate verde, sempre por nome registrado
  7. Verificar a dependência de pesquisa antes de cada onda — surf doctor: 0/1 = pronto (1 = só faltam os symlinks das skills do próprio surf, irrelevante para os binários), 78 = sem chave Brave válida (configuração; retentar é inútil), 127 = pacote ausente. Em 78/127 com pesquisa exigida, nenhuma worktree é criada e nenhum sub-agente é disparado; sem pesquisa exigida, a execução prossegue sem busca, com registro
  8. A worktree de invocação é a raiz-de-mundo — nada é escrito fora dela; o branch dela é o único alvo de integração; a limpeza só toca o que esta execução registrou
  9. Dependências: dentro da worktree, congeladas, nunca globais — instale só se necessário, com cwd na filha e HUSKY=0; cache global do usuário é permitido
  10. Só executa plano que o usuário aprovou — quando o portão está ativo, nenhuma worktree nasce antes do APROVADO; o título do plano é imutável entre revisões; cada anotação regera o plano num Plannotator novo; e o feedback do usuário é correção do plano, nunca tarefa de implementação

Técnicas e fundamentos

O deep-orchestrator-agent-skill não inventa orquestração do zero: ele compõe técnicas documentadas e verificadas (pesquisa profunda com fontes, agosto/2026) em cima do que o harness já oferece. As três colunas abaixo — ECC, busca em camadas e sub-agentes nativos — explicam de onde vem cada peça.

ECC — Everything Claude Code (a técnica-mãe)

O ECC — Everything Claude Code (MIT) é um sistema massivo de otimização de harness de agentes: 67 agents, 281 skills, 94 commands, além de hooks, Memory Vault, Continuous Learning e AgentShield (auditoria de segurança do próprio harness). O deep-orchestrator-agent-skill não o copia — porta e adapta o que ele faz de melhor, no fluxo plan → test → implement → review → verify → remember → improve:

  • prompts/ecc-prompts.md — 7 templates de prompt portados: System Prompt Base, Planning Prompt (Plan First), Code Review (método de confiança + veredito APPROVE/WARNING/BLOCK), Security Review (AgentShield + checklist OWASP), Memory Persistence, Continuous Improvement (instincts com scoring de confiança 0.3–0.9) e Clone-Analyze-Discard.
  • prompts/ecc-skills.md — 7 skills portadas no formato ECC (frontmatter YAML + workflow em passos): tdd-workflow (TDD gated RED→GREEN→REFACTOR com evidência e cobertura ≥ 80%), security-audit (checklist OWASP de 10 pontos + revisão do harness), doc-generator (docs/ADRs a partir do diff), research-deep-dive (search-first com matriz Adotar/Estender/Compor/Construir), memory-vault (handoffs entre ondas e sessões), clone-and-analyze (portar o melhor de repos de referência em worktree isolada) e code-quality-gate (gate mecânico determinístico — o braço de execução do gate pós-squash).

Princípio transversal herdado: entrada NÃO confiável — planos, diffs e repos clonados são lidos como texto não confiável; comandos embutidos só rodam após sanitização contra whitelist (test, lint, typecheck, coverage).

Pesquisa — surf-agent-skill v8 (dependência dura)

Esta skill não tem sistema de busca. Desde a v4.0.0 (decisão D23), toda pesquisa web passa pelos binários globais da surf-agent-skill v8, e por mais nada. Não há tabela de tiers porque não há cadeia: há um backend.

npm i -g surf-agent-skill    # dependência dura
surf                         # adiciona a chave Brave — validá-la é grátis
Binário Quando
surf-search-normal "<pergunta>" --sub-agents=N uma onda; o caminho padrão
surf-search-unlimit "<pergunta>" --sub-agents=N --max-depth 3 pergunta aberta que precisa descer em várias ondas
surf-research-skill search-parallel "q1" "q2" --sub-agents=N --json lote de perguntas cruas, sem síntese
surf doctor o portão

Brave é o único backend. Não existe Tavily, Parallel, Wikipedia, DuckDuckGo, provedor de reserva nem tier sem chave — o próprio surf estreitou para Brave-only na v8. Não existe modo degradado: ou há chave válida e a pesquisa funciona, ou a execução para.

Códigos de saída (o orquestrador e todo sub-agente branqueiam neles):

Código Significado Ação
0 funcionou cite as URLs que o surf devolveu
1 rodou e não achou nada registre o vazio e siga; nunca troque de ferramenta
2 o comando está errado corrija o comando
78 sem chave Brave válida (EX_CONFIG) PARE. É configuração, não pesquisa: retentar não conserta e não há de onde mais buscar
143 o harness matou por timeout refaça com surf-search-normal, que se auto-orça

--sub-agents é o único botão de simultaneidade, e ele SOMA com DO_MAX_PARALLEL. Seja N o teto global (surf-sub-agents=N na invocação, default 10, faixa 1..20) e R a quantidade de sub-agentes da onda que pesquisam: cada um recebe --sub-agents=max(1, floor(N / R)), de modo que a soma da onda nunca passa de N. Se multiplicassem, uma onda cheia seria 50 × 10 = 500 buscas simultâneas contra um plano Brave que pode servir uma por segundo.

É proibido envolver o surf em sleep, jitter, backoff ou retry. Ele aprende o requests-per-second real do plano Brave nos headers da resposta e o aplica num token bucket cross-process, compartilhado por todos os processos surf da máquina. Um ritmo por cima briga com o limitador e provoca exatamente o 429 que ele evita.

WebSearch/WebFetch do harness não descobrem fontes. Fonte que não veio pelo surf não pode ser citada em handoff nem em deliverable. Uso legítimo, único: abrir com Read/WebFetch uma URL que o surf já devolveu — é a única forma de ler o corpo de uma página, já que a Brave devolve título, URL e trecho, e os verbos extract/crawl/map foram removidos no surf v8.

Histórico: o surf foi o provedor original (v3.0.0), foi substituído por uma busca Brave interna, voltou como Tier 1 na v3.3.0, e na v4.0.0 virou a dependência única — os Tiers 2 (Brave direto) e 3 (DDG keyless) desta skill foram removidos. O gatilho está registrado no D23: search.sh tratava todo exit code não-zero do surf como falha transitória, então o exit 78 da v8 ficava indistinguível de um timeout e o wrapper respondia a mesma pergunta pelo DuckDuckGo — reproduzindo, uma camada acima, o defeito que o surf acabara de eliminar.

Sub-agentes no Claude Code — nativos, nenhum plugin necessário

Resposta curta da pesquisa profunda (25 claims verificadas adversarialmente contra as docs oficiais, 0 refutadas, 2026-08-18): o Claude Code já tem sub-agentes nativos. Não existe plugin a instalar para isso — e não há nada para abrir em outro terminal. Plugins são um canal opcional de distribuição, não um requisito.

  • O que são: arquivos Markdown com frontmatter YAML em .claude/agents/ (projeto) ou ~/.claude/agents/ (usuário — vale em todos os projetos, sem configuração extra). O frontmatter define name, description, tools, model, permissionMode, skills, memory, background, isolation; o corpo do arquivo vira o system prompt.
  • Como são disparados: pela ferramenta Agent (renomeada da Task na v2.1.63; Task(...) continua como alias), que roda o sub-agente em contexto próprio — em paralelo ou em background — e devolve um único resultado ao pai. Sub-agentes começam com contexto zero: prompts precisam ser autocontidos (é exatamente o que o template de delegação do SKILL.md faz).
  • Tipos embutidos: Explore (busca/análise read-only; pula CLAUDE.md e o git status do pai por velocidade), Plan, general-purpose, claude, statusline-setup, claude-code-guide. É o general-purpose que o orquestrador usa nas ondas.
  • Paralelismo: nativo, com teto de 20 sub-agentes concorrentes por sessão (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, v2.1.217+) e até 3 níveis de profundidade de spawn — o teto efetivo das ondas do orquestrador é min(DO_MAX_PARALLEL, 20): o default do DO_MAX_PARALLEL virou 50, mas o harness impõe 20 concorrentes reais por sessão (filas do resto), então na prática as ondas raramente passam de ~20 em voo.
  • Terminal novo: agentes de usuário em ~/.claude/agents/ persistem em todos os projetos. Prioridade de resolução de nomes: managed settings (org) > flag --agents (JSON, vale só na sessão) > .claude/agents/ (projeto) > ~/.claude/agents/ (usuário) > agents/ de plugins. Desde a v2.1.198 o /agents não abre mais wizard — imprime onde editar os arquivos.
  • Plugins (aditivos, opcionais): o sistema /plugin empacota skills, hooks, MCP e também agentes prontos (pasta agents/ do plugin; invocados por @-mention escopado plugin:agente). Marketplaces: o oficial anthropics/claude-plugins-official (adicionado automaticamente na primeira execução; ex.: pr-review-toolkit, com 6 agentes de revisão de PR) e o comunitário anthropics/claude-plugins-community (com triagem de segurança da Anthropic — que só vale para ele: plugins de URLs git arbitrárias ou diretórios locais não passam por triagem). Coleções grandes de terceiros existem (ex.: wshobson/agents, 200+ agentes) — nenhuma é necessária para o que este projeto faz.
  • Equipes nativas (agent teams): existem no harness, mas são experimentais e desabilitadas por padrão — o sistema de ondas com worktrees do deep-orchestrator-agent-skill segue sendo a abordagem de produção.
  • Nota: o harness também tem claude --worktree <nome> para sessões paralelas isoladas; o deep-orchestrator-agent-skill mantém o sistema próprio (R6/R8, do-wt.sh) porque precisa de nomes, branches e limpeza controlados por registro (owned.tsv) — isolamento real por worktree, não apenas por sessão.

Fontes primárias: subagents · agents — run in parallel · discover-plugins · claude-plugins-official · claude-plugins-community. Fatos version-sensitive (v2.1.63 / v2.1.186 / v2.1.198 / v2.1.217+) devem ser conferidos contra a versão do Claude Code instalada.

Estrutura da casa da skill ($SKILL_HOME)

deep-orchestrator-agent-skill/
├── README.md                    # Este arquivo
├── SKILL.md                     # Definição do skill v3.8.0 (frontmatter YAML + XML do orquestrador)
├── scripts/
│   ├── README.md                # Índice de todos os scripts
│   ├── do-context.sh            # FASE 0 — delimita a raiz-de-mundo e grava o estado
│   ├── do-wt.sh                 # ciclo de vida das worktrees-filhas (guardas de contenção)
│   ├── evolve-skill.sh          # evolução do CORPO da skill: search (prefs+prompts)/diff/apply (branch evolve/*, nunca merge sozinho)/status
│   ├── do-prefs.sh              # motor de prefs: .deep-orchestrator-preferences/ do projeto e da skill (load/add-project/add-global/pending/ensure-gitignore/status)
│   ├── evolution-survey.sh      # PERGUNTA de evolução em texto no terminal (ask/answer/apply/dismiss — v3.9.0, sem Plannotator)
│   ├── lib/evolve-common.sh     # parsers/validadores compartilhados do formato de bloco
│   ├── lib/plannotator-common.sh # contrato do Plannotator compartilhado (plan-approval.sh — o portão de plano continua no Plannotator)
│   ├── check-install.sh         # prova de instalação completa
│   ├── test-surf-gate.sh        # testes do portão da surf (46 asserções)
│   ├── check-plannotator.sh     # FASE 2.5 — resolve/instala o Plannotator (exit 0/1/2)
│   ├── plan-approval.sh         # FASE 2.5 — uma rodada de aprovação no Plannotator
│   ├── test-contencao.sh        # testes de regressão do MODO CONTIDO (85 asserções)
│   ├── test-evolve.sh           # testes do motor de prefs/questionário/evolução (suíte F1–Fxx)
│   └── test-plan-approval.sh    # testes do portão de aprovação (133 asserções, mockado)
├── prompts/
│   ├── ecc-prompts.md           # 7 templates de prompt portados do ECC
│   ├── ecc-skills.md            # 7 skills ECC portados
│   ├── search-prompts.md        # Prompts de busca otimizados para dev
│   └── plan-approval-prompts.md # Templates da FASE 2.5 (documento, feedback, regeração)

Requisitos

  • Claude Code (CLI)
  • Git
  • Node.js ≥ 18 + npm — para instalar a surf-agent-skill
  • surf-agent-skill v8 — OBRIGATÓRIA sempre que a tarefa exigir pesquisa: npm i -g surf-agent-skill, depois surf para adicionar a chave. Sem ela, o orquestrador para e pede (nunca instala sozinho: npm -g é vedado pela regra R9)
  • Chave Brave Search — OBRIGATÓRIA (https://api-dashboard.search.brave.com). Não há tier sem chave: sem ela todo comando surf sai 78 e a execução para. Validá-la é grátis e o surf faz isso sozinho a cada invocação (veredito em cache por 7 dias). Uma segunda chave não é redundância — cada uma carrega o próprio orçamento de requisições por segundo, então duas dobram o paralelismo real
  • Chave OpenRouter — recomendada (surf-research-skill ai-setup): sem ela o surf ainda faz buscas reais, mas devolve evidência crua em vez de síntese
  • curl e jq (usados pelos scripts de busca)
  • project-router skill resolvido a partir da raiz-de-mundo (<raiz>/.claude/skills/project-router/ ou <raiz>/.agents/skills/project-router/). Ausente, o sub-agente registra no handoff e segue — não cai para o repositório principal nem para ~/.claude
  • Plannotator — AUTO-INSTALADO se ausente (scripts/check-plannotator.sh --install; binário --minimal em ~/.local/bin, mínimo 0.19.1). Usado pela UI de anotação do EXPLAINER final (opcional — o arquivo é a entrega) e pelo PORTÃO DE APROVAÇÃO DO PLANO (FASE 2.5). Verificado na v3.6.0 em 0.27.6.

Dependências

Uma worktree recém-criada não herda node_modules, .venv ou target: são untracked e git worktree add não os copia. Se a sub-tarefa precisar deles, o sub-agente instala dentro da worktree (cwd na raiz da filha), em modo congelado (npm ci, pnpm install --frozen-lockfile, uv sync --frozen, …), com HUSKY=0, nunca com flags globais e nunca no projeto principal. O cache global do usuário (~/.npm, ~/.cache/uv, ~/.cargo, ~/.m2) é permitido e desejável: é conteúdo endereçado por hash, compartilhado pela máquina, e redirecioná-lo só forçaria re-download por agente.

Instalação

# Clone o repositório
git clone <repo-url> ~/Projects/deep-orchestrator-agent-skill

# Adicione ao seu projeto como skill — copie o diretório INTEIRO,
# pois scripts/ e prompts/ são referenciados pelo SKILL.md
mkdir -p .claude/skills/deep-orchestrator-agent-skill
cp -r SKILL.md scripts prompts .claude/skills/deep-orchestrator-agent-skill/

# Este bloco é setup MANUAL do usuário, executado UMA VEZ, fora de qualquer
# execução da skill — NUNCA por um sub-agente. A skill não se auto-instala no
# repositório-alvo: ela é lida de $SKILL_HOME.

# OBRIGATÓRIO se a tarefa exigir pesquisa — a skill não tem busca própria:
npm i -g surf-agent-skill
surf                                  # interativo: chave Brave (validação grátis)
# …ou, não-interativo:
export BRAVE_API_KEY=<chave>          # https://api-dashboard.search.brave.com
export OPENROUTER_API_KEY=<chave>     # recomendada: liga a síntese do surf-ai

Uso

/deep-orchestrator-agent-skill <descrição da tarefa>
/deep-orchestrator-agent-skill max-parallel=N <descrição da tarefa>   # prefixo OPCIONAL — cap de concorrência
/deep-orchestrator-agent-skill plan=on <descrição da tarefa>          # prefixo OPCIONAL — força o portão
/deep-orchestrator-agent-skill plan=off faça um plano e execute       # força a autonomia total
/deep-orchestrator-agent-skill wt=on <descrição da tarefa>            # prefixo OPCIONAL — worktree irmã nomeada como raiz-de-mundo
/deep-orchestrator-agent-skill wt=feature-x <descrição da tarefa>     # prefixo OPCIONAL — com nome explícito
/deep-orchestrator-agent-skill no-stop <descrição da tarefa>         # prefixo OPCIONAL — remove o teto de 10 ondas
/deep-orchestrator-agent-skill no-evolve <descrição da tarefa>       # prefixo OPCIONAL — pula a pergunta de evolução e a análise

O prefixo wt= (WT-ROOT) é o fato novo desta versão. Ele cria — ou reentra — uma worktree irmã verdadeira do projeto em <pai>/<repo>.worktrees/<nome> e faz todo o trabalho dentro dela, preservando o checkout principal intacto. O fluxo:

  1. A pasta irmã <pai>/<repo>.worktrees/ é criada se faltar, ou reentrada se já existir (nunca recriada).
  2. O nome do diretório da worktree é o <nome> passado (wt=feature-x), ou um slug derivado do prompt da tarefa se você usar wt=on sem valor. O nome é deduplicado contra o que já existe dentro da pasta irmã: colisão com um diretório de uma feature anterior ganha -2, -3, … até achar um livre.
  3. A FASE 0 re-executa com o cwd dentro da worktree: o resto é o MODO CONTIDO já existente — ondas, sub-agentes, merges via squash, gates, subwaves de teste/validação e o COMMIT-FINAL aterrissam lá dentro, e o checkout principal é $MAIN_ROOT, zona proibida.

A worktree irmã é persistente (ao contrário das worktrees-filhas efêmeras por onda): o branch do/wt/<nome> é reusado entre execuções. Variáveis: DO_WT_ROOT (1 quando ativo), DO_WT_NAME (o slug/nome resolvido), DO_WT_ROOT_ENTERED (sentinel interno de re-entrada).

O prefixo max-parallel=N (antigo mp=N) define o cap de concorrência (F3-02): o orquestrador o parseia antes da FASE 0 e exporta DO_MAX_PARALLEL=N (validado como inteiro positivo; inválido → aborta com mensagem clara). Ausente → default 50. O teto vale para TUDO em voo — features da onda, worktrees de teste/validação das subwaves (incluindo as até 3 worktrees de teste por onda), revisores e REVISOR DE PLANO. Ondas com mais features que o cap viram batches sequenciais, cada batch com a sua barreira. Nota: o harness do Claude Code impõe um teto próprio de ~20 sub-agentes concorrentes por sessão (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS), então o com max-parallel= acima de 20 a concorrência real fica limitada pelo harness (o resto espera em fila) — o max-parallel= continua servindo para dimensionar as ondas/batches.

O prefixo no-stop (booleano, sem valor) remove o teto de 10 ondas por execução: o orquestrador o parseia antes da FASE 0 e exporta DO_NO_STOP=1 (validado como 0/1; inválido → aborta com mensagem clara). Ausente → default 0, que preserva o comportamento histórico (máximo de 10 ondas). Com no-stop, a execução dura quantas ondas forem necessárias até o REVISOR DE PLANO declarar convergência — ideal para tarefas que exigem qualidade máxima sem teto arbitrário de rodadas. A válvula anti-loop permanece ativa mesmo com no-stop: 2 REPLANs consecutivos sem novas sub-tarefas aceitas forçam a convergência (documentada no relatório final), garantindo que a execução nunca itere para sempre sem progresso.

O portão de aprovação do plano

O prefixo plan=on|off liga ou desliga a FASE 2.5. Sem ele, a decisão vem dos gatilhos, nesta ordem:

Precedência Sinal Resultado
1 prefixo plan=on / plan=off vence tudo
2 DO_PLAN_APPROVAL no ambiente respeitado
3 gatilho negativo: "não me pergunte nada", "autônomo", "toca o barco", "sem interrupção" OFF (vence o positivo)
4 gatilho positivo: "faça um plano", "planeje", "quero aprovar antes", "revisar o plano", "plannotator" ON
5 nada disso OFF — o default

Variáveis do portão (todas com default, validadas na FASE 0):

Variável Default O que faz
DO_PLAN_APPROVAL 0 liga a FASE 2.5
DO_PLAN_MAX_REVISIONS 5 teto de rodadas no Plannotator
DO_PLAN_TIMEOUT 3600 segundos de espera pela decisão, por rodada
DO_PLAN_SHARE 0 1 permite o compartilhamento externo do Plannotator
DO_PLANNOTATOR_BIN — caminho explícito do executável
DO_PLANNOTATOR_INSTALL 1 0 proíbe a instalação automática
DO_PLAN_REMOTE 0 1 deixa o Plannotator escutar em 0.0.0.0 (revisão remota). Leia o aviso de segurança acima antes

O trail de cada execução fica em $DO_STATE/plan-approval/: um snapshot imutável e um arquivo de feedback por rodada, mais o trail.tsv. Como $DO_STATE é apagado no fim, a tabela de revisões é copiada para o relatório final antes da limpeza.

Se o navegador não abrir sozinho, plannotator sessions --open 1 reabre a sessão ativa.

Uma rodada interrompida (Ctrl-C, máquina suspensa, processo morto) não trava o portão: a numeração de revisões considera o que existe em disco, então a tentativa abortada fica preservada com o número dela e a próxima entra na seguinte. Se a rodada morreu depois de você decidir, a decisão está em rev-NNN.stdout.

Triggers

O skill é ativado automaticamente com frases como:

  • "orquestre isso"
  • "divida essa tarefa"
  • "coordene múltiplos agentes"
  • "resolva do início ao fim"
  • "não me pergunte nada"
  • "autônomo"
  • "toca o barco"

E, para a FASE 2.5 (portão de aprovação):

  • "faça um plano"
  • "planeje isso"
  • "quero aprovar o plano antes"
  • "revisar o plano"

Quando usar

Tarefas complexas que se beneficiam de decomposição em ondas paralelas — especialmente quando você quer uma solução completa do início ao fim sem interrupções. Nunca use para tarefas triviais de um passo só.

Exemplo

/deep-orchestrator-agent-skill Adicionar endpoint de busca com cache a uma API REST

O orquestrador vai:

  1. Analisar o repositório e identificar os subsistemas afetados (confirmando antes que há chave Brave válida — sem ela o surf sai 78 e a execução para)
  2. Criar um plano inicial com 2 ondas:
    • Onda 1 (Fundação): onda1-cache-service (CacheService genérico) + onda1-schema-busca (mapear schema de busca) — paralelo
    • Onda 2 (Implementação): onda2-endpoint-busca (endpoint com cache + testes)
  3. Executar cada onda com barreira, recálculo dinâmico (REVISOR DE PLANO), revisão adversarial, squash-merge com gate e limpeza — ondas adicionais podem surgir se o revisor detectar novas sub-tarefas
  4. Commitar tudo, gerar o EXPLAINER.html e entregar o relatório

Ao final, o histórico do branch da raiz-de-mundo (o branch da worktree em que a skill foi invocada; main/master apenas quando a invocação foi na árvore principal) terá 3 commits squash de feature — um por sub-agente —, um squash commit por worktree de teste das testing subwaves (até 3 por subwave; test-onda1-*, test-onda2-*), os fixes das validation subwaves (val-ondaN-*) e o commit final com o EXPLAINER.html. Nenhuma worktree-filha nem branch desta execução sobra; worktrees e branches pré-existentes de outras sessões não são tocados.

Novidades na v4.0.0

A skill deixou de ter um sistema de busca. O gatilho foi um bug: search.sh tratava todo exit code não-zero do surf como falha transitória, então o exit 78 da v8 — "não há chave Brave válida" — ficava indistinguível de um timeout, e o wrapper respondia a mesma pergunta pelo cliente Brave interno ou pelo DuckDuckGo. A skill reproduzia, uma camada acima, exatamente o defeito que o surf v8 acabara de eliminar: uma resposta confiante vinda de um provedor que o usuário não escolheu, sem nenhum sinal de que a chave estava quebrada.

Manter um "shim fino" em volta do surf não resolveria: um shim é um sistema de busca (mapeamento de flags, envelope próprio, códigos de saída próprios), e é exatamente onde o próximo mantenedor reintroduz um fallback. Por isso os seis scripts foram apagados, e o SKILL.md manda o sub-agente chamar os binários globais direto.

O que se perdeu de propósito: o piso keyless (uma resposta de Instant Answer apresentada com a mesma confiança de uma pesquisa real), a dedup por URL entre queries de um lote e o cache intra-run — todos substituídos por uma chamada surf-search-normal com brief, que planeja o conjunto de queries por LLM, roda até --sub-agents delas em paralelo e dedupa canonicamente no ledger.

Ver docs/decisions/2026-08-29-surf-agent-skill-obrigatorio.md.

Versão

4.0.0 — fim do sistema de busca interno. search.sh, search-parallel.sh, check-search-credits.sh, brave-search.sh, check-brave-credits.sh e test-search.sh REMOVIDOS (3.346 linhas). A pesquisa é 100% surf-agent-skill v8 — dependência obrigatória (npm i -g surf-agent-skill), Brave como único backend, sem tier sem chave e sem provedor de reserva. exit 78 = configuração (sem chave Brave válida): o orquestrador PARA, informa e aguarda; retentar não conserta. Portão passa a ser surf doctor, na FASE 0 e no passo 0 de cada onda. --sub-agents é o único teto de simultaneidade do surf e SOMA com DO_MAX_PARALLEL: cada sub-agente que pesquisa recebe max(1, floor(N/R)), prefixo surf-sub-agents=N na invocação (default 10, faixa 1..20). É proibido envolver o surf em jitter/backoff — ele já ritma pelo plano Brave, cross-process. WebSearch e WebFetch deixam de descobrir fontes (só abrem URL que o surf devolveu). Nova suíte test-surf-gate.sh (46 asserções) substitui test-search.sh. Decisão D23 em docs/decisions/2026-08-29-surf-agent-skill-obrigatorio.md.

3.9.0 — evolução como PERGUNTA EM TEXTO no terminal (fim do questionário Plannotator): depois de TUDO (commit, push, relatório) cada proposta vem numerada com opções a/b/c + escopo 1/2 (ex.: "1:b2"); o usuário responde com códigos na próxima mensagem e a opção escolhida vira a ação salva (evolution-survey.sh ask/answer/apply/dismiss); flag no-evolve pula a pergunta e o agente de análise; push explícito no COMMIT-FINAL (nunca bloqueia); prefixo mp=N → max-parallel=N; continuação da pergunta pendente na FASE 0 (passo 0.4); testes S1–S10 reescritos (78 PASS). Decisões D18–D22 em docs/decisions/2026-08-28-pergunta-evolucao-terminal.md.

3.8.0 — questionário de evolução pós-execução (substituído pela v3.9.0): agente de evolução + prefs por projeto em .deep-orchestrator-preferences/ (gitignored), evolution-survey.sh (round no Plannotator), do-prefs.sh, evolve-skill.sh sem add, decisões D12–D17.

3.7.0 — auto-evolução contínua (substituída pela v3.8.0): evolve-skill.sh add + LEARNINGS.md.

3.6.0 — HTML Explainer novo fluxo: fim do gerador/template antigos (scripts/generate-explainer.sh + templates/html-explainer.html removidos); geração delegada a sub-agente seguindo html-explainer-agent-skill + visual-explainer, sem limite de tempo, salvo em EXPLAINER.html no lugar; contrato de instalação (check-install.sh) atualizado.

3.5.0 — flag no-stop (DO_NO_STOP): remove o teto de 10 ondas por execução (ondas ilimitadas até a convergência); validação/export/resumo no do-context.sh + guarda anti-stale no caminho DO_REUSE; documentada no SKILL.md (frontmatter + FASE 0 + repeat + REPLAN + relatório) e no README.

3.3.0 — sistema de busca 3-tier (search.sh + check-search-credits.sh + search-parallel.sh), subwaves duplas (TESTING + VALIDATION), gate em snapshot de integração (F3-01), DO_MAX_PARALLEL (F3-02), gate definido uma vez (F3-03), lockfile singleton (F3-04), tiering de modelos por papel (F3-09), correções críticas da Fase 1 (F1-01 a F1-04).

3.2.0 — MODO CONTIDO (worktree como raiz-de-mundo), FASE 0 de bootstrap, guardas de contenção em do-wt.sh, regra de dependências (R9), testes de regressão.

3.1.0 — Testing subwaves assíncronas, enforcement do project-router.

3.0.0 — Brave Search interno, ondas ilimitadas, ECC prompts, verificação de créditos, HTML explainer.

Licença

MIT

About

Orquestrador autônomo multi-agente para Claude Code: planeja, divide em ondas paralelas, cria worktrees isoladas e nomeadas, revisa adversarialmente e commita do início ao fim. Flags: wt=<nome> faz todo o trabalho numa worktree irmã verdadeira; no-stop remove o teto de 10 ondas (ondas ilimitadas até a convergência).

Topics

agent-skill

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages