Skill spec-council
Você está executando a skill /spec-council. Execute todas as fases em ordem. Não pule fases.
Regras Rígidas
- Nunca modifique o código-fonte
- Nunca escreva diretamente em
.specify/— essa é a infraestrutura própria do GitHub Spec Kit (templates/,scripts/,memory/,feature.json,integration.json). Se as skills próprias do Spec Kit estiverem instaladas (veja Fase 0), delegue a elas e deixe que gerenciem esse estado; você nunca toca nele diretamente. - O único diretório no qual você escreve diretamente é o diretório de funcionalidade desta execução (
<FEATURE_DIR>, resolvido na Fase 0/1) — especificamente seu subdiretóriocouncil/sempre, e seus arquivosspec.md/plan.md/tasks.mdapenas quando as skills próprias do Spec Kit não estiverem instaladas e você estiver usando os modelos de fallback. - Mostre ao usuário o spec.md antes de prosseguir para o plano, a menos que a flag
--autoseja passada - Os agentes do conselho executam sequencialmente — nunca em paralelo
- Se qualquer agente do conselho emitir
BLOCK, pare e apresente as descobertas antes de continuar - Um BLOCKER corrigido deve ser re-verificado por uma nova execução do mesmo agente antes de continuar — não aceite a palavra de sua própria emenda. Forneça ao agente seu próprio relatório anterior mais os artefatos emendados e peça que ele confirme explicitamente a correção em relação à fonte, não apenas releia o novo texto.
- Uma CONCERN corrigida não requer uma re-execução completa do agente, mas nunca deixe seu relatório original afirmando silenciosamente que o problema ainda está aberto — acrescente uma linha de adendo a esse relatório observando o que mudou e que não foi re-verificado de forma independente. Um relatório não emendado é um registro desatualizado que o próximo agente (ou um humano) aceitará pelo valor de face.
Fase 0 — Inicialização
-
Determine a raiz do projeto (diretório contendo
CLAUDE.md/AGENTS.md, ou o diretório de trabalho atual). -
Detecte se o GitHub Spec Kit está instalado neste projeto:
test -d .specify && echo "SPECKIT_PRESENT" || echo "NO_SPECKIT"Não use
which specifypara isso — isso apenas verifica se o binário CLI está instalado globalmente nesta máquina, o que não informa se este projeto usa o Spec Kit. -
Detecte se as skills de fluxo de trabalho nativas do agente do Spec Kit estão instaladas (independente de qual agente você é — verifique ambas as raízes conhecidas, qualquer uma conta):
test -f .claude/skills/speckit-specify/SKILL.md -o -f .cursor/skills/speckit-specify/SKILL.md && echo "HAS_SPECKIT_SKILLS" || echo "NO_SPECKIT_SKILLS"Armazene como
HAS_SPECKIT_SKILLS(verdadeiro/falso). Estas são skills reais e abrangentes (ganchos de branch git, tratamento de[PRECISA DE ESCLARECIMENTO], validação de lista de verificação de qualidade) — quando presentes, as Fases 1–3 abaixo delegam inteiramente a elas em vez de reimplementar qualquer uma dessas funcionalidades. -
Obtenha a descrição da funcionalidade:
- Se a skill foi invocada com argumentos (ex.:
/spec-council adicionar redefinição de senha), use esses como a descrição. - Se não houver argumentos, pergunte ao usuário (por meio de uma ferramenta de escolha estruturada como o
AskUserQuestiondo Claude Code, se disponível, caso contrário, texto simples de chat): "Qual funcionalidade ou alteração devo especificar? Descreva em 1 a 3 frases."
- Se a skill foi invocada com argumentos (ex.:
-
Leia
CLAUDE.mde/ouAGENTS.md(raiz do projeto, e aninhados comoapi/CLAUDE.mdse presente) para carregar o contexto da arquitetura do projeto. Injete isso em cada prompt de geração e entregue a cada agente do conselho abaixo.
<FEATURE_DIR> ainda não é conhecido neste ponto — é resolvido durante a Fase 1, seja pela skill speckit-specify do próprio Spec Kit ou pela lógica de fallback abaixo.
Fase 1 — Especificação (spec.md)
Objetivo: produzir uma especificação de funcionalidade e aprender <FEATURE_DIR> para cada fase após esta.
Se HAS_SPECKIT_SKILLS = verdadeiro:
Leia o conteúdo completo de qualquer um destes que exista — .claude/skills/speckit-specify/SKILL.md ou .cursor/skills/speckit-specify/SKILL.md — e siga-o como suas instruções na íntegra, passando a descrição da funcionalidade como entrada. Deixe que ele lide com numeração, ganchos de branch git, prompts de [PRECISA DE ESCLARECIMENTO] e validação de lista de verificação de qualidade inteiramente em seus próprios termos; não questione ou reimplemente nada disso.
Após sua conclusão, leia .specify/feature.json e pegue seu campo feature_directory como <FEATURE_DIR> (ex.: specs/012-quote-export-print). Este é o registro autoritativo do próprio Spec Kit para a funcionalidade atual — use-o, não derive o caminho você mesmo.
Se HAS_SPECKIT_SKILLS = falso:
Resolva <FEATURE_DIR> você mesmo:
- Se
specs/não existir, ele será criado abaixo. - Varra
specs/em busca de diretóriosNNN-*existentes, encontre o maiorNNN, adicione 1 (preenchido com zero para 3 dígitos). Se nenhum existir, comece em001. - Transforme a descrição da funcionalidade em um nome curto em kebab-case (2–4 palavras, ex.: "Renderização de cotação amigável para PDF/impressão" →
quote-export-print). <FEATURE_DIR>=specs/<NNN>-<slug>mkdir -p <FEATURE_DIR>
Escreva <FEATURE_DIR>/spec.md diretamente. Use a seguinte estrutura:
# Especificação: <Nome da Funcionalidade>
## Visão Geral
<O que esta funcionalidade faz e por que é necessária. 2 a 4 frases.>
## Requisitos
1. <Requisito funcional>
2. ...
## Critérios de Aceitação
1. <Critério verificável — formato "dado X, quando Y, então Z" preferido>
2. ...
## Restrições Técnicas
- <Padrões, bibliotecas ou regras existentes que devem ser respeitados>
- <Limites arquiteturais que este projeto impõe (modelo de isolamento, soft-delete apenas, etc.), se houver>
## Fora do Escopo
- <Exclusões explícitas para evitar aumento de escopo>
Use o contexto de CLAUDE.md/AGENTS.md do projeto para preencher as Restrições Técnicas com precisão.
Após a especificação ser escrita (qualquer caminho):
Mostre ao usuário <FEATURE_DIR>/spec.md. Pergunte (por meio de uma ferramenta de escolha estruturada se disponível, caso contrário, texto simples de chat):
"A especificação está pronta. Prosseguir para o plano, ou devo esclarecer requisitos primeiro?"
- Se esclarecer: gere um agente
forkcom o prompt: "Leia<FEATURE_DIR>/spec.md. Faça ao usuário até 5 perguntas de esclarecimento direcionadas sobre ambiguidades, depois reescreva incorporando as respostas. Não altere a estrutura." (SeHAS_SPECKIT_SKILLSe uma skillspeckit-clarifyexistir na mesma raiz quespeckit-specify, prefira delegar a ela — é construída exatamente para isso.) - Se prosseguir: continue.
Fase 2 — Plano (plan.md)
Objetivo: produzir <FEATURE_DIR>/plan.md
Se HAS_SPECKIT_SKILLS = verdadeiro:
Leia e siga .claude/skills/speckit-plan/SKILL.md ou .cursor/skills/speckit-plan/SKILL.md (o que existir) na íntegra. Ele resolve a funcionalidade atual automaticamente (via .specify/scripts/bash/setup-plan.sh ou equivalente) — você não precisa passar <FEATURE_DIR> você mesmo.
Se HAS_SPECKIT_SKILLS = falso:
Escreva <FEATURE_DIR>/plan.md usando esta estrutura, informado por <FEATURE_DIR>/spec.md e pelo CLAUDE.md/AGENTS.md do projeto:
# Plano: <Nome da Funcionalidade>
## Abordagem
<Decisões de arquitetura. Quais padrões/camadas são usados. Por quê.>
## Arquivos / Módulos Afetados
- `caminho/para/arquivo.ts` — <quais alterações>
- ...
## Etapas de Implementação
1. <Título da etapa> (deps: nenhuma)
<Descrição de 1 a 2 linhas>
2. <Título da etapa> (deps: etapa 1)
...
## Riscos
- <Risco> — <Mitigação>
Fase 3 — Tarefas (tasks.md)
Objetivo: produzir <FEATURE_DIR>/tasks.md
Se HAS_SPECKIT_SKILLS = verdadeiro:
Leia e siga .claude/skills/speckit-tasks/SKILL.md ou .cursor/skills/speckit-tasks/SKILL.md (o que existir) na íntegra. Mesma auto-resolução da Fase 2.
Se HAS_SPECKIT_SKILLS = falso:
Escreva <FEATURE_DIR>/tasks.md. Cada tarefa deve ser atômica (1 PR ou menos) e testável independentemente:
# Tarefas: <Nome da Funcionalidade>
## Lista de Verificação
- [ ] T1: <Título> — <Descrição de 1 linha> (deps: nenhuma)
- [ ] T2: <Título> — <Descrição de 1 linha> (deps: T1)
- [ ] T3: <Título> — <Descrição de 1 linha> (deps: T1)
- [ ] T4: <Título> — <Descrição de 1 linha> (deps: T2, T3)
## Notas
<Quaisquer notas sobre sequenciamento ou paralelismo>
Fase 4 — Revisão do Conselho
A este ponto <FEATURE_DIR> é conhecido (da Fase 1, seja via .specify/feature.json ou sua própria resolução de fallback). Crie seu subdiretório council:
mkdir -p <FEATURE_DIR>/council
Execute 4 agentes sequencialmente, um subagente isolado por revisor. Esta é uma escolha de design, não uma limitação de ferramenta — cada revisor constrói explicitamente sobre as descobertas dos anteriores, então os agentes posteriores precisam que os relatórios anteriores já existam. Execute-os em paralelo e você perde isso (cada um começaria de zero descobertas), mesmo em um runtime que suporta execuções paralelas.
Cada agente executa como seu próprio subagente isolado, não inline neste thread:
- Claude Code: a ferramenta
Agentcomsubagent_type: "fork". - Cursor: a ferramenta
Taskcomsubagent_type: "generalPurpose"— confirmado para gerar um subagente genuinamente isolado sem visibilidade do contexto pai, sem necessidade de um arquivo.cursor/agents/*.mdexistir primeiro para esse tipo.
Use o que seu runtime fornecer. Ambos dão a mesma propriedade da qual esta fase depende: um subagente que vê apenas o que está em seu prompt, não o histórico deste thread.
Os arquivos de persona residem no diretório personas/ desta skill, próximo a este arquivo. Resolva o caminho relativo a este SKILL.md — não assuma um caminho relativo ao diretório de trabalho.
Para cada agente, gere o subagente isolado com o modelo de prompt abaixo. Em cada modelo, <PERSONA> significa: leia o conteúdo completo do arquivo de persona nomeado do diretório personas/ desta skill e siga-o como suas instruções para essa fase, incluindo suas próprias seções "antes de começar" e "saída". Diga a cada agente explicitamente para qual <FEATURE_DIR> foi resolvido nesta execução — as personas esperam ser informadas disso, não adivinhar. Como o subagente não tem visibilidade deste thread, seu prompt deve ser totalmente autocontido — não faça referência a nada como "conforme discutido acima", reafirme.
Agente 1 — Revisor de Domínio
Prompt:
<PERSONA: personas/domain-reviewer.md>
Diretório da funcionalidade para esta execução: <FEATURE_DIR>
Leia também, se presente:
- <FEATURE_DIR>/spec.md
- <FEATURE_DIR>/plan.md
- <FEATURE_DIR>/tasks.md
- .specify/memory/constitution.md
Após o agente concluir, leia <FEATURE_DIR>/council/01-domain.md e verifique se há BLOCK. Se BLOCK encontrado, pare a Fase 4, mostre as descobertas ao usuário (por meio de uma ferramenta de escolha estruturada se disponível, caso contrário, texto simples de chat) e pergunte: "O Revisor de Domínio bloqueou esta especificação. Alterar spec/plan/tasks e re-executar, ou ignorar e continuar?"
Agente 2 — Guardião de Arquitetura
Prompt:
<PERSONA: personas/architecture-guardian.md>
Diretório da funcionalidade para esta execução: <FEATURE_DIR>
Leia também:
- <FEATURE_DIR>/spec.md
- <FEATURE_DIR>/plan.md
- <FEATURE_DIR>/tasks.md
- <FEATURE_DIR>/council/01-domain.md
Verifique se há BLOCK antes de continuar (mesmo tratamento do Agente 1).
Agente 3 — Auditor de Segurança
Prompt:
<PERSONA: personas/security-auditor.md>
Diretório da funcionalidade para esta execução: <FEATURE_DIR>
Leia também, se presente:
- <FEATURE_DIR>/spec.md
- <FEATURE_DIR>/plan.md
- <FEATURE_DIR>/tasks.md
- <FEATURE_DIR>/council/01-domain.md
- <FEATURE_DIR>/council/02-architecture.md
- .specify/memory/constitution.md
Verifique se há BLOCK antes de continuar.
Agente 4 — Planejador de QA
Prompt:
<PERSONA: personas/qa-planner.md>
Diretório da funcionalidade para esta execução: <FEATURE_DIR>
Leia também:
- <FEATURE_DIR>/spec.md
- <FEATURE_DIR>/plan.md
- <FEATURE_DIR>/tasks.md
- <FEATURE_DIR>/council/01-domain.md
- <FEATURE_DIR>/council/02-architecture.md
- <FEATURE_DIR>/council/03-security.md
Verifique se há BLOCK antes de continuar.
Fase 5 — Síntese
-
Leia todos os quatro relatórios do conselho de
<FEATURE_DIR>/council/:01-domain.md02-architecture.md03-security.md04-qa.md
Antes de contabilizar, verifique cada relatório em relação ao estado atual de
spec.md/plan.md/tasks.md: se uma CONCERN foi corrigida por edição direta após a redação desse relatório e o relatório nunca foi re-verificado (veja Regras Rígidas), não a conte como aberta na tabela de resumo abaixo — mas diga explicitamente ("funcionalmente resolvido, relatório não re-verificado — veja nota") em vez de descartá-la silenciosamente ou apresentá-la como ainda aberta. Ambos são desonestos; apenas uma reconciliação rotulada é precisa. -
Colete cada item
BLOCKEReCONCERNem todos os relatórios. -
Para cada BLOCKER que requer uma nova tarefa de implementação (não apenas uma edição de especificação), acrescente-a a
<FEATURE_DIR>/tasks.md:- [ ] TC1: [Conselho] <título> — <o que implementar para resolver o bloqueador> (deps: <tarefa relevante>)Prefixe tarefas adicionadas pelo conselho com
[Conselho]. -
Escreva
<FEATURE_DIR>/council/REPORT.md:
# Relatório do Conselho — Resumo
| Agente | Veredito | Bloqueadores | Preocupações |
|--------|----------|--------------|--------------|
| Revisor de Domínio | <veredito> | <contagem> | <contagem> |
| Guardião de Arquitetura | <veredito> | <contagem> | <contagem> |
| Auditor de Segurança | <veredito> | <contagem> | <contagem> |
| Planejador de QA | <veredito> | <contagem> | <contagem> |
## Todos os Bloqueadores
<lista de todos os relatórios>
## Todas as Preocupações
<lista de todos os relatórios>
## Tarefas Adicionadas pelo Conselho
<lista de tarefas TC* adicionadas, ou "Nenhuma">
## Status Final
APROVADO | APROVADO_COM_PREOCUPACOES | BLOQUEADO
-
Mostre ao usuário
<FEATURE_DIR>/tasks.md(final) e<FEATURE_DIR>/council/REPORT.md. -
Imprima:
"Conselho concluído. Artefatos em
<FEATURE_DIR>. Pegue as tarefas em seu gerenciador de tarefas ou em seu fluxo de implementação usual."
Fase 6 — Acompanhamento da Implementação
Esta fase é executada durante e após a implementação (não durante a execução do conselho em si).
Regra: Toda vez que uma tarefa de <FEATURE_DIR>/tasks.md for totalmente implementada (código escrito, testes passando), atualize-a imediatamente:
Altere:
- [ ] T<n>: <título> ...
Para:
- [x] T<n>: <título> ...
Faça isso por tarefa, assim que for concluída — não em lote no final. Isso mantém tasks.md como um rastreador de progresso ao vivo durante toda a sessão de implementação.
Se várias tarefas forem concluídas em uma única etapa, atualize todas elas antes de prosseguir.
Mapa de Artefatos
specs/<NNN>-<slug-da-funcionalidade>/ ← <FEATURE_DIR>. Número/slug escolhido pela skill
speckit-specify do próprio Spec Kit quando
instalada, ou pela lógica de fallback abaixo.
├── spec.md Especificação da funcionalidade
├── plan.md Plano de implementação
├── tasks.md Lista de tarefas (rastreável)
└── council/ Revisões do conselho
├── 01-domain.md Revisor de Domínio
├── 02-architecture.md Guardião de Arquitetura
├── 03-security.md Auditor de Segurança
├── 04-qa.md Planejador de QA
└── REPORT.md Relatório de síntese do conselho
Notas Finais
- Sempre que o Spec Kit estiver instalado (
HAS_SPECKIT_SKILLS = verdadeiro), a skill delega a geração de especificação, plano e tarefas para as skills nativas do agente, que são mais abrangentes e lidam com numeração, ramificação git e validação de qualidade automaticamente. - A revisão do conselho é o mecanismo central de garantia de qualidade: quatro perspectivas diferentes (domínio, arquitetura, segurança, QA) examinam os artefatos antes da implementação, reduzindo drasticamente o risco de retrabalho.
- O sistema de bloqueio/preocupação garante que problemas críticos sejam resolvidos antes do prosseguimento, enquanto preocupações menores são documentadas sem paralisar o progresso.