Plugin para GitHub Copilot

O plugin Archgate para GitHub Copilot oferece aos agentes de IA que trabalham no GitHub Copilot guardrails integrados. Os agentes leem seus ADRs antes de escrever código, validam depois e capturam novos padrões para a equipe — o mesmo fluxo disponível no plugin para Claude Code.

Ambas as distribuições do Copilot são suportadas: o Copilot CLI (copilot no seu PATH) e o aplicativo desktop do Copilot. Elas compartilham o mesmo diretório de configuração (~/.copilot/ por padrão), então uma única instalação cobre as duas.

Como funciona

O Copilot suporta marketplaces de plugins baseados em repositórios git. O plugin Archgate é servido a partir de plugins.archgate.dev/archgate/vscode.git — o mesmo marketplace usado pela extensão do VS Code, no formato de manifesto .github/plugin/ que o Copilot reconhece nativamente.

A instalação é declarativa: o CLI escreve a declaração do marketplace e do plugin em ~/.copilot/settings.json (extraKnownMarketplaces + enabledPlugins). O Copilot lê esse arquivo na inicialização e instala automaticamente qualquer plugin declarado. Quando o CLI copilot está no seu PATH, o CLI também executa copilot plugin install para que o plugin fique disponível imediatamente, sem reiniciar.

Instalação

Acesso beta necessário

O plugin para GitHub Copilot está atualmente em beta. Execute archgate login para se cadastrar e autenticar antes de seguir os passos abaixo.

1. Faça login com o GitHub

Autentique-se com sua conta do GitHub para obter um token do plugin:

archgate login

Isso inicia um GitHub Device Flow. O CLI exibe um código único e uma URL — abra a URL no seu navegador, insira o código e autorize. Ao concluir, as credenciais são armazenadas de forma segura no gerenciador de credenciais do sistema operacional via git credential approve.

2. Inicialize seu projeto com o plugin

Execute archgate init com a flag --editor copilot:

archgate init --editor copilot

Se você estiver logado e o Copilot estiver instalado (CLI ou aplicativo desktop), o plugin é instalado automaticamente:

• Copilot CLI no PATH: o plugin é instalado imediatamente via copilot plugin install.
• Apenas o aplicativo desktop: o plugin é declarado em ~/.copilot/settings.json; reinicie o aplicativo Copilot e ele instala automaticamente ao iniciar.

Para solicitar explicitamente a instalação do plugin:

archgate init --editor copilot --install-plugin

Para instalar ou reinstalar o plugin em um projeto já inicializado:

archgate plugin install --editor copilot

Arquivos gerados

O comando cria o diretório .github/copilot/ para configuração no nível do projeto e atualiza o ~/.copilot/settings.json no nível do usuário com a declaração do marketplace e do plugin Archgate. Uma entrada apontando para uma URL de marketplace desatualizada é corrigida no próprio arquivo.

Instalação manual

Para instalar o plugin manualmente com o CLI copilot:

copilot plugin marketplace add "$(archgate plugin url --editor copilot)"
copilot plugin install archgate@archgate

As credenciais são fornecidas automaticamente pelo seu gerenciador de credenciais git (armazenadas durante archgate login).

O que o plugin oferece

O plugin adiciona agentes e skills baseadas em papéis ao Copilot. O agente orquestra o fluxo de guardrails, invocando skills conforme necessário.

Agentes

Agente	Propósito
archgate:developer	Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois
archgate:planner	Agente de planejamento somente leitura que projeta planos em conformidade com ADRs

O agente archgate:developer é definido como agente padrão via configurações do plugin. Ele orquestra as skills abaixo automaticamente como parte do seu fluxo de trabalho.

Skills

Skill	Propósito
archgate:reviewer	Valida mudanças de código contra todos os ADRs do projeto para conformidade estrutural
archgate:lessons-learned	Revisa a cobertura de regras e propõe novos ADRs quando padrões emergem
archgate:adr-author	Cria e edita ADRs seguindo as convenções do projeto
archgate:cli-reference	Fornece aos agentes a referência de comandos do CLI e o guia de autoria de regras
archgate:onboard	Configuração única: explora a base de código, entrevista o desenvolvedor, cria os ADRs iniciais

Configuração inicial com onboard

Após a instalação, execute a skill archgate:onboard no seu projeto uma vez. Essa skill:

1. Explora a estrutura da sua base de código (diretórios, arquivos principais, configuração de pacotes)
2. Entrevista você sobre as convenções, restrições e decisões arquiteturais da sua equipe
3. Cria um conjunto inicial de ADRs com base nas suas respostas
4. Configura o diretório .archgate/ com suas primeiras regras

A skill onboard foi projetada para ser executada uma vez por projeto. Após o onboarding, as outras skills cuidam do desenvolvimento no dia a dia.

Como funciona na prática

O plugin segue um fluxo de trabalho estruturado para cada tarefa de codificação:

1. Ler os ADRs aplicáveis

Quando o desenvolvedor passa uma tarefa de codificação, o agente executa archgate review-context para ler todos os ADRs que se aplicam aos arquivos sendo alterados. Isso fornece um resumo condensado com as seções Decision e Do’s and Don’ts de cada ADR relevante.

2. Escrever código seguindo as restrições dos ADRs

O agente escreve código em conformidade com as restrições dos ADRs. As seções Do’s and Don’ts servem como guardrails concretos.

3. Validar as mudanças

Após escrever o código, o agente executa archgate check para rodar as regras automatizadas contra as mudanças. Quaisquer violações são corrigidas antes de prosseguir.

4. Validação do reviewer

O agente invoca archgate:reviewer para validar a conformidade estrutural com os ADRs além do que as regras automatizadas capturam.

5. Capturar aprendizados

O agente invoca archgate:lessons-learned para revisar o trabalho e identificar padrões que valem a pena capturar como novos ADRs.

Dicas

• Execute onboard uma vez por projeto para gerar seus ADRs iniciais a partir da sua base de código real.
• Mantenha os arquivos de regras dos ADRs atualizados — o agente aplica o que as regras verificam.
• Usuários do aplicativo desktop: após a primeira instalação, reinicie o aplicativo Copilot para que ele carregue o plugin declarado.