| name | cp-orquestrador |
| description | Orquestrador da Fábrica de Software — coordena todo o pipeline de desenvolvimento executando crews especializadas em sequência, gerenciando artefatos entre fases e decidindo avanço/retrocesso baseado em quality gates. Use quando o usuário disser 'executar pipeline completo', 'fazer fábrica de software', 'entregar produto', 'coordenar desenvolvimento', 'gerenciar projeto'. |
cp-orquestrador — Orquestrador da Fábrica de Software
Orquestrador central do pipeline NEXUS. Coordena a execução de todas as crews especializadas (cp-*) em sequência, gerencia a passagem de artefatos entre fases, aplica quality gates e decide avanço/retrocesso.
Pipeline Completo (9 fases)
[Requisitos] ──► [Arquitetura] ──► [Implementação] ──► [Testes] ──► [Segurança] ──► [DevOps] ──► [Documentação] ──► [Qualidade] ──► [Entrega]
│ │ │ │ │ │ │ │ │
cp-requisitos cp-arquitetura cp-implementacao cp-testes cp-seguranca cp-devops cp-documentacao cp-qualidade Entrega
│ │ │ │ │ │ │ │ │
[Quality Gate] [Quality Gate] [Quality Gate] [Quality Gate] [Quality Gate] [Quality Gate] [Quality Gate] [Quality Gate] [Entrega]
Todas as skills cp-* acionáveis
O orquestrador é o ponto único de entrada para TODAS as skills cp-*. Além das 8
fases do pipeline, ele aciona as 6 skills complementares via modos dedicados:
| Modo | Skill | O que faz |
|---|
bugfix | cp-bug-fix | Corrige bugs (Developer → QA → Evidence Collector, máx. 3 retries) |
competitive | cp-competitive-analysis | Inteligência competitiva (mercado, concorrentes, pricing, estratégia) |
full-dev | nativo (merge de cp-full-dev) | Pipeline NEXUS completo (Discovery → ... → Operate), agora embutido no orquestrador |
goal-loop | cp-goal-loop | Loop autônomo de tentativa-e-correção até atingir sucesso |
manutencao | cp-manutencao | Manutenção/evolução (bug-fix, refactor, improvement, full) |
agilista | cp-agilista | Esteira de execução: monitora backlog, despacha tarefas e gerencia feedback bidirecional (dúvidas, impedimentos, retomada) |
inicializador-doc | cp-inicializador-doc | Inicializa a documentação: centraliza o contexto em .context/ (fonte de verdade única) e cria ponteiros CLAUDE.md/AGENT.md |
Nota: o cp-full-dev foi fundido no orquestrador. O pipeline NEXUS (7 fases,
39 agentes) agora roda nativamente via NexusExecutor — não depende mais da skill
cp-full-dev (que foi eliminada). O modo full-dev executa o NEXUS em memória, com
detecção automática de modo (full/sprint/micro) e quality gates por fase.
Cada skill é acionada respeitando sua interface CLI (metadado invoke no CREWS):
briefing_arg: positional (arg posicional), goal (--goal, ex. goal-loop),
input (--input, fases do pipeline), daemon (sem briefing posicional —
monta --daemon, ex. agilista) ou dir (monta --dir <cwd>, ex. inicializador-doc)output: True se a skill aceita --output, False caso contrário
⚠️ NÃO assuma que toda skill aceita --output nem que o briefing entra como
posicional — cada skill tem contrato CLI próprio. Ver
references/skills-cli-inventory.md para o inventário completo por skill e o
snippet de verificação. Pitfalls: cp-goal-loop só recebe briefing via --goal;
cp-bug-fix/cp-goal-loop/cp-agilista rejeitam --output; cp-agilista não
tem argumento posicional (só --daemon/--duvida/--impedimento/--resume);
cp-inicializador-doc não tem posicional (só --dir/--dry-run).
Regra de documentação em .context/
Toda skill cp-* documenta seus artefatos na estrutura .context/ (fonte de
verdade única do projeto). O cp-inicializador-doc cria a estrutura; o orquestrador
escreve automaticamente o artefato de cada fase no arquivo de disciplina correto:
| Crew | Arquivo em .context/docs/ |
|---|
| requisitos, competitive-analysis | 01-requisitos.md |
| arquitetura, implementacao, manutencao | 02-arquitetura.md |
| seguranca | 03-seguranca-lgpd.md |
| testes, documentacao, qualidade, bug-fix | 04-qualidade-qa.md |
| devops, goal-loop | 05-devops-operacoes.md |
| agilista | 06-kanban.md |
O cp-agilista também gera .context/docs/06-kanban.md com o estado do kanban
via --doc.
Como adicionar uma skill nova ao orquestrador
Para conectar uma nova skill cp-* ao fluxo, edite scripts/run.py em 4 pontos:
SKILL_PATHS — adicione "<chave>": SKILLS_DIR / "cp-<nome>" / "scripts" / "run.py"CREWS — adicione a crew com name, skill, agents, inputs, outputs,
quality_gate, cli_args e o metadado invoke (o briefing_arg DEVE refletir
como a skill realmente recebe o briefing — teste com _build_cli_args).MODOS — adicione o modo com crews: ["<chave>"]._build_cli_args — se a skill usa um briefing_arg novo (ex.: daemon),
adicione o branch correspondente.
Valide com: python run.py "<briefing>" --mode <modo> --dry-run (plano) e
python run.py "<briefing>" --mode <modo> --auto (execução). Se a skill não aceita
--output, o metadado invoke.output=False é OBRIGATÓRIO — sem ele o argparse da
skill rejeita o flag e a fase quebra.
Exemplos:
python run.py "o endpoint /login retorna 500" --mode bugfix --auto
python run.py "SaaS de clínicas; concorrentes: Doctoralia" --mode competitive --auto
python run.py "sistema de agendamento" --mode full-dev --auto
python run.py "deploy em staging funcionando" --mode goal-loop --auto
python run.py "refatorar módulo de pagamentos" --mode manutencao --auto
Agentes
| Agente | Função |
|---|
| Orquestrador de Pipeline | Coordena execução sequencial/paralela das crews. Maestro de orquestra de software que conhece cada instrumento e quando tocar. |
| Gestor de Artefatos | Garante que outputs de uma crew viram inputs da próxima, versiona artefatos. Bibliotecário de software que organiza e versiona cada artefato produzido. |
| Tomador de Decisão | Decide avançar, pausar, ou retroceder baseado nos quality gates. Gerente de projeto experiente que sabe quando pressionar e quando recuar. |
| Relator de Progresso | Gera relatórios de status do pipeline, dashboards, resumos executivos. PM que transforma progresso técnico em relatórios que stakeholders entendem. |
Modos de Operação
O orquestrador opera em dois modos:
🧪 Simulação (default)
Usa CrewAI para planejar, simular e documentar o pipeline. Ideal para:
- Planejamento antes de executar
- Apresentação para stakeholders
- Estimar esforço e riscos
🚀 Auto (--auto)
Executa as crews reais em sequência, passando artefatos entre fases e aplicando quality gates automaticamente. Ideal para:
- Execução real do pipeline do começo ao fim
- Integração contínua / esteira de deploy
- Uso como "gerente da fábrica" — um comando só
Como o modo auto funciona:
1. Recebe o briefing
2. Executa cp-requisitos → salva requisitos.md
3. Passa requisitos.md como input para cp-arquitetura
4. Executa cp-arquitetura → salva arquitetura.md
5. Passa arquitetura.md como input para cp-implementacao
6. ... continua até a última fase
7. Se um quality gate FAIL, o pipeline para e reporta
8. Gera relatório final com dashboard e métricas
Quality Gates
Cada fase possui um quality gate que avalia:
- PASS → Avança para próxima fase
- WARN → Avança com ressalvas documentadas
- FAIL → Pipeline interrompe com recomendações de correção
No modo --auto, o quality gate é verificado automaticamente analisando a saída de cada skill. Se FAIL, o pipeline para e você pode corrigir e retomar com --start-phase.
Uso
python .hermes/skills/cp-orquestrador/scripts/run.py "sistema de agendamento para clínicas"
python .hermes/skills/cp-orquestrador/scripts/run.py "sistema de agendamento" --auto
python .hermes/skills/cp-orquestrador/scripts/run.py "feature de relatório PDF" --mode sprint --auto
python .hermes/skills/cp-orquestrador/scripts/run.py "corrigir erro de login" --mode micro --auto
python .hermes/skills/cp-orquestrador/scripts/run.py "app financeiro" --mode security-audit --auto
python .hermes/skills/cp-orquestrador/scripts/run.py "API de pagamentos" --mode documentation --auto
python .hermes/skills/cp-orquestrador/scripts/run.py --input briefing.txt --auto
python .hermes/skills/cp-orquestrador/scripts/run.py "sistema de estoque" --start-phase implementacao --auto
python .hermes/skills/cp-orquestrador/scripts/run.py "sistema de agendamento" --dry-run
python .hermes/skills/cp-orquestrador/scripts/run.py "app de delivery" --output ./pipeline --auto
Exemplo
python .hermes/skills/cp-orquestrador/scripts/run.py \
"preciso de um sistema para clínica de estética onde a recepcionista agenda clientes, \
a esteticista vê sua agenda do dia, e a dona da clínica quer relatórios de faturamento. \
Também precisa enviar lembrete por WhatsApp automaticamente." \
--mode full --output ./pipeline-relatorio.md
Ponto Único de Entrada (Gerente da Fábrica)
O cp-orquestrador é o gerente da fábrica de software — direcione todos os pedidos para ele. Ele analisa o briefing, escolhe o modo, planeja as fases, define quality gates e gera o relatório.
Modo Simulação (default)
Por padrão o orquestrador simula a execução — documenta o que cada fase produziria, sem chamar as outras skills. Útil para planejamento, apresentação a stakeholders e estimativa de esforço/risco.
Modo --auto (executor real)
O modo --auto executa as crews reais em sequência, passando artefatos entre fases e aplicando quality gates automaticamente:
- Planeja o pipeline
- Chama
cp-requisitos → recebe requisitos.md
- Chama
cp-arquitetura --input requisitos.md → recebe arquitetura.md
- Chama
cp-implementacao --input arquitetura.md → recebe código
- ... até a entrega final
- Gera relatório completo
Cada fase só avança se o quality gate passar. Se falhar, pausa e documenta o que precisa ser corrigido (retome com --start-phase). O modo --auto também aciona as skills complementares (bugfix, competitive, full-dev, goal-loop, manutencao).
Script
O script scripts/run.py é self-contained — todos os 4 agentes estão embutidos no próprio código Python. Ele lista as crews disponíveis, simula a execução do pipeline (modo default) e executa as crews reais em sequência (modo --auto), acionando todas as skills cp-* via subprocess. Não depende de diretório externo de agentes.
Manutenção do roadmap e inbox (crewbotics-back)
Antes de reportar "o que falta" ou atualizar .hermes/roadmap/tasks.md, SEMPRE cruze o
estado do roadmap/inbox contra o código real (modelos, endpoints, testes) — o roadmap
frequentemente marca como pendente coisas já implementadas (e às vezes no app errado).
Ver references/roadmap-inbox-manutencao.md para o procedimento completo: verificação
de estado real, convenção inbox→processed (features [Concluído] e bugs [Corrigido]
movidos via git mv), frontend em outro repo, e o pitfall de escrita mascarando
placeholders de exemplo.
Windows: relay bash intermitente
Neste host Windows, terminal/write_file às vezes falham com
execvpe(/bin/bash) failed: No such file or directory (relay WSL intermitente).
Quando isso ocorrer, use execute_code com Python puro (subprocess/open) — não
passa pelo relay. Ver references/windows-wsl-bash-relay-workaround.md.
Execução do pipeline (crewbotics-back) — pitfalls reais
Ao executar o pipeline de desenvolvimento (rodar testes, commitar, validar), ver
references/dev-pipeline-execucao.md para lições duráveis: testes rodam com
uv run pytest (não há .venv próprio), testes que tocam banco falham sem
.env/Postgres (pré-existente, não é sua mudança), SEMPRE conferir
git status --short antes de commitar (commit pode sair incompleto se nem todos
os arquivos foram staged), fechar imagens PIL antes de deletar tempdir no Windows,
e usar True/False (não true/false) em dicts de parameters Python.
Skill design: auto-detecte o modo, não dependa do LLM lembrar de um flag
Ao adicionar um modo de renderização alternativo a uma skill (ex.: card_mode para
alternar entre executor de cards e renderer de marca), NÃO dependa de um flag opcional
que o LLM precisa lembrar de setar — o LLM chama a skill via function calling e decide
os parâmetros por conta própria, então um flag default=False cego faz o modo novo
nunca ser acionado. O modo correto deve ser DETECTADO automaticamente a partir do
prompt (ex.: padrão de "data + título" em lista → cards de lançamento). Ver
references/skill-design-auto-detect.md para a regra completa e a heurística de
detecção.
Debug: "código certo localmente mas não funciona no app"
Antes de debugar uma skill que parece não ter efeito no app web, confirme de QUAL
diretório o processo do backend (porta 8000) está rodando — pode estar subindo de um
CLONE antigo do repo (ex.: PycharmProjects\crewbotics-back) que não tem a feature,
enquanto o trabalho real fica em outro clone (ex.: Documents\Professional\...).
Verificar o CommandLine do listener via PowerShell e comparar o arquivo da skill entre
os clones. Ver references/debug-backend-clone-errado.md para o passo a passo.
Carrossel de currículo/perfil (caso de uso novo, não coberto)
instagram_carousel_skill.py hoje cobre: (a) cards de lançamento com data (detecção
automática) e (b) carrossel narrativo de marca. NÃO cobre bem "carrossel do MEU
currículo/perfil + foto real" — cai no caminho de marca genérico, ignora a foto e
reusa o template fallback constellation (layout idêntico ao caso anterior, o que
confunde o usuário). Para esse caso é preciso um executor dedicado: currículo →
slides + foto no cover. Ao depurar "gerou layout igual ao pedido anterior", confira
se a skill realmente consumiu a entrada nova ou caiu no fallback.
