golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
12ee75a509cbfd8fe2ae2871056fa81777d7dcf5
msd-core/docs/pt-BR/reference/planning-artifacts.md
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

15 KiB
Raw Blame History

Referência de artefatos de planejamento

O diretório .planning/ é a memória compartilhada do MSD Core para um projeto. Todos os fluxos de trabalho leem, gravam e deixam um rastro auditável de decisões. Esta página mapeia cada arquivo, sua finalidade e qual comando o produz ou consome. Consulte o índice de documentação.

Estrutura de diretórios

.planning/
├── PROJECT.md                          # Identidade do projeto e valor central
├── ROADMAP.md                          # Listagem de marcos e fases com objetivos
├── REQUIREMENTS.md                     # Critérios de aceitação numerados
├── STATE.md                            # Rastreador de posição em andamento
├── config.json                         # Configuração de fluxo de trabalho e modelo
├── MILESTONES.md                       # Arquivo de marcos (opcional)
├── BACKLOG.md                          # Trabalho adiado e futuro (opcional)
├── LEARNINGS.md                        # Aprendizados acumulados entre fases (opcional)
├── DECISIONS-INDEX.md                  # Resumo contínuo de decisões anteriores (opcional)
├── METHODOLOGY.md                      # Frameworks interpretativos reutilizáveis (opcional)
├── HANDOFF.json                        # Estado de pausa legível por máquina (transitório)
├── codebase/                           # Mapas do código-base (opcional)
│   ├── architecture.md
│   ├── stack.md
│   └── ...
├── onboarding/                         # Resumo de onboarding brownfield (opcional)
│   └── SUMMARY.md
├── intel/                              # Índice de símbolos consultável (opcional, intel.enabled)
│   └── API-SURFACE.md
└── phases/
    └── <NN>-<slug>/                    # Um diretório por fase
        ├── <NN>-CONTEXT.md             # Decisões de implementação (discuss-phase)
        ├── <NN>-DISCUSSION-LOG.md      # Auditoria legível da discussão (discuss-phase)
        ├── <NN>-RESEARCH.md            # Resultados de pesquisa técnica (plan-phase)
        ├── <NN>-VALIDATION.md          # Estratégia de cobertura de testes Nyquist (plan-phase)
        ├── <NN>-PATTERNS.md            # Mapa de análogos do código-base (plan-phase, opcional)
        ├── <NN>-<PP>-PLAN.md           # Plano executável (plan-phase, um por plano)
        ├── <NN>-<PP>-SUMMARY.md        # Registro de execução (execute-phase, um por plano)
        ├── <NN>-VERIFICATION.md        # Relatório de verificação dos objetivos da fase (verify-phase)
        ├── <NN>-UAT.md                 # Estado persistente de sessão UAT (execute-phase)
        └── .continue-here.md           # Instruções de retomada após pausa (pause-work)

Artefatos no nível raiz

PROJECT.md
Finalidade Identidade canônica do projeto: o que é, para quem é, valor central, requisitos, restrições e decisões-chave. Atualizado ao longo do ciclo de vida do projeto conforme o produto evolui.
Produzido por /msd-new-project (criação inicial, incluindo handoff do /msd-onboard); atualizado por /msd-complete-milestone à medida que as decisões são validadas.
Consumido por Todos os fluxos de trabalho de planejamento; msd-phase-researcher, msd-planner (contexto); discuss-phase (decisões anteriores); msd-plan-checker (restrições do projeto).

ROADMAP.md
Finalidade Listagem de marcos e fases com objetivos, IDs de requisitos, critérios de sucesso e referências canônicas por fase. A fonte única de verdade sobre o que o projeto está construindo e em que ordem.
Produzido por /msd-new-project (criação inicial, incluindo handoff do /msd-onboard); atualizado por /msd-phase --insert e /msd-complete-milestone.
Consumido por /msd-discuss-phase, /msd-plan-phase, /msd-execute-phase; todos os comandos de orquestração que precisam de informações de fase; msd-planner, msd-plan-checker, msd-phase-researcher.

REQUIREMENTS.md
Finalidade Critérios de aceitação numerados e verificáveis para o projeto. Cada requisito possui um ID (ex.: AUTH-01) que mapeia para as fases do roadmap. Marca os requisitos como concluídos conforme as fases são executadas.
Produzido por /msd-new-project (criação inicial, incluindo handoff do /msd-onboard); requisitos marcados como concluídos por execute-phase.
Consumido por msd-planner (os planos devem contemplar todos os IDs de requisitos da fase); msd-plan-checker Dimensão 1 (cobertura de requisitos); discuss-phase (requisitos anteriores).

