msd-core/docs/pt-BR/ARCHITECTURE.md

Arquitetura do GSD Core

Arquitetura do sistema para contribuidores e usuários avançados. Para a documentação voltada ao usuário, consulte a Referência de Funcionalidades ou o Guia do Usuário.

---

Índice

• Visão Geral do Sistema
• Princípios de Design
• Arquitetura de Componentes
• Modelo de Agentes
• Fluxo de Dados
• Estrutura do Sistema de Arquivos
• Arquitetura do Instalador
• Sistema de Hooks
• Camada de Ferramentas CLI
• Abstração de Runtime

---

Visão Geral do Sistema

O GSD Core é um framework de meta-prompting que fica entre o usuário e os agentes de codificação com IA (Claude Code, Kimi CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code). Ele fornece:

1. Engenharia de contexto — Artefatos estruturados que fornecem à IA tudo o que ela precisa por tarefa (consulte Engenharia de contexto)
2. Orquestração multi-agente — Orquestradores leves que criam agentes especializados com janelas de contexto novas (consulte Orquestração multi-agente)
3. Desenvolvimento orientado por especificações — Pipeline de Requisitos → pesquisa → planos → execução → verificação
4. Gerenciamento de estado — Memória persistente do projeto entre sessões e reinicializações de contexto

┌──────────────────────────────────────────────────────┐
│                      USUÁRIO                         │
│            /gsd-command [args]                        │
└─────────────────────┬────────────────────────────────┘
                      │
