SeemSeam/plan-tree

Árvore de Planejamento (Plan Tree)

Use esta skill como a autoridade de workflow de planejamento para direção durável de projeto, prontidão para execução, estado de progresso e árvores de planejamento em Markdown. Ela preserva a intenção do usuário, o estilo de documento existente, o raciocínio e a evidência do plano até a entrega entre sessões e agentes.

Modo de Operação Obrigatório

Para cada tarefa de plan-tree, determine o modo de trabalho antes de editar ou implementar.

• Se o modo não estiver claro, use como padrão clarify ou ready-check, não execute-ready.
• Quando o estado existente da plan-tree estiver disponível, inspecione o ponto de entrada relevante e o estado atual do plano antes de mudar de direção.
• Antes que uma solução esteja madura o suficiente para ser implementada, permaneça em modo de planejamento e esclarecimento. Expanda a intenção do usuário em metas, não-metas, restrições, opções, tradeoffs, riscos, dependências, critérios de aceitação, caminho de verificação e notas de rollout ou rollback.
• Não inicie a implementação formal na superfície principal do projeto enquanto houver ambiguidade central sobre escopo, abordagem, superfícies afetadas, comportamento esperado, critérios de aceitação, caminho de verificação ou riscos.
• Um protótipo pequeno e isolado ou amostra é permitido apenas quando valida uma direção e permanece claramente separado do caminho de produção.
• Um plano está pronto para implementação apenas quando a execução não deve depender de "descobrir durante a codificação" para decisões centrais.
• Após a implementação ser entregue, atualize o status da plan-tree, evidências entregues, decisões, perguntas em aberto e notas de handoff para que a implementação seja refletida de volta no estado durável do plano.

Modos de Trabalho

Escolha um modo primário no início de uma tarefa e faça a transição apenas quando o estado mudar.

• clarify: intenção, escopo, restrições, critérios de sucesso ou tradeoffs não estão claros. Discuta, faça perguntas focadas quando necessário e registre resultados de esclarecimento duráveis em arquivos de plan-tree quando útil. Não edite arquivos de implementação do projeto principal.
• shape-plan: a direção é amplamente conhecida, mas precisa de um mapa de solução concreto. Crie ou atualize itens de roadmap, tópicos, suposições, decisões, riscos, critérios de aceitação e perguntas em aberto.
• ready-check: o usuário deseja implementar ou prosseguir, mas a prontidão é incerta. Avalie se escopo, abordagem, superfícies afetadas, critérios de aceitação, verificação e riscos são explícitos o suficiente. Se não, retorne a clarify ou shape-plan.
• resume: continue a partir de trabalho anterior. Leia o ponto de entrada raiz, a linha de base relevante, o README do plano alvo, o status de implementação, o roadmap e apenas arquivos vinculados ativos. Resuma a fase atual, TODO ativo, bloqueadores, próximo alvo e última verificação antes de editar.
• execute-ready: o plano está pronto o suficiente para implementar. Modifique os arquivos do projeto apenas dentro do escopo acordado e, em seguida, atualize o estado da plan-tree e as evidências.
• status-update: atualize o estado do roadmap, status de implementação, Última Entrega, Próximo Alvo, bloqueadores, handoff ou registro do plano após trabalho ou revisão.
• archive: mova detalhes obsoletos, snapshots de status antigos, evidências aceitas ou material apenas de referência para fora dos arquivos ativos, preservando links de recuperação.
• normalize: reorganize uma árvore de planejamento existente ou arquivos de origem de função mista e superdimensionados em unidades de recuperação menores. Primeiro, crie ou atualize indexes/migration-map.md ou o índice útil mais próximo, em seguida, classifique o material de origem por função de recuperação, crie cápsulas curtas e shards de detalhe para leitor de tarefas, mova a verificação aceita para evidence/ e mova o status antigo ou narrativa de raciocínio para history/ sem excluir o material de origem, a menos que explicitamente aprovado.
• audit ou migrate: inspecione consistência, recuperação, desvio, raízes legadas ou mapeamento de migração. Use como padrão somente leitura, a menos que o usuário peça para reparar, normalizar ou migrar.

