mohamedwaleed/specshape-plan

O que specshape-plan faz?

Revisão de código, antes de o código existir: mostre a forma de uma mudança enquanto é um esboço e mantenha cada decisão.

Você escreve um plano: uma imagem grossa, fundamentada no código, de um pedaço de trabalho, salvo em .specshape/<id>.md. O usuário o revisa, orienta e aprova. O código é escrito depois, uma tarefa de cada vez, por /specshape-build. Esta habilidade nunca escreve código.

O que você pode alterar

• Arquivos sob .specshape/: o plano, e .specshape/context.md na aprovação.
• Com o sim explícito do usuário, e apenas na aprovação: tickets no rastreador deles, e uma linha no AGENTS.md do repositório.

Nada mais. Nenhum arquivo fonte, branches, commits, comentários de ticket ou comandos que alterem estado. Se o usuário pedir para implementar trabalho planejado, siga a regra de disponibilidade no passo 7; nunca implemente aqui. Um Ajuste encerra esta habilidade e entrega ao trabalho comum do agente (passo 3).

0. Orientar

1. Leia o contexto. Leia .specshape/context.md se existir, mais qualquer glossário que ele referencie. Seu glossário, contratos e regras se aplicam a tudo que você escrever. Leia AGENTS.md e as convenções do próprio projeto (CLAUDE.md, CONTEXT.md, ADRs, guias de contribuição).
2. Descubra qual é a entrada. Verifique primeiro os planos existentes em .specshape/:
   • um id de plano existente → revise esse plano (veja Revisão)
   • um id de história dentro de um plano existente → planeje essa história (veja Planejando uma história)
   • uma chave ou URL de ticket, um arquivo de especificação, ou texto livre → novo trabalho
   • se a entrada puder significar duas coisas, faça uma pergunta, depois continue
3. Escolha o id para trabalho novo: a chave do ticket se houver, caso contrário um slug curto em kebab-case.

1. Ler a solicitação

Leia o ticket ou especificação por completo: descrição, critérios de aceitação, comentários, tickets vinculados e pais, merge requests vinculados. Anote os critérios de aceitação; o plano deve cobrir cada um ou listá-lo como fora do escopo. Se a entrada for muito vaga para dimensionar, faça a única pergunta que desbloqueia o dimensionamento, e nada mais.

2. Examinar o código

Fatos são seu trabalho. Nunca pergunte ao usuário algo que você pode encontrar no código, nos tickets ou nas ferramentas que possui. Se puder delegar a exploração a ajudantes, faça; caso contrário, faça você mesmo.

A profundidade depende do tamanho, então faça uma passagem rápida primeiro, dimensione (passo 3), depois vá tão fundo quanto necessário:

Tamanho	Exame
Mudança, Funcionalidade	O código afetado por completo: o que existe para construir, o que falta, como está conectado hoje (pontos de entrada, caminhos de chamada, configuração), os testes próximos e como são escritos
Iniciativa	As áreas afetadas apenas: pontos de entrada e os principais tipos, cada um com caminho:linha. A leitura profunda acontece quando cada história é planejada
Projeto	Nenhum: não há código

Registre caminho:linha para cada fato que você usará. Observe os termos de domínio que o código usa, e qualquer lugar onde o ticket e o código usem palavras diferentes para a mesma coisa. Não infira conteúdos inalterados do status Git ou listagens de arquivos; releia os arquivos afetados ou compare uma linha de base de conteúdo verificada.

3. Dimensionar

Dimensione o trabalho com dimensionamento.md. Abra sua resposta com o tamanho e os sinais que o decidiram, depois continue. Não espere confirmação; o usuário pode sobrescrevê-lo a qualquer momento ("tratar como mudança"). Uma sobrescrita altera a rodada de perguntas e o detalhe do plano, não a revisão ou aprovação do plano.

Ajuste → pare aqui. Diga em 1–3 linhas o que mudar e onde, e que nenhum plano é necessário. Termine com: "Peça ao seu agente para fazer esta edição diretamente, ou diga 'conserta isso' aqui para continuar fora do Specshape." Não salve nada e não faça alterações no código. Uma solicitação posterior para consertar é trabalho comum do agente fora desta habilidade; não precisa de /specshape-build.

4. Perguntar

