orch-pipeline

Pipeline do Orquestrador (motor compartilhado)

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

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

Quando usar

• Carregado indiretamente sempre que uma habilidade 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

Habilidade	Operação	Gatilho	Primeiro movimento
orch-add-feature	funcionalidade	capacidade ainda não existe	pesquisar + planejar um novo slice
orch-change-feature	ajuste	funciona, mas o comportamento desejado é diferente	alterar o comportamento existente e seus testes
orch-fix-defect	correção	quebrado; comportamento está errado	reproduzir como um teste com falha, depois corrigir
orch-refine-code	refatoração	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 invólucros 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 habilidade tdd-workflow. A família orch-* adiciona o classificador de tamanho compartilhado e os dois portões sobre eles, para que um guarda-chuva cubra todas as cinco operações de forma consistente.

Etapa 0 — Classificar tamanho (dimensionamento correto)

A cerimônia escala com o raio de explosão. Pontue a solicitação 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 substituir:

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
pequeno	1 arquivo / 1 função	nenhum	claro ao ler o código	(1 leve) → 4 → 5 → 6
padrão	2–5 arquivos	talvez um novo módulo interno	uma escolha real a fazer	1 → 2 → 4 → 5 → 6
grande	muitos / transversais	nova dep externa, API pública ou documento de especificação	múltiplas questões em aberto	1 → 2 → (3) → 4 → 5 → 6

A Fase 0 (Intake) sempre é executada 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 é pelo menos padrão, independentemente da contagem de arquivos.

As fases

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

• 0. Intake — reformule a solicitação. Para orch-build-mvp, leia o documento de especificação/design e extraia o escopo, decisões travadas e uma lista de funcionalidades.
• 1. Pesquisa e Reuso — conforme rules/common/development-workflow.md: gh search repos / gh search code, depois Context7 / documentação do fornecedor, depois registros de pacotes, depois Exa. Prefira adotar uma implementação comprovada em vez de código totalmente novo.
• 2. Planejamento — delegue ao 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 orch-build-mvp: levante o primeiro slice ponta a ponta.
• 4. Implementar (TDD) — conduza cada tarefa através do agente tdd-guide (ou da habilidade tdd-workflow): vermelho → verde → refatorar. Respeite a regra do primeiro movimento da operação.
• 5. Revisão — agente code-reviewer / /code-review. Adicione security-reviewer sempre que o diff tocar em um gatilho de segurança (abaixo).
• 6. Commit — 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 o Planejamento. Apresente a task_list; não escreva código de implementação até que o usuário aprove.
2. PORTÃO 2 — antes do Commit. 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 agentes / comandos

Fase	Principal	Substituto / escalonamento
Intake / entender	code-explorer	rastreie caminhos existentes antes de um ajuste, correção ou refatoração
Planejamento	planner	architect, code-architect para chamadas estruturais
Implementar	tdd-guide (ou habilidade tdd-workflow)	build-error-resolver / /build-fix em quebras de build
Revisão	code-reviewer / /code-review	revisor de linguagem (python-reviewer, typescript-reviewer, …)
Segurança	security-reviewer	—
Loop interno MVP	/gan-build "<breve>" --skip-planner	aciona gan-generator → gan-evaluator; ajuste --max-iterations / --pass-threshold

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

Gatilho de revisão de segurança

Inclua 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 do sistema de arquivos, chamadas de API externas, 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) aciona o loop de Implementação.
• Trabalhos maiores também podem gerar PRD / arquitetura / system_design sob o docs/ do repositório conforme rules/common/development-workflow.md.
• Descobertas da revisão (CRÍTICO / ALTO) devem ser resolvidas antes do Portão 2.

Verificação

• o nível de tamanho foi declarado e correspondeu ao trabalho
• Portão 1 (planejamento) 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 tem testes; cobertura ≥ 80% conforme rules/common/testing.md