Skill Onboard

A skill onboard inicializa um projeto na governança do Archgate. É a primeira coisa que você executa ao configurar o Archgate em um repositório: ela verifica a CLI, inicializa o esqueleto de governança, explora o codebase, faz uma entrevista com você, propõe um backlog de Architecture Decision Records (ADRs), escreve todos os ADRs aprovados e entrega um resumo de governança.

Execute uma vez

Execute o onboard uma única vez por projeto na configuração inicial. Execute-o novamente mais tarde para estender a governança a novos domínios ou auditar ADRs existentes — a skill detecta ADRs existentes e pergunta qual você deseja.

O que ela faz

O onboard percorre uma sequência fixa de fases e não pula etapas. Ela determina o que pode explorando o codebase e só pergunta a você o que a exploração não consegue responder.

1. Verificação prévia da CLI. Ela detecta sua plataforma (macOS, Linux ou Windows) e verifica se a CLI archgate está instalada, instalando-a a partir da fonte oficial se necessário.

2. Inicializa o esqueleto. Se .archgate/adrs/ não existir, ela executa archgate init. Se a governança já existir, ela conta os ADRs reais e pergunta se você quer estender ou auditar. Ela sempre remove o ADR de exemplo de placeholder para que o slot GEN-001 continue livre.

3. Avalia a maturidade do repositório. Usando arquivos de manifesto, a contagem de arquivos de código-fonte e a atividade recente do git, ela classifica o repositório como Maduro, Estágio inicial ou Greenfield. O nível governa qual exploração roda e quais perguntas são feitas.

4. Descobre (apenas Maduro e Estágio inicial). Ela lança três sub-agentes de exploração em paralelo — Stack e Config, Estrutura e Padrões, e Docs e Intenção — cada um em sua própria janela de contexto, para que a leitura profunda de arquivos nunca esgote o contexto do pai. Projetos Greenfield vão direto para a entrevista.

5. Entrevista. Ela faz no máximo três perguntas direcionadas — normalmente quais domínios de governança são de maior prioridade e se a exploração deixou algo passar. Se você fornecer uma URL, ela busca o conteúdo e o incorpora ao contexto dos ADRs.

6. Prioriza e pré-atribui IDs. A partir das evidências, ela monta um backlog de 6 a 8 ADRs, cada um com um ID pré-atribuído, nome de arquivo, domínio, uma justificativa de uma frase e se ele justifica regras automatizadas. A pré-atribuição de IDs é o que torna a autoria paralela segura — dois sub-agentes nunca podem colidir em um ID.

7. Aprova o backlog. Ela imprime o backlog completo como texto visível e então pede que você o aprove (via modo de plano onde disponível) com a aceitação automática de edições habilitada, para que as escritas paralelas não sejam interrompidas por prompts por arquivo.

8. Escreve em paralelo. Após a aprovação, ela cria um sub-agente por ADR em uma única mensagem. Cada um delega ao padrão do adr-author, escreve seu arquivo atribuído (e o companheiro .rules.ts quando as regras se justificam) e retorna seu ID e caminho.

9. Correção de referências cruzadas. Como os ADRs foram escritos em paralelo, ela lê cada novo arquivo e adiciona ou repara as referências cruzadas entre ADRs topicamente relacionados.

10. Relatório. Ela imprime um resumo de governança: ADRs criados, domínios cobertos, domínios ainda não cobertos, lacunas de governança em aberto e próximos passos.

Seleção do backlog de ADRs

A skill mapeia as evidências observadas para ADRs candidatos, incluindo apenas o que as evidências sustentam:

Gatilho	Domínio	Padrão de título
Sempre	general	Tech Stack and Runtime
Test runner detectado	general	Testing Standards
Gerenciador de pacotes detectado	general	Dependency Policy
Convenções claras de src/	architecture	Code Organization
Padrões de tratamento de erros	backend	Error Handling Pattern
Padrões REST/RPC/GraphQL	backend	API Design
Framework de frontend detectado	frontend	Component Patterns
ORM/driver de BD detectado	data	Data Access Layer
Workflows de CI encontrados	architecture	CI/CD Pipeline Standards

A primeira execução é limitada a 6 a 8 ADRs, favorecendo amplitude sobre profundidade para que os domínios mais críticos sejam cobertos primeiro.

Formato de saída

Após a autoria, o onboard imprime um resumo de governança em texto simples:

## Onboarding Complete

### ADRs Created
- <ID>  <title>  (<domain>)
...

### Governance Coverage
Domains covered: <list>
Domains not yet covered: <list>

### Open Governance Gaps
- <Patterns found but not documented, with the reason>

### Next Steps
- Run `archgate check` to verify automated rules pass
- Use the lessons-learned skill after future coding sessions to extend governance
- Use the adr-author skill to document decisions not covered above
- Re-run onboard at any time to extend governance for new domains

Em seguida, ela oferece adicionar uma curta seção de governança do Archgate ao arquivo de instruções de IA do seu projeto (CLAUDE.md, .cursorrules/.cursor/rules, .github/copilot-instructions.md ou agents.md), de modo que toda sessão futura de IA herde a consciência da governança.

Como se encaixa no fluxo

O onboard é o ponto de entrada — ele produz os ADRs que o restante do sistema aplica. Uma vez que o backlog inicial exista, o agente desenvolvedor lê esses ADRs antes de codificar, a skill reviewer valida as alterações em relação a eles e a skill lessons-learned os amplia ao longo do tempo. Toda escrita de ADR — no onboard e depois — passa pela skill adr-author.

skill adr-author O padrão que todo sub-agente do onboard segue ao escrever um ADR.

Nota

Para a sintaxe exata de archgate init, archgate adr list e archgate adr show, veja a referência autoritativa em cli.archgate.dev.