spec-a23

name	spec-a23
description	Workflow de spec-driven development para Claude Code, focado em VELOCIDADE e BAIXO CUSTO de tokens, mas com regras pesadas de SEGURANÇA, qualidade, review e testes. Cria estrutura completa de implementação em pastas .md (resumo, visão geral, research, fases) na pasta `implementacao/<slug>/` do projeto, pré-cria todas as fases e subfases de uma vez para discussão única, executa cada subfase via subagent em modelo padrão e effort padrão e VALIDA tudo (segurança, qualidade, testes, correções) com o modelo da sessão. Use sempre que o usuário falar sobre planejar, implementar, especificar, criar implementação, ajustar feature, refatorar módulo, migrar sistema, ou pedir spec/roadmap de qualquer demanda técnica. Use quando o usuário disser /spec-a23 ou citar 'spec a23'. Funciona em qualquer stack — detecta a linguagem/framework do projeto e segue as convenções existentes. Toda interação e todos os documentos em PT-BR com acentuação correta.
argument-hint	Descreva a demanda/implementação que deseja planejar e executar

spec-a23 — Spec-Driven Implementation (Claude Code, A23)

Você transforma demandas em uma estrutura completa de implementação documentada, com fases atômicas e subfases auto-executáveis. A prioridade é velocidade e baixo custo de tokens, mas com regras pesadas e inegociáveis de segurança, qualidade e validação.

A skill é exclusiva para Claude Code e usa subagents, hooks e ferramentas do harness para reduzir o atrito do usuário e acelerar o fluxo.

---

REGRAS MÁXIMAS (não negociáveis)

1. 🔒 SEGURANÇA é o fator principal. Toda fase tem security-review obrigatório (ver references/security-rules.md). Nada vai pra "concluído" sem passar.
2. 🇧🇷 PT-BR com acentuação correta em TUDO: discovery, docs .md, mensagens da sessão, retornos de API e textos de frontend gerados nas fases. Nunca trocar acentos por ASCII (ex: nunca "nao" — sempre "não").
3. ⚡ Custo e velocidade são prioridade, mas qualidade NÃO é negociável. Discovery é proporcional à demanda — curto para tarefas simples, profundo para tarefas complexas. Nunca cortar etapas de validação para ganhar velocidade.
4. 📁 Output prioritário em .md — a sessão emite o mínimo possível de texto. Tudo que importa vai pra arquivo. A sessão só comunica: status, perguntas, checkpoints e blockers.
5. 🤖 Construção via subagent em modelo padrão e effort padrão (sem especificar model/effort) — sempre. Validação, testes, review de segurança, review de qualidade e correções pelo MODELO DA SESSÃO — nunca delegar isso a subagent (a menos que o usuário peça explicitamente outro agent).
6. 💬 Discussão única — depois do discovery, todas as fases e subfases são apresentadas de uma vez. O usuário discute tudo, aprova tudo, e só então a skill cria os .md em paralelo.
7. 🧠 Use a memória do projeto (MEMORY.md em .claude/projects/.../memory/) para puxar feedback prévio, regras críticas e contexto antes do discovery — reduz perguntas e evita repetir erros do passado.
8. 🌳 Commit obrigatório por fase. Ao final de cada fase, depois que TODOS os reviews passaram (security, quality, testes, validação final), a sessão comita as mudanças com mensagem em PT-BR no padrão do repo (feat(escopo): FASE-XX — <título>), referenciando a fase. Preferir adicionar arquivos específicos a git add -A/. (evita incluir secrets/binários acidentais). Nunca --no-verify. Push só sob comando explícito do usuário. O hash do commit vai pro log da fase. Builder agent NÃO comita — só a sessão. Detalhes em agents/reviewer.md.

---

Como invocar

/spec-a23 [descrição da demanda]

Exemplos:

• /spec-a23 adicionar painel de relatórios de vendas com export CSV/PDF
• /spec-a23 migrar autenticação de JWT cookie para refresh token rotation
• /spec-a23 criar fluxo de checkout com PIX, cartão e split de pagamento

---

Estrutura de Output (obrigatória)

Tudo dentro do projeto, em pasta dedicada:

implementacao/<slug>/
├── README.md               ← índice navegável (links pros docs e fases)
├── 00-VISAO-GERAL.md       ← objetivo, escopo (dentro/fora), estado atual vs desejado, riscos macro, stakeholders
├── 01-RESUMO.md            ← resumo executivo curto (TL;DR — 1 página)
├── 02-RESEARCH.md          ← pesquisa técnica, padrões aplicáveis, decisões de arquitetura, referências
├── 10-LOG-EXECUCAO.md      ← log vivo (formato em [`templates/10-LOG-EXECUCAO.md`](./templates/10-LOG-EXECUCAO.md))
├── evidencias/             ← screenshots, dumps, logs de validação (criada sob demanda)
└── fases/
    ├── FASE-00-<nome>.md   ← uma fase = um conjunto coeso de mudanças
    ├── FASE-01-<nome>.md
    └── ...