STATE.md
Finalidade Rastreador de posição em andamento — fase e plano atuais, métricas de progresso, decisões acumuladas, notas de continuidade de sessão. Lido no início de toda execução de fluxo de trabalho. Atualizado após cada ação significativa.
Produzido por /msd-new-project (criação inicial, incluindo handoff do /msd-onboard); atualizado continuamente por todos os fluxos de fase, /msd-pause-work, /msd-resume-work.
Consumido por Todos os fluxos de orquestração; /msd-progress; execução de tarefas avulsas via /msd-quick; msd-planner e msd-phase-researcher (decisões do projeto).

Consulte o esquema de STATE.md para a referência completa de campos.

config.json
Finalidade Configuração do fluxo de trabalho: perfis de modelo, alternâncias de pesquisa e verificador de plano, estratégia de ramificação git, validação Nyquist, configurações de paralelização e substituições de modelo por agente.
Produzido por /msd-new-project (criação inicial); /msd-settings (edição interativa).
Consumido por Todos os fluxos de trabalho e subagentes — lido no momento de inicialização via msd-tools query config-get.

Consulte CONFIGURATION para o esquema completo.

onboarding/SUMMARY.md (opcional)
Finalidade Índice de onboarding brownfield que registra status dos artefatos, se o mapeamento do código-base está completo e o próximo comando MSD recomendado após a configuração inicial.
Produzido por /msd-onboard depois que PROJECT.md, REQUIREMENTS.md, ROADMAP.md e STATE.md existem.
Consumido por Humanos revisando a configuração inicial; futuras execuções de /msd-onboard ao confirmar o estado de onboarding existente.

MILESTONES.md (opcional)
Finalidade Registro histórico de marcos concluídos. Preenchido à medida que cada marco é encerrado; fornece um instantâneo de arquivo do que foi entregue e quando.
Produzido por /msd-complete-milestone.
Consumido por /msd-audit-milestone; revisão humana.

DECISIONS-INDEX.md (opcional)
Finalidade Resumo contínuo limitado de decisões capturadas em arquivos CONTEXT.md de fases anteriores. Quando presente, o discuss-phase lê este único arquivo em vez de ler até três arquivos CONTEXT.md anteriores individualmente, economizando orçamento de contexto.
Produzido por Gerado quando o número de fases anteriores ultrapassa o limite de leitura contínua.
Consumido por discuss-phase (etapa load_prior_context).

HANDOFF.json (transitório)
Finalidade Estado de pausa legível por máquina gravado quando o trabalho é interrompido. Contém o ponto de retomada, contexto em andamento e instruções de continuação. Consumido exatamente uma vez — na retomada.
Produzido por /msd-pause-work.
Consumido por /msd-resume-work.

Artefatos por fase

Todos os arquivos por fase ficam em .planning/phases/<NN>-<slug>/, onde NN é o número da fase com zero à esquerda e slug é o nome da fase com hifens.

<NN>-CONTEXT.md
Finalidade Decisões de implementação capturadas antes do início do planejamento. Contém o limite da fase (<domain>), decisões bloqueadas com identificadores D-NN (<decisions>), referências canônicas de documentos (<canonical_refs>), insights de código existente (<code_context>), inspirações específicas (<specifics>) e ideias adiadas (<deferred>).
Produzido por /msd-discuss-phase (discussão interativa ou caminhos expressos PRD/ADR).
Consumido por msd-phase-researcher (o que investigar); msd-planner (decisões bloqueadas); msd-plan-checker Dimensão 7 (conformidade de contexto).

Consulte o esquema de CONTEXT.md para a referência completa de campos.

<NN>-DISCUSSION-LOG.md
Finalidade Rastro de auditoria legível da sessão de discuss-phase: áreas discutidas, opções apresentadas, seleções feitas, ideias adiadas e itens deixados ao critério do Claude. Não é consumido por fluxos de trabalho automatizados.
Produzido por /msd-discuss-phase (etapa git_commit).
Consumido por Revisão humana; retrospectivas.

<NN>-RESEARCH.md
Finalidade Resultados de pesquisa técnica produzidos antes do planejamento. Responde à pergunta "O que preciso saber para planejar bem esta fase?" — abrange análise de domínio, padrões, riscos, um Mapa de Responsabilidade Arquitetural e uma seção de Arquitetura de Validação (usada pelo gate Nyquist).
Produzido por /msd-plan-phase via agente msd-phase-researcher.
Consumido por msd-planner (entradas de planejamento); msd-plan-checker Dimensão 7c (conformidade de camada), Dimensão 8 (Nyquist), Dimensão 11 (resolução de pesquisa); msd-pattern-mapper (fonte de lista de arquivos).