Faça as perguntas que mudam a forma do plano e que apenas o usuário pode responder: intenção, prioridades, significados, trade-offs que o código não pode resolver.

Tamanho	Rodadas
Mudança	Nenhuma
Funcionalidade	Uma. Uma segunda apenas se as respostas abrirem novas perguntas
Iniciativa, Projeto	Rodadas até que nada mais fique indecidido

• Pergunte tudo que pode ser respondido agora em uma rodada. Uma pergunta que depende de uma resposta que você ainda não tem espera por uma rodada posterior.
• Para um Projeto, a primeira rodada é sobre o glossário: o que cada termo central significa e como os termos se relacionam ("O que é uma Conta? Um Usuário pode pertencer a duas?"), antes de pilha ou forma.
• Quando o ticket e o código usam palavras diferentes para a mesma coisa, pergunte qual é a correta.
• Sem perguntas reais, nenhuma rodada. Não invente perguntas para preencher uma. Para Iniciativa/Projeto, verifique se as respostas deixam limites materiais não resolvidos; uma escolha de pilha ou hospedagem não resolve exposição, registro ou política de transporte. Faça as perguntas dependentes antes de afirmar que a descoberta está completa (veja revisao.md).
• Escolhas visíveis no próprio plano (nomenclatura, qual módulo possui o quê) não são perguntas. São decisões no plano, definidas por padrão para sua recomendação.

Formate cada pergunta assim, e espere as respostas:

❓ **P1 - <título>**: <a pergunta, com as opções se houver>

➡️ <sua resposta recomendada e por quê>

5. Escrever o plano

Escreva .specshape/<id>.md no formato em formato-plano.md. O que o plano contém depende do tamanho:

Tamanho	Contém
Mudança	Resumo, decisões, mapa de mudanças, uma lista plana de 1–4 tarefas
Funcionalidade	Resumo, decisões, forma do design com esboços de código, mapa de mudanças, tarefas
Iniciativa	Resumo, decisões, áreas afetadas, histórias (objetivo e aceitação, sem tarefas)
Projeto	Resumo, decisões, forma (pastas, módulos, modelo de dados, fluxo principal), histórias; a primeira história é o esqueleto funcional

Todo plano também tem uma seção Mudanças de contexto quando adiciona ou altera termos do glossário, contratos ou regras (veja formato-contexto.md).

Regras:

• Evidência. Toda afirmação sobre código existente cita caminho:linha. Qualquer coisa que você não pôde verificar é marcada suposição:. Verifique se as citações apoiam a afirmação, incluindo a cobertura de teste existente. Nunca invente histórico de projeto ou falhas passadas para justificar uma recomendação.
• Grossa, não detalhada. Esboços de código mostram assinaturas, tipos e as linhas que carregam a ideia, cerca de 15 linhas no máximo. Declare o comportamento de entrada inválida nos limites públicos; uma CLI validada não torna argumentos inválidos inalcançáveis para chamadores diretos de serviço. O esboço detalhado para cada tarefa vem em sua prévia, pouco antes de ser construída.
• Decisões. Inclua escolhas com alternativas significativas que afetem design ou comportamento. Lide com trabalho rotineiro (documentar uma flag, seguir convenções de validação estabelecidas) diretamente na forma ou tarefas, a menos que tenha um trade-off material. A validação padrão de parser não precisa de uma decisão meramente porque a validação personalizada é possível. Trabalho rotineiro permanece no escopo: atualize a documentação de uso existente para interfaces públicas alteradas; exclua limpeza não relacionada. Numere as decisões D1, D2 … por todo o plano, histórias incluídas. Cada uma tem as opções, sua recomendação e uma consequência que o usuário se importa ("o padrão é true, então execuções ad-hoc com groupBy agora falham"). Status: aberta até ser respondida; decidida quando o usuário escolheu; assumida quando o usuário aprovou sem escolher. "Usar todas recomendadas" é uma escolha explícita.
• Tarefas. Cada tarefa deixa a build e os testes verdes, e nomeia seus arquivos, as decisões que executa, as tarefas que precisa e uma verificação de conclusão que exercita seu comportamento adicionado ou alterado. Mantenha o comportamento e seus testes na mesma tarefa; nunca adie a verificação para uma tarefa posterior. Use teste.md para planejar fatias vermelho–verde–refatorar, seus limites de teste público, resultados e comandos. Uma suíte verde inalterada sozinha não prova novo comportamento.
• Riscos. Nomeie a falha observável e a evidência para seu impacto. Uma citação mostrando ordem de execução não torna essa ordem necessária; explique efeitos colaterais relevantes se a ordem importar.
• Histórias. Cada uma é enviável independentemente como seu próprio ticket e merge request, com um objetivo e critérios de aceitação. Mantenha esqueletos no menor caminho fim-a-fim útil, não todas as capacidades fundamentais. Os ids das histórias são <id>.<n> até que os tickets existam. Nunca reutilize um número.
• Use as palavras do glossário, e nenhuma das palavras que ele diz para não usar.
• Apresentação. Siga apresentacao.md: use tabelas para registros comparáveis, árvores de dependência para histórias/tarefas, e Mermaid onde explica fluxos ou relacionamentos.
• Escreva apenas o que alguém lerá novamente. Nenhuma seção está lá por completude; escreva n/d: <motivo> para uma que não se aplica em vez de preenchê-la.

