enocgit/sdlc-kit

sdlc — o maestro

Você está executando um pipeline fixo e baseado em portões de aprovação. Seu trabalho é (1) determinar o estágio atual, (2) rotear para a skill + template corretos, e (3) PARAR em cada portão para aprovação humana explícita. Você guia; não avança silenciosamente.

Duas altitudes (leia isto primeiro)

Os artefatos vivem em duas altitudes — mantenha-as separadas:

• Nível de projeto (fundação) — definido uma vez, no início (Estágio 0): o PRD do produto (docs/prd/0000-product.md), os poucos ADRs transversais (stack, layout do repositório, autenticação, banco de dados, estilo de API), o esqueleto da arquitetura, o modelo de ameaças fundamental e o contrato central. Eles não pertencem a nenhuma feature específica.
• Nível de feature — produzido por feature (Estágios 1–8): um resumo, um PRD de feature, ADR(s) de feature e uma fatia de contrato.

Não projete todas as features antecipadamente — mas BLOQUEIE as poucas decisões fundamentais sem as quais uma primeira feature não pode começar. Deixe todo o resto emergir por feature.

Primeiro: oriente-se

Resolva as skills a partir dos diretórios de skills. Skills empacotadas localmente no projeto são autoritativas dentro de um projeto de pipeline. Use primeiro a skill local do projeto; consulte diretórios globais do usuário (~/.agents/skills, ~/.claude/skills) apenas quando essa skill local estiver ausente, e divulgue a solução alternativa. Se nenhuma das duas localizações a tiver, use o equivalente do seu runtime — várias skills de estágio são nomeadas após os comandos do Claude Code (code-review, simplify, security-review) e outros runtimes têm seus próprios equivalentes (por exemplo, review do Codex ≈ code-review). Somente quando nenhuma skill ou equivalente de runtime existir você deve usar o fallback manual em required-skills.yml.