<NN>-VALIDATION.md
Finalidade Estratégia de validação inspirada no Nyquist, derivada da seção ## Validation Architecture do RESEARCH.md. Especifica requisitos de cobertura de testes automatizados que os planos devem respeitar.
Produzido por /msd-plan-phase (Etapa 5.5, quando workflow.nyquist_validation está habilitado e o RESEARCH.md contém uma seção de Arquitetura de Validação).
Consumido por msd-plan-checker Dimensão 8 (gate Check 8e — deve existir antes de os checks Nyquist prosseguirem); msd-verifier.

<NN>-PATTERNS.md
Finalidade Mapa de análogos do código-base produzido pelo msd-pattern-mapper. Para cada arquivo a ser criado ou modificado nesta fase, identifica o análogo existente mais próximo, classifica o papel e o fluxo de dados do arquivo e extrai trechos concretos de código. Orienta o planejador em direção a padrões consistentes.
Produzido por /msd-plan-phase via agente msd-pattern-mapper (opcional; ignorado se workflow.pattern_mapper: false).
Consumido por msd-planner (orientação de padrões); msd-plan-checker Dimensão 12 (conformidade de padrões).

<NN>-<PP>-PLAN.md
Finalidade Plano executável para uma única unidade de trabalho dentro da fase. Contém frontmatter YAML (onda, dependências, arquivos, requisitos, must_haves), um objetivo, referências de contexto, tarefas estruturadas em XML com campos <read_first>, <action>, <verify> e <acceptance_criteria>, e critérios de verificação.
Produzido por /msd-plan-phase via agente msd-planner. Um arquivo por plano — ex.: 03-02-PLAN.md é Fase 3, Plano 2.
Consumido por /msd-execute-phase (agente executor lê o plano e executa as tarefas); msd-plan-checker (revisão de qualidade pré-execução); msd-verifier (lê must_haves para verificação pós-execução).

Consulte o esquema de PLAN.md para a referência completa de campos.

<NN>-<PP>-SUMMARY.md
Finalidade Registro de execução gravado após a conclusão de um plano. Documenta o que foi construído, desvios em relação ao plano, uma autoverificação em relação aos critérios de aceitação e o grafo de dependências da fase.
Produzido por Agente executor de execute-phase (gravado ao final da execução de cada plano).
Consumido por /msd-progress (status da fase); msd-planner (quando um plano subsequente tem dependência genuína da saída de um plano anterior); milestone-summary.

<NN>-VERIFICATION.md
Finalidade Relatório de verificação dos objetivos da fase. Verifica must_haves.truths, must_haves.artifacts e must_haves.key_links de todos os planos em relação ao código-base real após a execução. Registra `status: passed
Produzido por /msd-verify-work (ou a etapa de verificação dentro de /msd-execute-phase).
Consumido por Gate de fase encerrada do plan-phase (um VERIFICATION.md com status: passed marca a fase como Complete e bloqueia replanejamento sem --force); /msd-progress; revisão humana.

<NN>-UAT.md
Finalidade Rastreamento persistente de sessão UAT. Registra cada caso de teste, comportamento observável esperado, resultado e resposta do desenvolvedor ao longo de uma sessão UAT ativa. Carrega frontmatter YAML (status, phase, source, timestamps).
Produzido por /msd-audit-uat (sessão UAT interativa).
Consumido por /msd-audit-uat (retomada de uma sessão UAT anterior).

.continue-here.md
Finalidade Instruções de retomada legíveis gravadas quando o trabalho em uma fase é pausado. Contém contexto para agentes retomarem: antipadrões críticos, problemas bloqueantes, leitura obrigatória e o comando exato para retomar.
Produzido por /msd-pause-work.
Consumido por Qualquer fluxo de trabalho que inicia em uma fase — tanto discuss-phase quanto plan-phase verificam a existência deste arquivo na entrada e exigem que o agente demonstre compreensão de quaisquer antipadrões blocking antes de prosseguir.

Convenções de nomenclatura

Segmento Formato Exemplo
Diretório de fase <NN>-<slug> 03-post-feed
Arquivo de nível de fase <NN>-<ARTIFACT>.md 03-CONTEXT.md
Arquivo de nível de plano <NN>-<PP>-<ARTIFACT>.md 03-02-PLAN.md
NN Número da fase com zero à esquerda 03 para Fase 3
PP Número do plano com zero à esquerda dentro da fase 02 para Plano 2

Quando project_code está definido no config.json, os diretórios de fase usam o código do projeto como prefixo: CK-03-post-feed para o código de projeto CK, Fase 3.

Relacionados

Reference in New Issue View Git Blame Copy Permalink