Orquestrar-Plano

O que Orquestrar-Plano faz?

Ponte entre um documento de plano e /orquestrar personalizado, emitindo uma invocação pronta para colar por etapa. A skill é apenas generativa — nunca executa /orquestrar. O usuário cola cada linha quando estiver pronto.

Quando Ativar

• O usuário tem um documento de plano com várias etapas (PRD, RFC, plano de implementação) e quer executá-lo através de /orquestrar.
• O usuário diz "orquestrar este plano", "me dê prompts de orquestrar para cada etapa", "compor cadeias para este plano".
• Existe um plano passo a passo, mas o usuário não quer selecionar agentes manualmente por etapa.

Pular quando:

• O trabalho é uma etapa ad-hoc → chame /orquestrar personalizado diretamente.
• O plano está ilegível ou vazio. A falta de numeração explícita sozinha não é condição de pular — veja o caso extremo "Sem etapas claras" abaixo.

Entradas

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

• <caminho-doc-plano> — 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 — exibe apenas a decomposição e a justificativa da cadeia; não emite prompts finais.

Forma Autoritária de /orquestrar (não desviar)

{ORCH_CMD} personalizado "<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 espaço reservado.

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

Forma de Instalação do ECC e Namespacing

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

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

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

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

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

Gerais:

• planner — reformulação de requisitos, decomposição de riscos, planejamento de etapas
• architect — arquitetura, design de sistema, propostas de refatoração
• tdd-guide — escrever testes → implementar → cobertura de 80%+
• 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 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 de harness de agente local
• loop-operator — loops autônomos de longa duração
• chief-of-staff — triagem multicanal (raramente adequado para etapas de plano)

Resolvedores de erro 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 de ortografia faz /orquestrar falhar. Verifique novamente em relação a esta lista antes de emitir.

Como Funciona

Fase 0 — Detectar modo ECC + idioma

