spec-a23

Spec-driven development para Claude Code que planeja, constrói, valida e executa sozinho a noite inteira — sem queimar seu limite de plano.

A spec-a23 transforma uma demanda em linguagem natural numa estrutura completa de implementação documentada, quebra em fases atômicas, constrói com subagent e valida cada subfase (segurança, qualidade, testes) antes de commitar. Tudo em PT-BR com acentuação correta, com foco em velocidade e baixo custo de tokens — mas sem afrouxar segurança pra ir mais rápido.

E o destaque: o modo autopilot deixa tudo rodando de forma autônoma, pausando sozinho quando seu uso do plano chega perto do limite e retomando quando reseta.

/spec-a23 criar fluxo de checkout com PIX, cartão e split de pagamento

🤖 Modo Autopilot — o diferencial

Você descreve a feature, aprova o plano de fases, e diz:

"pode seguir sozinho, pausa em 90% e retoma quando resetar"

A partir daí a skill executa a SPEC inteira sem te perguntar nada — e, o mais importante, respeita o limite do seu plano Max/Pro automaticamente.

O que o autopilot faz por você

• Decide tudo sozinho com a opção mais segura. Classificação de risco, escolha de padrão, correção de review, ordem das subfases — nunca para pra perguntar. Cada decisão fica registrada no log.
• Converte validação humana em validação automática. Onde a SPEC pedia "smoke manual", ele roda o equivalente automatizado (curl, chrome-devtools, lighthouse, snapshot) e acumula uma seção "Testes humanos pendentes" no log com passos detalhados pra você revisar quando acordar.
• Não trava por decisão de produto. Pendência de negócio vira o default mais conservador, marcado como [ASSUMPTION-AUTOPILOT] e listado em "Decisões pendentes de revisão". Você ajusta depois se quiser.
• Comita por fase, sempre. Mesmo no modo autônomo: nada de --no-verify, nada de git push sem você mandar, nada de operação destrutiva irreversível. As regras de segurança continuam de pé.
• Só para de vez em blocker técnico irrecuperável — build/teste que falha após 2 tentativas, dependência externa fora do ar, conflito de merge inseguro, ou limite semanal duro.

🚦 Gate de usage — o que o torna seguro deixar rodando

Antes de cada subfase, o autopilot consulta seu uso real do plano:

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

O script bate no mesmo endpoint OAuth (/api/oauth/usage) que o slash /usage usa internamente — então o número é o real do seu plano Max/Pro, não uma estimativa inferida. Lê o token de ~/.claude/.credentials.json, com cache de 90s pra não tomar rate limit.

Quando pausa, usa ScheduleWakeup em janelas de 1h pra acordar, re-checar o gate e retomar exatamente de onde parou — sem intervenção sua. Se o limite semanal estourar (≥ 95% com reset > 24h), registra o blocker e para de vez, deixando a decisão pra você.

Na prática: você inicia uma SPEC grande à noite, vai dormir, e acorda com várias fases prontas, commitadas e validadas — sem nenhuma surpresa na fatura de uso.

Como ativar

Depois de aprovar o plano de fases, diga qualquer variante de:

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

Pra interromper a qualquer momento: "parar autopilot" — ele termina a subfase atual, comita, e devolve o controle.

⚠️ Honestidade sobre limitações

• Depende da sessão local ativa — laptop fechado mata o autopilot.
• O endpoint /api/oauth/usage é interno do Claude Code (não documentado) — pode mudar de schema. Em caso de erro, conferir com bash check-usage.sh --raw.
• Token OAuth expira; com o Claude Code aberto o refresh é automático, mas se ficar dias fechado o script pede claude login.
• Cache de 90s — picos curtos de uso podem demorar até 1m30s pra refletir no gate.

Por que usar a spec-a23

