a9a7a328e6
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD across contents and paths, upstream package/repo coordinates -> @golem15/msd-core and golem15com/msd-core. Deep links into upstream history, sibling upstream packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is. Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line, package/plugin identity, regenerated lockfile, install-tree fixtures, derived registries and benchmark baseline; migration checksum baseline re-locked (MSD keeps its own install state, so no install had applied the old sums); sort-order and regex-escaped expectations in tests adjusted.
6.2 KiB
Como conduzir o MSD Core a partir de uma issue do rastreador
Objetivo: Levar uma única issue bem delimitada do GitHub, Linear ou Jira por todo o pipeline do MSD — desde o workspace isolado até o PR mesclado — usando apenas comandos já existentes no MSD Core, sem scripts customizados ou integrações com rastreadores.
Pré-requisitos: MSD Core está instalado. A issue tem escopo delimitado, critérios de aceitação observáveis e nenhum bloqueador upstream.
Para os conceitos e a justificativa de design por trás desse padrão, consulte Orquestração orientada a issues explicada.
Passo 1: Mapear a issue para uma fase
Abra sua issue no rastreador e decida como ela se encaixa no ROADMAP.md:
- A issue corresponde a uma fase existente → anote o número da fase e avance para o Passo 2.
- A issue é um trabalho novo independente → adicione uma fase:
/msd-phase "Descrição correspondente ao título da issue"
- A issue é urgente e precisa ser inserida entre fases existentes → insira uma fase decimal:
/msd-phase --insert 3 "Fix: descrição da issue"
Copie a URL da issue do rastreador. Você irá colá-la no CONTEXT.md no Passo 3 para que a rastreabilidade sobreviva à compactação de contexto.
Passo 2: Criar um workspace isolado
Cada issue recebe seu próprio workspace — um git worktree com um diretório .planning/ independente. Trabalhos parciais, planos abandonados e commits exploratórios ficam fora do main.
/msd-workspace --new --name my-issue-slug --repos . --strategy worktree
Entre no diretório do workspace antes de continuar:
cd ~/msd-workspaces/my-issue-slug
Passo 3: Discutir a fase
Execute discuss-phase para definir as decisões de implementação antes que qualquer planejamento aconteça. Quando a sessão abrir, cole a URL da issue do rastreador na discussão para que ela seja capturada no CONTEXT.md.
/msd-discuss-phase N
O MSD pergunta sobre ambiguidades no escopo da issue — tratamento de erros, casos extremos, contratos de interface, escolhas tecnológicas. Suas respostas moldam o plano que se segue.
Se você já sabe todas as respostas e quer avançar rapidamente:
/msd-discuss-phase N --auto
Passo 4: Planejar a fase
/msd-plan-phase N
O MSD cria agentes de pesquisa, lê suas decisões do CONTEXT.md (incluindo a URL da issue) e produz arquivos PLAN.md atômicos. Um verificador de planos valida cada plano antes de salvá-lo.
Se você quiser revisão por pares de CLIs externas de IA antes da execução (recomendado para mudanças significativas):
/msd-review --phase N
/msd-plan-phase N --reviews
Ou execute o loop completo de planejar–revisar–convergir até que não haja mais preocupações de nível HIGH:
/msd-plan-review-convergence N
Passo 5: Executar a fase
Para execução interativa, fase por fase:
/msd-execute-phase N
Para uma execução sem supervisão por todas as fases restantes:
/msd-autonomous
Para um painel interativo onde você pode acompanhar o progresso e despachar trabalho entre fases:
/msd-manager
As três abordagens atualizam o STATE.md, fazem commit de cada tarefa atomicamente e executam o verificador pós-fase.
Passo 6: Verificar o trabalho
/msd-verify-work N
O MSD percorre os critérios de aceitação do objetivo da fase (que reflete sua issue do rastreador) um de cada vez. Se algo falhar, o MSD diagnostica a causa raiz e cria um plano de correção. Execute novamente e re-verifique até que todas as verificações passem.
Trate verification_failed como um bloqueador mesmo quando o código parece correto — a falha geralmente revela um critério de aceitação não atendido da issue original.
Passo 7: Revisar e publicar
Execute uma revisão de código antes de abrir o PR:
/msd-code-review N
/msd-code-review N --fix
Em seguida, crie o PR:
/msd-ship N
O MSD monta o corpo do PR a partir dos seus artefatos de planejamento: objetivo da fase, resumo das mudanças, requisitos atendidos, status de verificação e decisões-chave. Inclua Closes #NNN ou Fixes #NNN no corpo do PR (ou configure via /msd-config) para que a issue do rastreador seja fechada automaticamente quando o PR for mesclado.
Passo 8: Registrar trabalho de acompanhamento
Ao trabalhar na issue, você frequentemente descobrirá trabalhos relacionados. Registre-os sem perder o contexto:
/msd-capture "Acompanhamento: descrição do trabalho descoberto" # Adicionar como tarefa
/msd-capture --seed "Ideia que vale uma fase futura" # Preservar para o próximo milestone
/msd-capture --backlog "Não urgente, mas vale registrar" # Arquivar no backlog
O MSD não publica no seu rastreador automaticamente. Criar uma issue no rastreador a partir dos acompanhamentos registrados é uma etapa manual separada — isso mantém a revisão humana no ciclo.
Condicionais
| Situação | O que fazer |
|---|---|
| A issue é muito pequena (typo, mudança de config) | Pule workspace + discuss + plan; use /msd-quick em vez disso |
| A issue tem múltiplas subtarefas independentes | Use /msd-manager para paralelizar a execução entre planos |
| A issue está bloqueada em outra issue | Não inicie até que o bloqueador upstream seja resolvido; o MSD não possui poller automático de dependências |
| O escopo da issue se mostra maior do que o esperado durante a execução | Pare, execute /msd-phase --insert N para adicionar subfases, continue |
| Você quer pular a discussão interativa | Use a flag --auto com /msd-discuss-phase, ou defina workflow.skip_discuss: true para automação em todo o projeto |
| Múltiplas issues formam uma release coerente | Execute /msd-new-milestone para agrupá-las e /msd-autonomous para executar em sequência |