Ações de documento como idea, promote, question e decision ocorrem dentro desses modos:

• idea: adicione um pensamento de baixo compromisso a ideas/inbox.md ou equivalente local.
• promote: mova uma ideia para um item de roadmap, tópico, pergunta em aberto ou decisão e vincule a ideia original.
• question: adicione, restrinja ou resolva uma pergunta não resolvida.
• decision: crie ou atualize um registro de decisão estável.

Workflow Principal

Para cada tarefa de plan-tree:

1. Selecione o modo de trabalho e a superfície de escrita permitida: nenhuma, apenas plan-tree, protótipo isolado ou arquivos de projeto mais atualização de plan-tree.
2. Identifique a raiz da plantree, a raiz do plano alvo e a intenção do usuário.
3. Leia o índice raiz mais apenas os arquivos de roadmap, status, tópico, decisão, pergunta, ideia, histórico ou linha de base relevantes.
4. Preserve pontos de entrada existentes, raízes registradas, nomes de pastas, estilo de documento e ordem de autoridade, a menos que a tarefa seja explicitamente reorganizá-los.
5. Mantenha os arquivos ativos de roadmap, handoff e cápsula de tópico pequenos; mova detalhes, evidências e histórico para fora do estado ativo.
6. Atualize índices, cabeçalhos de recuperação e links ao adicionar, mover, promover, arquivar ou dividir arquivos duráveis.
7. Execute verificações finais antes de responder.
8. Relate arquivos alterados, perguntas não resolvidas, o modo ativo e a próxima ação de manutenção útil quando relevante.

Sistema de Arquivos Padrão

Use docs/plantree/ como o sistema de arquivos padrão entre projetos para material gerenciado pela plan-tree. É a raiz e o registro do sistema plantree, não uma única raiz de plano; o nome evita colisões com pastas nativas do provedor ou do framework plans/.

Forma padrão:

• docs/plantree/README.md: registro, ordem de autoridade, link da linha de base, tabela de planos ativos e como ler a árvore.
• docs/plantree/baseline/: contexto de todo o projeto, como mapa de módulos, fluxos de runtime, limites de estado/armazenamento, portões de teste/release e hotspots de risco.
• docs/plantree/plans/<NNN>-<plan-name>/: raízes de plano específicas com numeração estável, roadmap/status, tópicos, decisões, perguntas em aberto, evidências, índices e histórico opcional quando o projeto não tem uma convenção de nomenclatura estabelecida.
• docs/plantree/ideas/inbox.md: caixa de entrada de ideias de baixo compromisso.

Ordem de descoberta:

1. Use um caminho explícito do usuário quando fornecido.
2. Caso contrário, use docs/plantree/ quando docs/plantree/README.md existir.
3. Caso contrário, preserve outra árvore estabelecida claramente ativa para a tarefa atual; avalie a migração apenas quando o usuário pedir para adotá-la, normalizá-la ou migrá-la.
4. Caso contrário, inicialize docs/plantree/ antes de criar ou atualizar um plano.

Novos planos específicos usam como padrão docs/plantree/plans/<NNN>-<plan-name>/ quando não há convenção local, devem ser registrados em docs/plantree/README.md e devem vincular aos arquivos de linha de base relevantes em vez de copiar o contexto global. Preserve árvores estabelecidas não numeradas ou organizadas de forma diferente, a menos que o usuário aprove explicitamente a migração.

Primeiro Uso

Quando uma tarefa de plan-tree for invocada em um projeto sem docs/plantree/, crie uma raiz mínima, a menos que o usuário peça explicitamente para não criar arquivos.

Inicialização:

• Raiz: docs/plantree/README.md
• Linha de base: baseline/README.md, module-map.md, runtime-flows.md, storage-and-state.md, test-and-release-gates.md, risk-hotspots.md
• Contêineres: plans/, ideas/inbox.md