Slug = kebab-case derivado da demanda (ex: painel-relatorios-vendas, auth-refresh-rotation, checkout-pix-split). Se já existir uma pasta com o mesmo slug, criar <slug>-v2.

Cada arquivo de fase contém:

• Objetivo, dependências, duração estimada, entregável
• Subfases (A, B, C, D, …) — cada subfase é uma unidade construível por subagent
• Para CADA subfase: o que construir, arquivos afetados, padrões a seguir, critérios de validação, checks de segurança, testes, review de qualidade
• Riscos e mitigações
• Comandos de verificação

Templates prontos em templates/.

---

Fluxo (5 fases sequenciais)

Fase	Nome	Quem faz	Output
F0	Discovery proporcional	Sessão	Contexto consolidado em memória
F1	Auto-geração de docs base	Subagent (paralelo)	README.md, 00, 01, 02, 10 em disco
F2	Pré-criação textual das fases + subfases	Sessão	Apresentação única na sessão para discussão
F3	Geração paralela dos .md de fase	Subagent (paralelo)	fases/FASE-XX-*.md em disco
F4	Execução fase a fase (loop)	Subagent constrói + sessão valida	Código + log atualizado

---

F0 — Discovery proporcional à demanda

Princípio: discovery é o suficiente para garantir qualidade. Curto para demandas simples, profundo para demandas complexas. Nunca cortar perguntas críticas para ganhar velocidade.

F0.1 — Classificar a demanda

Categorize internamente:

Tipo	Exemplos	Discovery esperado
Trivial	Ajuste de copy, fix bug pontual, ajuste visual isolado	0–2 perguntas, pode até pular F0
Simples	Novo CRUD pequeno, novo endpoint, nova página estática	3–5 perguntas, 1 rodada
Média	Feature com UI + API + DB, integração externa simples	6–10 perguntas, 1–2 rodadas
Complexa	Refator estrutural, migração de subsistema, multi-módulo	10–20 perguntas, 2–3 rodadas, possivelmente Architecture Overview
Épica	Sistema novo inteiro, redesenho de domínio	Faça o Architecture Overview primeiro (ver F0.5)

A classificação NÃO é compartilhada com o usuário — é interna pra calibrar o discovery.

F0.2 — Pré-discovery (sem perguntar nada ainda)

Antes de qualquer pergunta, explore o projeto em paralelo para reduzir perguntas:

1. Ler memória — MEMORY.md em .claude/projects/.../memory/ e arquivos referenciados. Puxa feedback, regras críticas, preferências.
2. Ler CLAUDE.md — instruções do projeto.
3. Ler .claude/napkin.md se existir (skill napkin) — runbook curado do repo.
4. Listar implementacao/ — pra evitar duplicar slug e pra reaproveitar padrão de SPECs anteriores.
5. Detectar stack via arquivos de manifesto (package.json, pyproject.toml/requirements.txt, go.mod, Cargo.toml, composer.json, Gemfile, pom.xml, etc.) e configs de framework — usar Glob + Grep em paralelo, NÃO subagent (mais barato).
6. Detectar convenções do projeto — estrutura de pastas, modelos/entidades, rotas, camada de dados, biblioteca de UI — referenciar nas fases.
7. Skills relacionadas ao domínio da demanda — se a demanda for SEO, invocar seo-audit para diagnóstico antes do discovery; se for sobre Claude API/SDK, invocar claude-api. Reduz perguntas de discovery porque a skill especializada já levanta o estado atual.

Apresentar uma linha curtinha com o que detectou (não detalhar muito — economizar tokens):

🔍 Detectei: <stack do projeto — ex: Django + PostgreSQL + React>. Pasta `implementacao/` ativa. Memória do projeto carregada.

F0.3 — Discovery em rodadas

Rodada 1 — perguntas obrigatórias agrupadas por tema. Use o template em references/discovery-questions.md. Selecione perguntas baseado no que ainda é UNKNOWN após F0.2.

Sempre aborde, no mínimo:

• Domínio / regra de negócio chave
• Modelo de dados / impacto no banco
• Segurança e autorização (obrigatório — ver references/security-rules.md)
• Performance / escala quando aplicável
• Compliance (LGPD, PCI, etc.) quando aplicável
• Validação / testes — como o usuário quer validar (manual, automatizado, smoke, dupla validação SSR+DOM em apps com SSR)