• 🔒 Segurança em primeiro lugar. Toda fase passa por security-review obrigatório (19 categorias de checklist). Nada vira "concluído" sem passar — nem no autopilot.
• ⚡ Velocidade e baixo custo de tokens. Discovery proporcional à demanda, output prioritário em .md, paralelização de I/O, subagent em modelo padrão e effort padrão. A sessão emite o mínimo de texto.
• 💬 Discussão única. Todas as fases e subfases são apresentadas de uma vez, depois do discovery — você discute e aprova tudo numa rodada, ao invés de iterar seção por seção.
• 🤖 Constrói com subagent, valida com a sessão. O subagent escreve o código; o modelo da sessão testa, revê segurança, revê qualidade e corrige — sem delegar a validação.
• 🧩 Agnóstica de stack. Detecta a linguagem, o framework e as convenções do seu projeto na F0.2 e segue os padrões já existentes — sem impor estrutura nova. Funciona em qualquer repo.
• 🌳 Commit obrigatório por fase, com mensagem em PT-BR no padrão do repo. Nunca git add -A, nunca --no-verify.
• 🇧🇷 Tudo em PT-BR com acentuação correta — discovery, docs, mensagens, código gerado.

Como instalar

git clone https://github.com/a23comunicacoes/spec-a23.git ~/.claude/skills/spec-a23

Em Windows (PowerShell ou Git Bash):

git clone https://github.com/a23comunicacoes/spec-a23.git "$HOME/.claude/skills/spec-a23"

Reabrir o Claude Code — a skill aparece como spec-a23 na lista.

Como usar

/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

Depois do discovery e da aprovação do plano, é só dizer "executar fase 00" para começar manualmente — ou ativar o modo autopilot e deixar rodar.

Fluxo (5 fases)

Cada SPEC vira uma pasta navegável no projeto:

implementacao/<slug>/
├── README.md               ← índice navegável
├── 00-VISAO-GERAL.md       ← objetivo, escopo, riscos, stakeholders
├── 01-RESUMO.md            ← TL;DR de 1 página
├── 02-RESEARCH.md          ← pesquisa técnica e decisões de arquitetura
├── 10-LOG-EXECUCAO.md      ← log vivo (inclui autopilot, testes pendentes, decisões)
├── evidencias/             ← screenshots, dumps, logs de validação
└── fases/
    └── FASE-XX-<nome>.md    ← uma fase = um conjunto coeso de mudanças

Estrutura da skill

spec-a23/
├── SKILL.md                              ← orquestração das 5 fases + autopilot
├── README.md                             ← este arquivo
├── scripts/
│   └── check-usage.sh                    ← gate de usage via /api/oauth/usage oficial
├── references/
│   ├── security-rules.md                 ← 19 categorias de checklist obrigatório
│   ├── quality-rules.md                  ← 12 categorias de qualidade
│   └── discovery-questions.md            ← banco de perguntas calibrado por complexidade
├── agents/
│   ├── builder.md                        ← prompt do subagent de construção
│   ├── md-builder.md                     ← prompt do subagent que gera os .md
│   └── reviewer.md                       ← protocolo de review pelo modelo da sessão
└── templates/                            ← README, 00, 01, 02, 10, FASE

Regras máximas (não negociáveis)

1. 🔒 Segurança em primeiro lugar — checklist obrigatório por subfase.
2. 🇧🇷 PT-BR com acentuação correta sempre.
3. ⚡ Custo/velocidade são prioridade, mas validação não é negociável.
4. 📁 Output prioritário em .md; sessão emite o mínimo.
5. 🤖 Construção por subagent; validação pela sessão.
6. 💬 Discussão única após o discovery.
7. 🧠 Memória do projeto sempre carregada antes do discovery.
8. 🌳 Commit obrigatório ao fim de cada fase, com mensagem em PT-BR.

Essas regras valem inclusive no autopilot — o modo autônomo nunca afrouxa segurança pra terminar mais rápido.

Em resumo

• 📦 Output estruturado — uma pasta com vários .md (resumo, visão, research, fases, log), não um arquivo único.
• 💬 Discussão única depois do discovery, com todas as fases de uma vez.
• 🔁 Cobre a execução — loop de construção + validação por subfase, não só a geração da spec.
• 🤖 Autônoma de verdade — autopilot com gate de usage, único no gênero.
• 🇧🇷 Tudo em PT-BR com acentuação correta.
• 🧩 Agnóstica de stack — funciona em qualquer projeto.

Detalhes completos em SKILL.md.