0xKoios/skills

Azure DevOps Boards: meus cartões

Ajuda uma pessoa a gerenciar seus próprios cartões no Azure Boards via MCP ou az. As convenções do time ficam na config; a mesma skill se adapta a diferentes times.

1. Antes de tudo

1. Leia a config — ~/.config/ado-boards/config.md (Windows: %USERPROFILE%\.config\ado-boards\config.md). Se não existir → execute a configuração principal (workflows/setup.md) primeiro; adivinhar org/project escreve no lugar errado. Valores marcados como not set yet são coletados na primeira vez que um fluxo precisar deles.
2. Escolha o backend apenas para esta execução:
   • MCP quando as ferramentas MCP do Azure DevOps estiverem disponíveis (ex.: wit_work_item): carregue mcp-tools.md (mais um arquivo de lacuna az/ apenas quando esse mapa documentar uma lacuna do MCP).
   • az caso contrário: carregue az/README.md mais o arquivo de seção correspondente a este fluxo. Também az/windows.md apenas quando uma escrita de descrição/CA em HTML retornar corrompida, ou a citação do PowerShell falhar. Confirme o login (az account show ou AZURE_DEVOPS_EXT_PAT); se nenhum dos dois, o usuário executa az login por conta própria.
   • Nenhum → aponte para a configuração.
3. Abra o fluxo correspondente (tabela abaixo) e siga-o. Os fluxos dizem o quê; o arquivo do backend diz como. As regras da §2 vinculam ambos os backends.

Feito quando a config estiver em mãos, um backend for escolhido e o arquivo do fluxo estiver aberto.

O usuário faz login por conta própria (Entra / az login). As credenciais ficam fora do chat.

2. Regras

Leituras não precisam de permissão. Cada escrita precisa de uma prévia e de um sim explícito — mesmo quando a ferramenta em si não pergunta. O board é compartilhado; escritas MCP frequentemente pulam um prompt, então a prévia é a barreira.

Regra	Critério
Tamanho da prévia	Uma alteração no próprio cartão do usuário → uma linha (#512: State Active -> Closed. OK?). Várias alterações, ou cartão de outra pessoa → tabela (ID, campo, antigo, novo). Mais de 10 → informe a quantidade e confirme novamente.
Leitura de volta	Após cada escrita: informe ID, o que mudou, URL https://dev.azure.com/<org>/<project>/_workitems/edit/<id>.
Pais	Quando a config disser Parent required: yes, crie apenas com um pai (órfãos desaparecem das visões do backlog).
Bugs	Quando a config disser que bugs vivem em outro lugar: ofereça uma Tarefa sob o bug existente (um segundo Bug divide o histórico).
Cartões externos	Prefixo de título na config (ex.: EXT): avise que comentários podem sincronizar com o relator antes da alteração de comentário ou campo; pule Impacto ao fechar.
Unidades	Campos de tempo são números simples; a unidade está na config. Converta quando o usuário falar outra unidade, mostre ambas, sempre nomeie a unidade (a interface do Boards diz "h" de qualquer forma).
Cartões permanecem	Feche ou mova; deixe o cartão no board. Remova um comentário apenas depois de mostrá-lo por completo e obter um sim — nenhum dos dois é desfeito.
Comentários próprios	Edite ou remova apenas os comentários do próprio usuário (ADO rejeita os demais).
Valores reais	Pergunte por estimativas, responsáveis, datas, impacto — ou deixe em branco. Números inventados parecem reais no board.
Citações seguras	Cite valores com segurança; títulos podem conter aspas.
Rodapé de escrita	Após uma escrita: o que você fez, o que você pulou, um próximo passo. Leituras simples: apenas responda.

3. Fluxos de trabalho

Quando	Abrir
Configurar a skill ado; config ausente; algo mudou	workflows/setup.md
O que está na minha lista; mostrar meus cartões; mover; registrar tempo; fechar	workflows/my-cards.md
Criar um cartão; dividir uma história em tarefas	workflows/create-card.md
Adicionar, listar, editar ou remover um comentário	workflows/comments.md
Descrição ou critérios de aceitação	workflows/write-description.md
Planejar minha sprint; no que devo trabalhar primeiro	workflows/plan-my-sprint.md

4. Referência ágil (verifique conforme a config)

Hierarquia: Epic > Feature > User Story > Task. Bugs ficam ao lado ou sob histórias conforme configuração do time.

Tipo	Estados
Feature / User Story	New, Active, Resolved, Closed, Removed
Bug	New, Active, Resolved, Closed
Task	New, Active, Closed, Removed

Pais: Task sob User Story (ou Bug), User Story sob Feature. Estados personalizados e campos obrigatórios ficam na config depois de coletados.