Levix-Digital/plan-memory

📐 Skill de Memória de Planos de Projeto (plan-memory)

Caminhos: <skills_root> é a pasta que contém esta skill (o pai da pasta deste SKILL.md). Use o caminho absoluto real ao executar os comandos.

A skill plan-memory mantém 100% completos, sem compactação, planos arquiteturais, roadmaps estratégicos e blueprints multi-etapa de um projeto, compartilhados por todos que trabalham nele.

• Fonte da verdade: um arquivo Markdown por plano no repositório do projeto, docs/plans/<plan_id>.md (frontmatter YAML + corpo do plano). Os planos são versionados, revisados e mesclados com o código. Altere a pasta com "plans_dir" no .dev-cycle.json do projeto.
• Índice de busca: um ChromaDB local em ~/.ai-code-agent-memory/plan-memory/db (substitua com PLAN_MEMORY_DB), coleção plan_index. Ele é descartável: cada comando o sincroniza a partir dos arquivos (por SHA-256), e rebuild_index (engine) o recria.
• Projeto: resolvido a partir do repositório Git do diretório atual (ou --dir): project_name em .dev-cycle.json, caso contrário o nome da pasta do repositório, normalizado para kebab-case. --project o substitui.
• Níveis: o backlog (docs/BACKLOG.md) captura o trabalho em segundos, sem descoberta, agrupado em épicos; o roadmap (docs/ROADMAP.md) ordena as releases e atribui itens a elas; um plano é criado quando o usuário promove itens do backlog e contém a descoberta e o planejamento (veja "Backlog" e "Roadmap").
• Envelopes Spec Kit: quando o projeto usa Spec Kit, um plano de funcionalidade é um envelope (spec_dir) de uma pasta Spec Kit (specs/NNN-slug/) que contém os detalhes; a busca, detecção de desvios e get_plan leem os artefatos da pasta junto com o plano (veja "Planos com Spec Kit").
• Princípio orientador: Zero Compactação / Zero Perda. Os planos são preservados em sua totalidade (diagramas Mermaid, tabelas, etapas, fórmulas, fundamentação) como conhecimento persistente para cada desenvolvedor e sessão.

---

🏛️ Formato do Arquivo de Plano

---
plan_id: my_app_blueprint_v1_2_0_two_stage_search
project: my-app
title: Busca em dois estágios com reclassificação local
kind: feature              # feature (padrão) | bug
version: v1.2.0
status: in_progress        # draft | planned | active | in_progress | completed | superseded
author: João Silva         # git user.name de quem o criou
created_at: '2026-10-15T16:36:00'
updated_at: '2026-10-16T09:10:00'
session_id: 8abbc3bf-...   # conversa onde o plano foi concebido (opcional)
tags: [search, reranker]
supersedes: my_app_blueprint_v1_1_0_search
superseded_by: null
parent_plan_id: null
backlog_items: [FEAT-004]  # itens do backlog que o plano entrega (opcional)
spec_dir: specs/004-reranker  # Pasta Spec Kit com o detalhe do plano (opcional)
milestones:
- name: M1 Base do runtime
  done: true
  done_at: '2026-10-15'
  by: João Silva
- name: M2 Reclassificador
  done: false
status_log:
- at: '2026-10-15T16:36:00'
  by: João Silva
  status: active
  note: Plano criado
---

# Título do plano

...corpo completo do plano em Markdown...

• Os scripts apenas reescrevem o frontmatter; o corpo é escrito uma vez por save_plan (ou editado manualmente). Mudanças de marco e status produzem diffs pequenos e legíveis.
• O nome do arquivo é o ID do plano. Os campos de linhagem (supersedes, superseded_by, parent_plan_id) referenciam outros IDs de plano.
• Os scripts nunca fazem commit. O agente faz commit dos arquivos de plano junto com o trabalho que eles descrevem (veja "Fluxo de trabalho da equipe").

---

⚙️ Comandos

Todos os scripts estão em <skills_root>/plan-memory/ e aceitam --dir <diretório do projeto> (padrão: diretório atual) e --project <nome>.

1. Salvar / Atualizar um Plano com Linhagem (save_plan)

