Files

Jakub Zych a9a7a328e6 refactor: hard-fork GSD -> MSD (Make Software Done)

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.

2026-10-06 01:47:40 +02:00

7.1 KiB

Raw Blame History

Como planejar uma fase

Objetivo: Transformar decisões de fase e pesquisa em um plano de tarefas atômico e verificável, pronto para execução.

Pré-requisitos: .planning/ROADMAP.md deve existir. Um {fase}-CONTEXT.md gerado pelo /msd-discuss-phase é fortemente recomendado, mas não obrigatório.

Execute o fluxo de planejamento padrão

/msd-plan-phase 2

Isso executa três estágios em sequência:

Pesquisa — Um subagente msd-phase-researcher investiga o domínio e escreve {fase}-RESEARCH.md.
Planejamento — Um subagente msd-planner lê o contexto, a pesquisa e os requisitos, e então escreve um ou mais arquivos {fase}-{N}-PLAN.md.
Verificação — Um subagente msd-plan-checker valida a qualidade do plano em oito dimensões e aciona um ciclo de revisão (até três iterações) até que os critérios de qualidade sejam aprovados.

Se nenhum número de fase for fornecido, o MSD Core seleciona a próxima fase não planejada do roadmap.

Pular ou forçar a pesquisa

Se o domínio for familiar e não houver necessidade de nova pesquisa:

/msd-plan-phase 3 --skip-research

Se o RESEARCH.md já existir, mas você quiser forçar uma atualização:

/msd-plan-phase 3 --research

Se você quiser executar apenas a pesquisa — escrever o RESEARCH.md e encerrar antes do planejamento:

/msd-plan-phase --research-phase 4

Se o RESEARCH.md já existir, será solicitado que você atualize, visualize ou pule. Para forçar a atualização sem o prompt:

/msd-plan-phase --research-phase 4 --research

Para imprimir o RESEARCH.md existente no stdout sem acionar o pesquisador:

/msd-plan-phase --research-phase 4 --view

Nota: --research-phase <N> é uma flag do /msd-plan-phase. Não existe um comando standalone de fase de pesquisa — o comando standalone foi removido em favor desta flag.

Planejar fatias verticais de funcionalidades em vez de camadas horizontais

Se você quiser tarefas organizadas como fatias finas de ponta a ponta (UI → API → BD por funcionalidade) em vez de por camada técnica:

/msd-plan-phase 1 --mvp

Na Fase 1 de um novo projeto sem resumos de fases anteriores, --mvp também produz SKELETON.md — um Walking Skeleton que cobre o scaffold do projeto, roteamento, uma leitura/escrita real no BD, uma interação real de UI e implantação de desenvolvimento.

É possível persistir o modo MVP para uma fase sem a flag, adicionando **Mode:** mvp à entrada daquela fase no ROADMAP.md.

Exigir um teste falho por tarefa que adiciona comportamento

Se você quiser a aplicação de TDD — cada tarefa que adiciona comportamento começa com um teste falho antes da implementação:

/msd-plan-phase 1 --tdd

Combinável com --mvp:

/msd-plan-phase 1 --mvp --tdd

Isso produz fatias verticais onde cada tarefa que adiciona comportamento segue o ciclo RED → GREEN → REFACTOR. O planejador aplica type: tdd às tarefas elegíveis (lógica de negócio, endpoints de API, transformações de dados) e usa o type: execute padrão para UI, configuração e código de integração.

O modo TDD também pode ser persistido em config:

node msd-tools.cjs config-set workflow.tdd_mode true

Replanejar usando feedback de revisão cruzada por IA

Se você executou /msd-review --phase N e um REVIEWS.md existe:

/msd-plan-phase 3 --reviews

O planejador lê o REVIEWS.md e revisa os planos para endereçar o feedback. Não pode ser combinado com --gaps.

Se você quiser um ciclo automatizado — replanejar e revisar até que não restem preocupações de nível HIGH:

/msd-plan-review-convergence 3

O ciclo de convergência executa ciclos de planejar → revisar → replanejar → revisar novamente (até três por padrão). Use --max-cycles N para substituir o limite máximo.

Fechar lacunas após uma verificação falha

Se o VERIFICATION.md existir com lacunas não resolvidas e você quiser replanejar apenas para essas lacunas:

/msd-plan-phase 3 --gaps

A pesquisa é ignorada; o planejador lê as lacunas de verificação diretamente.

Executar uma validação externa de bounce após o planejamento

Se workflow.plan_bounce_script estiver configurado e você quiser validação externa do plano concluído:

/msd-plan-phase 1 --bounce

Para pular o bounce mesmo que esteja habilitado em config:

/msd-plan-phase 1 --skip-bounce

Suprimir confirmações interativas

/msd-plan-phase --auto

Ignora todos os prompts. Útil em pipelines automatizados. A pesquisa é ignorada se research_enabled for false em config.

O que o plano produz

Uma execução bem-sucedida escreve:

Arquivo	Finalidade
`{fase}-RESEARCH.md`	Pesquisa de domínio, auditoria de legitimidade de pacotes, arquitetura de validação
`{fase}-VALIDATION.md`	Mapeamento de testes Nyquist — os casos de teste que o plano deve satisfazer (Dimensão 8)
`{fase}-{N}-PLAN.md`	Plano de tarefas executável com frontmatter, atribuições de wave e critérios de aceitação
`{fase}/SKELETON.md`	Walking Skeleton (modo MVP, apenas Fase 1 de novo projeto)

Cada PLAN.md contém tarefas com os campos obrigatórios <read_first> e <acceptance_criteria>. Cada entrada de <acceptance_criteria> é verificável como uma asserção de fonte, asserção de comportamento, comando de teste ou saída de CLI — nunca linguagem subjetiva.

Para a referência completa de campos, consulte o schema do PLAN.md.

Dimensões de qualidade do plano

O msd-plan-checker valida os planos em oito dimensões antes de permitir a execução:

Atomicidade das tarefas — cada tarefa abrange uma única preocupação
Correção das dependências — a ordenação de waves é consistente
Verificabilidade dos critérios de aceitação — nenhum critério subjetivo
Completude do <read_first> — o arquivo sendo modificado está sempre listado
Valores concretos de <action> — sem instruções vagas como "alinhar com"
must_haves derivados do objetivo da fase
Cobertura de IDs de requisitos — cada ID de requisito da fase aparece em pelo menos um plano
Mapeamento de testes Nyquist — os planos abordam a estratégia de validação no VALIDATION.md

O ciclo de revisão executa até três vezes. Se os critérios de qualidade não forem aprovados após três iterações, o verificador apresenta os problemas remanescentes para revisão manual.

Replanejamento de uma fase encerrada

Se uma fase possui VERIFICATION.md com status: passed, ela é considerada encerrada. Tentar replanejá-la resulta em erro. Se o encerramento foi incorreto, substitua com --force:

/msd-plan-phase 2 --force

Um aviso é emitido na transcrição e em quaisquer documentos de plano confirmados.

7.1 KiB Raw Blame History