Plan-Orchestrate

O que Plan-Orchestrate faz?

Conecte um documento de plano ao /orchestrate custom emitindo uma invocação pronta para colar por etapa. A habilidade é apenas generativa — nunca executa /orchestrate. O usuário cola cada linha quando estiver pronto.

Quando Ativar

• O usuário tem um documento de plano com múltiplas etapas (PRD, RFC, plano de implementação) e deseja executá-lo via /orchestrate.
• O usuário diz "orquestre este plano", "forneça prompts do orchestrate para cada etapa", "componha cadeias para este plano".
• Existe um plano passo a passo, mas o usuário não deseja selecionar agentes manualmente por etapa.

Pular quando:

• O trabalho é uma etapa única e ad-hoc → chame /orchestrate custom diretamente.
• O plano está ilegível ou vazio. A ausência de numeração explícita por si só não é condição de pular — veja o caso extremo "Sem etapas claras" abaixo.

Entradas

<plan-doc-path> [--lang=python|typescript|go|rust|cpp|java|kotlin|flutter|auto] [--scope=all|step:<n>|range:<a>-<b>] [--dry-run]

• <plan-doc-path> — obrigatório; caminho relativo ou absoluto (@docs/... aceito).
• --lang — variante de idioma do revisor; padrão é auto (detectado a partir do projeto).
• --scope — limita as etapas emitidas; padrão é all.
• --dry-run — imprime apenas a decomposição e a justificativa da cadeia; não emite os prompts finais.

Forma Autoritativa do /orchestrate (não desviar)

{ORCH_CMD} custom "<agente1>,<agente2>,...,<agenteN>" "<descrição da tarefa>"

Onde {ORCH_CMD} é determinado na Fase 0 (veja abaixo). A string de comando na saída emitida sempre usa uma forma concreta — nunca ambas, nunca um marcador.

• custom é uma cadeia sequencial; o HANDOFF de cada agente alimenta o próximo.
• Lista de agentes separada por vírgulas. Sem espaços é preferível; um espaço é tolerado.
• Não existem flags --mode / --gate / --agents=... — nunca as invente.
• Os nomes dos agentes vêm do catálogo desta habilidade. Aspas duplas incorporadas na descrição da tarefa são escapadas como \".

Forma de Instalação e Namespacing do ECC

Duas formas de instalação determinam o prefixo tanto no comando de barra quanto no nome de cada agente. As duas DEVEM permanecer sincronizadas — uma forma por saída, nunca misturadas:

Seja <claude-home> o diretório inicial do Claude Code: ~/.claude no macOS/Linux e %USERPROFILE%\.claude no Windows. Resolva-o da forma como a plataforma host resolve o diretório inicial do usuário (não codifique ~).

Forma	Detecção	{ORCH_CMD}	Formato do nome do agente
Instalação via plugin (2.0.0+)	<claude-home>/plugins/marketplaces/ecc/ existe	/ecc:orchestrate	ecc:<nome>
Instalação legada	Acima ausente; arquivos de agente em <claude-home>/agents/	/orchestrate	<nome>

Por que isso importa: na instalação via plugin, os agentes se registram como ecc:tdd-guide. Nomes simples forçam correspondência difusa, que falha intermitentemente sob chamadas paralelas. Na instalação legada, as formas prefixadas não são registradas e falham completamente.

Catálogo de Agentes Disponível (deve escolher entre estes)

Gerais:

• planner — redefinição de requisitos, decomposição de riscos, planejamento de etapas
• architect — arquitetura, design de sistemas, propostas de refatoração
• tdd-guide — escrever testes → implementar → 80%+ de cobertura
• code-reviewer — revisão de código genérica
• security-reviewer — auditoria de segurança, OWASP, vazamento de segredos
• refactor-cleaner — código morto, duplicatas, limpeza do tipo knip
• doc-updater — documentação, mapa de código, README
• docs-lookup — consultas de API de bibliotecas de terceiros (Context7)
• e2e-runner — orquestração de testes ponta a ponta
• database-reviewer — esquema PostgreSQL, migração, desempenho
• harness-optimizer — configuração local do harness de agente
• loop-operator — loops autônomos de longa duração
• chief-of-staff — triagem multicanal (raramente adequado para etapas de plano)

Resolvedores de erros de compilação:

• build-error-resolver (genérico) / cpp-build-resolver / go-build-resolver / java-build-resolver / kotlin-build-resolver / rust-build-resolver / pytorch-build-resolver

Revisores de código:

• python-reviewer / typescript-reviewer / go-reviewer / rust-reviewer / cpp-reviewer / java-reviewer / kotlin-reviewer / flutter-reviewer

Um nome de agente com erro ortográfico faz o /orchestrate falhar. Verifique novamente esta lista antes de emitir.

Como Funciona