Mantenha o conteúdo da inicialização leve e baseado em evidências. Se código suficiente não foi inspecionado, escreva "Desconhecido / precisa de inventário" em vez de inventar fatos do projeto. Para projetos antigos ou desconhecidos, construa ou atualize a linha de base antes de criar um plano detalhado.

Modelo de Plano

Use estas funções ao criar ou manter uma raiz de plano, adaptando os nomes à convenção local:

• README.md: escopo, autoridade, mapa de arquivos, caminho de leitura e registro ativo quando é a raiz da plantree. Para tabelas de Planos ativos, prefira ID | Plano | Módulos Afetados | Status | Fase Atual | Última Entrega | Próximo Alvo quando IDs leves estiverem em uso.
• roadmap.md: estado durável agrupado como Concluído, Em Andamento, Próximo e Adiado, a menos que a árvore já use outro modelo.
• implementation-status.md: handoff operacional curto apenas para planos Em Andamento. Planos em planejamento ou adiados geralmente não precisam deste arquivo.
• open-questions.md: apenas perguntas não resolvidas.
• topics/: contexto durável, mapas de solução, opções, restrições, critérios de aceitação, notas de implementação, planos de higiene do repositório e análise de risco. Mantenha os arquivos de tópico de nível superior como cápsulas curtas; divida tópicos grandes em pastas de tópicos com shards de detalhe.
• decisions/: decisões estáveis, indexadas quando o conjunto cresce.
• evidence/: registros de verificação atuais ou aceitos, resultados de revisão, notas de artefato e índices de evidência quando precisam ser recuperados independentemente do histórico.
• history/: logs de checkpoint aceitos, revisões antigas, snapshots aposentados, notas de origem apenas para arquivo e detalhes obsoletos.
• indexes/: mapas de recuperação opcionais, como mapas de fase, mapas de tópico, mapas de autoridade, mapas de migração e mapas de evidência, quando índices locais resolvem um problema de navegação.
• ideas/: pool de ideias de baixo compromisso opcional quando as ideias de nível raiz não são específicas o suficiente.

Leia references/maintenance-patterns.md ao criar modelos, lidar com árvores grandes, manter arquivos de decisão/status/handoff/histórico/índice, adicionar planos de higiene do repositório ou precisar da lista de verificação de verificação final detalhada.

IDs Leves e Classificação de Módulos

Quando um projeto não tem uma convenção de nomenclatura de Plano estabelecida, use IDs leves para melhorar a varredura do sistema de arquivos e referências duráveis sem criar um banco de dados de tarefas:

• Aloque IDs de Plano em todo o projeto como P001, P002 e assim por diante. Mapeie P001 para uma raiz plana como docs/plantree/plans/001-authentication/.
• Use números decimais de três dígitos de largura fixa. Aloque o número máximo de Plano retido mais um; nunca reutilize um ID, feche lacunas renumerando, ou codifique prioridade, status, módulo, proprietário, trabalhador, fase ou data.
• Mantenha o slug semântico estável e em kebab-case minúsculo. Um título ou módulo afetado pode mudar sem alterar o ID do Plano ou diretório.
• Enquanto o registro de Plano for pequeno, mantenha a identidade e o registro de ciclo de vida em docs/plantree/README.md. Divida-o em um índice apenas quando isso melhorar a recuperação; não mantenha um livro-razão de alocação paralelo por padrão.
• IDs de tarefas de roadmap, como T001, são opcionais e locais do Plano. Use-os apenas quando referências estáveis entre arquivos ajudarem. Quando presentes, roadmap.md é a única autoridade ativa para identidade, status e ordem da tarefa; não crie um registro de tarefas separado ou pasta de tarefas por padrão.
• Os nomes dos arquivos de decisão podem manter a convenção 001-<decision>.md. Perguntas em aberto podem usar Q001 quando referências duráveis ajudarem. As ideias permanecem não numeradas até serem promovidas.
• Trate módulos de código ou produto como metadados de Plano, como Módulos Afetados, usando chaves estáveis definidas em baseline/module-map.md. Mantenha as raízes de Plano planas por padrão; adicione índices de módulo ou diretórios de módulo físico apenas após necessidade demonstrada de navegação e uma decisão registrada.
• Aplique consistência de mesma alteração: atualize o arquivo autoritativo e qualquer resumo de ponto de entrada necessário em uma alteração de manutenção e, em seguida, verifique IDs, caminhos, chaves de módulo, exclusividade do roadmap, reivindicações de status e links relativos antes de finalizar.
• Prefira detecção de desvio somente leitura em vez de reparo automático. Não adicione observadores, renomeação automática, bloqueios de alocação ou diários de recuperação até que falhas de coordenação observadas justifiquem seu custo.