Escreve docs/plans/<plan_id>.md com o plano completo, sem cortes ou resumos. Salvar um ID existente atualiza título, corpo e campos, mantendo autor, data de criação e progresso dos marcos. --supersedes marca o plano mais antigo como superseded. save_plan é executado no engine nativo. Em shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory save_plan \
  --title "Roadmap Integrado: Python -> Rust, Roteador de Modelos & Kit de Modelos" \
  --file "caminho/para/plano.md" \
  --version "v1.2.0" \
  --tags "roadmap,rust_refactor,model_router" \
  --milestones "Prioridade 1,Prioridade 2,Milestone 3" \
  --status "active" \
  --session-id "<session_id>" \
  --supersedes "<old_plan_id>"

No PowerShell, execute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory save_plan [argumentos]. Opções: --id (padrão: slug <project>_<title>), --parent-id, --content em vez de --file, --kind feature|bug, --backlog-items "BUG-001,FEAT-002" (vincula os itens, que se tornam planned), --spec-dir specs/NNN-slug (o plano é o envelope dessa pasta Spec Kit).

2. Rastreador de Marcos e Progresso (check_milestone)

check_milestone é executado no engine nativo. Em shells sh (Linux, macOS, Git Bash):

# Progresso e checklist do plano ativo mais recente (ou --id <plan_id>):
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --list

# Marcar um marco como concluído (registra data e autor):
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --milestone "Prioridade 1" --notes "Concluído via PR #319"

# Reverter um marco para pendente:
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --milestone "Prioridade 1" --uncheck

No PowerShell, execute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory check_milestone [argumentos]. O primeiro marco concluído move um plano active para in_progress; o último o move para completed.

3. Detector de Desvio Arquitetural (detect_drift)

Compara qualquer proposta de implementação, issue ou novo prompt contra o plano ativo: similaridade semântica, cobertura e ordem dos marcos, e as regras de anti-padrão do próprio projeto. detect_drift é executado no engine nativo. Em shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory detect_drift --proposal "Prioridade 1: construir o orquestrador ReAct nativo em Rust, substituindo o Python LangGraph"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory detect_drift --file "caminho/para/proposta.md" --strict   # código de saída != 0 em caso de conflito

No PowerShell, execute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory detect_drift [argumentos].

As regras de anti-padrão estão na chave drift_rules do .dev-cycle.json do projeto (procurado a partir de --dir para cima). Sem regras, apenas similaridade e marcos são verificados.

"drift_rules": [
  { "tech": "langchain", "conflict_msg": "O plano base remove LangChain." },
  {
    "tech": "banco de dados paralelo",
    "negative_markers": ["fonte única", "settings.db"],
    "proposal_allow": [],
    "conflict_msg": "A proposta sugere um banco de dados paralelo, violando a fonte única de verdade."
  }
]

Uma regra gera um conflito quando um plano em vigor (active / in_progress) menciona tech junto com um marcador de rejeição, e a proposta menciona tech sem uma frase permitida.

• negative_markers (opcional): palavras que marcam a rejeição. Padrão: remove, replace, without, forbidden, ... mais seus equivalentes em português, mantidos enquanto os planos existentes ainda não foram traduzidos.
• proposal_allow (opcional): frases que tornam uma menção aceitável. Padrão: without <tech>, remove <tech>, replace <tech>, ... mais seus equivalentes em português.

4. Listar Planos (list_plans)

list_plans é executado no engine nativo. Em shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory list_plans [--status active] [--kind bug]

No PowerShell, execute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory list_plans [argumentos].

5. Ler um Plano Completo (get_plan)

get_plan é executado no engine nativo. Em shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory get_plan --id "<plan_id>"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory get_plan                  # plano ativo mais recente

No PowerShell, execute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory get_plan [argumentos].

6. Busca Semântica (search_plans)

search_plans é executado no engine nativo. Em shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory search_plans --query "como implementar o roteador de modelos no chat" [--limit 5] [--all-projects]

No PowerShell, execute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory search_plans [argumentos].

7. Atualizar Status do Ciclo de Vida (update_plan_status)