Fase 0 — Detectar modo ECC + idioma

1. Leia <plan-doc-path>. Se estiver faltando ou vazio, reporte e pare.

2. Detecte a forma de instalação do ECC uma vez e congele-a em ECC_MODE. Algoritmo (execute em ordem, pare no primeiro acerto):

   1. Se <claude-home>/plugins/marketplaces/ecc/ existir → ECC_MODE=plugin.
   2. Caso contrário, se <claude-home>/agents/ existir e contiver pelo menos um arquivo de agente ECC (por exemplo, tdd-guide.md, code-reviewer.md) → ECC_MODE=legacy.
   3. Caso contrário → padrão é ECC_MODE=legacy e emita um aviso de uma linha no topo da saída: > Aviso: não foi possível detectar a instalação do ECC; usando a forma legada como padrão. Se você usa a instalação via plugin, edite os prefixos manualmente.
   4. Se ambos os marcadores existirem (instalação mista), plugin vence — o namespace do plugin é o único que resolve nomes de agentes sem correspondência difusa.

   A partir deste ponto, cada linha emitida usa o prefixo correspondente tanto no comando de barra quanto em cada nome de agente. Nunca emita ambas as formas na mesma saída.

3. Resolva --lang. Quando auto, execute uma detecção poliglota:

   • Marcadores de sonda: pyproject.toml / uv.lock / requirements.txt → python; package.json → typescript; go.mod → go; Cargo.toml → rust; CMakeLists.txt ou *.cpp de nível superior → cpp; pom.xml / build.gradle (Java) → java; build.gradle.kts ou Kotlin de nível superior → kotlin; pubspec.yaml → flutter.
   • Desempate poliglota: se mais de um marcador corresponder, escolha o idioma cujos arquivos de origem superam os demais (conte via git ls-files, excluindo vendor/, node_modules/, dist/, build/, .venv/, arquivos gerados e fixtures de teste óbvias). Em caso de empate ou quando nenhum idioma exceder 60% dos arquivos de origem, defina lang=unknown.
   • Nenhum marcador correspondeu → defina lang=unknown.
   • lang=unknown é um sentinela — não é um nome de agente. As regras 4 e 5 da Fase 2 o transformam em code-reviewer / build-error-resolver no momento da composição da cadeia.

4. Detecte um subperfil PyTorch: quando lang=python e qualquer um de pyproject.toml / requirements.txt / uv.lock declarar uma dependência em torch, defina pytorch=true. Isso afeta apenas a seleção da cadeia build (regra da Fase 2 abaixo); o revisor permanece python-reviewer.

5. Normalize quaisquer nomes de agente declarados no plano: se o texto do plano fizer referência a agentes por sua forma prefixada de plugin (por exemplo, ecc:tdd-guide), remova o prefixo para obter o nome do catálogo simples antes de validar ou compor cadeias. O re-prefixamento ocorre apenas no momento da saída, de acordo com ECC_MODE (Fase 4). Nunca deixe um nome pré-prefixado fluir na composição da cadeia — ele seria duplamente prefixado no modo plugin.

Fase 1 — Decompor etapas

Identifique "unidades de etapa" em ordem de prioridade:

1. Numeração explícita: ## Etapa N / ### Fase N / ## N. ... / lista ordenada de nível superior.
2. Uma coluna "Etapa" em uma tabela.
3. Blocos separados por --- com cabeçalhos iniciados por verbo.
4. Caso contrário, trate cada H2 como uma etapa.

Por etapa, extraia id (baseado em 1), title (≤ 80 caracteres), intent (1–3 frases), tags.

Fase 2 — Marcar e escolher cadeia

Marque por intenção (várias tags permitidas; cadeia construída a partir da primária + secundárias empilhadas):

As palavras de gatilho abaixo são combinadas de forma insensível a maiúsculas/minúsculas. Planos multilíngues são suportados pela correspondência dos radicais das palavras em qualquer idioma, desde que o significado esteja alinhado com as palavras de gatilho em inglês listadas.

Tag	Palavras de gatilho	Cadeia padrão
design	architecture, design, choose, evaluate, RFC	planner,architect
plan	plan, breakdown, milestone	planner
impl	implement, build, add, create, port	tdd-guide,<lang>-reviewer
test	test, coverage, e2e, integration	tdd-guide,e2e-runner
refactor	refactor, cleanup, dedupe, split	architect,refactor-cleaner,<lang>-reviewer
migration	migrate, upgrade, rewrite, port	architect,tdd-guide,<lang>-reviewer
db	schema, migration, index, SQL, Postgres, alembic, sqlmodel	database-reviewer,<lang>-reviewer
security	encrypt, auth, secret, OWASP, PII	security-reviewer,<lang>-reviewer
build	build, compile, lint failure, CI	<lang>-build-resolver (recai em build-error-resolver)
docs	docs, readme, codemap, changelog	doc-updater
lookup	lookup, reference, API usage	docs-lookup
review	review, audit, verify	<lang>-reviewer,code-reviewer
loop	loop, autonomous, watchdog	loop-operator