Esses padrões são progressivos. Preserve a convenção local de ID, issue, ticket ou pasta de uma árvore madura em vez de sobrepor um namespace concorrente.

Status Dinâmico e Evidências

• Apenas planos Em Andamento precisam de implementation-status.md; planos Em Planejamento devem expressar prontidão em roadmap.md, tópicos, perguntas em aberto ou decisões.
• Mantenha implementation-status.md operacional e curto. Prefira menos de 100 linhas; se crescer, arquive ou indexe detalhes antigos.
• Mantenha TODO Ativo com no máximo cinco itens atuais. Mais itens geralmente significa que o trabalho precisa de uma fase de roadmap, tópico ou divisão.
• Quando IDs de tarefas de roadmap são usados, reutilize esses IDs em TODO Ativo em vez de reafirmar a identidade da tarefa em um segundo registro.
• Inclua Fase Atual, Próximo Alvo, Última Entrega, TODO Ativo, Bloqueado Por e Última Verificação ou notas de handoff concretas quando aplicável.
• Última Entrega deve apontar para um commit, artefato, resultado de teste, checkpoint aceito ou outra evidência com uma data quando disponível.
• Use evidence/README.md, indexes/evidence-map.md ou equivalente local para evidências de nível de fase/pacote/portão. Use history/evidence-index.md apenas para arquivos de evidências obsoletos. Não registre cada pequeno passo ali.
• Arquivos ativos de roadmap/status devem vincular a evidências antigas, não absorver logs repetidos, saída de automação antiga, detalhes de trabalho de revisão ou narrativas históricas.

Modelo de Recuperação

Plan-tree é um sistema de unidades de recuperação, não um lugar para criar grandes documentos onipresentes. Todo arquivo durável deve ter uma função primária:

• Ponto de entrada ou índice: roteamento, ordem de autoridade, caminhos de leitura e resumos de uma linha.
• Estado atual: roadmap ativo, fase atual, bloqueadores, próximo alvo e handoff.
• Cápsula de tópico: um resumo curto de um domínio, recurso, conjunto de restrições ou fluxo de trabalho com links para shards de detalhe.
• Shard de detalhe: contratos, alternativas, casos de borda, notas de implementação, rollout, operações, prontidão ou detalhes de higiene do repositório para uma tarefa de leitor.
• Decisão: uma escolha estável com contexto e consequências.
• Evidência: registros de verificação, resultados de revisão, links de artefato, resumos de teste aceitos ou índices de evidência.
• Histórico/arquivo: status obsoleto, logs de execução antigos, material de origem migrado e detalhes retirados.

Não deixe um arquivo carregar resumo, estado ativo, decisões, raciocínio longo, logs, evidências e histórico ao mesmo tempo. Se uma atualização fizer um arquivo cruzar seu limite de função, crie ou atualize uma unidade de recuperação vinculada primeiro, depois deixe apenas o resumo conciso e links no arquivo ativo.

Use essas contagens de linha como gatilhos de divisão, não testes de correção rígidos:

• README raiz, README do plano, roadmap e status de implementação: mantenha perto de 150 linhas ou menos.
• Cápsula de tópico: mantenha perto de 250 linhas ou menos.
• Shard de detalhe comum: divida ou indexe por volta de 400 linhas.
• Arquivos de histórico ou evidência: indexe ou divida por volta de 500 linhas.

Ao dividir

... [truncado para tradução]