Azure DevOps

A integração com Azure DevOps é opcional. Sem ela, o Makuco opera 100% local-only: as PBIs vivem no disco com id local (pbi-NNN + slug) e nada no fluxo deixa de funcionar.

Com ela, o makuco-analisar cria os work items da Feature e das PBIs, e o makuco-desenvolver lê o item e sincroniza o status de volta.

Local-only vs. modo ado

Fluxo assistido (makuco init)

Ao rodar makuco init, responda "sim" para "Usa Azure DevOps?" e informe:

1. Projeto do Azure DevOps.
2. Personal Access Token (PAT) — perguntado apenas se o VSCode estiver entre as ferramentas selecionadas (o Claude não precisa de PAT).

O init grava:

• .makuco/integrations/azure-devops.yml com org/project preenchidos. Nomes de tipo de work item, estados e custom fields ficam comentados — são descobertos em runtime, ou você pode mapeá-los manualmente depois.
• o server azure-devops no .mcp.json (Claude, autenticação interativa) e/ou no .vscode/mcp.json (VSCode, --authentication pat + envFile).
• (somente VSCode) PERSONAL_ACCESS_TOKEN=<base64> no .env, garantindo que .env está no .gitignore.

Responder "não" não cria nenhum arquivo relacionado ao Azure DevOps.

Configuração alternativa: pela própria skill

Se você pulou a pergunta no init, o makuco-analisar / makuco-desenvolver oferece um setup curto na primeira vez que precisar do tracker:

1. Organização (obrigatório) — o nome ou a URL completa; a skill deriva o nome.
2. Projeto (obrigatório).
3. Vocabulário de tipos/estados (opcional — recomendado pular) — é descoberto automaticamente no primeiro uso e cacheado no config.
4. Area / iteration path (opcional) — se os itens novos devem cair numa área e sprint específicas.

Autenticação nunca é capturada nesse Q&A — ela é por ferramenta, veja abaixo.

O arquivo de configuração

.makuco/integrations/azure-devops.yml:

org: minhaorg
project: MeuProjeto
 
# work_item_types:
#   feature: Feature
#   pbi: Product Backlog Item
#   task: Task
#   bug: Bug
 
# states:
#   new: New
#   active: Active
#   resolved: Resolved
#   closed: Closed
 
# custom_fields:
#   Custom.MeuCampo: valor
 
# area_path: 'MeuProjeto\Time'
# iteration_path: 'MeuProjeto\Time\Sprint X'

• org/project presentes, o resto comentado → o caso normal. Tipos e estados são resolvidos por descoberta em runtime.
• Um mapa presente → ele vence a descoberta para as chaves que define; a descoberta continua valendo para as que ele não mapeia.
• area_path / iteration_path presentes → todo item criado é colocado nessa área e iteração. Ausentes, o Azure DevOps usa o default do projeto/time.

Nenhum nome é chumbado

Cada projeto Azure DevOps nomeia tipos, estados e custom fields de forma diferente. A skill nunca assume um vocabulário fixo — nada de literal "PBI", "Bug" ou "Active" embutido. A única suposição fixa é a forma da hierarquia: Feature → PBI → Task. Níveis extras que um projeto tenha (um Epic acima de Feature, por exemplo) são ignorados, não modelados.

Isso resolve tanto templates de fábrica ("Product Backlog Item") quanto processos customizados — Feature → Deliverable → Development, onde pbi = "Deliverable" e task = "Development" — com zero mudança de código.

A descoberta é cacheada: assim que os nomes canônicos são resolvidos, eles são escritos de volta no azure-devops.yml. A descoberta acontece uma vez por projeto, não a cada sessão.

Autenticação por ferramenta

• Claude Code — autenticação interativa. A primeira chamada de uma tool do Azure DevOps abre o login pelo navegador (MSAL). Não precisa de AZ CLI nem de PAT.
• VSCode + Copilot / ambientes headless / CI — autenticação via PAT, enviado como PERSONAL_ACCESS_TOKEN (base64 de email:pat) via .env.

Configuração manual do PAT (para CI/headless, ou sem passar pelo init)

1. Crie um PAT no Azure DevOps (User Settings → Personal Access Tokens) com o escopo mínimo recomendado: Work Items (Read & Write).

2. Gere o base64 de email:pat (qualquer e-mail não vazio serve — só o PAT importa):

   • Linux/macOS: echo -n "seu-email@exemplo.com:SEU_PAT" | base64
   • Windows (PowerShell): [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("seu-email@exemplo.com:SEU_PAT"))

   ⚠️ Garanta que o comando não quebra linha no resultado — um token com quebra de linha corrompe a autenticação.

3. Adicione ao .env do projeto:

   PERSONAL_ACCESS_TOKEN=<base64 gerado acima>

4. No .vscode/mcp.json, o server azure-devops deve apontar envFile: "${workspaceFolder}/.env" e usar --authentication pat.

Os dois gates de confirmação

Ambos são obrigatórios e inegociáveis:

• Confirmar antes de criar — nenhum work item é criado até você aprovar. As criações são enfileiradas durante o loop de PBIs do makuco-analisar e apresentadas em uma única lista numerada, com uma confirmação. Nada é escrito antes disso.
• Confirmar antes de fechar/finalizar — nenhuma transição para estado terminal é aplicada sem sua aprovação explícita. Fechar um card é ação de alta visibilidade. Se você recusar, o estado no tracker fica intocado e a recusa é registrada no resumo final.

Transições não-terminais (para "em andamento") e atualizações só de conteúdo passam sem gate.

Sync é unidirecional

O makuco-desenvolver empurra o resultado local para o work item: local → tracker, nunca o contrário. Ele nunca lê o estado do tracker de volta para sobrescrever o sessao-dev.md, o task.md ou o .makuco/STATE.md.

Um sync que falha (auth, rede, item obsoleto) é reportado claramente e nunca bloqueia o fechamento local da sessão.

O makuco-code-review não fala com o tracker

A skill de review nunca lê nem escreve no Azure DevOps. O veredito vive no status.yml (campo pbis.{slug}.review), e sincronizar isso para fora é trabalho do makuco-desenvolver.

PBIs que você recusou não são reportadas como sincronizadas

Uma PBI que você pulou ou recusou no gate de criação fica sem id de tracker. A skill nunca inventa um id e nunca a marca como sincronizada.