┌─────────────────────▼────────────────────────────────┐
│              CAMADA DE COMANDOS                       │
│   commands/gsd/*.md — Arquivos de comandos baseados   │
│   em prompts (comandos customizados Claude Code /     │
│   skills do Codex)                                    │
└─────────────────────┬────────────────────────────────┘
                      │
┌─────────────────────▼────────────────────────────────┐
│              CAMADA DE WORKFLOWS                      │
│   gsd-core/workflows/*.md — Lógica de            │
│   orquestração                                        │
│   (Lê referências, cria agentes, gerencia estado)     │
└──────┬──────────────┬─────────────────┬──────────────┘
       │              │                 │
┌──────▼──────┐ ┌─────▼─────┐ ┌────────▼───────┐
│  AGENTE     │ │  AGENTE   │ │  AGENTE        │
│  (contexto  │ │  (contexto│ │  (contexto     │
│   novo)     │ │   novo)   │ │   novo)        │
└──────┬──────┘ └─────┬─────┘ └────────┬───────┘
       │              │                 │
┌──────▼──────────────▼─────────────────▼──────────────┐
│              CAMADA DE FERRAMENTAS CLI                │
│   gsd-tools.cjs command families + domain modules     │
│   command-routing-hub + observability seams           │
└──────────────────────┬───────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────┐
│              SISTEMA DE ARQUIVOS (.planning/)         │
│   PROJECT.md | REQUIREMENTS.md | ROADMAP.md          │
│   STATE.md | config.json | phases/ | research/       │
└──────────────────────────────────────────────────────┘

---

Princípios de Design

1. Contexto Novo por Agente

Cada agente criado por um orquestrador recebe uma janela de contexto limpa (até 200 mil tokens). Isso elimina o desgaste do contexto — a degradação de qualidade que ocorre à medida que uma IA preenche sua janela de contexto com a conversa acumulada.

2. Orquestradores Leves

Os arquivos de workflow (gsd-core/workflows/*.md) nunca fazem trabalho pesado. Eles:

• Carregam contexto via gsd-tools.cjs init <workflow>
• Criam agentes especializados com prompts focados
• Coletam resultados e encaminham para a próxima etapa
• Atualizam o estado entre as etapas

3. Estado Baseado em Arquivos

Todo o estado fica em .planning/ como Markdown e JSON legíveis por humanos. Sem banco de dados, sem servidor, sem dependências externas. Isso significa:

• O estado sobrevive a reinicializações de contexto (/clear)
• O estado é inspecionável tanto por humanos quanto por agentes
• O estado pode ser commitado no git para visibilidade da equipe

4. Ausente = Habilitado

Os feature flags de workflow seguem o padrão ausente = habilitado. Se uma chave estiver ausente do config.json, o padrão é true. Os usuários desabilitam funcionalidades explicitamente; não precisam habilitar os padrões.

5. Defesa em Profundidade

Múltiplas camadas previnem modos comuns de falha:

• Os planos são verificados antes da execução (agente plan-checker)
• A execução produz commits atômicos por tarefa
• A verificação pós-execução confronta os objetivos da fase
• O UAT fornece verificação humana como portão final

---

Arquitetura de Componentes

Comandos (commands/gsd/*.md)

Pontos de entrada voltados ao usuário. Cada arquivo contém frontmatter YAML (name, description, allowed-tools) e um corpo de prompt que inicializa o workflow. Os comandos são instalados como:

• Claude Code: Comandos slash customizados (forma com hífen, /gsd-command-name)
• OpenCode / Kilo: Comandos slash (forma com hífen, /gsd-command-name)
• Codex: Skills ($gsd-command-name)
• Copilot: Comandos slash (forma com hífen, /gsd-command-name)
• Antigravity: Skills

Total de comandos: consulte docs/INVENTORY.md para a contagem oficial e o roster completo.

Roteamento hierárquico em dois estágios (v1.40, #2792)

Para manter baixo o custo em tokens da listagem de skills antecipada, a v1.40 introduz seis meta-skills de namespace (gsd-workflow, gsd-project, gsd-quality, gsd-context, gsd-manage, gsd-ideate — originados de commands/gsd/ns-*.md, mas o name: invocável é a forma básica mostrada aqui) dispostos acima das sub-skills concretas. O modelo vê 6 roteadores de namespace (~120 tokens) em vez de uma listagem plana de 86 skills (~2.150 tokens), seleciona um namespace e depois roteia para a sub-skill concreta via tabela de roteamento embutida no corpo do roteador de namespace. As skills de namespace são aditivas — cada comando concreto ainda é diretamente invocável.

As descrições dos roteadores usam tags de palavras-chave separadas por pipe (≤ 60 caracteres) conforme a pesquisa Tool Attention, que mostra que tags ricas em palavras-chave superam a prosa no roteamento com ~40% do custo em tokens.

Interação com o orçamento de tokens do MCP

A listagem de skills antecipada é um dos dois custos recorrentes de tokens por turno. O outro é o schema de ferramenta MCP injetado por cada servidor MCP habilitado em .claude/settings.json. Servidores MCP pesados (browser/playwright, Mac-tools, Windows-tools) podem custar mais de 20 mil tokens por turno cada — muitas vezes eclipsando o que o ajuste do model_profile economiza. O controle fica no harness do Claude Code (enabledMcpjsonServers / disabledMcpjsonServers em .claude/settings.json) e não é uma preocupação do GSD. Juntos, a camada de roteamento em dois estágios (#2792) e o controle criterioso do MCP são as maiores alavancas de custo por turno. Consulte docs/USER-GUIDE.md e references/context-budget.md para o checklist de auditoria.

Workflows (gsd-core/workflows/*.md)

Lógica de orquestração que os comandos referenciam. Contém o processo passo a passo, incluindo:

• Carregamento de contexto via handlers gsd-tools.cjs init
• Instruções de criação de agente com resolução de modelo
• Definições de portões/checkpoints
• Padrões de atualização de estado
• Tratamento de erros e recuperação

Total de workflows: consulte docs/INVENTORY.md para a contagem oficial e o roster completo.

Divulgação progressiva para workflows

Os arquivos de workflow são carregados verbatim no contexto do Claude cada vez que o comando /gsd-* correspondente é invocado. Para manter esse custo limitado, o orçamento de tamanho de workflow aplicado por tests/workflow-size-budget.test.cjs espelha a convenção de orçamento de tamanho de agentes:

Tier	Limite de linhas por arquivo
XL	1700 — orquestradores de nível superior (execute-phase, plan-phase, new-project)
LARGE	1500 — planejadores com múltiplas etapas e workflows de funcionalidades grandes
DEFAULT	1000 — workflows simples e de propósito único (o tier alvo)

workflows/discuss-phase.md é mantido em um teto mais restrito conforme o orçamento de bytes do discuss-phase (#717; a divisão discuss-phase/modes mantém ≈32000 bytes). Quando um workflow cresce além de seu tier, extraia os corpos por modo em workflows/<workflow>/modes/<mode>.md, templates em workflows/<workflow>/templates/, e conhecimento compartilhado em gsd-core/references/. O arquivo pai se torna um despachante leve que lê apenas os arquivos de modo e template necessários para a invocação atual.

workflows/discuss-phase/ é o exemplo canônico deste padrão — o pai despacha, modes/ contém o comportamento por flag (power.md, all.md, auto.md, chain.md, text.md, batch.md, analyze.md, default.md, advisor.md), e templates/ contém os schemas CONTEXT.md, DISCUSSION-LOG.md e checkpoint.json que são lidos apenas quando o arquivo de saída correspondente está sendo escrito.

Agentes (agents/*.md)

Definições de agentes especializados com frontmatter especificando:

• name — Identificador do agente
• description — Papel e propósito
• tools — Acesso às ferramentas permitidas (Read, Write, Edit, Bash, Grep, Glob, WebSearch, etc.)
• color — Cor de saída no terminal para distinção visual

Total de agentes: 33

Referências (gsd-core/references/*.md)

Documentos de conhecimento compartilhado que workflows e agentes @-referenciam (consulte docs/INVENTORY.md para a contagem oficial e o roster completo):

Referências principais:

• checkpoints.md — Definições de tipos de checkpoint e padrões de interação
• gates.md — 4 tipos canônicos de portões (Confirm, Quality, Safety, Transition) conectados ao plan-checker e ao verifier
• model-profiles.md — Atribuições de tier de modelo por agente
• model-profile-resolution.md — Documentação do algoritmo de resolução de modelo
• verification-patterns.md — Como verificar diferentes tipos de artefatos
• verification-overrides.md — Regras de substituição de verificação por artefato
• planning-config.md — Schema completo de configuração e comportamento
• git-integration.md — Padrões de commit no git, branching e histórico
• git-planning-commit.md — Convenções de commit do diretório de planejamento
• questioning.md — Filosofia de extração de visão para inicialização de projetos
• tdd.md — Padrões de integração de desenvolvimento orientado por testes
• ui-brand.md — Padrões de formatação de saída visual
• common-bug-patterns.md — Padrões comuns de bugs para revisão de código e verificação

Referências de workflow:

• agent-contracts.md — Interface formal entre orquestradores e agentes
• context-budget.md — Regras de alocação do orçamento da janela de contexto
• continuation-format.md — Formato de continuação/retomada de sessão
• domain-probes.md — Perguntas de sondagem específicas de domínio para a discuss-phase
• gate-prompts.md — Templates de prompt para portões/checkpoints
• revision-loop.md — Padrões de iteração de revisão de plano
• universal-anti-patterns.md — Anti-padrões comuns a detectar e evitar
• artifact-types.md — Definições de tipos de artefatos de planejamento
• phase-argument-parsing.md — Convenções de análise de argumentos de fase
• decimal-phase-calculation.md — Regras de numeração decimal de sub-fases
• workstream-flag.md — Convenções do ponteiro ativo de workstream
• user-profiling.md — Metodologia de perfilamento comportamental do usuário
• thinking-partner.md — Ativação condicional de parceiro de raciocínio em pontos de decisão

Referências para modelos de raciocínio:

Referências para integrar modelos de classe thinking (o3, o4-mini, Gemini 2.5 Pro) aos workflows do GSD:

• thinking-models-debug.md — Padrões de modelos de raciocínio para workflows de depuração
• thinking-models-execution.md — Padrões de modelos de raciocínio para agentes de execução
• thinking-models-planning.md — Padrões de modelos de raciocínio para agentes de planejamento
• thinking-models-research.md — Padrões de modelos de raciocínio para agentes de pesquisa
• thinking-models-verification.md — Padrões de modelos de raciocínio para agentes de verificação

Decomposição modular do planner:

O agente planner (agents/gsd-planner.md) foi decomposto de um único arquivo monolítico em um agente central mais módulos de referência para permanecer abaixo do limite de 50 mil caracteres imposto por alguns runtimes:

• planner-gap-closure.md — Comportamento do modo de fechamento de lacunas (lê VERIFICATION.md, replanejamento direcionado)
• planner-reviews.md — Integração de revisão entre IAs (lê REVIEWS.md do /gsd-review)
• planner-revision.md — Padrões de revisão de plano para refinamento iterativo

Templates (gsd-core/templates/)

Templates Markdown para todos os artefatos de planejamento. Usados por gsd-tools.cjs template fill / phase.scaffold (e scaffold de nível superior) para criar arquivos pré-estruturados:

• project.md, requirements.md, roadmap.md, state.md — Arquivos principais do projeto
• phase-prompt.md — Template de prompt de execução de fase
• summary.md (+ summary-minimal.md, summary-standard.md, summary-complex.md) — Templates de resumo com granularidade ajustável
• DEBUG.md — Template de acompanhamento de sessão de depuração
• UI-SPEC.md, UAT.md, VALIDATION.md — Templates de verificação especializados
• discussion-log.md — Template de trilha de auditoria de discussão
• codebase/ — Templates de mapeamento de brownfield (stack, architecture, conventions, concerns, structure, testing, integrations)
• research-project/ — Templates de saída de pesquisa (SUMMARY, STACK, FEATURES, ARCHITECTURE, PITFALLS)

Hooks (hooks/)

Hooks de runtime que se integram ao agente de IA anfitrião:

Hook	Evento	Propósito
gsd-statusline.js	statusLine	Exibe modelo, tarefa, diretório e barra de uso do contexto
gsd-context-monitor.js	PostToolUse / AfterTool	Injeta avisos de contexto voltados ao agente em 35%/25% restante
gsd-check-update.js	SessionStart	Gatilho em primeiro plano para a verificação de atualização em segundo plano
gsd-check-update-worker.js	(auxiliar)	Worker em segundo plano criado por gsd-check-update.js; sem registro de evento direto
gsd-prompt-guard.js	PreToolUse	Escaneia escritas em .planning/ em busca de padrões de injeção de prompt (consultivo)
gsd-read-injection-scanner.js	PostToolUse	Escaneia saídas da ferramenta Read em busca de instruções injetadas em conteúdo não confiável
gsd-workflow-guard.js	PreToolUse	Detecta edições de arquivos fora do contexto de workflow do GSD (consultivo, ativado via hooks.workflow_guard)
gsd-secret-read-guard.js	PreToolUse	Bloqueia rigorosamente leituras de .env, .env.<suffix> (exceto templates como .env.example) e .secrets via Read / Grep / Bash; substitui as regras deny Read(.env*) que o instalador escrevia (#4221)
gsd-read-guard.js	PreToolUse	Guarda consultivo que impede Edit/Write em arquivos ainda não lidos na sessão
gsd-session-state.sh	SessionStart	Rastreamento de estado de sessão para runtimes baseados em shell
gsd-validate-commit.sh	PreToolUse	Validação de commit para aplicação de commits convencionais
gsd-phase-boundary.sh	PostToolUse	Detecção de limite de fase para transições de workflow

Consulte docs/INVENTORY.md para o roster oficial de 11 hooks.

Hub de Roteamento de Comandos (gsd-core/bin/lib/command-routing-hub.cjs)

Os roteadores de família de comandos CJS despacham através do CommandRoutingHub. O hub possui o contrato de resultado puro sem lançamento de exceções (hub.dispatch() captura exceções internas e retorna { ok: false, kind, ...typedPayload }) e a taxonomia fechada de erros de runtime (UnknownCommand, InvalidArgs, HandlerRefusal, HandlerFailure). Os adaptadores de roteador permanecem como tradutores CLI leves — eles constroem o hub, chamam dispatch e depois mapeiam o Result para chamadas output()/error(). O runtime é de caminho único (sem seleção de modo de runtime duplo). Consulte docs/adr/0174-retire-gsd-sdk-package-boundary.md.

Ferramentas CLI (gsd-core/bin/)

Utilitário CLI Node.js (gsd-tools.cjs) com módulos de domínio distribuídos em gsd-core/bin/lib/ (consulte docs/INVENTORY.md para o roster oficial):

Módulo	Responsabilidade
core.cjs	Tratamento de erros, formatação de saída, utilitários compartilhados; re-exportações de compatibilidade para helpers de planejamento
planning-workspace.cjs	Camada de planejamento (planningDir, planningPaths, roteamento de workstream ativo, .planning/.lock)
state.cjs	Análise, atualização, progressão e métricas do STATE.md
phase.cjs	Operações de diretório de fase, numeração decimal, indexação de planos
roadmap.cjs	Análise do ROADMAP.md, extração de fases, progresso do plano
config.cjs	Leitura/escrita do config.json, inicialização de seções
verify.cjs	Estrutura do plano, integridade de fase, referência, validação de commit
template.cjs	Seleção e preenchimento de template com substituição de variáveis
frontmatter.cjs	Operações CRUD de frontmatter YAML
init.cjs	Carregamento composto de contexto para cada tipo de workflow
milestone.cjs	Arquivamento de milestones, marcação de requisitos
commands.cjs	Comandos diversos (slug, timestamp, todos, scaffolding, stats)
model-profiles.cjs	Tabela de resolução de perfis de modelo
security.cjs	Prevenção de path traversal, detecção de injeção de prompt, análise segura de JSON, validação de argumentos de shell
uat.cjs	Análise de arquivo UAT, rastreamento de débito de verificação, suporte a audit-uat
docs.cjs	Inicialização do workflow de atualização de docs, escaneamento de Markdown, detecção de monorepo
workstream.cjs	CRUD de workstream, migração, ponteiro ativo com escopo de sessão
schema-detect.cjs	Detecção de desvio de schema para padrões ORM (Prisma, Drizzle, etc.)
profile-pipeline.cjs	Pipeline de dados de perfilamento comportamental do usuário, escaneamento de arquivos de sessão
profile-output.cjs	Renderização de perfil, geração de USER-PROFILE.md e dev-preferences.md

---

Modelo de Agentes

Padrão Orquestrador → Agente

Orquestrador (workflow .md)
    │
    ├── Carregar contexto: gsd-tools.cjs init <workflow> <phase>
    │   Retorna JSON com: informações do projeto, config, estado, detalhes da fase
    │
    ├── Resolver modelo: gsd-tools.cjs resolve-model <agent-name>
    │   Retorna: opus | sonnet | haiku | inherit
    │
    ├── Criar Agente (chamada Task/SubAgent)
    │   ├── Prompt do agente (agents/*.md)
    │   ├── Payload de contexto (JSON do init)
    │   ├── Atribuição de modelo
    │   └── Permissões de ferramentas
    │
    ├── Coletar resultado
    │
    └── Atualizar estado: gsd-tools.cjs state update / state patch / state advance-plan

Categorias Principais de Criação de Agentes

Taxonomia conceitual de padrões de criação para os 21 agentes primários. Para o roster oficial de 31 agentes (incluindo os 10 agentes avançados/especializados como gsd-pattern-mapper, gsd-code-reviewer, gsd-code-fixer, gsd-ai-researcher, gsd-domain-researcher, gsd-eval-planner, gsd-eval-auditor, gsd-framework-selector, gsd-debug-session-manager, gsd-intel-updater), consulte docs/INVENTORY.md.

Categoria	Agentes	Paralelismo
Pesquisadores	gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher	4 paralelos (stack, features, architecture, pitfalls); advisor criado durante a discuss-phase
Sintetizadores	gsd-research-synthesizer	Sequencial (após a conclusão dos pesquisadores)
Planejadores	gsd-planner, gsd-roadmapper	Sequencial
Verificadores de plano	gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor	Sequencial (loop de verificação, máximo 3 iterações)
Executores	gsd-executor	Paralelo dentro de ondas, sequencial entre ondas
Verificadores	gsd-verifier	Sequencial (após a conclusão de todos os executores)
Mapeadores	gsd-codebase-mapper	4 paralelos (tech, arch, quality, concerns)
Depuradores	gsd-debugger	Sequencial (interativo)
Auditores	gsd-ui-auditor, gsd-security-auditor	Sequencial
Escritores de doc	gsd-doc-writer, gsd-doc-verifier	Sequencial (escritor depois verificador)
Perfiladores	gsd-user-profiler	Sequencial
Analisadores	gsd-assumptions-analyzer	Sequencial (durante a discuss-phase)

Modelo de Execução em Ondas

Durante a execute-phase, os planos são agrupados em ondas de dependência:

Análise de Ondas:
  Plano 01 (sem deps)      ─┐
  Plano 02 (sem deps)      ─┤── Onda 1 (paralelo)
  Plano 03 (depende: 01)   ─┤── Onda 2 (aguarda a Onda 1)
  Plano 04 (depende: 02)   ─┘
  Plano 05 (depende: 03,04) ── Onda 3 (aguarda a Onda 2)

Cada executor recebe:

• Janela de contexto nova de 200 mil tokens (ou até 1 M para modelos que suportam)
• O PLAN.md específico a executar
• Contexto do projeto (PROJECT.md, STATE.md)
• Contexto da fase (CONTEXT.md, RESEARCH.md se disponível)

Enriquecimento Adaptativo de Contexto (Modelos de 1 M)

Quando a janela de contexto tem 500 mil tokens ou mais (modelos classe 1 M como Opus 4.6, Sonnet 4.6), os prompts de subagentes são automaticamente enriquecidos com contexto adicional que não caberia em janelas de 200 mil tokens padrão:

• Agentes executores recebem os arquivos SUMMARY.md de ondas anteriores e o CONTEXT.md/RESEARCH.md da fase, possibilitando consciência entre planos dentro de uma fase
• Agentes verificadores recebem todos os arquivos PLAN.md, SUMMARY.md, CONTEXT.md mais REQUIREMENTS.md, possibilitando verificação com consciência do histórico

O orquestrador lê context_window da configuração (gsd-tools.cjs config-get context_window) e inclui condicionalmente um contexto mais rico quando o valor é >= 500.000. Para janelas de 200 mil tokens padrão, os prompts usam versões truncadas com ordenação favorável ao cache para maximizar a eficiência do contexto.

Segurança de Commits Paralelos

Quando múltiplos executores rodam dentro da mesma onda, dois mecanismos previnem conflitos:

1. Commits --no-verify — Agentes paralelos pulam hooks de pré-commit (que podem causar contenção de lock de build, por exemplo, disputas de cargo lock em projetos Rust). O orquestrador executa git hook run pre-commit uma vez após a conclusão de cada onda.
2. Bloqueio de arquivo STATE.md — Todas as chamadas writeStateMd() usam exclusão mútua baseada em lockfile (STATE.md.lock com criação atômica O_EXCL). Isso previne a condição de corrida leitura-modificação-escrita onde dois agentes leem o STATE.md, modificam campos diferentes, e o último a escrever sobrescreve as alterações do outro. Inclui detecção de lock obsoleto (timeout de 10 s) e espera em spin com jitter.

---

Fluxo de Dados

Fluxo de Novo Projeto

Entrada do usuário (descrição da ideia)
    │
    ▼
Perguntas (filosofia questioning.md)
    │
    ▼
4x Pesquisadores de Projeto (paralelo)
    ├── Stack → STACK.md
    ├── Features → FEATURES.md
    ├── Architecture → ARCHITECTURE.md
    └── Pitfalls → PITFALLS.md
    │
    ▼
Sintetizador de Pesquisa → SUMMARY.md
    │
    ▼
Extração de requisitos → REQUIREMENTS.md
    │
    ▼
Roadmapper → ROADMAP.md
    │
    ▼
Aprovação do usuário → STATE.md inicializado

Fluxo de Execução de Fase

discuss-phase → CONTEXT.md (preferências do usuário)
    │
    ▼
ui-phase → UI-SPEC.md (contrato de design, opcional)
    │
    ▼
plan-phase
    ├── Portão de pesquisa (bloqueia se RESEARCH.md tiver perguntas abertas não resolvidas)
    ├── Pesquisador de Fase → RESEARCH.md
    │       └── Portão de Legitimidade de Pacotes: veredicto da API de registro em cada pacote; [SLOP] removido,
    │           [SUS]/[ASSUMED] sinalizados; tabela de Auditoria escrita no RESEARCH.md
    ├── Planner (com verificação de alcançabilidade) → arquivos PLAN.md
    │       └── checkpoint:human-verify injetado antes de instalações [ASSUMED]/[SUS];
    │           linha STRIDE T-{phase}-SC adicionada para planos com instalação
    ├── Plan Checker → Loop de verificação (máximo 3x)
    ├── Portão de cobertura de requisitos (REQ-IDs → planos)
    └── Portão de cobertura de decisões (CONTEXT.md `<decisions>` → planos, BLOQUEANTE — #2492)
    │
    ▼
state planned-phase → STATE.md (Planned/Ready to execute)
    │
    ▼
execute-phase (redução de contexto: prompts truncados, ordenação favorável ao cache)
    ├── Análise de ondas (agrupamento por dependência)
    ├── Executor por plano → código + commits atômicos
    ├── SUMMARY.md por plano
    └── Verifier → VERIFICATION.md
        └── Portão de cobertura de decisões (decisões do CONTEXT.md → artefatos entregues, NÃO BLOQUEANTE — #2492)
    │
    ▼
verify-work → UAT.md (testes de aceitação do usuário)
    │
    ▼
ui-review → UI-REVIEW.md (auditoria visual, opcional)

Propagação de Contexto

Cada estágio de workflow produz artefatos que alimentam as etapas subsequentes:

PROJECT.md ────────────────────────────────────────────► Todos os agentes
REQUIREMENTS.md ───────────────────────────────────────► Planner, Verifier, Auditor
ROADMAP.md ────────────────────────────────────────────► Orquestradores
STATE.md ──────────────────────────────────────────────► Todos os agentes (decisões, bloqueadores)
CONTEXT.md (por fase) ─────────────────────────────────► Researcher, Planner, Executor
RESEARCH.md (por fase) ────────────────────────────────► Planner, Plan Checker
PLAN.md (por plano) ───────────────────────────────────► Executor, Plan Checker
SUMMARY.md (por plano) ────────────────────────────────► Verifier, rastreamento de estado
UI-SPEC.md (por fase) ─────────────────────────────────► Executor, UI Auditor

---

Estrutura do Sistema de Arquivos

Arquivos de Instalação

~/.claude/                          # Claude Code (instalação global)
├── skills/gsd-*/SKILL.md           # Skills globais (roster oficial: docs/INVENTORY.md)
├── commands/gsd/*.md               # Instalações locais do Claude usam slash commands em vez de skills globais
├── gsd-core/
│   ├── bin/gsd-tools.cjs           # Utilitário CLI
│   ├── bin/lib/*.cjs               # Módulos de domínio (roster oficial: docs/INVENTORY.md)
│   ├── workflows/*.md              # Definições de workflow (roster oficial: docs/INVENTORY.md)
│   ├── references/*.md             # Docs de referência compartilhados (roster oficial: docs/INVENTORY.md)
│   └── templates/                  # Templates de artefatos de planejamento
├── agents/*.md                     # Definições de agentes (roster oficial: docs/INVENTORY.md)
├── hooks/*.js                      # Hooks Node.js (statusline, guards, monitors, verificação de atualização)
├── hooks/*.sh                      # Hooks shell (estado de sessão, validação de commit, limite de fase)
├── settings.json                   # Registros de hooks
└── VERSION                         # Número da versão instalada

Caminhos equivalentes para outros runtimes:

• OpenCode: ~/.config/opencode/ global ou ./.opencode/ local
• Kilo: ~/.config/kilo/ global ou ./.kilo/ local
• Codex: ~/.codex/ global ou ./.codex/ local
• Copilot: ~/.copilot/ global ou ./.github/ local
• Antigravity: raiz global detectada automaticamente (~/.gemini/antigravity/, ~/.gemini/antigravity-ide/, ou ~/.gemini/antigravity-cli/) ou ./.agent/ local
• Cursor: ~/.cursor/ global ou ./.cursor/ local
• Windsurf: ~/.codeium/windsurf/ global ou ./.windsurf/ local
• Augment Code: ~/.augment/ global ou ./.augment/ local
• Trae: ~/.trae/ global ou ./.trae/ local
• Qwen Code: ~/.qwen/ global ou ./.qwen/ local
• Hermes Agent: ~/.hermes/ global ou ./.hermes/ local
• CodeBuddy: ~/.codebuddy/ global ou ./.codebuddy/ local
• Cline: ~/.cline/ global ou .clinerules local na raiz do projeto

Arquivos do Projeto (.planning/)

.planning/
├── PROJECT.md              # Visão do projeto, restrições, decisões, regras de evolução
├── REQUIREMENTS.md         # Requisitos com escopo (v1/v2/fora do escopo)
├── ROADMAP.md              # Detalhamento de fases com rastreamento de status
├── STATE.md                # Memória viva: posição, decisões, bloqueadores, métricas
├── config.json             # Configuração de workflow
├── MILESTONES.md           # Arquivo de milestones concluídos
├── research/               # Pesquisa de domínio do /gsd-new-project
│   ├── SUMMARY.md
│   ├── STACK.md
│   ├── FEATURES.md
│   ├── ARCHITECTURE.md
│   └── PITFALLS.md
├── codebase/               # Mapeamento de brownfield (do /gsd-map-codebase ou /gsd-onboard)
├── onboarding/             # Resumo de onboarding brownfield (do /gsd-onboard)
│   ├── STACK.md            # Frontmatter YAML carrega `last_mapped_commit`
│   ├── ARCHITECTURE.md     # para o portão de desvio pós-execução (#2003)
│   ├── CONVENTIONS.md
│   ├── CONCERNS.md
│   ├── STRUCTURE.md
│   ├── TESTING.md
│   └── INTEGRATIONS.md
├── phases/
│   └── XX-phase-name/
│       ├── XX-CONTEXT.md       # Preferências do usuário (da discuss-phase)
│       ├── XX-RESEARCH.md      # Pesquisa de ecossistema (da plan-phase)
│       ├── XX-YY-PLAN.md       # Planos de execução
│       ├── XX-YY-SUMMARY.md    # Resultados de execução
│       ├── XX-VERIFICATION.md  # Verificação pós-execução
│       ├── XX-VALIDATION.md    # Mapeamento de cobertura de testes Nyquist
│       ├── XX-UI-SPEC.md       # Contrato de design de UI (da ui-phase)
│       ├── XX-UI-REVIEW.md     # Pontuações de auditoria visual (da ui-review)
│       └── XX-UAT.md           # Resultados de testes de aceitação do usuário
├── quick/                  # Rastreamento de tarefas rápidas
│   └── YYMMDD-xxx-slug/
│       ├── PLAN.md
│       └── SUMMARY.md
├── todos/
│   ├── pending/            # Ideias capturadas
│   └── completed/          # Todos concluídos
├── threads/               # Threads de contexto persistentes (do /gsd-thread)
├── seeds/                 # Ideias prospectivas (do /gsd-capture --seed)
├── debug/                  # Sessões de depuração ativas
│   ├── *.md                # Sessões ativas
│   ├── resolved/           # Sessões arquivadas
│   └── knowledge-base.md   # Aprendizados persistentes de depuração
├── ui-reviews/             # Screenshots do /gsd-ui-review (ignoradas pelo git)
└── continue-here.md        # Handoff de contexto (do pause-work)

Portão de Desvio de Código Base Pós-Execução (#2003)

Após a última onda de commits do /gsd-execute-phase, o workflow executa uma etapa codebase_drift_gate não bloqueante (entre schema_drift_gate e verify_phase_goal). Ele compara o diff last_mapped_commit..HEAD contra .planning/codebase/STRUCTURE.md e conta quatro tipos de elementos estruturais:

1. Novos diretórios fora dos caminhos mapeados
2. Novas exportações barrel em (packages|apps)/<name>/src/index.*
3. Novos arquivos de migração
4. Novos módulos de rota em routes/ ou api/

Se a contagem atingir workflow.drift_threshold (padrão 3), o portão avisa (padrão) com o comando /gsd-map-codebase --paths … sugerido, ou remapeia automaticamente (workflow.drift_action = auto-remap) criando gsd-codebase-mapper com escopo para os caminhos afetados. Qualquer erro na detecção ou remapeamento é registrado e a fase continua — a detecção de desvio não pode falhar a verificação.

last_mapped_commit fica no frontmatter YAML no topo de cada arquivo .planning/codebase/*.md; bin/lib/drift.cjs fornece os helpers de ida e volta readMappedCommit e writeMappedCommit.

---

Arquitetura do Instalador

O instalador (bin/install.js, ~10.700 linhas) trata de:

1. Detecção de runtime — Prompt interativo ou flags CLI (--claude, --opencode, --kimi, --kilo, --codex, --copilot, --antigravity, --cursor, --windsurf, --augment, --trae, --qwen, --hermes, --codebuddy, --cline, --all)
2. Seleção de local — Global (--global) ou local (--local)
3. Implantação de arquivos — Copia comandos, skills, workflows, referências, templates, agentes e hooks
4. Adaptação de runtime — Transforma o conteúdo de arquivos por runtime:

• Claude Code: Usa como está
• OpenCode: Converte comandos/agentes para o formato de comando plano + subagente compatível com OpenCode
• Kilo: Reutiliza o pipeline de conversão do OpenCode com os caminhos de configuração do Kilo
• Codex: Gera config TOML + skills a partir de comandos
• Copilot: Mapeia nomes de ferramentas (Read→read, Bash→execute, etc.)
• Antigravity: Skills em primeiro lugar com equivalentes de modelo do Google; ajusta nomes de eventos de hook (AfterTool em vez de PostToolUse)
• Cursor: Skills em primeiro lugar com referências de regras do Cursor
• Windsurf: Skills em primeiro lugar com referências de regras do Windsurf
• Trae: Instalação skills-first em ~/.trae / ./.trae sem settings.json ou integração de hooks
• Qwen Code: Skills em primeiro lugar com reescritas de caminho e prompt com marca Qwen
• Hermes Agent: Skills por categoria em skills/gsd/
• CodeBuddy: Skills em primeiro lugar com reescritas de caminho e prompt do CodeBuddy
• Cline: Escreve .clinerules para integração baseada em regras
• Augment Code: Skills em primeiro lugar com conversão completa de skills e gerenciamento de configuração

5. Normalização de caminhos — Substitui caminhos ~/.claude/ por caminhos específicos do runtime
6. Integração de configurações — Registra hooks no settings.json do runtime
7. Backup de patches — Desde a v1.17, faz backup de arquivos modificados localmente em gsd-local-patches/ para /gsd-update --reapply
8. Rastreamento de manifesto — Escreve gsd-file-manifest.json para desinstalação limpa
9. Modo de desinstalação — --uninstall remove todos os arquivos, hooks e configurações do GSD

Movimentações de arquivos no momento da instalação, limpeza de artefatos obsoletos, reescritas de configuração e preservação de dados do usuário são governadas pelo Módulo de Migração do Instalador. Consulte Migrações do Instalador e ADR 0008. O módulo de migração também controla o escaneamento de linha de base inicial condicionado para instalações legadas, classificando as superfícies de instalação de runtime conhecidas antes que migrações posteriores removam ou reescrevam qualquer coisa.

O guarda de desvio de plano (plan_review.source_grounding) — que verifica referências de símbolos em planos gerados contra o código-fonte ativo antes da execução — é especificado no ADR 22.

Tratamento de Plataforma

• Windows: windowsHide em processos filho, proteção EPERM/EACCES em diretórios protegidos, normalização de separador de caminho
• WSL: Detecta o Node.js do Windows rodando no WSL e avisa sobre incompatibilidades de caminho
• Docker/CI: Suporta a variável de ambiente CLAUDE_CONFIG_DIR para locais de diretório de configuração personalizados

---

Sistema de Hooks

Arquitetura

Motor de Runtime (Claude Code / Antigravity CLI)
    │
    ├── evento statusLine ──► gsd-statusline.js
    │   Lê: stdin (JSON de sessão)
    │   Escreve: stdout (status formatado), /tmp/claude-ctx-{session}.json (bridge)
    │
    ├── evento PostToolUse/AfterTool ──► gsd-context-monitor.js
    │   Lê: stdin (JSON de evento de ferramenta), /tmp/claude-ctx-{session}.json (bridge)
    │   Escreve: stdout (hookSpecificOutput com aviso additionalContext)
    │
    └── evento SessionStart ──► gsd-check-update.js
        Lê: arquivo VERSION
        Escreve: ~/.claude/cache/gsd-update-check.json (cria processo em segundo plano)

Limites do Monitor de Contexto

Contexto Restante	Nível	Comportamento do Agente
> 35%	Normal	Nenhum aviso injetado
≤ 35%	AVISO	"Evite iniciar trabalho complexo novo"
≤ 25%	CRÍTICO	"Contexto quase esgotado, informe o usuário"

Debounce: 5 usos de ferramenta entre avisos repetidos. A escalada de severidade (AVISO→CRÍTICO) contorna o debounce.

Propriedades de Segurança

• Todos os hooks encapsulam em try/catch, saem silenciosamente em caso de erro
• Guarda de timeout de stdin (3 s) evita travamento em problemas de pipe
• Métricas obsoletas (> 60 s) são ignoradas
• Arquivos bridge ausentes são tratados graciosamente (subagentes, sessões novas)
• O monitor de contexto é consultivo — nunca emite comandos imperativos que substituam as preferências do usuário

Portão de Legitimidade de Pacotes (v1.42.1)

O pipeline pesquisador → planner → executor inclui um portão de cadeia de suprimentos contra slopsquatting (nomes de pacotes alucinados por IA pré-registrados com scripts pós-instalação maliciosos).

Modelo de ameaça: O GSD automatiza o caminho completo de "pesquisador nomeia um pacote" a "executor executa npm install". Um nome alucinado que passa pelo npm view (provando apenas o registro, não a legitimidade) anteriormente fluía sem ser detectado. ~20% das referências de pacotes geradas por IA são alucinadas; ~43% desses nomes recorrem consistentemente entre prompts, tornando o pré-registro economicamente viável para atacantes.

Camadas do portão:

Camada	Componente	Ação
Pesquisa	gsd-phase-researcher	Executa gsd-tools query package-legitimacy check --ecosystem <npm|pypi|crates> <pkgs>; escreve tabela ## Package Legitimacy Audit no RESEARCH.md; remove pacotes [SLOP] antes de o RESEARCH.md ser escrito
Planejamento	gsd-planner	Lê a tabela de Auditoria; insere checkpoint:human-verify antes de qualquer tarefa de instalação [ASSUMED] ou [SUS]; adiciona linha STRIDE T-{phase}-SC supply-chain ao <threat_model>
Execução	gsd-executor	REGRA 3 exclui a instalação de pacotes do escopo de correção automática; instalações com falha surgem como checkpoints, nunca substituições silenciosas

Integração de proveniência de afirmações: Nomes de pacotes descobertos via WebSearch são marcados como [ASSUMED] (não [VERIFIED]) independentemente do resultado do npm view. Isso estende o sistema de proveniência [ASSUMED] / [VERIFIED] / [CITED] existente, aplicando a tag de proveniência como um portão rígido no limite de instalação — [ASSUMED] sempre gera um checkpoint:human-verify no PLAN.md.

Cobertura de ecossistemas: O pesquisador usa comandos de verificação específicos de registro — npm view (Node), pip index versions (Python), cargo search (Rust) — em vez de uma única verificação genérica. Isso captura alucinações entre ecossistemas (taxa de ~9% documentada em pesquisa USENIX de 2025).

Degradação graceful: Se o slopcheck não estiver disponível, cada pacote recomendado é marcado como [ASSUMED] e condicionado com um checkpoint. Pesquisa e planejamento prosseguem; o sistema nunca falha definitivamente por dependência de ferramenta ausente.

Dependência externa: slopcheck (MIT, instalável via pip). Se abandonado, o fallback do portão [ASSUMED] mantém a cobertura de checkpoint humano.

---

Hooks de Segurança (v1.27)

Para uma visão geral conceitual de como as camadas de hook e guarda se encaixam na abordagem de segurança mais ampla, consulte Modelo de segurança.

Prompt Guard (gsd-prompt-guard.js):

• Acionado em Write/Edit para arquivos .planning/
• Escaneia o conteúdo em busca de padrões de injeção de prompt (substituição de papel, bypass de instrução, injeção de tag de sistema)
• Apenas consultivo — registra a detecção, não bloqueia
• Padrões são embutidos (subconjunto de security.cjs) para independência do hook

Workflow Guard (gsd-workflow-guard.js):

• Acionado em Write/Edit para arquivos fora de .planning/
• Detecta edições fora do contexto de workflow do GSD (sem comando /gsd- ativo ou subagente Task)
• Aconselha o uso de /gsd-quick ou /gsd-fast para alterações rastreadas por estado
• Ativado via hooks.workflow_guard: true (padrão: false)

---

Abstração de Runtime

O GSD suporta múltiplos runtimes de codificação com IA por meio de uma arquitetura unificada de comandos/workflows:

Matriz de Contrato de Instalação por Runtime

Esta matriz descreve as superfícies de runtime que o instalador materializa hoje. A propriedade específica de migração e os snapshots de fonte vivem em Migrações do Instalador.

Runtime	Raiz global	Raiz local	Superfície de invocação	Superfície de agente	Configuração e hooks
Claude Code	~/.claude	./.claude	skills/gsd-*/SKILL.md global; commands/gsd/*.md local	agents/gsd-*.md	Entradas de hook e statusLine em settings.json
OpenCode	~/.config/opencode	./.opencode	command/gsd-*.md	agents/gsd-*.md	opencode.json ou opencode.jsonc; sem hooks do GSD
Kilo	~/.config/kilo	./.kilo	command/gsd-*.md	agents/gsd-*.md	kilo.json ou kilo.jsonc; sem hooks do GSD
Codex	~/.codex	./.codex	skills/gsd-*/SKILL.md	markdown de origem de agentes mais TOML por agente	config.toml [agents.gsd-*], [features].hooks (canônico; alias legado codex_hooks é reconhecido e migrado no reinstall, #3566) e tabelas de hooks
GitHub Copilot	~/.copilot	./.github	skills/gsd-*/SKILL.md e copilot-instructions.md	arquivos .agent.md	Sem hooks ou statusline do GSD
Antigravity	detectado automaticamente: ~/.gemini/antigravity, ~/.gemini/antigravity-ide, ou ~/.gemini/antigravity-cli	./.agent	skills/gsd-*/SKILL.md	agents/gsd-*.md	Entradas de hook settings.json no estilo Gemini quando instalado pelo GSD
Cursor	~/.cursor	./.cursor	skills/gsd-*/SKILL.md	agents/gsd-*.md	Referências de regras em rules/; sem hooks do GSD
Windsurf	~/.codeium/windsurf	./.windsurf	skills/gsd-*/SKILL.md	agents/gsd-*.md	Referências de regras em rules/; sem hooks do GSD
Augment Code	~/.augment	./.augment	skills/gsd-*/SKILL.md	agents/gsd-*.md	Sem hooks ou statusline do GSD
Trae	~/.trae	./.trae	skills/gsd-*/SKILL.md	agents/gsd-*.md	Referências de regras em rules/; sem hooks do GSD
Qwen Code	~/.qwen	./.qwen	skills/gsd-*/SKILL.md	agents/gsd-*.md	Configurações comuns do GSD e entradas de hook onde suportado
Hermes Agent	~/.hermes	./.hermes	skills/gsd/DESCRIPTION.md mais skills/gsd/gsd-*/SKILL.md	agents/gsd-*.md	Configurações comuns do GSD e entradas de hook onde suportado
CodeBuddy	~/.codebuddy	./.codebuddy	skills/gsd-*/SKILL.md	agents/gsd-*.md	Configurações comuns do GSD e entradas de hook onde suportado
Cline	~/.cline	raiz do projeto	.clinerules	Somente regras	Sem hooks ou statusline do GSD

Fontes do Contrato Upstream

As expectativas de instalação por runtime são verificadas contra documentação primária quando disponível. O snapshot de fonte atual é 2026-05-11:

• Claude Code: Documentação de comandos slash, configurações, hooks e subagentes da Anthropic.
• OpenCode e Kilo: Documentação de configuração do OpenCode e documentação de subagente customizado do Kilo.
• Qwen Code: Documentação de comandos/configuração; a documentação de comandos do Qwen foi atualizada pela última vez em 2026-05-06.
• Codex: Documentação do OpenAI Codex e config-schema.json; o instalador também carrega compatibilidade com o Codex 0.124.0 para o formato de tabela de agentes.
• Copilot, Cursor, Cline, Augment, Hermes e CodeBuddy: Documentação do fornecedor para instruções customizadas, regras, skills ou configuração.
• Antigravity, Windsurf e Trae: Linhas com fontes limitadas. O instalador documenta os shims de compatibilidade atuais, e as migrações devem atualizar essas fontes antes de reescrever sua configuração.

Pontos de Abstração

1. Mapeamento de nomes de ferramentas — Cada runtime tem seus próprios nomes de ferramentas (ex.: Bash do Claude → execute do Copilot)
2. Nomes de eventos de hook — Claude usa PostToolUse, Antigravity usa AfterTool
3. Frontmatter de agente — Cada runtime tem seu próprio formato de definição de agente
4. Convenções de caminho — Cada runtime armazena a configuração em diretórios diferentes
5. Referências de modelo — O perfil inherit permite que o GSD adie para a seleção de modelo do runtime

O instalador trata de toda a tradução no momento da instalação. Workflows e agentes são escritos no formato nativo do Claude Code e transformados durante a implantação.

---

Relacionados

• Orquestração multi-agente
• Modelo de segurança
• Ferramentas CLI
• Índice de documentação