CommunityEscrita e Ediçãogithub.com

Scoville Plan

Guardrail de planejamento nativo do repositório contra desorganização de processos de IA.

O que é Scoville Plan?

O Scoville Plan é uma habilidade (skill) para agentes de IA que estabelece uma disciplina de planejamento robusta e nativa ao repositório. Em vez de depender de CLIs, servidores MCP, bancos de dados ou estados ocultos, ele armazena planos e decisões em arquivos revisáveis do próprio projeto. Sua principal função é garantir que escolhas humanas sejam registradas e preservadas, e que decisões materiais não resolvidas sejam propostas antes de serem tomadas. O Scoville Plan suporta a superfície de funcionalidades completa do formato `format_version: 1`, incluindo planos, itens de trabalho, decisões, propostas, ciclo de vida, bloqueios e evidências. Ele não cria um segundo plano se o projeto já possuir um mecanismo de planejamento, em vez disso, aplica seus guardrails de qualidade para manter a consistência e autoridade das decisões. A habilidade é independente, não requer dependências executáveis e pode ser usada com ferramentas de arquivo comuns. É útil para desenvolvedores que trabalham com agentes de IA como Claude Code, Cursor ou Codex, fornecendo uma estrutura de planejamento confiável e transparente diretamente no código-fonte.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add benjaminstelzer/scoville-plan

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Scoville Plan faz?

Mantenha a direção do projeto em arquivos de repositório revisáveis sem exigir um CLI de planejamento, servidor MCP, banco de dados, diário ou estado oculto. Esta Skill é dona da disciplina de planejamento e da manutenção nativa de Plano e Decisão. Ela registra escolhas que os humanos já fizeram e preserva uma escolha material não resolvida como uma proposta antes de pedir sua decisão de ciclo de vida. Ela não concede autoridade a escolhas inferidas nem prova que o trabalho relatado realmente ocorreu.

Mantenha a superfície de funcionalidades completa suportada por format_version: 1: recuperação somente leitura, configuração, Planos, Itens de Trabalho, Decisões, propostas, ciclo de vida, bloqueadores, evidências e reparos restritos. Use edições nativas diretas sem remover ou reinterpretar uma funcionalidade de conhecimento do projeto.

Em opt-out explícito, não leia referências, crie ou altere arquivos de planejamento, ou faça alegações derivadas da Skill. Se uma instrução de projeto de prioridade mais alta exigir este sistema de Plano, reporte esse conflito exato. Um opt-out Scoville irmão exclui apenas aquele irmão.

Siga o dono existente

Resolva os requisitos de planejamento nesta ordem:

  1. instruções de sistema, segurança e explícitas para a solicitação atual;
  2. instruções do repositório e seu mecanismo de planejamento canônico existente;
  3. um perfil nativo suportado existente; e
  4. os padrões desta Skill para o que permanecer não especificado.

Nunca crie um segundo plano ao lado de um plano de propriedade do projeto. Se outro sistema de plano durável já for dono do estado, use-o e aplique apenas os guardrails de qualidade de planejamento desta Skill onde forem compatíveis. Um plano de tempo de execução é um espelho descartável, nunca um segundo dono canônico.

Esta Skill não tem dependência executável obrigatória e nunca invoca um CLI de planejamento. Seu validador Python integrado é uma verificação estrutural opcional estritamente somente leitura, nunca um caminho de escrita. Não reivindique bloqueio, publicação atômica de múltiplos arquivos, segurança de mutação tipada ou prova semântica. Use ferramentas de arquivo com escopo comum e relate apenas as verificações realmente executadas.

Esta Skill funciona de forma independente. Nunca exija, instale ou simule Code, UI, ou Scribe. Quando um irmão for aplicável de forma independente, componha apenas sua própria implementação, interface ou preocupação de redação; sua ausência não enfraquece as regras de estrutura, ciclo de vida, autoridade ou evidência do Plano.

Decida se o planejamento durável é justificado

Use um Plano de repositório para múltiplos resultados dependentes, sequenciamento de materiais, trabalho que deve sobreviver a interrupção ou transferência, ou um fluxo de trabalho vinculativo do projeto. Para uma pequena mudança reversível, implemente e valide diretamente, a menos que o projeto já exija um Item de Trabalho rastreado.

Classifique a operação antes de carregar os detalhes:

OperaçãoCarregar
Ler a direção atual ou listar registros sem escreverread-only.md
Inicializar um perfil totalmente ausenteplanning-granularity.md, native-plan-format.md, native-project-lifecycle.md e native-editing.md
Criar ou reestruturar um Planoplanning-granularity.md, native-plan-format.md, native-project-lifecycle.md e native-editing.md
Inserir, refinar, mover, selecionar, bloquear, avançar ou remover um Item de Trabalhonative-plan-format.md, native-work-items.md e native-editing.md
Registrar uma escolha humana explícita ou uma Decisão possível materialnative-decision-format.md, native-plan-format.md e native-editing.md
Aplicar uma transição de Decisão explicitamente autorizadanative-decision-format.md, native-plan-format.md e native-editing.md
Aplicar um lote de aceitar-ou-rejeitar explicitamente autorizadonative-decision-format.md, native-decision-batches.md, native-plan-format.md e native-editing.md
Ativar, completar ou cancelar um Planonative-plan-format.md, native-project-lifecycle.md, native-work-items.md quando o trabalho atual mudar, e native-editing.md
Auditar estrutura ou ciclo de vida do Plano nativonative-plan-format.md; adicione planning-granularity.md apenas ao julgar decomposição
Auditar estrutura ou ciclo de vida de Decisão nativanative-decision-format.md
Validar após escritas nativas ou diagnosticar um perfil suportado completoExecute a verificação integrada através de profile-validation.md, depois carregue apenas a referência nativa necessária para um diagnóstico ou correção relatada