Formato:

📋 **Discovery — rodada 1**

**Domínio e regras de negócio**
1. [pergunta] _(sugestão se inferível)_
2. ...

**Dados e persistência**
3. ...

**🔒 Segurança e autorização** _(obrigatório)_
4. ...

**Validação e testes**
5. ...

💡 Se preferir, posso seguir com as sugestões padrão e você corrige no checkpoint.

Rodada 2 (e seguintes) — apenas se respostas levantarem novos UNKNOWNS críticos. Não force rodadas extras só pra parecer detalhista.

F0.4 — Checkpoint do discovery

Resumo curto + opções:

📝 **Resumo do que entendi:**
- Demanda: ...
- Entidades: ...
- Atores e permissões: ...
- 🔒 Modelo de segurança: ...
- Validação esperada: ...

🔄 **O que deseja fazer?**
1. ✅ Continuar — gerar docs base + pré-criar fases
2. ➕ Adicionar / corrigir algo
3. 🔍 Discutir alternativa de arquitetura
4. ❓ Mais perguntas

Avançar APENAS quando o usuário confirmar.

F0.5 — Architecture Overview (apenas para demanda Épica)

Quando a demanda for grande demais pra uma única SPEC, gere primeiro um architecture-overview.md em implementacao/<slug>/ cobrindo: bounded contexts, integrações entre módulos, ordem de implementação, infra compartilhada. Depois siga F1+ tratando cada bounded context como uma SPEC menor (ou cada um como uma fase, dependendo do tamanho).

---

F1 — Auto-geração paralela dos docs base

Após confirmação no checkpoint do discovery, um único subagent (modelo padrão, effort padrão) cria em paralelo TODOS os arquivos base, lendo os templates em templates/:

• implementacao/<slug>/README.md
• implementacao/<slug>/00-VISAO-GERAL.md
• implementacao/<slug>/01-RESUMO.md
• implementacao/<slug>/02-RESEARCH.md
• implementacao/<slug>/10-LOG-EXECUCAO.md

Use o prompt em agents/md-builder.md. Pase o contexto consolidado do discovery, NUNCA invente — se faltou info, marca [ASSUMPTION: ...] no doc.

A sessão não repete o conteúdo dos docs após gerar — só confirma:

📄 Docs base criados em `implementacao/<slug>/`:
  - README.md, 00-VISAO-GERAL.md, 01-RESUMO.md, 02-RESEARCH.md, 10-LOG-EXECUCAO.md

Em seguida, avança automaticamente pra F2 (sem comando do usuário).

---

F2 — Pré-criação textual das fases + subfases (DISCUSSÃO ÚNICA)

Esse é o ponto crítico do fluxo.

A sessão (modelo da sessão, NÃO subagent — porque envolve julgamento de design) elabora a quebra em fases e subfases e apresenta TUDO de uma vez para discussão única.

Princípios de quebra

• Fase = conjunto coeso de mudanças, com objetivo claro e entregável testável.
• Subfase = unidade construível por subagent em uma única sessão dele — máximo 30–45 min de trabalho de agent.
• Ordem das fases segue dependências (data model → core logic → API → UI → integrações → polish).
• Cada fase contém OBRIGATORIAMENTE as etapas de validação:
  • Construção (subagent em modelo padrão, effort padrão) — invocar frontend-design ANTES da construção quando a subfase tiver UI nova
  • Testes (sessão escreve/roda)
  • 🔒 Security review (sessão — checklist em references/security-rules.md + invocar skill security-review em fases sensíveis)
  • Quality review (sessão — checklist em references/quality-rules.md + opcionalmente skill simplify)
  • Correções (sessão — sempre que validação falhar)
  • Validação final (sessão executa critérios de aceite da fase) — usar mcp__chrome-devtools__* para validação dupla quando UI

Formato da apresentação

Apresentar como árvore hierárquica enxuta. Não colar todo o conteúdo — só o esqueleto (1 linha por subfase). O .md detalhado vem depois, em F3.

📐 **Plano de fases proposto** (discutir tudo de uma vez):

▸ FASE-00 — <nome curto>
   Objetivo: ...
   Entregável: ...
   Subfases:
     A. <título> — arquivos: <paths> · valida: <o que prova que tá certo>
     B. <título> — ...
     C. <título> — ...
   🔒 Security: <pontos específicos desta fase>
   ✅ Quality gates: testes <unit/int/e2e>, review de <pontos>

▸ FASE-01 — ...
▸ FASE-02 — ...
...

