orch-pipeline (mecanismo de orquestração compartilhado)

Pipeline do Orquestrador (mecanismo compartilhado)

As skills orch-* são wrappers finos. Elas não reimplementam nenhum trabalho — elas classificam a solicitação, escolhem quais fases deste pipeline executar, e delegam cada fase para um agente ou comando ECC existente. Este arquivo é esse pipeline.

Invoque uma skill de operação (orch-add-feature, orch-fix-defect, …) em vez de usar este motor diretamente. Este arquivo é a referência para a qual elas apontam.

Quando usar

• Carregado indiretamente sempre que uma skill de operação orch-* é executada.
• Lido diretamente apenas ao adicionar uma nova operação à família ou ajustar as fases, portões ou mapa de agentes compartilhados.

A família de operações

Skill	Operação	Gatilho	Primeira ação
orch-add-feature	feature	capacidade ainda não existe	pesquisar + planejar um novo slice
orch-change-feature	tweak	funciona, mas o comportamento desejado é diferente	alterar o comportamento existente e seus testes
orch-fix-defect	fix	quebrado; o comportamento está errado	reproduzir como um teste falho, depois consertar
orch-refine-code	refactor	comportamento permanece, estrutura melhora	reestruturar mantendo os testes verdes
orch-build-mvp	mvp	inicializar a partir de um documento de design/especificação	ingerir documento → slices verticais

Esses wrappers compõem comandos ECC existentes em vez de substituí-los: /feature-dev, /plan, /code-review, /build-fix, /refactor-clean, e /gan-build, além da skill tdd-workflow. A família orch-* adiciona o classificador de tamanho compartilhado e os dois portões sobre eles, de modo que um único guarda-chuva cobre todas as cinco operações de forma consistente.

Passo 0 — Classificar tamanho (dimensionamento correto)

A cerimônia escala conforme o raio de impacto. Avalie a solicitação com base em três sinais, pegue o maior nível que qualquer sinal atingir e declare o resultado em uma linha para que o usuário possa sobrescrever:

Nível	Arquivos tocados	Nova dependência / contrato	Ambiguidade de design	Fases executadas
trivial	1, algumas linhas	nenhum	nenhuma — a mudança é óbvia	4 → 5 → 6
small	1 arquivo / 1 função	nenhum	clara assim que você lê o código	(1 leve) → 4 → 5 → 6
standard	2–5 arquivos	talvez um novo módulo interno	uma escolha real a fazer	1 → 2 → 4 → 5 → 6
large	muitos / transversal	nova dependência externa, API pública ou documento de especificação	múltiplas perguntas em aberto	1 → 2 → (3) → 4 → 5 → 6

A Fase 0 (Intake) sempre executa e é omitida da coluna de máscara acima. O desempate: qualquer coisa que toque em um gatilho de segurança (abaixo) ou em uma API pública / contrato é no mínimo standard, independentemente da contagem de arquivos.

As fases

Cada fase delega — ela não faz o trabalho inline.

• 0. Intake — reafirme a solicitação. Para orch-build-mvp, leia o documento de especificação/design e extraia o escopo, as decisões bloqueadas e uma lista de funcionalidades.
• 1. Pesquisa e Reuso — conforme rules/common/development-workflow.md: gh search repos / gh search code, depois Context7 / documentações de fornecedores, depois registros de pacotes, depois Exa. Prefira adotar uma implementação comprovada em vez de código novo do zero.
• 2. Planejar — delegue para o agente planner (ou architect / code-architect para decisões estruturais). Gere uma task_list ordenada como slices verticais finos. → PORTÃO 1.
• 3. Scaffold — apenas para orch-build-mvp: monte o primeiro slice de ponta a ponta.
• 4. Implementar (TDD) — conduza cada tarefa pelo agente tdd-guide (ou pela skill tdd-workflow): vermelho → verde → refatorar. Respeite a regra de primeira ação da operação.
• 5. Revisar — agente code-reviewer / /code-review. Adicione security-reviewer sempre que o diff tocar em um gatilho de segurança (abaixo).
• 6. Commitar — commits convencionais (feat: / fix: / refactor: / …), um por bloco lógico. → PORTÃO 2.

Os dois portões

Esta família é com portões, não autônoma:

1. PORTÃO 1 — após Planejar. Apresente a task_list; não escreva código de implementação até que o usuário aprove.
2. PORTÃO 2 — antes de Commitar. Apresente o resumo do diff e as mensagens propostas; não faça commit até que o usuário confirme.

Tudo entre os portões flui sem parar.

Mapa de agente / comando

Fase	Primário	Substituto / escalação
Intake / entender	code-explorer	rastrear caminhos existentes antes de um tweak, fix ou refactor
Planejar	planner	architect, code-architect para decisões estruturais
Implementar	tdd-guide (ou skill tdd-workflow)	build-error-resolver / /build-fix em quebras de build
Revisar	code-reviewer / /code-review	revisor de linguagem (python-reviewer, typescript-reviewer, …)
Segurança	security-reviewer	—
Loop interno MVP	/gan-build "<breve_descrição>" --skip-planner	aciona gan-generator → gan-evaluator; ajuste --max-iterations / --pass-threshold

Associe o revisor de linguagem ao repositório (veja o próprio CLAUDE.md do repositório).

Gatilho de revisão de segurança

Acione security-reviewer quando o diff tocar em qualquer um dos seguintes: autenticação ou autorização, manipulação de entrada do usuário, consultas a banco de dados, caminhos de sistema de arquivos, chamadas a API externa, criptografia, ou segredos/credenciais. (Conforme rules/common/security.md.)

Artefatos de handoff

O pipeline não carrega estado oculto — os documentos de planejamento são o handoff:

• task_list (do Planejamento) guia o loop de Implementação.
• Trabalhos maiores também podem gerar PRD / arquitetura / system_design sob o diretório docs/ do repositório, conforme rules/common/development-workflow.md.
• Achados da revisão (CRITICAL / HIGH) devem ser resolvidos antes do Portão 2.

Verificação

• o nível de tamanho foi declarado e correspondeu ao trabalho
• Portão 1 (plano) e Portão 2 (commit) foram ambos honrados
• security-reviewer foi executado se e somente se um gatilho de segurança foi tocado
• commits são convencionais e com escopo para uma única mudança lógica
• comportamento novo / alterado possui testes; cobertura ≥ 80% conforme rules/common/testing.md