stack-architecture — instruções para agentes de IA

A arquitetura de stacks web da Hibex Solutions: as regras, o modelo de repositório e os padrões com que toda stack (produto) da Hibex nasce e é mantida. Não tem código de produto. Hoje é só documentação, em validação pelo mantenedor; depois receberá o modelo zerado (modelo/) e as ferramentas que o acompanham.

Antes de trabalhar, leia o README.md e o documento de docs/ do assunto.

Construindo o modelo zerado. A visão está validada, as ORGs e ADRs daqui estão aceitas, e os arquivos, os scripts, os hooks e as CIs de modelo/ estão prontos. O harness do E2E (modelo/e2e/hierarchy/) está provado no exemplo exemplos/e2e-atendimento/. O eng/new-stack.sh gera uma stack que passa no portão 0; agora vem a stack piloto (docs/20-…). Ajustes pedidos pelo mantenedor são feitos editando os próprios documentos.

• Git e GitHub são exclusivos do mantenedor. Nunca execute Git de escrita (init, add, commit, push, tag, mv, restore, checkout, stash, worktree…) nem crie recursos no GitHub. Leitura (status, log, diff) é permitida. Ao fim de cada entrega, forneça as instruções de commit com mensagem sugerida;
• Nunca toque em infraestrutura real (Kamal, SSH, Keycloak, bancos, Grafana);
• Segredos jamais no repositório: só placeholders (<VALOR>);
• A documentação vive por conta própria. O leitor não conhece a stack-projetos. Ela é só histórico: aparece no doc 19 (o estudo) e numa menção de origem no README e no doc 01, e em nenhum outro lugar — nem como origem de regra, nem como exemplo, nem como "ADR-NNNN de lá";
• Os exemplos usam o produto fictício de 03, o atendimento (enterprise-stack-atendimento: atendimento-gestao, atendimento-cliente, atendimento-site), nunca nomes, números ou domínios de uma stack real;
• No doc 19, os fatos vêm da fonte. Números, ADRs e arquivos da stack-projetos citados lá são conferidos no repositório dela antes de escrever;
• Não edite outros repositórios (stack-projetos, design system, toolbox) a partir daqui: este repositório os lê e referencia.

• Documentação e respostas ao mantenedor em português brasileiro;
• identificadores, nomes de arquivo de ferramenta e código em inglês;
• termos técnicos consagrados sem tradução (commit, deploy, container, realm).

• Cada documento grande abre com um rabisco que resume o assunto, desenhado por código em eng/sketches/boards/ (um arquivo por documento; node eng/sketches/build.mjs gera docs/imagens/desenhos/). Nunca edite o SVG à mão nem volte a Mermaid neste repositório. O texto ao redor diz o mesmo que o desenho; confira cada quadro renderizado nos dois temas antes de entregar;
• Tabelas para comparar; listas numeradas para passos; prosa curta;
• Lacunas do modelo no formato {{LACUNA:<id>}}, com id estável;
• Um documento por assunto, numerado em docs/, ligado no índice do README.md.

• Duas famílias, em docs/decisoes/ (ORG-0001): ORG em organizacao/ORG-NNNN-slug.md, para o que vale para toda stack; ADR em ADR-NNNN-slug.md, para o que vale só para este repositório. Cada uma a partir do seu template.md, com uma linha no índice docs/decisoes/README.md;
• Toda ORG ou ADR escrita pelo agente nasce proposta; só o mantenedor aceita;
• A pasta organizacao/ é copiada para as stacks: uma ORG nunca tem lacuna, nunca cita a stack-projetos e liga para os documentos daqui pelo endereço do site (https://architecture.enterprise.hibex.net/…), não por caminho relativo;
• Mudou uma ORG? O resumo dela em docs/07-orgs-e-adrs.md muda junto.

• modelo/ é a raiz de uma stack recém-nascida (ADR-0002): o que estiver lá chega igual a toda stack nova. As ORGs não são copiadas para modelo/: o eng/new-stack.sh as traz de docs/decisoes/organizacao/, e escreve o arquivo ARQUITETURA;
• Toda lacuna é {{LACUNA:<id>}}, com id em minúsculas, dígitos, . e -. Cada id aparece uma vez, com a descrição, no catálogo de modelo/docs/guias/definir-a-stack.md; o mesmo id em vários arquivos recebe o mesmo valor;
• O marcador nunca aparece em prosa no modelo (o gaps.sh da stack o contaria): para falar dele, escreva LACUNA:<id> sem as chaves;
• O modelo segue as próprias regras: pt-BR, exemplos nunca de uma stack real, links para as ORGs por docs/decisoes/organizacao/… (como ficam na stack) e para esta documentação pelo endereço do site;
• Mudou o modelo? Os documentos que o descrevem (05, 06, 07, 08, 17) mudam junto;
• Os scripts e hooks do modelo têm testes (modelo/eng/tests/, modelo/.claude/hooks/test_*.py), e eng/gap-catalog.sh confere o catálogo. Rode os três antes de entregar; a CI (.github/workflows/ci.yml) roda os mesmos;
• O harness do E2E (modelo/e2e/hierarchy/) é provado por node exemplos/e2e-atendimento/prove.mjs (antes: npm ci e npx playwright install chromium em exemplos/e2e-atendimento/e2e/). Mudou o harness? A prova passa, e o doc 11 muda junto.

• site/gerar.mjs gera site/dist/ (não vai para o Git); node site/gerar.mjs --servir serve em http://localhost:8080. Veja site/README.md;
• O site é uma aplicação do design system da Hibex: antes de mexer em site/, leia vendor/hibex/agentes/AGENTS.md; antes de entregar, rode node vendor/hibex/verificar.mjs site/site.css site/dist/*.html site/dist/design-system/*.html e corrija todo erro. vendor/hibex/ nunca é editado à mão, e o eng/atualizar-design-system.sh é do mantenedor (faz git clone);
• Publicar (kamal setup, kamal deploy) é só do mantenedor; docker compose up --build local é ok.