🔄 **O que deseja fazer?**
1. ✅ Está bom — gerar os .md das fases
2. ✏️ Ajustar fase X (descreva o que mudar)
3. ➕ Adicionar/remover fase ou subfase
4. 🔀 Reordenar dependências
5. 📊 Detalhar mais [segurança / testes / arquitetura]

Iterar quantas vezes o usuário quiser. Só avançar pra F3 quando ele aprovar tudo.

---

F3 — Geração paralela dos .md das fases

Disparar UM subagent (modelo padrão, effort padrão) que cria todos os arquivos fases/FASE-XX-*.md em paralelo (cada Write é uma chamada independente). Usar o template em templates/FASE-template.md. Prompt em agents/md-builder.md.

Cada .md de fase contém:

• Cabeçalho (objetivo, dependências, duração, entregável)
• Cada subfase com: descrição, arquivos, padrões, critérios de aceite, checklist de segurança, estratégia de teste, comandos de verificação
• Riscos e mitigações
• Bloco "Log da fase" (checklist marcado durante execução)

Confirmação curta:

📄 Fases criadas em `implementacao/<slug>/fases/`: <N> arquivos.
Pronto para iniciar execução. Rodar com: `executar fase 00` (ou diga "iniciar fase X").

---

F4 — Execução fase a fase

Para cada fase, o loop é:

para cada subfase:
  1. [Subagent — modelo padrão, effort padrão] CONSTRUÇÃO
  2. [Sessão] TESTES — escrever/rodar testes
  3. [Sessão] 🔒 SECURITY REVIEW — checklist obrigatório
  4. [Sessão] QUALITY REVIEW — checklist obrigatório
  5. [Sessão] CORREÇÕES — se algum review falhou, voltar pra (1) com diff específico
  6. [Sessão] VALIDAÇÃO FINAL — critérios de aceite da subfase
  7. [Sessão] LOG — atualizar 10-LOG-EXECUCAO.md (resultado, evidências, blockers)

ao terminar todas as subfases:
  8. [Sessão] CRITÉRIO DE ACEITE DA FASE — rodar validações da fase inteira
  9. [Sessão] LOG DE FASE — fechamento
  10. [Sessão] PERGUNTAR AO USUÁRIO — fase X concluída, seguir pra fase X+1?

Quem usa qual modelo

Etapa	Quem
Construção	Subagent (modelo padrão, effort padrão) — ver agents/builder.md
Testes	Sessão
Security review	Sessão
Quality review	Sessão
Correções pós-review	Sessão (a menos que o usuário peça outro agent)
Validação final	Sessão
Atualização de log	Sessão

O usuário pode override: "use Opus para construir esta fase" ou "use Haiku, é simples". Respeite.

Comando de execução

Quando o usuário disser "executar fase X" ou "iniciar fase X" ou variantes:

1. Ler fases/FASE-XX-*.md completo
2. Para cada subfase, executar o loop acima
3. Atualizar 10-LOG-EXECUCAO.md ao final de cada subfase E ao final da fase

Não execute mais de uma fase sem confirmação do usuário — ele pode querer revisar entre fases.

Comportamento se uma validação falha

• Pequeno desvio: a sessão corrige direto (mais barato e rápido).
• Mudança grande: re-disparar subagent com prompt corretivo (diff exato do que precisa mudar).
• Bloqueio externo (ex: dependência ausente, decisão de produto): pausar, perguntar ao usuário, registrar no log.

---

Ferramentas integradas (skills, MCPs e comandos do Claude Code)

A skill deve acionar outras ferramentas do harness sempre que se aplicarem. Não reinventar o que já existe.

⚠️ Regra inegociável — subagents NÃO acessam Skill/MCP

Subagents disparados via Agent tool não enxergam o Skill tool nem os MCPs registrados na sessão. Eles têm apenas as ferramentas built-in (Read, Write, Edit, Bash, Grep, Glob, WebFetch, etc.).

Por isso, toda skill ou MCP que a subfase precisar é executada PELA SESSÃO ANTES de delegar, e o output é embutido no prompt do builder como contexto resolvido. O builder só implementa.

Padrão de injeção:

1. Sessão identifica que a subfase precisa de uma skill (ex: tem UI nova → frontend-design).

2. Sessão invoca Skill(frontend-design, args=...) — recebe specs de design, hierarquia de componentes, tokens, breakpoints.

3. Sessão monta o prompt do builder colando o output da skill em uma seção marcada:

   # CONTEXTO DE SKILL JÁ RESOLVIDO PELA SESSÃO
   ## frontend-design — implementar fielmente
   <colar output da skill aqui>
   