Define o status do plano, registra no log de status e atualiza os itens do backlog vinculados. update_plan_status é executado no engine nativo. Em shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory update_plan_status --id "<plan_id>" --status "completed" --notes "Prioridade 1 e 2 entregues."

No PowerShell, execute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory update_plan_status [argumentos].

8. Exportar (export_plan)

Copia um plano para outro local, como JSON ou Markdown com ou sem frontmatter. export_plan é executado no engine nativo. Em shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory export_plan --id "<plan_id>" --format json --output-dir "out/"

No PowerShell, execute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory export_plan [argumentos].

9. Recriar o Índice (rebuild_index)

rebuild_index é executado no engine nativo. Em shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory rebuild_index [--project <nome>] [--dir <caminho>]

No PowerShell, execute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory rebuild_index [argumentos].

---

📥 Backlog (backlog)

O primeiro nível de planejamento: um arquivo Markdown (backlog.file em .dev-cycle.json, padrão docs/BACKLOG.md), criado pelo primeiro add a partir de templates/BACKLOG_TEMPLATE.md.

## Bugs | Funcionalidades | Melhorias | Ajustes | Épicos | Fechados

### BUG-001: Predefinição Frontier seleciona um id de modelo obsoleto
- **Severidade**: alta              # bugs: crítica | alta | média | baixa
- **Status**: aberto                # aberto | planejado | em_andamento (concluído | descartado | duplicata | substituído em Fechados)
- **Encontrado em**: 2026-10-16, v0.45.0, PR #333
- **Plano**: -                     # id do plano após promoção
- **Descrição**: `/preset frontier` define `claude-3-7-sonnet`, que o provedor pode rejeitar.