1. Leia <caminho-doc-plano>. Se ausente 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 na primeira correspondência):

   1. Se <home-claude>/plugins/marketplaces/ecc/ existir → ECC_MODE=plugin.
   2. Senão, se <home-claude>/agents/ existir e contiver pelo menos um arquivo de agente ECC (ex.: tdd-guide.md, code-reviewer.md) → ECC_MODE=legacy.
   3. Senão → padrão para 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; padronizando para a forma legada. Se você usa a instalação por 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:

   • Sondar marcadores: pyproject.toml / uv.lock / requirements.txt → python; package.json → typescript; go.mod → go; Cargo.toml → rust; CMakeLists.txt ou *.cpp no nível superior → cpp; pom.xml / build.gradle (Java) → java; build.gradle.kts ou Kotlin no nível superior → kotlin; pubspec.yaml → flutter.
   • Desempate poliglota: se mais de um marcador corresponder, escolha o idioma cujos arquivos de código-fonte superam os outros (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 código-fonte, 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 de 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 agentes declarados no plano: se o texto do plano referenciar agentes pela forma prefixada do plugin (ex.: ecc:tdd-guide), remova o prefixo para obter o nome do catálogo simples antes de validar ou compor cadeias. O re-prefixing ocorre apenas no momento da saída, de acordo com ECC_MODE (Fase 4). Nunca deixe um nome pré-prefixado fluir para a 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 títulos iniciados por verbo.
4. Caso contrário, trate cada H2 como uma etapa.

Por etapa, extraia id (baseado em 1), título (≤ 80 caracteres), intenção (1–3 frases), tags.

Fase 2 — Etiquetar e escolher cadeia

Etiquetar por intenção (multi-etiqueta permitida; cadeia construída a partir da primária + secundárias empilhadas):

As palavras de gatilho abaixo são correspondidas sem distinção entre maiúsculas e minúsculas. Planos multilíngues são suportados combinando os radicais das palavras em qualquer idioma, desde que o significado esteja alinhado com as palavras de gatilho em inglês listadas.

Etiqueta	Palavras de gatilho	Cadeia padrão
design	arquitetura, design, escolher, avaliar, RFC	planner,architect
plan	plano, decomposição, marco	planner
impl	implementar, construir, adicionar, criar, portar	tdd-guide,<lang>-reviewer
test	teste, cobertura, e2e, integração	tdd-guide,e2e-runner
refactor	refatorar, limpar, deduplicar, dividir	architect,refactor-cleaner,<lang>-reviewer
migration	migrar, atualizar, reescrever, portar	architect,tdd-guide,<lang>-reviewer
db	esquema, migração, índice, SQL, Postgres, alembic, sqlmodel	database-reviewer,<lang>-reviewer
security	criptografar, autenticação, segredo, OWASP, PII	security-reviewer,<lang>-reviewer
build	construir, compilar, falha de lint, CI	<lang>-build-resolver (recai para build-error-resolver)
docs	docs, readme, mapa de código, changelog	doc-updater
lookup	consultar, referência, uso de API	docs-lookup
review	revisar, auditar, verificar	<lang>-reviewer,code-reviewer
loop	loop, autônomo, vigilante	loop-operator

Regras de composição de cadeia:

1. Seleção de etiqueta primária: quando uma etapa corresponder a várias etiquetas, 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 com combinações específicas de múltiplas etiquetas explicitamente; caso contrário, anexe cadeias secundárias na ordem da tabela de etiquetas.
2. impl + security → tdd-guide,<lang>-reviewer,security-reviewer.
3. impl + db → tdd-guide,database-reviewer,<lang>-reviewer.
4. Deduplique a cadeia resultante (preserve a primeira ocorrência). Ex.: review + lang=unknown resultaria em code-reviewer,code-reviewer após a regra 5; a deduplicação a reduz para code-reviewer.
5. <lang>-reviewer resolve para code-reviewer quando lang=unknown.
6. <lang>-build-resolver resolve 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 resolve para build-error-resolver.
7. Etapas sem etiqueta: se nenhuma palavra de gatilho corresponder, defina a cadeia como code-reviewer e escreva nenhuma etiqueta correspondida; cadeia de revisão padrão em "Justificativa da cadeia".
8. Comprimento da cadeia ≤ 4 após deduplicação. Se excedido, descarte a etiqueta 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 etiquetadas como impl, refactor ou migration terminam com um agente da classe de revisor — qualquer um de <lang>-reviewer, code-reviewer, security-reviewer ou database-reviewer. O revisor mais específico do domínio vence a posição final (ex.: 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 anteriormente na cadeia). Etapas test e build são fechadas por seus próprios validadores (e2e-runner e o resolvedor de compilação, respectivamente) e não exigem 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 do documento de plano aberto).
• Começar com [Plano: <caminho>#etapa-<id>].
• Incluir 1–3 Critérios de aceitação verificáveis.
• Incluir uma proteção de Escopo (Fora do escopo: ...) apenas se o plano declarar uma para esta etapa. Herde textualmente. Se o plano não tiver uma declaração de fora do escopo, omita a cláusula inteiramente — não invente uma.
• Ter 200–600 caracteres; uma linha; " incorporado escapado como \"; sem quebras de linha literais.

Fase 4 — Saída

Emita Markdown usando a forma determinada por ECC_MODE. A saída usa uma forma em toda a sua extensão — cada {ORCH_CMD} e cada nome de agente é renderizado com o prefixo correspondente da Fase 0. Não emita ambas as formas; não inclua instruções "esta é a forma de plugin" / "remova o prefixo" na saída renderizada.

Regras de renderização concretas:

• {ORCH_CMD} = /ecc:orchestrate sob plugin, /orchestrate sob legacy.
• {AGENT(nome)} = ecc:<nome> sob plugin, <nome> sob 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. Sem comentários # forma de plugin ou # forma legada — a forma é implícita e uniforme em toda a saída.

Estrutura da saída:

# Resultado do Orquestrar-Plano

**Plano**: `<caminho>`
**Idioma**: `<detectado-ou-fornecido>`
**Modo ECC**: `<plugin | legado>`
**Etapas**: <N>
**Escopo**: <all | etapa:n | intervalo:a-b>

## Visão geral das etapas

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

---

## Etapa 1 — <título>

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

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

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

Anexe um bloco final "Execução em lote" agregando o comando de cada etapa em ordem para que o usuário possa colá-los todos de uma vez. Pule o bloco de lote no modo somente 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 a etapa 5 da Fase 0).
• O {ORCH_CMD} resolvido e cada {AGENT(...)} resolvido usam a mesma forma (plugin ou legacy) — nunca misturados em uma saída.
• Nenhuma anotação # forma de plugin / # forma legada e nenhuma instrução "remova o prefixo" permanecem na saída renderizada.
• Nenhum campo --mode / --gate / --agents=... inventado.
• Cada descrição de tarefa é de linha única, entre aspas duplas, com " incorporado escapado.
• Cada descrição de tarefa começa com [Plano: <caminho>#etapa-<id>] e inclui 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 dedup da Fase 2.
• Comprimento da cadeia ≤ 4.
• Etapas etiquetadas como impl/refactor/migration terminam com um agente da classe de revisor

… (truncado para tradução)