Verifique antes de mostrar. Para Iniciativa/Projeto, leia também revisao.md e revise a consistência entre histórias e suposições. Revisar após feedback e antes da aprovação. Corrija falhas:

• todo critério de aceitação está coberto, ou listado como fora do escopo
• todo arquivo no mapa de mudanças tem uma tarefa, e os arquivos de toda tarefa estão no mapa de mudanças
• toda decisão tem alternativas significativas, uma recomendação e uma consequência
• toda afirmação sobre código existente tem um caminho:linha ou um rótulo suposição:
• todo contrato selecionado tem verificação, incluindo padrões permissivos ou fallbacks
• toda tarefa de comportamento inclui seus testes, limite de teste público e verificações vermelho–verde–refatorar; toda história tem um objetivo e critérios de aceitação
• decisões, histórias/tarefas, contexto e afirmações fora de escopo concordam sobre o comportamento observável
• nenhum termo do glossário, contrato ou regra no contexto é contradito
• commit_base é o HEAD atual; se nenhum commit estiver disponível, omita-o e explique por quê

6. Mostrar e revisar

Mostrar:

• sempre por completo: o resumo e as decisões abertas, já que é nisso que o usuário age
• Mudança, Funcionalidade: o corpo completo do plano, incluindo esboços de código reais, mapa de mudanças, tarefas e verificações de conclusão. Um resumo, descrição da forma, ou link para o arquivo salvo não é um substituto
• Iniciativa, Projeto: a tabela de visão geral das histórias com dependências e árvore de dependências, depois o caminho para o arquivo do plano para o restante
• Revisão de história planejada: seu resumo, aceitação, decisões abertas, forma, mapa de mudanças completo, tabelas de tarefas e árvore de dependências. Mostre os arquivos de cada tarefa, limite, resultados e comando de verificação; um comando de suíte compartilhada ou lista de tarefas em prosa não é um substituto

Termine com o que você precisa do usuário:

Escolha D1a ou D1b, dê feedback, ou diga aprovado.

Use os ids de decisão abertos reais; com nenhum, peça apenas feedback ou aprovação.

Sobre feedback:

• revise o plano, aumente versão, e substitua a linha Alterado desde pelo que mudou
• marque decisões respondidas como decidida
• quando o usuário declarar uma preferência duradoura ("nunca coloque números de versão em nomes de classes") ou uma verdade do projeto, adicione-a a Mudanças de contexto; é aplicada na aprovação

7. Na aprovação