4. Builder agent recebe esse contexto pronto, sem precisar invocar nada.

Mesma lógica para MCP: se a validação de UI exige chrome-devtools, a sessão é quem roda — depois do builder terminar.

Mapa de quem invoca o quê:

Recurso	Invocado por	Quando
Skill(frontend-design)	Sessão, antes de delegar	F2 (planejamento) e F4 (antes de cada subfase com UI)
Skill(claude-api)	Sessão, antes de delegar	Antes de subfase que toca @anthropic-ai/sdk
Skill(seo-audit)	Sessão	F0.2 (pré-discovery) e F4 (página pública nova)
Skill(security-review)	Sessão	F4, ao final da fase, ANTES do commit
Skill(simplify)	Sessão	F4, ao final de fase grande
mcp__chrome-devtools__*	Sessão	Validação pós-construção em subfases de UI
mcp__sequential-thinking__*	Sessão	Trade-offs arquiteturais em F0.5/F1
mcp__fetch__*	Sessão	Research em F1
Read/Write/Edit/Bash/Grep/Glob	Builder ou sessão	Ambos

Em resumo: subagent recebe um prompt completo e auto-contido. Skills/MCPs são "pré-processadores" que a sessão usa pra montar esse prompt. Nunca peça pro builder invocar skill — ele não consegue.

Skills do Claude Code (invocar via Skill tool)

Skill	Quando usar dentro do spec-a23
frontend-design	Em F2 (planejamento) e F4 (execução) sempre que a fase tiver UI nova ou redesenho. Sessão invoca antes de delegar e cola o output no prompt do builder na seção # CONTEXTO DE SKILL JÁ RESOLVIDO. Builder não chama.
seo-audit	Em F0.2 (pré-discovery) quando a demanda mencionar SEO, ranking, indexação, tráfego. Em F4 quando a fase incluir página pública nova.
security-review	Em F4, ao final de fase com mudanças sensíveis (auth, pagamento, upload, multi-tenant). Complementa o checklist de references/security-rules.md — a sessão roda os dois.
review	Quando o usuário pedir review de PR aberto durante a execução.
simplify	Após uma fase grande, antes de fechar — pra revisar reuso/qualidade no que o builder produziu.
schedule	Ao fim de uma SPEC com follow-up natural (cleanup de feature flag, soak window, métrica a verificar) — oferecer agendar agente futuro.
napkin	Sempre lida no início do projeto — entra junto com MEMORY.md em F0.2.
claude-api	Se a fase mexer em código que importa @anthropic-ai/sdk — disparar antes de mexer em prompt/tool config.

MCPs disponíveis (invocar quando aplicável)

MCP	Quando usar
mcp__chrome-devtools__*	Validação de UI em F4 (subfases com frontend): navigate_page + take_snapshot + take_screenshot + list_console_messages + lighthouse_audit. Padrão "validação dupla" em apps com SSR (curl do HTML cru + DOM hidratado, com sleep 3 após navegação).
mcp__sequential-thinking__sequentialthinking	Em F0.5 (Architecture Overview de demanda épica) e em F1 (raciocínio sobre trade-offs arquiteturais complexos). Não usar pra coisa simples — custa tokens.
mcp__memory__*	Complementar ao MEMORY.md da auto-memory. Salvar entidades/relações cross-session de SPEC grandes (ex: Coupon como entidade com relações). Ler em F0.2.
mcp__filesystem__*	Alternativa ao Read/Write quando precisar de operações em lote ou diretórios fora do CWD. Padrão é usar Read/Write/Glob/Grep do harness.
mcp__fetch__*	Pesquisa web em F0/F1 (research técnico). Salvar achados relevantes em 02-RESEARCH.md.
mcp__wuzapi__*	Apenas se a fase envolver integração com WhatsApp (envio de mensagens, webhooks, sessão).

Ferramentas nativas do harness

• Agent (subagent_type: general-purpose, sem especificar model/effort — herda o padrão da sessão) — F1, F3 e construção em F4. Sempre seguir prompts em agents/builder.md e agents/md-builder.md.
• Glob + Grep — F0.2 pré-discovery (paralelo).
• Read — leitura direta de templates, MEMORY.md, CLAUDE.md, fases.
• Edit — correções pequenas em F4 review (mais barato que reagent).
• Bash — rodar testes, curl de validação, git status/diff/log.
• TaskCreate — apenas se a SPEC tiver muitas fases (≥ 5) e o usuário quiser tracking visual. Default: usar o log da SPEC.

Como decidir entre skill embutida vs raciocínio próprio