Regras de composição da cadeia:

1. Seleção de tag primária: quando uma etapa corresponder a várias tags, a primeira na ordem da tabela (topo da tabela = maior prioridade) é a primária; as demais são secundárias. As regras de composição 2 e 3 abaixo lidam explicitamente com combinações específicas de várias tags; caso contrário, anexe cadeias secundárias na ordem da tabela de tags.
2. impl + security → tdd-guide,<lang>-reviewer,security-reviewer.
3. impl + db → tdd-guide,database-reviewer,<lang>-reviewer.
4. Desduplique a cadeia resultante (preserve a primeira ocorrência). Por exemplo, review + lang=unknown resultaria em code-reviewer,code-reviewer após a regra 5; a desduplicação o reduz para code-reviewer.
5. <lang>-reviewer é resolvido para code-reviewer quando lang=unknown.
6. <lang>-build-resolver é resolvido para build-error-resolver quando lang=unknown. Caso especial: se a Fase 0 definiu pytorch=true, use pytorch-build-resolver para cadeias build independentemente de <lang>. Não existe python-build-resolver; --lang=python sem pytorch=true é resolvido para build-error-resolver.
7. Etapas com zero tags: se nenhuma palavra de gatilho corresponder, defina a cadeia como code-reviewer e escreva nenhuma tag correspondida; cadeia padrão apenas de revisão sob "Justificativa da cadeia".
8. Comprimento da cadeia ≤ 4 após desduplicação. Se excedido, descarte a tag mais fraca (lookup e docs primeiro).
9. Não emparelhe planner e architect em uma cadeia impl (desperdício de tokens). Emparelhe-os apenas em etapas design.
10. Etapas marcadas com impl, refactor ou migration terminam com um agente da classe revisor — qualquer um de <lang>-reviewer, code-reviewer, security-reviewer ou database-reviewer. O revisor mais específico de domínio vence a posição final (por exemplo, a regra 2 impl+security termina com security-reviewer; a regra 3 impl+db termina com <lang>-reviewer porque database-reviewer já fecha a migração mais cedo na cadeia). Etapas test e build são protegidas por seus próprios validadores (e2e-runner e o resolvedor de build, respectivamente) e não requerem um revisor adicional.

Fase 3 — Comprimir descrição da tarefa

Cada <descrição da tarefa> emitida deve:

• Ser autocontida (o primeiro agente não precisa ter o documento de plano aberto).
• Começar com [Plano: <caminho>#etapa-<id>].
• Incluir de 1 a 3 Critérios de Aceitação verificáveis.
• Incluir um guarda de Escopo (Fora do escopo: ...) apenas se o plano declarar um para esta etapa. Herde literalmente. Se o plano não tiver uma declaração de fora do escopo, omita a cláusula completamente — não invente uma.
• Ter de 200 a 600 caracteres; uma linha; " incorporado escapado como \"; sem novas linhas literais.

Fase 4 — Saída

Emita Markdown usando a forma determinada por ECC_MODE. A saída usa uma forma durante todo o conteúdo — cada {ORCH_CMD} e cada nome de agente são renderizados com o prefixo correspondente da Fase 0. Não emita ambas as formas; não inclua instruções como "esta é a forma de plugin" / "remova o prefixo" na saída renderizada.

Regras concretas de renderização:

• {ORCH_CMD} = /ecc:orchestrate em plugin, /orchestrate em legacy.
• {AGENT(nome)} = ecc:<nome> em plugin, <nome> em legacy.
• A coluna "Cadeia" da tabela de visão geral usa a mesma renderização {AGENT(nome)}.
• Os blocos bash por etapa contêm apenas o comando executável. Nenhum comentário # forma de plugin ou # forma legada — a forma é implícita e uniforme em toda a saída.

Estrutura da saída:

# Resultado do Plan-Orchestrate

**Plano**: `<caminho>`
**Idioma**: `<detectado-ou-fornecido>`
**Modo ECC**: `<plugin | legacy>`
**Etapas**: <N>
**Escopo**: <all | step:n | range:a-b>

## Visão geral das etapas

| # | Título | Tags | Cadeia |
|---|---|---|---|
| 1 | ... | impl, db | `{AGENT(tdd-guide)},{AGENT(database-reviewer)},{AGENT(python-reviewer)}` |
| ... | | | |

---

## Etapa 1 — <título>

**Intenção**: <1–3 frases>
**Tags**: <a, b>
**Justificativa da cadeia**: <por que esta cadeia; qual agente fecha o loop>

```bash
{ORCH_CMD} custom "{AGENT(tdd-guide)},{AGENT(database-reviewer)},{AGENT(python-reviewer)}" "[Plano: docs/foo.md#etapa-1] <descrição da tarefa comprimida>; Critérios de Aceitação: <1–3 itens>; Fora do escopo: <…>"
```

A notação {ORCH_CMD} e {AGENT(...)} acima descreve a substituição que esta habilidade realiza em tempo de execução. O Markdown realmente emitido contém as strings resolvidas, nunca os marcadores.

Anexe um bloco final de "Execução em lote" agregando o comando de cada etapa em ordem para que o usuário possa colar todos de uma vez. Pule o bloco de lote no modo apenas de visão geral (veja o caso extremo "Plano grande"): quando apenas a tabela de visão geral está sendo emitida, não há comandos por etapa para agregar.

Fase 5 — Autoverificação (executar antes de emitir)

• Cada agente em cada cadeia vem do catálogo (após remover qualquer prefixo ecc: que tenha aparecido no plano; veja passo 5 da Fase 0).
• O {ORCH_CMD} resolvido e cada {AGENT(...)} resolvido usam a mesma forma (plugin ou legacy) — nunca misturadas em uma saída.
• Nenhuma anotação # forma de plugin / # forma legada e nenhuma instrução "remova o prefixo" permanece na saída renderizada.
• Nenhum campo inventado --mode / --gate / --agents=....
• Cada descrição de tarefa está em linha única, entre aspas duplas, com " incorporado escapado.
• Cada descrição de tarefa começa com [Plano: <caminho>#etapa-<id>] e inclui Critérios de Aceitação (1–3 itens). A cláusula Fora do escopo: está presente apenas quando herdada do plano.
• Nenhum agente duplicado em qualquer cadeia após a desduplicação da Fase 2.
• Comprimento da cadeia ≤ 4.
• Etapas marcadas com impl/refactor/migration terminam com um agente da classe revisor (qualquer um de <lang>-reviewer, code-reviewer, security-reviewer, database-reviewer). A verificação é feita nos tokens finais da lista de agentes.
• As cadeias build nunca contêm <lang>-build-resolver quando lang=unknown; em vez disso, build-error-resolver é usado. Cadeias build com pytorch=true usam pytorch-build-resolver.
• A regra de desempate poliglota foi aplicada quando relevante.
• O bloco de lote está presente (a menos que esteja no modo apenas de visão geral) e contém cada comando por etapa na ordem correta.

Casos Extremos

Plano grande (>20 etapas)

Se a Fase 1 produzir >20 etapas, emita apenas a tabela de visão geral com uma nota no topo:

> Este plano tem <N> etapas. Para reduzir o ruído, apenas a visão geral é mostrada. Use --scope=step:<n> ou --scope=range:<a>-<b> para obter prompts individuais.

Pule a decomposição detalhada e os blocos de comando. A saída contém o plano, idioma, modo e tabela, seguido por --- e a nota acima. Fim.

Pule também o bloco de lote — não há comandos para agregar.

Etapas derivadas de dados (tabela de migração, mudanças de configuração)

Quando uma etapa descreve uma mudança de esquema, uma conversão de dados ou uma migração de configuração, trate-a como db ou migration conforme as palavras de gatilho. Se ambos se aplicarem, migration vence como primária (está acima na tabela); db é anexada como secundária. Resultado: architect,tdd-guide,<lang>-reviewer,database-reviewer — a cadeia migration padrão (3) mais database-reviewer anexado.

Desduplicação: se <lang>=python e o idioma revisor é python-reviewer, a cadeia se torna architect,tdd-guide,python-reviewer,database-reviewer.

Sem etapas claras (falta de numeração, poucos cabeçalhos)

Quando a Fase 1 retorna 0 ou 1 etapas:

• Se não houver etapas, emita: > Plano detectado como de etapa única ou amorfo. Execute /orchestrate custom diretamente. e pare.
• Se houver 1 etapa, emita um comando único (a Fase 2 é executada em todo o texto do documento). Saída com apenas uma linha na tabela e um bloco de comando. Sem bloco de lote.

Etapa com restrições de fora do escopo

A descrição da tarefa comprimida herda a cláusula Fora do escopo: apenas quando o documento do plano contém explicitamente um bloco de fora do escopo para aquela etapa. Se a cláusula estiver faltando, omita-a completamente. Use a redação exata do plano.

Prefixo misto no texto do plano

Se o plano fizer referência a agentes com prefixo ecc: (por exemplo, Delegue a revisão para ecc:code-reviewer), remova o prefixo na Fase 0 para obter code-reviewer. Em seguida, aplique os prefixos de saída normalmente na Fase 4. A cadeia nunca conterá ecc:ecc:code-reviewer.