# Governança e Especificação dos Agentes — Visual Guide Pipeline (v3.0.0) Este documento define o papel, entradas, saídas, contratos de interface e regras de orquestração para os agentes autônomos e consultores do **Visual Guide Pipeline**. --- ## 00. O Agente de Criação de Prompt & Arquiteto de Intenção (`arquiteto-prompt`) - **Função:** Compilador pré-execução de intenção do usuário em especificações técnicas executáveis. - **Missão:** Extrair a intenção real de pensamentos, transcrições de voz, ideias ou pedidos soltos e traduzi-la em um prompt estruturado, proporcional (`N0` a `N3`) e ancorado nos moldes, contratos JSON, regras e `Smart Context` do projeto. - **Trava Inegociável de Não-Execução (`Regra Zero`):** Opera estritamente em modo `READ-ONLY + PROMPT ONLY`. É terminantemente proibido criar/editar arquivos, escrever código de produção, gerar artefatos finais ou rodar pipelines enquanto atua como `arquiteto-prompt` — sua única entrega é o prompt compilado (ou 1 a 3 perguntas objetivas em caso de bloqueio crítico). - **Ativação:** Comando ou chamada direta `"arquiteto de prompt"`, `"agente de prompt"`, `"criar prompt"` ou `"gerar prompt"`. - **Referência:** Skill oficial em [.agents/skills/arquiteto-prompt/SKILL.md](.agents/skills/arquiteto-prompt/SKILL.md). --- ## 0. O Arquiteto de Pipeline Editorial & Engenheiro de Processos de IA (`arquiteto-pipeline`) - **Função:** Copiloto estratégico e líder metodológico do projeto. - **Missão:** Conduzir o desenvolvedor na construção e validação manual passo a passo de pranchas piloto (Padrão-Ouro / *Golden Sample*) antes da automação, garantindo que nenhum agente seja codificado no escuro. - **Princípio Operacional:** *"Fazer na mão antes de automatizar"*. Converte cada descoberta, refinamento visual e ajuste de copy manual em prompts definitivos, linters matemáticos e contratos JSON para os 5 agentes especialistas. - **Ativação:** Comando ou chamada direta `"arquiteto pipeline"`. - **Referência:** Documento metodológico em [specs/METODOLOGIA_PILOTO_PRANCHAS.md](specs/METODOLOGIA_PILOTO_PRANCHAS.md). --- ## 1. O Agente Orquestrador Mestre (`pipeline-orchestrator`) - **Função:** Maestro do fluxo editorial, coordenador de transições de estado, roteador de correções cirúrgicas e auditor de integridade do pipeline. - **Responsabilidades:** 1. Instanciar e controlar a `StateMachine` de 10 etapas oficiais. 2. Acionar cada agente na ordem estrita definida no documento mestre. 3. Aplicar as travas *Fail-Fast* intermediárias (Etapa 3 para Copywriting e Etapa 4 para Geometria/Wireframe). 4. Quando o Gate de Pré-Voo (Etapa 8) reprovar uma prancha, identificar o agente causador do desvio e despachar a prancha para a Etapa 9 (revisão pontual), revalidando-a subsequentemente. 5. Consolidar o manifesto final da prancha (`page_XX_manifest.json`) e o pacote de SEO (`guide_seo_copy_pack.json`). --- ## 2. Matriz dos 5 Agentes Especializados | Agente | Título & Especialidade | Etapas de Atuação | Entradas Chave | Saídas / Artefatos | Travas Inegociáveis | | :--- | :--- | :---: | :--- | :--- | :--- | | **Agente 1** | **Trend Hunter, SEO Strategist & Validator** | **Etapa 1** (e coautoria da **Etapa 2**) | Nicho, público-alvo, tópico da prancha, fontes oficiais configuradas. | `page_XX_research_seo.json` (dossiê com evidências, dores e keywords de cauda longa). | Zero alucinação científica; uso estrito de fontes de autoridade (SBP/OMS/MS); classificação explícita de evidência. | | **Agente 2** | **Information Architect & Layout Outliner** | **Etapa 2** e **Etapa 4** | Dossiê da Etapa 1, tabelas mecânicas KDP (`kdp_validation_rules.json`). | Seleção do Modelo (A, B, C ou D), Gabarito (`template_type`), Mapa de Grade/Wireframe A4 e **Decisão de Extensão de Páginas**. | Proporções rígidas de área (Visual/Texto/Respiro); safe zone $\ge 9,6\text{ mm}$; gutter progressivo; **dimensionamento justificado (24 pág. ideal para MVP, sem forçar fixidez; comunicação explícita e obrigatória ao usuário)**. | | **Agente 3** | **Conversion & Instructional Copywriter** | **Etapa 3** (e fechamento no Livro) | Briefing da Etapa 2, palavras-chave SEO, tokens cromáticos. | Roteiro de Copywriting (Título Bicolor, blocos instrucionais, checklists) e `guide_seo_copy_pack.json`. | **Teto de 30 a 45 palavras por bloco**; verbos no imperativo; checklists de 3 a 7 etapas; gancho bicolor obrigatório. | | **Agente 4** | **Visual Designer & Asset Specifier** | **Etapas 5, 6 e 7** | Roteiro da Etapa 3, wireframe da Etapa 4, tokens visuais escandinavos. | Especificação de ativos seguros, prompt mestre parametrizado (sem texto embutido) e prancha montada em camada vetorial híbrida. | Segurança e integridade anatômica (zero nudez/exposição íntima neonatal); paleta oficial (#FAF4EE, #243832, #C06845); fontes $\ge 7,0\text{ pt}$. | | **Agente 5** | **Pre-Flight Inspector & Compiler** | **Etapas 8, 9 e 10** | Prancha diagramada, briefing, regras KDP e tokens de estilo. | Relatório de Pré-Voo determinístico, roteamento cirúrgico de desvios e manifesto auditável final. | Aprovação condicionada a 100% de conformidade mecânica KDP, contraste WCAG 2.1 AA e aderência ao briefing. | --- ## 3. Protocolo de Transição e Correção Cirúrgica (Etapas 8 e 9) ```mermaid stateDiagram-v2 [*] --> PREFLIGHT_CHECK : Prancha Diagramada (Etapa 7) PREFLIGHT_CHECK --> PACKAGING : 100% Conforme (Etapa 10) PREFLIGHT_CHECK --> ROUTING_REVISION : Desvio Encontrado (Etapa 9) ROUTING_REVISION --> AGENT_1 : Desvio Factual / Fontes / SEO ROUTING_REVISION --> AGENT_2 : Desvio de Safe Zone / Sangria / Gutter ROUTING_REVISION --> AGENT_3 : Excesso de Palavras (>45) / Copy ROUTING_REVISION --> AGENT_4 : Contraste WCAG / Paleta / Arte AGENT_1 --> PREFLIGHT_CHECK : Revalidação AGENT_2 --> PREFLIGHT_CHECK : Revalidação AGENT_3 --> PREFLIGHT_CHECK : Revalidação AGENT_4 --> PREFLIGHT_CHECK : Revalidação PACKAGING --> COMPLETED : Manifesto e PDFs Gravados ``` --- ## 4. Diretrizes para Desenvolvimento Modular dos Agentes 1. **Desacoplamento:** Cada agente deve operar como um módulo independente que herda de uma interface base comum (`AgentBase`), expondo métodos padronizados: `execute(context) -> Result` e `revise(context, deviation_report) -> Result`. 2. **Imutabilidade de Entrada:** Agentes não devem alterar artefatos de etapas anteriores; apenas gerar ou atualizar seus respectivos entregáveis versionados. 3. **Determinismo nas Validações:** Agente 5 e os micro-gates nunca devem depender de critérios subjetivos; usam linters matemáticos para contraste relativo WCAG, contagem de palavras com regex e geometria milimétrica. 4. **Autonomia e Transparência no Dimensionamento de Páginas:** O Agente 2 e o Orquestrador têm autonomia técnica para arbitrar a extensão de páginas do guia/MVP (adotando **24 páginas como padrão ideal de referência**, sem rigidez arbitrária), sendo mandatório informar explicitamente a decisão e a justificativa ao usuário. --- ## 5. Protocolo Transversal de Encerramento e Aprendizado Contínuo O encerramento de qualquer sessão (seja pesquisa, briefing, copywriting, planejamento visual, diagramação, pré-voo ou revisão) é um procedimento transversal e obrigatório gerido pelo **Agente Orquestrador Mestre**, composto por 6 etapas estritas: 1. **Etapa 1 — Análise da Sessão:** Mapeamento do objetivo, atividades, entregáveis, decisões, instruções, preferências, correções, sucessos, erros e pendências. 2. **Etapa 2 — Extração e Classificação:** Classificação dos aprendizados nas 8 categorias oficiais com níveis de evidência (`CONFIRMADO`, `HIPOTESE`, `OBSERVACAO_PONTUAL`), impedindo que impressões isoladas se tornem regras permanentes. 3. **Etapa 3 — Atualização Documental Seletiva:** Gravação atômica nos documentos estratégicos (`REGRAS_GERAIS.md`, `PREFERENCIAS.md`, `PLAYBOOK_MESTRE.md`, `ERROS_E_SOLUCOES.md`) com verificação anti-duplicação e rastreabilidade de origem. 4. **Etapa 4 — Melhoria Contínua:** Registro de oportunidades em `MELHORIAS_PIPELINE.md`, mantendo separação estrita entre melhorias propostas (com justificativa e benefício) e melhorias aprovadas. 5. **Etapa 5 — Preparação da Próxima Sessão:** Atualização de `STATUS_PROJETO.md` com status consolidado, pendências e lista cirúrgica de documentos a consultar para a próxima tarefa. 6. **Etapa 6 — Relatório de Encerramento:** Apresentação do sumário executivo em 6 blocos obrigatórios. --- ## 6. Consulta Inteligente de Documentação (Otimização de Tokens) Antes de iniciar qualquer atividade: - Consultar `STATUS_PROJETO.md` para resgatar a continuidade operacional. - Carregar seletivamente apenas as seções e documentos estritamente necessários para a tarefa corrente (via `load_smart_context`). - Evitar o carregamento de históricos de chat longos ou playbooks não relacionados à especialidade ativa. --- ## 7. Governança do Painel Visual Central & Entrega Incremental (Zero-Token-Waste) Para atender ao perfil cognitivo visual do usuário e eliminar desperdício de tokens ou esquecimento de entregas entre sessões: 1. **Proibição de Pranchas Isoladas/Efêmeras:** Nenhuma prancha, protótipo HTML/SVG, ilustração ou PDF 300 DPI deve ser entregue de forma avulsa apenas no chat ou em diretórios temporários sem vínculo com o painel central (`docs/painel_visual/index.html`). 2. **Registro Incremental Desacoplado:** A cada nova prancha ou atualização visual produzida, o agente deve gravar/atualizar apenas um descritor leve `.json` em `docs/painel_visual/pranchas/` (referenciando miniatura, HTML imprimível e/ou PDF final) — **jamais reescrever o `index.html` inteiro**. 3. **Sincronização Determinística Automática:** Executar `python orchestrator.py --sync-hub` (ou acionar `SessionClosureProtocol.execute()`, que invoca `sync_visual_hub()` automaticamente) para regenerar `docs/painel_visual/pranchas_registry.js` com custo zero de tokens de IA e funcionamento 100% offline via `file:///`. --- ## 8. Fronteira Estrita de Projeto & Blindagem Anti-Contaminação (Zero Contaminação Externa) Para assegurar o desacoplamento arquitetural e a soberania do isual-guide-pipeline: 1. **Isolamento de Leitura e Escrita:** Nenhum agente ou rotina automatizada deve ler diretórios irmãos fora do workspace ativo ( isual-guide-pipeline/) ou consultar repositórios externos do usuário. 2. **Zero Herança Oculta:** Nenhuma regra clínica, token visual, gabarito ou lógica de negócio deve ser inferida ou importada de outros projetos; toda especificação deve ser autocontida neste repositório. 3. **Higienização de Saídas:** Nenhuma menção, link ou analogia a outros projetos deve ser inserida em interfaces web, manifests, pranchas, PDFs ou documentos do projeto.