Funcionalidades (FEAT-NNN), melhorias (IMP-NNN) e ajustes (ADJ-NNN) têm Prioridade (alta, média, baixa) em vez de Severidade. Qualquer item, exceto um épico, pode ter - **Épico**: EPIC-NNN. Épicos (EPIC-NNN, seção ## Épicos) agrupam os itens do produto completo; eles têm Prioridade, Status (aberto até fechado), Encontrado em e Descrição, sem Plano, e nunca são promovidos: seus itens são. validate avisa sobre um épico aberto cujos itens estão todos fechados. Os IDs nunca são reutilizados: itens fechados permanecem em ## Fechados com uma nota - **Fechado**: (data e pull request, motivo, duplicata de <ID>, ou substituído por <ID>[, <ID>...]). Um item é substituído quando é substituído por itens diferentes e melhor definidos (uma ideia dividida ou reformulada após a concepção); uma duplicata é a mesma solicitação capturada duas vezes.

backlog é executado no engine nativo: "<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory backlog <comando> [argumentos] em shells sh (Linux, macOS, Git Bash). No PowerShell, execute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory backlog [argumentos].

Tarefa	Comando
Capturar	backlog add --type bug|feature|improvement|adjustment|epic --title "<t>" --description "<d>" [--severity S] [--priority P] [--epic EPIC-NNN] [--found-in "v1.2.0, PR #12"]
Capturar testes manuais com falha	backlog add --from-failed --run vX.Y.Z-rc.N [--severity S]
Resumo (bugs antes de novo trabalho primeiro)	backlog summary [--json]
Listar, exibir	backlog list [--type T] [--status S] [--epic EPIC-NNN] [--all] [--json], backlog show <ID>
Alterar	backlog set <ID> [--title] [--description] [--severity] [--priority] [--status] [--plan] [--epic ID|-]
Promover para um plano	backlog promote <ID> [<ID> ...] [--title T] [--id PLAN_ID] [--version V] ou --into <PLAN_ID>
Fechar	backlog close <ID> [--ref "PR #12"], drop <ID> --reason R, duplicate <ID> --of <ID>, supersede <ID> --by <ID>[,<ID>...], reopen <ID>
Validar	backlog validate

• Capturar não custa nada: sem descoberta, sem plano. O usuário faz isso com o comando /backlog; o agente faz isso para bugs que encontra fora do escopo atual.
• Promoção cria um plano draft a partir de templates/BUG_PLAN_TEMPLATE.md (se todo item for bug: reprodução, evidência e causa raiz, design da correção, teste de regressão) ou templates/FEATURE_PLAN_TEMPLATE.md, com os itens copiados para sua seção Itens do backlog, e vincula ambos os lados. A descoberta é escrita nesse plano; ele é salvo novamente como active, com marcos, para aprovação.
• Itens vinculados seguem seu plano: planned enquanto o plano é draft ou active, in_progress quando está em andamento, fechados como done quando é concluído (check_milestone e update_plan_status no engine).
• Triagem é decisão do usuário: o agente nunca promove, descarta ou re-prioriza por conta própria.
• O script nunca faz commit e se recusa a reescrever um arquivo cuja estrutura não consegue ler, então edições manuais nunca são perdidas.

---

🗺️ Roadmap (roadmap)

As releases do produto em ordem de entrega (roadmap.file em .dev-cycle.json, padrão docs/ROADMAP.md), criado pelo primeiro add a partir de templates/ROADMAP_TEMPLATE.md. Contém a seção ## Releases com formatação fixa:

## Releases

### v1.3.0 (planejada para: 2026-11-30)
- **Itens**: v1.3.0 contém FEAT-005, FEAT-006.
- **Notas**: Refatoração do Rust para tirar o LangChain.
- **Dependências**: v1.2.0.
- **Estado**: planned (planejada | backfilled (lançada e preenchida) | publicada | cancelada).

roadmap é executado no engine nativo. Em shells sh (Linux, macOS, Git Bash):

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory roadmap add --release v1.3.0 --date 2026-11-30 --items "FEAT-005,FEAT-006" --notes "Refatoração do Rust para tirar o LangChain." --depends-on v1.2.0
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory roadmap list [--json]
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory roadmap set v1.3.0 --state published --date 2026-12-01
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory roadmap assign v1.3.0 --items "FEAT-007"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory roadmap validate

No PowerShell, execute & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory roadmap [argumentos].

---

🧩 Planos com Spec Kit

Quando a chave "spec_kit" está presente em .dev-cycle.json e um plano tem spec_dir definido (ex.: specs/004-reranker), o plano atua como envelope para uma pasta Spec Kit completa. A pasta Spec Kit contém readme.md, use_cases.md, sequence.md, api_spec.md, datamodel.md, diagrams/ e assets/ — sem frontmatter, apenas detalhamento. search_plans e get_plan varrem os artefatos em busca do plano, e detect_drift compara com eles.

---

🧠 Índice de Busca

• Localização do banco de dados: ~/.ai-code-agent-memory/plan-memory/db (substitua com a variável de ambiente PLAN_MEMORY_DB).
• Coleção: plan_index.
• Sincronização: a cada comando, o índice é sincronizado a partir dos arquivos de plano (por SHA-256). rebuild_index recria o índice do zero.
• Query: executa busca semântica sobre o conteúdo do plano, título e tags.

---

🔧 Configuração

Adicione ao .dev-cycle.json do projeto:

{
  "plan_memory": {
    "plans_dir": "docs/plans",
    "backlog_file": "docs/BACKLOG.md",
    "roadmap_file": "docs/ROADMAP.md"
  },
  "drift_rules": [
    { "tech": "langchain", "conflict_msg": "O plano base remove LangChain." }
  ]
}

---

📚 Fluxo de Trabalho da Equipe

1. Capture tarefas no backlog (backlog add).
2. Planeje uma release (roadmap add) e atribua itens a ela.
3. Promova itens do backlog para um plano (backlog promote).
4. Escreva o plano de descoberta e detalhamento (save_plan).
5. Aprove o plano (defina como active com update_plan_status).
6. Acompanhe o progresso com check_milestone.
7. Detecte desvios com detect_drift durante o desenvolvimento.
8. Conclua o plano e feche os itens do backlog.
9. Atualize o roadmap conforme necessário.

---

🌐 Idiomas

Os arquivos de plano e documentação podem estar em qualquer idioma. Os comandos e mensagens de erro estão em inglês, mas a documentação da skill pode ser localizada.