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>
6.2 KiB
Como conduzir o GSD 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 GSD — desde o workspace isolado até o PR mesclado — usando apenas comandos já existentes no GSD Core, sem scripts customizados ou integrações com rastreadores.
Pré-requisitos: GSD 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:
/gsd-phase "Descrição correspondente ao título da issue"
- A issue é urgente e precisa ser inserida entre fases existentes → insira uma fase decimal:
/gsd-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.
/gsd-workspace --new --name my-issue-slug --repos . --strategy worktree
Entre no diretório do workspace antes de continuar:
cd ~/gsd-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.
/gsd-discuss-phase N
O GSD 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:
/gsd-discuss-phase N --auto
Passo 4: Planejar a fase
/gsd-plan-phase N
O GSD 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):
/gsd-review --phase N
/gsd-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:
/gsd-plan-review-convergence N
Passo 5: Executar a fase
Para execução interativa, fase por fase:
/gsd-execute-phase N
Para uma execução sem supervisão por todas as fases restantes:
/gsd-autonomous
Para um painel interativo onde você pode acompanhar o progresso e despachar trabalho entre fases:
/gsd-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
/gsd-verify-work N
O GSD 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 GSD 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:
/gsd-code-review N
/gsd-code-review N --fix
Em seguida, crie o PR:
/gsd-ship N
O GSD 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 /gsd-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:
/gsd-capture "Acompanhamento: descrição do trabalho descoberto" # Adicionar como tarefa
/gsd-capture --seed "Ideia que vale uma fase futura" # Preservar para o próximo milestone
/gsd-capture --backlog "Não urgente, mas vale registrar" # Arquivar no backlog
O GSD 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 /gsd-quick em vez disso |
| A issue tem múltiplas subtarefas independentes | Use /gsd-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 GSD 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 /gsd-phase --insert N para adicionar subfases, continue |
| Você quer pular a discussão interativa | Use a flag --auto com /gsd-discuss-phase, ou defina workflow.skip_discuss: true para automação em todo o projeto |
| Múltiplas issues formam uma release coerente | Execute /gsd-new-milestone para agrupá-las e /gsd-autonomous para executar em sequência |