3bb2f8f1c5
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
250 lines
14 KiB
Markdown
250 lines
14 KiB
Markdown
# Referência do esquema PLAN.md
|
||
|
||
Um `PLAN.md` por plano é a unidade executável de trabalho do GSD Core — um documento estruturado que instrui exatamente um agente executor sobre o que construir e como verificar se foi construído corretamente. Esta página documenta sua estrutura. Veja o [índice da documentação](../README.md).
|
||
|
||
---
|
||
|
||
## Visão geral
|
||
|
||
Os planos ficam dentro de diretórios de fase em:
|
||
|
||
```
|
||
.planning/phases/<NN>-<slug>/<NN>-<PP>-PLAN.md
|
||
```
|
||
|
||
Por exemplo: `.planning/phases/03-post-feed/03-02-PLAN.md` (Fase 3, Plano 2).
|
||
|
||
Os planos são produzidos pelo agente `gsd-planner` (disparado por `/gsd:plan-phase`) e consumidos por `execute-phase`. Uma fase normalmente contém entre um e quatro planos; os planos dentro de uma fase são atribuídos a ondas de execução para que trabalhos independentes sejam executados em paralelo.
|
||
|
||
---
|
||
|
||
## Frontmatter YAML
|
||
|
||
Todo PLAN.md começa com um bloco de frontmatter YAML entre delimitadores `---`.
|
||
|
||
### Exemplo comentado
|
||
|
||
```yaml
|
||
---
|
||
phase: 03-post-feed
|
||
plan: 02
|
||
type: execute
|
||
wave: 2
|
||
depends_on: ["03-01"]
|
||
files_modified:
|
||
- src/components/PostFeed.tsx
|
||
- src/components/PostCard.tsx
|
||
- src/app/feed/page.tsx
|
||
autonomous: true
|
||
requirements: ["FEED-01", "FEED-03"]
|
||
user_setup: []
|
||
|
||
must_haves:
|
||
truths:
|
||
- "User can scroll through posts from followed accounts"
|
||
- "Each post shows author avatar, name, timestamp, and content"
|
||
- "Empty state appears when no posts exist"
|
||
artifacts:
|
||
- path: "src/components/PostFeed.tsx"
|
||
provides: "Scrollable post list"
|
||
min_lines: 40
|
||
- path: "src/components/PostCard.tsx"
|
||
provides: "Individual post card"
|
||
exports: ["PostCard"]
|
||
key_links:
|
||
- from: "src/components/PostFeed.tsx"
|
||
to: "/api/feed"
|
||
via: "fetch in useEffect"
|
||
pattern: "fetch.*api/feed"
|
||
---
|
||
```
|
||
|
||
### Referência dos campos de frontmatter
|
||
|
||
| Campo | Obrigatório | Tipo | Finalidade |
|
||
|---|---|---|---|
|
||
| `phase` | Sim | string | Identificador da fase, ex.: `03-post-feed`. |
|
||
| `plan` | Sim | string | Número do plano dentro da fase, ex.: `02`. |
|
||
| `type` | Sim | `execute` ou `tdd` | `execute` para planos padrão; `tdd` para planos orientados a testes, onde os testes são escritos antes da implementação. |
|
||
| `wave` | Sim | inteiro | Onda de execução. Planos na onda 1 são executados em paralelo (sem dependências). Planos na onda 2 ou superior aguardam a conclusão de todos os planos da onda anterior. Pré-calculado durante o planejamento pelo `gsd-planner`. |
|
||
| `depends_on` | Sim | array de IDs de planos | Planos dos quais este plano depende. Array vazio = onda 1. Exemplo: `["03-01"]` significa que este plano é executado após o Plano 01 da Fase 3. |
|
||
| `files_modified` | Sim | array de caminhos | Todos os arquivos que este plano cria ou modifica. Usado pelo verificador de planos para detectar conflitos de arquivos na mesma onda e pelo execute-phase para rastreamento de merge. |
|
||
| `autonomous` | Sim | booleano | `true` quando todas as tarefas são do tipo `auto`. `false` quando o plano contém alguma tarefa `checkpoint:*` que requer interação humana. |
|
||
| `requirements` | Sim | array de IDs | IDs de requisitos do ROADMAP.md que este plano atende. Todo ID de requisito de fase deve aparecer no campo `requirements` de pelo menos um plano. Arrays vazios são um BLOQUEADOR. |
|
||
| `user_setup` | Não | array de objetos | Etapas de configuração de serviços externos que o Claude não pode automatizar (criação de conta, recuperação de segredos, configuração de painel). Quando presente, o execute-phase gera um checklist `USER-SETUP.md` para o desenvolvedor. |
|
||
| `must_haves` | Sim | objeto | Critérios de verificação orientados ao objetivo final. Veja abaixo. |
|
||
|
||
---
|
||
|
||
## Campo `must_haves`
|
||
|
||
`must_haves` captura o que deve ser observavelmente verdadeiro para que o objetivo da fase seja alcançado. É derivado durante o planejamento e verificado após a execução pelo agente `gsd-verifier`.
|
||
|
||
### Sub-campos
|
||
|
||
| Sub-campo | Tipo | Finalidade |
|
||
|---|---|---|
|
||
| `truths` | array de strings | Comportamentos observáveis do ponto de vista do usuário. Cada um deve ser verificável. Exemplo: `"User can send a message"`, não `"WebSocket library installed"`. |
|
||
| `artifacts` | array de objetos | Arquivos que devem existir com implementação substantiva (não stubs). |
|
||
| `artifacts[].path` | string | Caminho do arquivo relativo à raiz do projeto. |
|
||
| `artifacts[].provides` | string | Qual capacidade este arquivo entrega. |
|
||
| `artifacts[].min_lines` | inteiro (opcional) | Contagem mínima de linhas para não ser considerado um stub. |
|
||
| `artifacts[].exports` | array de strings (opcional) | Exportações nomeadas esperadas para verificação. |
|
||
| `artifacts[].contains` | string (opcional) | Expressão regular ou padrão literal que deve aparecer no arquivo. |
|
||
| `key_links` | array de objetos | Conexões críticas entre artefatos — a ligação que faz o sistema funcionar de ponta a ponta. |
|
||
| `key_links[].from` | string | Arquivo ou componente de origem. |
|
||
| `key_links[].to` | string | Arquivo, endpoint ou módulo de destino. |
|
||
| `key_links[].via` | string | Descrição de como eles se conectam (ex.: `fetch in useEffect`, `Prisma query`, `import`). |
|
||
| `key_links[].pattern` | string (opcional) | Expressão regular para verificar se a conexão existe no código-fonte. |
|
||
|
||
---
|
||
|
||
## Estrutura do corpo
|
||
|
||
Após o frontmatter, o corpo do plano utiliza blocos no estilo XML lidos pelo agente executor.
|
||
|
||
### `<objective>`
|
||
|
||
Declara o que o plano entrega e por que isso importa para o projeto:
|
||
|
||
```xml
|
||
<objective>
|
||
Implement the post feed as a scrollable card list.
|
||
|
||
Purpose: Core display feature for the social feed phase.
|
||
Output: PostFeed and PostCard components wired to /api/feed.
|
||
</objective>
|
||
```
|
||
|
||
### `<execution_context>`
|
||
|
||
Lista os arquivos de workflow que o executor lê antes de começar. Sempre inclui o workflow execute-plan; adiciona a referência de checkpoints quando o plano contém tarefas de checkpoint:
|
||
|
||
```xml
|
||
<execution_context>
|
||
@~/.claude/get-shit-done/workflows/execute-plan.md
|
||
@~/.claude/get-shit-done/templates/summary.md
|
||
</execution_context>
|
||
```
|
||
|
||
### `<context>`
|
||
|
||
Referencia os arquivos-fonte que o executor precisa ler. Inclui documentos de planejamento no nível do projeto e quaisquer arquivos-fonte cujos padrões ou tipos o plano deve replicar. Arquivos `SUMMARY.md` de planos anteriores são incluídos apenas quando há uma dependência genuína (tipos importados, decisão compartilhada) — não de forma reflexiva:
|
||
|
||
```xml
|
||
<context>
|
||
@.planning/PROJECT.md
|
||
@.planning/ROADMAP.md
|
||
@.planning/STATE.md
|
||
@src/components/UserCard.tsx
|
||
</context>
|
||
```
|
||
|
||
### `<tasks>`
|
||
|
||
Contém um ou mais elementos `<task>`. Todo elemento de tarefa deve ter `<name>`, `<files>`, `<read_first>`, `<action>`, `<verify>`, `<acceptance_criteria>` e `<done>` para tarefas do tipo `type="auto"`.
|
||
|
||
---
|
||
|
||
## Tipos de tarefa
|
||
|
||
| Tipo | Uso | Autonomia |
|
||
|---|---|---|
|
||
| `auto` | Tudo o que o executor pode fazer de forma independente. | Totalmente autônomo. |
|
||
| `checkpoint:human-verify` | Verificação visual ou funcional que requer que um humano observe uma UI ou serviço em execução. | Pausa a execução; apresenta ao desenvolvedor; retoma com aprovação. |
|
||
| `checkpoint:decision` | Escolhas de implementação que surgiram durante a execução e requerem a contribuição do desenvolvedor. | Pausa a execução; apresenta opções; retoma com a seleção. |
|
||
| `checkpoint:human-action` | Etapas manuais verdadeiramente inevitáveis (criação de conta, interação com hardware). Usadas com parcimônia. | Pausa a execução; retoma com confirmação. |
|
||
|
||
Planos que contêm qualquer tarefa de checkpoint devem definir `autonomous: false` no frontmatter.
|
||
|
||
---
|
||
|
||
## Estrutura de tarefa `auto`
|
||
|
||
```xml
|
||
<task type="auto">
|
||
<name>Task 1: Create PostCard component</name>
|
||
<files>src/components/PostCard.tsx</files>
|
||
<read_first>src/components/UserCard.tsx, src/types/post.ts</read_first>
|
||
<action>Create PostCard component accepting a Post prop (id, authorId, content, createdAt,
|
||
reactionCount). Render author avatar using UserAvatar from UserCard pattern. Show timestamp
|
||
using date-fns formatDistanceToNow. Export as named export PostCard.</action>
|
||
<verify>npx tsc --noEmit</verify>
|
||
<acceptance_criteria>
|
||
- src/components/PostCard.tsx exports named export PostCard
|
||
- PostCard.tsx contains "reactionCount" prop usage
|
||
- npx tsc --noEmit exits 0
|
||
</acceptance_criteria>
|
||
<done>PostCard renders post content with author and timestamp</done>
|
||
</task>
|
||
```
|
||
|
||
### Campos obrigatórios para tarefas `auto`
|
||
|
||
| Campo | Regra |
|
||
|---|---|
|
||
| `<files>` | Todo arquivo que a tarefa cria ou modifica. O executor escreve apenas nesses arquivos. |
|
||
| `<read_first>` | Arquivos que o executor deve ler antes de tocar em qualquer coisa — o arquivo sendo modificado, qualquer arquivo de padrão de referência, qualquer arquivo cujos tipos ou convenções devem ser replicados. |
|
||
| `<action>` | Instruções concretas com identificadores exatos, caminhos de arquivo, assinaturas de função e valores esperados. Nunca diz "alinhe X com Y" sem especificar o estado-alvo. Nunca contém blocos de código cercados ou implementações completas. |
|
||
| `<verify>` | Um comando ou verificação executável que comprova o sucesso da tarefa. Deve distinguir aprovação de falha — `echo "done"` não é válido. |
|
||
| `<acceptance_criteria>` | Condições verificáveis: strings verificáveis por grep, códigos de saída de comandos, comportamentos observáveis. Sem linguagem subjetiva ("parece correto", "configurado corretamente"). |
|
||
| `<done>` | Uma declaração curta e mensurável do resultado concluído. |
|
||
|
||
---
|
||
|
||
## Dimensões de qualidade do plano
|
||
|
||
O agente `gsd-plan-checker` avalia cada PLAN.md em 12 dimensões antes do início da execução. Um plano que falha em qualquer verificação de severidade BLOQUEADOR é devolvido ao `gsd-planner` para revisão (até 3 iterações):
|
||
|
||
| Dimensão | O que verifica |
|
||
|---|---|
|
||
| **1 — Cobertura de Requisitos** | Todo ID de requisito de fase do ROADMAP.md aparece no campo de frontmatter `requirements` de pelo menos um plano e possui tarefa(s) correspondente(s). |
|
||
| **2 — Completude das Tarefas** | Toda tarefa `auto` contém todos os campos obrigatórios (`<files>`, `<action>`, `<verify>`, `<acceptance_criteria>`, `<done>`). Nenhum campo vago ou vazio. |
|
||
| **3 — Correção de Dependências** | As referências de `depends_on` são válidas, acíclicas e consistentes com os números de onda. Um plano da Onda N depende apenas de planos em ondas < N. |
|
||
| **4 — Links Principais Planejados** | Artefatos em `must_haves.key_links` possuem tarefas correspondentes que implementam a ligação — não apenas a criação do artefato. |
|
||
| **5 — Sanidade do Escopo** | Os planos permanecem dentro do orçamento de contexto: 2–3 tarefas por plano (4 = aviso, 5+ = BLOQUEADOR), ≤ 8–10 arquivos por plano (15+ = BLOQUEADOR). |
|
||
| **6 — Derivação de Verificação** | `must_haves.truths` são comportamentos observáveis pelo usuário, não detalhes de implementação. Artefatos mapeiam para truths. Links principais cobrem a ligação crítica. |
|
||
| **7 — Conformidade de Contexto** | Toda decisão `D-NN` do CONTEXT.md é abordada por pelo menos uma tarefa. Nenhuma tarefa implementa nada de `<deferred>`. |
|
||
| **7b — Detecção de Redução de Escopo** | As ações das tarefas não reduzem silenciosamente uma decisão bloqueada para um "v1", "stub" ou "melhoria futura" sem entregar o escopo completo da decisão. Sempre é um BLOQUEADOR quando encontrado. |
|
||
| **7c — Conformidade de Nível Arquitetural** | As tarefas atribuem capacidades ao nível correto conforme o Mapa de Responsabilidade Arquitetural do RESEARCH.md (quando presente). Capacidades sensíveis à segurança no nível errado são BLOCKEADOREs. |
|
||
| **8 — Conformidade Nyquist** | Quando `workflow.nyquist_validation` está habilitado e RESEARCH.md existe, toda tarefa tem um comando de verificação `<automated>`, nenhuma janela consecutiva de 3 tarefas carece de cobertura, e VALIDATION.md está presente. |
|
||
| **9 — Contratos de Dados Entre Planos** | Quando planos compartilham pipelines de dados, suas transformações são compatíveis — nenhum plano remove dados que outro plano precisa em sua forma original. |
|
||
| **10 — Conformidade com CLAUDE.md** | Os planos respeitam convenções específicas do projeto, padrões proibidos, ferramentas obrigatórias e requisitos de segurança do `./CLAUDE.md`. |
|
||
| **11 — Resolução de Pesquisa** | Quando RESEARCH.md existe, sua seção `## Open Questions` está marcada como `(RESOLVED)` antes de o planejamento prosseguir. |
|
||
| **12 — Conformidade de Padrões** | Quando PATTERNS.md existe, as tarefas referenciam os padrões analógicos corretos para cada arquivo novo ou modificado. |
|
||
|
||
---
|
||
|
||
## Modelo de execução por ondas
|
||
|
||
Os números de onda são pré-calculados durante o planejamento. O execute-phase agrupa os planos por número de onda e executa os planos de cada onda em paralelo:
|
||
|
||
```
|
||
Wave 1: Plan 01, Plan 02, Plan 03 (all run simultaneously — no dependencies)
|
||
Wave 2: Plan 04 (waits for Wave 1 to complete)
|
||
Wave 3: Plan 05 (waits for Wave 2 to complete)
|
||
```
|
||
|
||
Planos dentro de uma mesma onda que modificam arquivos sobrepostos não devem estar na mesma onda — a Dimensão 3 do verificador de planos sinaliza isso como um BLOQUEADOR.
|
||
|
||
---
|
||
|
||
## Saída do plano
|
||
|
||
Após a execução bem-sucedida de um plano, o executor escreve um SUMMARY.md em:
|
||
|
||
```
|
||
.planning/phases/<NN>-<slug>/<NN>-<PP>-SUMMARY.md
|
||
```
|
||
|
||
O SUMMARY.md é o registro canônico do que foi construído. Planos subsequentes na mesma fase podem referenciá-lo quando há uma dependência genuína em seus tipos ou decisões.
|
||
|
||
---
|
||
|
||
## Relacionados
|
||
|
||
- [Esquema CONTEXT.md](context-md.md)
|
||
- [Artefatos de planejamento](planning-artifacts.md)
|
||
- [Funcionalidades](../FEATURES.md)
|
||
- [Índice da documentação](../README.md)
|