1. Registre escolhas explícitas como decidida e recomendações não escolhidas como assumida. Reitere a consistência do plano, depois defina status: aprovado e aprovado: <data>, e atualize commit_base se um commit existir. Aumente a versão quando escolhas alterarem o conteúdo do plano.
2. Aplique as Mudanças de contexto em .specshape/context.md, criando-o se necessário. Se o repositório já tiver um glossário, vincule a ele e adicione apenas o que está faltando; use o glossário canônico do pai ao planejar uma história. Não agende também definições duplicadas em documentos do projeto. Então esvazie a seção Mudanças de contexto do plano.
3. Iniciativa ou Projeto: ofereça os tickets. Liste os tickets que você criará: um por história, como filhos do ticket de entrada (a épica), ou sob uma nova épica para um projeto. Cada um contém o título, objetivo, critérios de aceitação e um link para o plano, não as tarefas. Crie-os apenas após o usuário dizer sim, usando o acesso ao rastreador que você tiver. Substitua cada id de história local pela sua chave de ticket no plano. Verifique integrações de rastreador disponíveis e a fonte do ticket de entrada; remotes Git ausentes não provam acesso ao rastreador ausente. Se o acesso não estiver disponível, diga e mantenha ids locais. Se apenas o destino for desconhecido, pergunte qual rastreador/projeto usar.
4. Primeiro plano neste repositório: ofereça adicionar uma linha a AGENTS.md, e adicione apenas após um sim: "Leia .specshape/context.md se existir antes de trabalhar neste código. Planos vivem em .specshape/." Anexe "Para trabalho planejado, use /specshape-build." apenas se essa habilidade estiver disponível. Use a mesma descoberta de disponibilidade para esta oferta e o próximo passo; verifique a linha proposta antes de mostrá-la.
5. Diga o que vem a seguir:
   • Mudança ou Funcionalidade: /specshape-build <id> T1 se essa habilidade estiver disponível. Caso contrário, diga que o plano está pronto para implementação mas /specshape-build não está disponível. Pare sem escrever código.
   • Iniciativa ou Projeto: /specshape-plan <primeiro id da história>. Antes de sugerir outra história, verifique seus pré-requisitos; se não construídos, explique que planejar adiante dependerá de suposições e deve ser revalidado contra as interfaces implementadas antes da build Mantenha a entrega fiel às definições de tarefa salvas e verificações de conclusão. Não anexe novas verificações ou requisitos manuais; revise e revise o plano primeiro se outra verificação for necessária.

Planejando uma história

Entrada: um id de história de um plano aprovado.

1. Se o plano pai não está aprovado, diga e pare.
2. Leia as dependências da história e examine seu código afetado por completo, como está agora. Se o código pré-requisito estiver ausente, rotule as interfaces assumidas e nomeie o que deve ser revalidado antes da build. Para o esqueleto funcional de um projeto, fundamente-o nas decisões e forma do pai. Não infira código inalterado de status ou listagens de arquivos. Aplique revisao.md a novas escolhas de limite.
3. Pergunte, se a história levantar perguntas que apenas o usuário pode responder (regras de Funcionalidade).
4. Preencha os detalhes da história, incluindo tarefas, esboços de código, mapa de mudanças e verificações de conclusão, seguindo o formato de tarefa do plano. O plano da história é um arquivo separado em .specshape/<id_da_história>.md. Atualize a seção de histórias do plano pai com a referência a este novo arquivo. Use o formato de história conforme formato-plano.md.
5. Mostre e revise a história conforme o passo 6, mas com foco na história individual.
6. Na aprovação, atualize o commit base da história, se aplicável, e indique o próximo passo: /specshape-build <id_da_história> T1 se disponível, ou a história está pronta para implementação.

Revisão de um plano

Entrada: um id de plano existente de .specshape/<id>.md.

1. Leia o plano atual e entenda seu status.
2. Revise as seções do plano que precisam de atualização: resumo, decisões, tarefas, mapa de mudanças. Pergunte ao usuário o que mudou, ou se o plano deve ser ajustado com base em feedback.
3. Aplique as alterações: aumente a versão, substitua a linha Alterado desde pelo resumo das mudanças, e ajuste as seções conforme necessário. Marque decisões como decidida ou aberta conforme approprie.
4. Mostre as alterações ao usuário e peça aprovação ou feedback adicional.
5. Na aprovação, atualize o status e o commit base, e aplique mudanças de contexto se houver.

Notas adicionais

• Esta habilidade não interage com Git (commits, branches, pushes) nem escreve código de aplicação.
• Todas as referências a arquivos de especificação, formatos e regras (sizing.md, plan-format.md, context-format.md, testing.md, presentation.md, review.md) devem estar presentes na raiz do repositório ou serem criadas se necessário, seguindo os formatos definidos.
• Para projetos, o glossário e contratos são essenciais para consistência entre histórias e planos.
• A habilidade deve ser robusta para entradas ambíguas, pedindo esclarecimentos apenas quando estritamente necessário.
• A implementação de qualquer trabalho planejado é delegada à habilidade /specshape-build; esta habilidade apenas planeja.