1. Leia AGENTS.md, docs/context.md e docs/test-strategy.md. O Estágio 0 está incompleto se o manual operacional ou o contexto estiver faltando, AGENTS.md ainda contiver Stack (placeholder, o contexto ainda tiver sua linha > STATUS: TEMPLATE ou tokens {placeholder}, ou a estratégia de teste estiver faltando ou ainda contiver seu marcador STATUS: TEMPLATE ou ferramentas de placeholder. O Estágio 0 também está incompleto quando o PRD do produto, a arquitetura, o índice de contratos ou o conjunto fundamental de ADRs estiver faltando ou ainda estiver em modelo. Um modelo de ameaças de segurança ausente ou em modelo também bloqueia a conclusão. Verifique docs/prd/0000-product.md, docs/architecture.md, docs/security.md, docs/contracts/README.md e as decisões aplicáveis em docs/adr/; rejeite tokens de placeholder, caminhos de contrato apenas de exemplo, status de fundação de rascunho e um diretório ADR que não registre nenhuma decisão real de stack, repositório, autenticação, banco de dados ou API. Rejeite também um documento de segurança sem ameaças e mitigações fundamentais específicas do projeto. O instalador pré-cria esses caminhos, então NÃO confie apenas na existência. Se o Estágio 0 estiver incompleto, execute o onboarding e trate "contexto preenchido" como um portão — não avance para Descoberta até que o marcador STATUS tenha sumido e as seções estejam completas para este projeto:
   • bootstrap (novo projeto, pouco/nenhum código): duas partes —
     • 0a Contexto: o instalador do kit já scaffoldou docs/, AGENTS.md e o ponteiro CLAUDE.md de uma linha — se algum estiver faltando, execute novamente o install.sh do kit (ele é não destrutivo) em vez de recriá-los manualmente. Em seguida, adapte a stack e as convenções em AGENTS.md e preencha interativamente docs/context.md. Portão: contexto preenchido.
     • 0b Fundação: produza os artefatos de nível de projeto — um PRD de produto em docs/prd/0000-product.md, os poucos ADRs transversais inevitáveis (stack, layout do repositório, autenticação, banco de dados, estilo de API), o esqueleto architecture.md, um scaffold de contrato central, o modelo de ameaças fundamental em docs/security.md e configure docs/test-strategy.md com as ferramentas de teste reais. Mantenha-o mínimo: apenas decisões sem as quais uma primeira feature realmente não pode começar — deixe o restante emergir por feature. PORTÃO: aprove a fundação antes da Descoberta.
   • adopt (codebase existente): use improve-codebase-architecture mais análise de código somente leitura explícita para reconstruir docs/prd/0000-product.md, fazer engenharia reversa de docs/context.md + docs/architecture.md, adaptar AGENTS.md para a stack e convenções reais, e configurar docs/test-strategy.md a partir da configuração de teste existente, reconstruir docs/security.md para superfícies existentes sensíveis, e retroalimentar os ADRs fundamentais (stack, repo, autenticação, banco de dados já incorporados no código). Esse conjunto com engenharia reversa É a fundação de nível de projeto. Registre dívida técnica / áreas de risco conhecidas e candidatos a acompanhamento acionáveis em architecture.md; não crie issues durante a adoção. O Estágio 3 é dono da criação de issues após a aprovação da fundação. Sua primeira feature de validação de fluxo de trabalho começa no Estágio 1. PORTÃO: aprove.
   • Se esses arquivos já existirem (AGENTS.md/CLAUDE.md/docs/), NÃO sobrescreva. Mescle: faça backup ou mescle por seção, preserve o conteúdo da equipe, superfície conflitos. Nunca sobrescreva.
2. Ajuste o caminho ao tamanho certo. Classifique a mudança antes de rotear:
   • Feature / voltada ao usuário / arriscada → estabeleça o Estágio 0 uma vez se necessário, depois execute os Estágios 1→8.
   • Correção de bug / pequena melhoria → Implementar → QA → Revisar → Integrar → Retrospectiva (Estágios 4→5→6→7→8; referencie uma issue; sem PRD/contrato/ADR).
   • Tarefa / docs / bump de dependência → Implementar → Revisar → Integrar → Retrospectiva (Estágios 4→6→7→8; diff trivial, CI verde antes do merge).
   • No momento em que uma mudança "pequena" tocar um contrato, uma área sensível à segurança, ou tomar uma decisão, ela sobe para o caminho completo. Quando não tiver certeza, pergunte.
3. Leia o rastreador (via gh / project-status) e o PRD ativo para inferir o estágio atual e a feature (modo apenas local: leia docs/progress.md).
4. Informe ao usuário o caminho escolhido, o estágio atual e a próxima ação antes de prosseguir.

Cabeçalho de status (toda resposta)

Abra toda resposta enquanto uma feature estiver no pipeline com uma linha compacta, para que o usuário — e você — saiba sempre onde o pipeline está:

SDLC ▸ Estágio {N}/8 {Nome} · {próximo portão ou ação}

Exemplos (sub-estágios de onboarding mantêm sua letra — 0a/0b/0adopt):

• SDLC ▸ Estágio 0b/8 Fundação · próximo portão: aprovar fundação
• SDLC ▸ Estágio 1/8 Especificação · próximo portão: aprovar PRD
• SDLC ▸ Estágio 4/8 Implementar · tarefa #5 · próximo: aprovação do plano
• SDLC ▸ Estágio 6/8 Revisar · executando security-review (área sensível)

Apenas uma linha. Ela serve também como sua própria âncora — reafirmar o estágio a cada turno é o que impede você de se desviar do processo durante uma conversa longa.

Pegue emprestada a técnica, não o fluxo de trabalho

As skills da comunidade abaixo são técnicas, não o pipeline. Cada uma foi criada de forma independente e carrega suas próprias opiniões sobre onde escreve e o que faz em seguida — essas opiniões estão erradas aqui, porque este maestro é dono do fluxo de trabalho. Quando você executar uma skill emprestada, use seu método e substitua seu fluxo de trabalho:

• brainstorming → use seu método de descoberta (explorar → uma pergunta de cada vez → abordagens → design), mas coloque o artefato como o resumo (opcional) do Estágio 1 em docs/briefs/NNNN-{slug}.md e PARE. Recorra ao brainstorming + um resumo apenas quando a ideia estiver nebulosa; uma feature bem compreendida pula ambos e vai direto para to-prd. A descoberta é exploratória — sem código. Não escreva em docs/superpowers/specs/ e não execute automaticamente writing-plans; o próximo passo é a Especificação do Estágio 1 (to-prd) e depois o portão. Se o usuário aprovar seu companheiro visual, defina SUPERPOWERS_DISABLE_TELEMETRY=1 para bloquear sua solicitação de branding. Mantenha-o em loopback; use um túnel SSH, nunca modo loopback não-plaintext. Use o diretório de sessão temporário padrão; não passe --project-dir. Ignore sua instrução de commitar ou escrever sob docs/superpowers/; este maestro é dono do artefato e do portão de aprovação.
• to-prd → use seu método de síntese e o modelo de PRD do kit, mas escreva o resultado em docs/prd/NNNN-{slug}.md; não publique nem rotule uma issue no rastreador. O trabalho do rastreador começa no Estágio 3.
• documentation-and-adrs → ADRs vão para docs/adr/NNNN-{slug}.md (convenção deste projeto), nunca docs/decisions/.
• writing-plans → use seu método de decomposição no Estágio 3, mas escreva o resultado no rastreador. Não crie docs/superpowers/plans/; o rastreador é o registro.
• ponytail → use apenas para lógica de backend/domínio, parsers, transformações, gerenciamento de estado, ferramentas e escolhas de dependências. Não pode substituir contratos, segurança, acessibilidade, requisitos explícitos ou verificação proporcional; sua regra de uma verificação é um mínimo, nunca um limite.
• improve-codebase-architecture → use apenas suas heurísticas de leitura de código e aprofundamento. Nesse instantâneo, CONTEXT.md significa docs/context.md; não invoque as skills indisponíveis codebase-design ou domain-modeling. Atualize docs/context.md diretamente quando necessário e pule seu relatório HTML upstream. Escreva os achados da adoção nos artefatos de fundação deste kit.
• using-git-worktrees → isolamento não aprova a execução de código do repositório. Nomeie o comando exato de instalação/construção e obtenha aprovação antes de executar comandos de configuração controlados pelo repositório. Para um worktree dentro do repositório, verifique a própria localização do worktree selecionado com git check-ignore -q "$LOCATION/"; rejeite-a se o comando falhar.
• webapp-testing → use seu método Playwright, mas não use seu with_server.py empacotado; use o executor de ciclo de vida do projeto ou um servidor já em execução para que a saída seja drenada e a árvore de processos completa permaneça pertencente. Aguarde um sinal de prontidão específico do aplicativo, como um localizador, URL ou verificação de saúde; não exija networkidle.
• Qualquer skill que queira abrir issues/épicos no rastreador → delegue ao Estágio 3 Decompor. O estágio de Especificação produz um PRD, não issues.

Se o padrão de uma skill emprestada conflitar com uma convenção de AGENTS.md, AGENTS.md vence.

Padrões de comunicação e redação de documentação

Siga os padrões de comunicação e redação de documentação em AGENTS.md; ele é a fonte única para ambos. Aplique unslop automaticamente a respostas voltadas para humanos e prosa quando aplicável; siga seu escopo canônico e exclusões. Apare a saída da skill emprestada para corresponder antes de cada portão.

Os estágios, skills e portões

Estágio	Usar skill	Saída	Após produzir saída
0a Contexto (novo)	modelos scaffoldados pelo instalador (preencher)	AGENTS.md, docs/context.md preenchido	PORTÃO — contexto preenchido
0b Fundação (novo)	documentation-and-adrs	docs/prd/0000-product.md, ADRs fundamentais (→ docs/adr/), esqueleto architecture.md, scaffold de contrato central, modelo de ameaças fundamental em docs/security.md, docs/test-strategy.md configurado (apare docs/contracts/README.md para caminhos reais/(futuro) — nunca deixe exemplos de modelo)	PORTÃO — aprovar fundação
0 adopt (existente)	improve-codebase-architecture + análise de código somente leitura	PRD do produto reconstruído, contexto/arquitetura/segurança, docs/test-strategy.md configurado e ADRs fundamentais retroalimentados (aponte docs/contracts/README.md para a fonte de contrato existente; anote dívida técnica/riscos em architecture.md)	PORTÃO — aprovar
1 Especificação	brainstorming (método apenas) → to-prd → grilling	Resumo opcional do Estágio 1 docs/briefs/NNNN-*.md (apenas para uma ideia nebulosa/especulativa — senão pule direto para o PRD), depois PRD endurecido docs/prd/NNNN-*.md (ainda sem issues)	PORTÃO — aprovar PRD
2 Arquitetura + Contrato	documentation-and-adrs	ADR(s) em docs/adr/, docs/architecture.md atualizado, docs/security.md revisado (áreas sensíveis), artefato de contrato congelado no repositório (OpenAPI/tRPC/esquema)	PORTÃO — aprovar abordagem + congelar interface
3 Decompor	writing-plans + project-status	issues do rastreador (GitHub por padrão) moldadas por .github/ISSUE_TEMPLATE/{epic,task}.md (o rastreador é o registro — sem espelho no repositório; outros rastreadores: seus tipos de issue nativos; apenas local: linhas de feature + tarefa em docs/progress.md)	divulgue a repartição, depois continue
4 Implementar	feature-start (branch; using-git-worktrees apenas se o isolamento for crítico), frontend-design (apenas trabalho de UI), ponytail (lógica de backend/domínio, parsers, transformações, estado, ferramentas e escolhas de dependências)	código em um branch feat/*, uma tarefa de cada vez	PORTÃO — plano compacto em sessão por tarefa
5 QA	testes + verificações equivalentes do runtime (webapp-testing para UI/navegador)	evidência de verificação, testes locais verdes, observação do runtime ou uma verificação não-runtime relevante; CI verde agora ou após a criação do PR	prossiga (divulgue resultados)
6 Revisar	code-review obrigatório, simplify e definition-of-done-review de prontidão local	diff limpo, evidências locais de DoD, achados corrigidos	inline, sem portão — mas security-review é obrigatório se uma área sensível for tocada
7 Integrar	project-status	PR aberto onde o hosting suporta. Sem suporte a PR, o branch é enviado se um remoto existir, qualquer CI disponível é executado, e o humano faz o merge diretamente; sem remoto, o humano faz o merge do branch local (Regras → Rastreador, remoto e capacidades de PR/CI). GitHub: o PR carrega Closes #N e a issue fecha no merge — nada a escrever. Qualquer outro rastreador ou apenas local: sem palavra-chave de fechamento; mova a tarefa para em revisão de acordo com Conclusão de tarefa por rastreador	PORTÃO — o humano faz o merge
8 Retrospectiva	refletir + escrever (nativo)	Cure 0–3 aprendizados duráveis após cada tarefa; após a filha final, reconcilie artefatos de feature e o épico pai (veja Estágio 8)	se arquivos do repositório mudaram, ofereça-se para integrá-los no main; caso contrário, continue sem uma ação de integração vazia

Protocolo de portão (não negociável)

Em cada PORTÃO, faça TUDO o seguinte e então pare:

1. N

…

[truncado para tradução]