Não pré-carregue detalhes de formato para uma resposta de status somente leitura.

Quando a existência do perfil for desconhecida, liste a raiz do projeto antes de ler qualquer caminho canônico. Se PROJECT_INDEX.md estiver ausente, não tente lê-lo. Para um novo Plano durável explicitamente solicitado, trate o espaço de trabalho atual como a raiz de configuração, classifique o perfil completo e inicialize apenas quando todos os três caminhos canônicos estiverem totalmente ausentes. Se a criação não foi solicitada, relate que nenhum perfil existe em vez de inicializar um implicitamente. Preserve e pare em um perfil parcial, estrangeiro, não suportado ou com intenção inválida.

Preserve autoridade e evidência

  • Nunca invente o Objetivo, Não-objetivos, resultado de aceitação, bloqueador, dependência, evidência ou uma escolha de ciclo de vida aceita. Trate implementação, documentação comum, código-fonte, silêncio e comportamento atual como evidência, não como autorização humana.
  • Pergunte antes da ativação, cancelamento, escopo alterado, aceitação mais fraca, um sucessor ambíguo, ou adotar uma escolha material meramente possível.
  • Quando o usuário seleciona explicitamente uma direção, pede para preservá-la nas regras do projeto, ou uma instrução aplicável do projeto indica inequivocamente uma direção selecionada por humano, crie e aceite a Decisão correspondente sem perguntar novamente. Vincule cada Item de Trabalho mutável afetado.
  • Quando a análise revela apenas uma Decisão material possível sobre escopo, arquitetura, comportamento público, dados armazenados, segurança, dependências, reversibilidade, aceitação, migração ou implantação, crie-a como proposed, vincule cada Item de Trabalho mutável afetado, relate sua recomendação, alternativas, tradeoffs e efeito prático, então peça ao usuário para aceitar, rejeitar ou revisá-la. Não a aceite antes dessa resposta.
  • Uma solicitação para redigir uma proposta cria proposed. Uma escolha clara para registrar a direção declarada autoriza sua aceitação. Nunca rejeite, descontinue ou substitua uma Decisão sem essa escolha explícita de ciclo de vida.
  • No início do trabalho do projeto, faça um inventário do frontmatter das Decisões, leia cada proposta, relate seu ID, título, escolha recomendada e efeito prático, e pergunte ao usuário para aceitar, rejeitar ou revisá-la. Repita propostas não resolvidas na transferência. Apenas o trabalho dependente para.
  • Marque um Item de Trabalho como done apenas depois de observar seu resultado de Aceitação e adicionar evidência concisa. Uma verificação de formato de arquivo prova apenas estrutura.
  • Mantenha trabalho falho ou parcial como in_progress, paused ou explicitamente bloqueado.

Mantenha Itens de Trabalho com comportamento completo

  • Mantenha no máximo um Item de Trabalho in_progress, igual a current_item. Isso limita execução concorrente; não limita um Plano a um Item de Trabalho no total.
  • Separe resultados retomáveis independentemente com limites de aceitação, dependências, donos ou tempo de implantação distintos em Itens de Trabalho separados.
  • Mantenha a ordem de implementação dentro de Etapas opcionais. Testes, revisão, documentação e verificações de lançamento pertencem a Aceitação ou Evidência, a menos que entregas solicitadas independentemente precisem de seu próprio resultado retomável.
  • Altere conteúdo ou ordenação autoral apenas enquanto um item estiver todo. Depois que começar, preserve sua abordagem inicial e atualize apenas o estado ativo.
  • Mantenha Next action igual à primeira ação concreta ainda não executada. Uma vez que a implementação exista, avance-a para o próximo teste, compilação, verificação de navegador, revisão ou verificação pertencente ao avaliador não observado.
  • Selecione novo trabalho atual apenas quando suas dependências estiverem concluídas e o sucessor for explícito. Use complete_and_advance apenas quando a conclusão e o início da substituição exata forem ambos válidos como um resultado preparado.
  • Quando o trabalho real final for concluído, complete seu Item de Trabalho e Plano e defina o índice do projeto como ocioso. Nunca invente um sucessor meramente para mantê-lo ativo.

Trabalhe nativa e restritamente

Antes de escrever, confirme a raiz do projeto, formato suportado, Plano ativo, Item de Trabalho atual, bytes afetados, resultado observável e evidência de aceitação. Use patches com limite de contexto e preserve trabalho não relacionado. Prepare uma mudança completa de vários arquivos antes de aplicar qualquer membro, reconhecendo que edições diretas não são atômicas.

Após escrever:

  1. releia cada arquivo canônico alterado;
  2. inspecione o diff completo com escopo;
  3. verifique propriedade do índice, contagem de Planos ativos, status do item atual, ordem de chave do Item de Trabalho, ordem e ciclos de dependência, referências de Decisão e Plano, bloqueadores, campos de ciclo de vida, Evidência e Next action;
  4. execute o validador opcional integrado através de profile-validation.md quando seu script e Python já estiverem disponíveis, caso contrário, execute e relate a inspeção manual com escopo; e
  5. registre apenas evidência de aceitação observada.

Pare em formato não suportado, mudanças concorrentes, autoridade de ciclo de vida ambígua, estado inválido cujo reparo alteraria a intenção, ou uma transição parcial de vários arquivos. Não sobrescreva o problema em aparente validade.

Relate o estado durável

Lidere com o resultado atual do Plano. Nomeie arquivos canônicos alterados, trabalho ativo e bloqueado, verificações observadas, evidência registrada, escolhas materiais não resolvidas e a próxima ação concreta. Distinga inspeção estrutural nativa de verificação comportamental. Não narre operações de arquivo rotineiras.

Habilidades Relacionadas