• Tem skill que cobre exatamente o caso (frontend-design, seo-audit, security-review)? → invocar skill.
• É decisão de arquitetura única dessa SPEC? → raciocínio próprio (sessão).
• É código que precisa rodar em paralelo / volumoso? → subagent.
• É review final? → sessão (com possível chamada à skill security-review ou simplify no fim).

---

Checklists obrigatórios (referências)

A sessão usa essas referências durante reviews — leia-as quando for executar a fase, não no momento da geração da SPEC.

• 🔒 Segurança: references/security-rules.md — input validation, authn/authz, injection, data exposure, secrets, rate limit, CSRF, SSRF, deserialização insegura, headers, log seguro.
• ✅ Qualidade: references/quality-rules.md — testes, manutenibilidade, observabilidade, performance, acessibilidade, padrões do projeto.
• 📋 Discovery: references/discovery-questions.md — banco de perguntas por categoria.
• 🤖 Subagent prompts: agents/builder.md, agents/md-builder.md, agents/reviewer.md.

Templates

• templates/README.md
• templates/00-VISAO-GERAL.md
• templates/01-RESUMO.md
• templates/02-RESEARCH.md
• templates/10-LOG-EXECUCAO.md
• templates/FASE-template.md

---

Modo Autopilot (execução autônoma com gate de usage)

Disparado quando o usuário diz qualquer variante de:

• "modo autopilot", "modo automático", "deixa rodando", "pode seguir sozinho"
• "vou dormir, [continue/execute/pause em X%]"
• "executa tudo até acabar", "não me pergunte"
• "pause em 90% e retome no reset"

Princípios do autopilot (NÃO negociáveis)

1. Decisão é da skill, não do usuário. No autopilot a sessão decide tudo: classificação de risco, escolha de padrão, correção de review, qual subfase fazer primeiro, quando agrupar testes. Nunca para pra perguntar — escolhe a opção mais segura e segue, registrando a decisão no log.
2. Toda validação humana vira validação automática + tarefa de teste manual documentada. Onde a SPEC original previa "smoke manual pelo Janderson", o autopilot:
   • Roda a validação automatizada equivalente (curl, MCP chrome-devtools, lighthouse, snapshot, etc.).
   • Registra no 10-LOG-EXECUCAO.md uma seção "Testes humanos pendentes" com passos detalhados pra você executar quando acordar.
3. Pendências de produto/decisão de negócio NÃO param a execução. Se aparecer "esse comportamento depende de o cliente decidir" → escolhe o default mais conservador documentado no 02-RESEARCH.md, marca [ASSUMPTION-AUTOPILOT: ...] e segue. Cria entrada em "Decisões pendentes de revisão" no log.
4. Só para de vez se for blocker técnico irrecuperável. Definição estrita:
   • Falha de build/teste/lint que persiste após 2 tentativas de correção pelo modelo.
   • Dependência externa indisponível (banco caiu, npm registry fora, gateway de pagamento sem credencial real e a fase EXIGE chamada real).
   • Conflito de merge com mudanças desconhecidas no branch que o modelo não consegue resolver com segurança.
   • Limite de plano semanal (weekly_pct ≥ 95%) com reset > 24h. Em qualquer outro caso: prossegue. Reviews de segurança/qualidade/teste que o modelo conseguir resolver sozinho, ele resolve sozinho.
5. Nunca usa --no-verify, nunca dá git push, nunca executa operação destrutiva irreversível (apagar dados, remover arquivos de config/segredos, force-push). As regras destrutivas continuam valendo — o autopilot não "afrouxa" segurança pra terminar.
6. Sempre comita por fase, mesmo no autopilot — exatamente como em modo manual.

Gate de usage (5h + semanal via API oficial OAuth)

Antes de cada subfase a sessão roda:

bash ~/.claude/skills/spec-a23/scripts/check-usage.sh

O script consulta GET https://api.anthropic.com/api/oauth/usage — mesmo endpoint que o slash /usage usa internamente. Lê o accessToken OAuth de ~/.claude/.credentials.json (escopos user:inference + user:profile, gerados pelo login do Claude Code). Retorna percentuais reais do plano Max/Pro, sem inferência. Cache local de 90s em $TMPDIR/spec-a23-usage-cache.json evita 429.

JSON de saída:

{
  "gate": "GO|CAUTION|PAUSE",
  "reason": "5h X% | semanal Y%",
  "five_hour":  { "pct_used": 65.0, "resets_at": "ISO timestamp" },
  "seven_day":  { "pct_used": 60.0, "resets_at": "ISO timestamp" },
  "config":     { "pause_pct": 90, "caution_pct": 85, "cache_ttl_sec": 90, "source": "api.anthropic.com/api/oauth/usage" }
}

Variáveis opcionais: SPEC_A23_PAUSE_PCT (default 90), SPEC_A23_CAUTION_PCT (default 85), SPEC_A23_USAGE_TTL (default 90s).

Códigos de saída: 0 ok · 1 API falhou · 2 credencial ausente / token expirado · 3 node não encontrado.

Decisão do gate: trigger_pct = max(five_hour.pct_used, seven_day.pct_used).

gate	Condição	Ação no autopilot
GO	trigger_pct < 85%	Executa subfase normalmente
CAUTION	85% ≤ trigger_pct < 90%	Executa apenas se a subfase for "leve" (< 5 arquivos, sem subagent pesado). Caso contrário trata como PAUSE.
PAUSE	trigger_pct ≥ 90%	Pausa autopilot e dorme até resets_at da janela que disparou

Bloqueio semanal duro: se seven_day.pct_used ≥ 95% e resets_at - now > 24h, registrar blocker no log e parar de vez (não adianta ScheduleWakeup).

ccusage foi descontinuado nesta skill — divergia do /usage real (denominador inferido). Não voltar a usar.

Como pausar e retomar (uso de ScheduleWakeup)

ScheduleWakeup aceita delay máximo de 1h (3600s). O autopilot faz polling em janelas de 1h até passar do reset_at:

1. Calcular wait_seconds = min(reset_at - now + 60s_buffer, 3600)
2. Atualizar log: entrada ## YYYY-MM-DD HH:mm — AUTOPILOT PAUSE com usage_pct, reset_at, próximo wake em <wait_seconds>s.
3. Chamar ScheduleWakeup com delaySeconds=wait_seconds, reason="autopilot pausa por usage X% — proximo check em Yh", prompt="<<retomar autopilot da fase X subfase Y>>".
4. Quando acordar: re-rodar gate. Se ainda PAUSE → repete passo 2. Se GO ou CAUTION → registra ## YYYY-MM-DD HH:mm — AUTOPILOT RESUME no log e segue.
5. Janela semanal: se weekly_pct ≥ 95% e reset > 24h → registra blocker, para de vez, deixa o usuário acordar e decidir.

Aviso obrigatório ao entrar em autopilot

Quando o autopilot é ativado, a sessão emite uma única mensagem pro usuário e depois entra em modo silencioso (só log):

🤖 Modo autopilot ativado.

Configuração:
  - Gate de usage (5h + semanal, fonte: /api/oauth/usage oficial): PAUSE em ≥ 90%, CAUTION em ≥ 85%
  - Bloqueio semanal duro: ≥ 95% com reset > 24h
  - Validações humanas: serão executadas como automáticas e documentadas em "Testes humanos pendentes"
  - Decisões de produto: usarei o default conservador e marcarei como [ASSUMPTION-AUTOPILOT]
  - Commit por fase: continua valendo

⚠️ Mantenha o Claude Code aberto — o autopilot depende da sessao ativa.
   Se fechar o terminal/laptop, a execucao para ate voce reabrir.

📄 Acompanhamento em: implementacao/<slug>/10-LOG-EXECUCAO.md
🛑 Pra interromper: digite "parar autopilot".

Iniciando da fase X subfase Y.

Depois disso, silêncio — só fala quando: blocker irrecuperável, mensagem do usuário, ou conclusão da SPEC inteira.

Seção do log no autopilot

A sessão acrescenta no 10-LOG-EXECUCAO.md (em adição ao formato normal):

## YYYY-MM-DD HH:mm — AUTOPILOT START

- Modo: autopilot
- Iniciado em: FASE-XX subfase Y
- Gate config: PAUSE 90% / CAUTION 85% / weekly blocker 95%
- Estimativa de fases restantes: <N>

## YYYY-MM-DD HH:mm — AUTOPILOT PAUSE

- Motivo: usage 5h = X% (limite >= 90%) | weekly = Y%
- reset_at: ISO timestamp
- ScheduleWakeup em: <segundos>s
- Próxima ação ao acordar: re-checar gate

## YYYY-MM-DD HH:mm — AUTOPILOT RESUME

- usage 5h = X% | weekly = Y%
- Retomando: FASE-XX subfase Y

## YYYY-MM-DD HH:mm — DECISÃO AUTÔNOMA

- Contexto: <onde apareceu>
- Opção escolhida: <X>
- Alternativas descartadas: <lista curta>
- Justificativa: <por que essa é a mais conservadora/segura>
- Marcado como: [ASSUMPTION-AUTOPILOT: ...] (se aplicável)

## TESTES HUMANOS PENDENTES (acumulativo)

> Esta seção fica no topo do log e é atualizada continuamente.
> Quando o usuário acordar, validar manualmente:

### FASE-XX subfase Y — <título>
- [ ] <passo 1: ex. "Abrir /admin/cupons e clicar em Criar — verificar que modal abre">
- [ ] <passo 2>
- [ ] Critério: <como saber que passou>

## DECISÕES PENDENTES DE REVISÃO (acumulativo)

> Decisoes tomadas com [ASSUMPTION-AUTOPILOT] que voce pode querer ajustar:

- FASE-XX: <decisão> — corrigir editando <arquivo> se preferir <alternativa>

Comando de interrupção

Se o usuário digitar "parar autopilot" / "stop autopilot" / "pause" a qualquer momento (mesmo via wakeup), a sessão:

1. Termina a subfase em andamento (não para no meio).
2. Comita o que conseguiu.
3. Sai do autopilot, registra ## AUTOPILOT STOP no log, retorna controle.

Limitações honestas (mostrar uma vez ao ativar)

• Depende da sessão local ativa — laptop fechado mata o autopilot.
• O endpoint /api/oauth/usage é interno do Claude Code (não documentado publicamente) — pode mudar de schema sem aviso. Se gate retornar erro, conferir resposta crua com bash check-usage.sh --raw.
• Token OAuth expira (expiresAt em .credentials.json) — Claude Code aberto faz refresh automático; se rodar com Claude fechado por dias, o script retorna exit 2 e pede claude login.
• Cache de 90s — picos curtos podem demorar até 1m30s pra refletir no gate.
• Estimativa de "subfase leve vs pesada" é heurística (tamanho do prompt + nº arquivos), pode errar.

---

Otimizações de custo / velocidade

1. Reaproveitar contexto — carregar memória + CLAUDE.md uma única vez no início; não re-ler arquivos sem necessidade.
2. Paralelizar I/O — Glob/Grep/Read em uma única mensagem sempre que independentes.
3. Subagents em paralelo quando geram arquivos diferentes (F1 e F3).
4. Output mínimo na sessão — docs em .md, sessão só comunica status. Reduz tokens consumidos.
5. Não re-emita conteúdo já escrito em arquivos — só referencie path.
6. Não pergunte o que dá pra detectar — F0.2 antes de F0.3.
7. Não especifique model/effort no subagent de construção — herda o modelo padrão e o effort padrão da sessão.
8. Validação pela sessão já tem o contexto carregado — não reespawnar agent só pra validar.

Recuperação de erro

• Faltou contexto crítico: marcar [ASSUMPTION: ...] e listar em 00-VISAO-GERAL.md numa seção "Suposições a revisar".
• Subagent retornou algo errado: reescrever prompt, NÃO assumir que tá certo só porque retornou.
• Conflito de slug: anexar -v2, -v3 etc.
• Fase explodiu de escopo durante execução: parar, perguntar ao usuário, sugerir quebra em mais subfases.

---

Exemplo curto de interação

Usuário: /spec-a23 painel admin para gerenciar cupons de desconto com validade e limite de uso

Sessão:

🔍 Detectei: <stack do projeto>. Pasta `implementacao/` ativa.

📋 Discovery — rodada 1
**Domínio**
1. Cupons são por tenant (se o app for multi-tenant) ou globais?
2. Tipo de desconto: percentual, valor fixo, frete grátis, ou todos?
3. Quem cria cupons: admin global, admin de área, ou ambos?

**Dados**
4. Limite de uso é por cupom (total) ou por usuário?
5. Já existe entidade Discount/Coupon ou é criar nova?

**🔒 Segurança e autorização**
6. Quais permissões precisam ser checadas pra criar/editar/aplicar cupom?
7. Cupom expirado ou esgotado retorna que erro?

**Validação**
8. Como você quer validar: smoke manual + testes de unit nas regras críticas?

[usuário responde]

Sessão:

📝 Resumo: cupons por tenant, tipos %/fixo/frete, criados por admin de área, limite total e por usuário, nova entidade Coupon, permissão "manage Coupon" checada no backend, smoke + unit nas regras de cálculo.
🔄 1. ✅ Continuar  2. ✏️ Corrigir  3. ❓ Mais perguntas

[usuário: 1]

→ F1 dispara subagent que cria 5 docs base. → F2 a sessão apresenta plano de fases (F0 schema → F1 backend regra → F2 admin UI → F3 aplicação no checkout → F4 testes/observabilidade). → Discussão. → F3 cria os 5 .md de fases em paralelo. → F4 executa cada fase com builder agent + reviews da sessão.