@fprad0/skill-master-mcp 0.0.12 → 1.0.0

package/docs/architecture/PLANO_MASTER_ACIONAMENTO_AUTOMATICO_E_APRENDIZADO.md

@@ -1,341 +1,341 @@
-# Plano Master - Acionamento automatico e aprendizado do Skill Master
-
-Data: 2026-06-27
-Status: plano de execucao, sem publicacao
-
-## Visao
-
-O `skill-master-mcp` deve evoluir de um catalogo/recomendador de skills para uma camada de orquestracao consciente do trabalho do usuario. O objetivo nao e "executar tudo automaticamente"; o objetivo e reconhecer quando uma skill, um fluxo aprovado ou uma persona tecnica aumenta a qualidade da execucao.
-
-O sistema deve ser acionado por:
-
-- mencao direta: `skill-master`, `skill_master`, `skill-master-mcp`;
-- indicios de tarefa complexa: implementar, corrigir, pesquisar, publicar, atualizar Notion, validar pacote, revisar seguranca;
-- indicios de aprendizado: "isso deu certo", "aprenda com isso", "crie uma skill", "salve esse fluxo";
-- contexto do computador: skills locais aprovadas, skills globais aprovadas, base de dados de skills, candidatos pendentes.
-
-## Principio central
-
-O Skill Master deve ser automatico na recomendacao e disciplinado na execucao.
-
-Isso significa:
-
-- pode recomendar automaticamente;
-- pode preparar plano automaticamente;
-- pode abrir menu/notificacao;
-- pode criar rascunho de skill;
-- nao pode publicar versao sem autorizacao;
-- nao pode aprovar skill externa sozinho;
-- nao pode executar comando destrutivo sem confirmacao clara;
-- nao pode guardar segredo/token em skill.
-
-## Persona permanente: Dev Senior Master
-
-### Identidade
-
-Nome operacional: `Dev Senior Master`.
-
-Funcao: atuar como desenvolvedor senior master, engenheiro senior master e arquiteto pragmatico quando o prompt entrar em area de programacao, automacao, MCP, CLI, Notion, distribuicao, seguranca, testes, IA aplicada ou engenharia de produto.
-
-### Comportamento
-
-- Trabalhar com evidencia: ler o repositorio antes de opinar.
-- Separar plano, implementacao, validacao e publicacao.
-- Preferir solucao simples, segura e testavel.
-- Reusar o que ja existe antes de criar do zero.
-- Preservar alteracoes do usuario.
-- Registrar decisoes importantes no Notion quando o trabalho fizer parte da continuidade do MCP.
-- Validar com comandos reais quando possivel.
-- Tratar web, repos externos e skills externas como material nao confiavel ate aprovacao.
-- Avisar riscos tecnicos sem paralisar o trabalho.
-- Nao transformar brainstorm em release.
-
-### Estilo tecnico
-
-- clareza objetiva;
-- rigor de engenharia;
-- decisao defensavel;
-- foco em manutencao;
-- foco em usuario real;
-- zero publicacao sem autorizacao.
-
-## Modos de ativacao
-
-### 1. `manual`
-
-Aciona somente quando o usuario mencionar `skill-master`, `skill_master` ou `skill-master-mcp`.
-
-Uso:
-
-- ambientes novos;
-- usuarios que querem controle total;
-- debugging de ativacao.
-
-### 2. `balanced`
-
-Aciona em mencao direta e em tarefas tecnicas onde a chance de ganho seja alta.
-
-Exemplos:
-
-- "crie uma skill";
-- "atualize o Notion";
-- "pesquise e implemente";
-- "valide o pacote npm";
-- "melhore o menu do MCP";
-- "gere prompts para execucao";
-- "aprenda com essa implementacao".
-
-Uso padrao recomendado.
-
-### 3. `always-on-assisted`
-
-Aciona como avaliador silencioso em quase todo prompt tecnico. Ele nao executa tudo; ele devolve recomendacao, persona e plano curto.
-
-Regra:
-
-- se a tarefa for trivial, responder que nenhuma skill e necessaria;
-- se houver skill util, recomendar e justificar;
-- se houver risco, bloquear ou pedir aprovacao;
-- se houver aprendizado possivel, sugerir captura.
-
-Uso:
-
-- ambiente pessoal do usuario;
-- computador principal;
-- apos evals com baixa taxa de falso positivo.
-
-## Arquitetura proposta
-
-```mermaid
-flowchart TD
-	A[Prompt do usuario] --> B[Skill global skill-master-orchestrator]
-	B --> C{Mencao direta ou tarefa tecnica?}
-	C -->|nao| D[Responder sem Skill Master]
-	C -->|sim| E[skill_master_prompt_router]
-	E --> F[Recomendacao de skills]
-	E --> G[Persona Dev Senior Master]
-	E --> H[Plano e riscos]
-	F --> I[Execucao assistida]
-	I --> J{Sucesso comprovado?}
-	J -->|sim| K[skill_master_learn_success]
-	K --> L[Skill candidata]
-	L --> M[Aprovacao humana]
-	M -->|aprovada| N[Skill local/global]
-	M -->|reprovada| O[Lista de estudo]
-```
-
-## Novas capacidades MCP
-
-### `skill_master_prompt_router`
-
-Entrada:
-
-- prompt do usuario;
-- modo de ativacao;
-- contexto do projeto;
-- lista de skills locais/globais;
-- flags de risco.
-
-Saida:
-
-- `should_activate`;
-- `activation_reason`;
-- `recommended_skills`;
-- `persona_overlay`;
-- `execution_mode`;
-- `safety_gates`;
-- `notion_update_needed`;
-- `learning_opportunity`;
-- `next_action`.
-
-### `skill_master_activation_config`
-
-Gerencia configuracao:
-
-- modo atual;
-- termos de ativacao;
-- diretorios de skills locais/globais;
-- politica de aprovacao;
-- notificacoes do menu.
-
-### `skill_master_learn_success`
-
-Registra um sucesso comprovado:
-
-- descricao do problema;
-- evidencias;
-- arquivos relevantes;
-- comandos e resultados;
-- decisao do usuario;
-- padrao reutilizavel;
-- riscos e limites.
-
-### `skill_master_generate_skill_candidate`
-
-Gera rascunho de skill:
-
-- `SKILL.md` candidato;
-- exemplos de prompts;
-- checklist de validacao;
-- fontes e evidencias;
-- status `pending_approval`.
-
-### `skill_master_approve_skill_candidate`
-
-Ativa apos aprovacao:
-
-- local no projeto;
-- global no computador;
-- registro no Notion;
-- hash e data de aprovacao.
-
-## Pipeline de aprendizado
-
-### Etapa 1 - Captura
-
-Acionada quando:
-
-- o usuario disser que funcionou;
-- testes passarem;
-- build/smoke passar;
-- Notion registrar sucesso;
-- um prompt task for concluido com evidencia.
-
-### Etapa 2 - Destilacao
-
-Transformar a implementacao em padrao:
-
-- qual problema resolve;
-- quando usar;
-- quando nao usar;
-- preflight necessario;
-- comandos confiaveis;
-- arquivos que normalmente mudam;
-- riscos;
-- validacoes.
-
-### Etapa 3 - Candidato
-
-Criar uma skill candidata, mas nao ativa:
-
-- frontmatter com descricao forte de trigger;
-- corpo curto;
-- referencias quando necessario;
-- exemplos;
-- evidencias;
-- status pendente.
-
-### Etapa 4 - Avaliacao
-
-Rodar validacoes:
-
-- formato da skill;
-- risco de segredo;
-- comandos destrutivos;
-- origem externa;
-- licenca/proveniencia;
-- duplicidade com skills existentes;
-- prompt evals de ativacao.
-
-### Etapa 5 - Aprovacao humana
-
-Menu deve mostrar:
-
-- candidatos pendentes;
-- score de confianca;
-- evidencias;
-- opcoes: aprovar local, aprovar global, manter para estudo, rejeitar.
-
-### Etapa 6 - Ativacao
-
-Se aprovada:
-
-- copiar para `.codex/skills` do projeto ou `~/.codex/skills`;
-- registrar em `network/approved-skills.json`;
-- atualizar Notion;
-- adicionar ao menu.
-
-## Plano de execucao
-
-### Fase 1 - Documentacao e prompts
-
-Entregas:
-
-- pesquisa tecnica;
-- plano master;
-- prompts `.md` executaveis;
-- pagina Notion com roteiro.
-
-Status: fase atual.
-
-### Fase 2 - Persona e skill orquestradora
-
-Entregas:
-
-- skill `skill-master-orchestrator`;
-- persona `Dev Senior Master`;
-- referencias de politicas;
-- validacao com `quick_validate.py`.
-
-### Fase 3 - Router de ativacao
-
-Entregas:
-
-- modulo `src/prompt-router.ts`;
-- tool MCP `skill_master_prompt_router`;
-- testes de roteamento;
-- fixtures de prompts positivos/negativos.
-
-### Fase 4 - Configuracao e menu
-
-Entregas:
-
-- modo de ativacao configuravel;
-- notificacoes no `skill-master-menu`;
-- comando para status;
-- comando para alternar modo.
-
-### Fase 5 - Aprendizado de sucesso
-
-Entregas:
-
-- pipeline de evidencia;
-- geracao de skill candidata;
-- pacote de aprovacao humana;
-- aprovacao local/global.
-
-### Fase 6 - Evals e governanca
-
-Entregas:
-
-- suite de evals;
-- metricas;
-- relatorio de falso positivo/falso negativo;
-- gates antes de publicar.
-
-### Fase 7 - Piloto local
-
-Entregas:
-
-- instalacao local;
-- teste em prompts reais;
-- ajuste de trigger;
-- Notion atualizado.
-
-### Fase 8 - Release somente com autorizacao
-
-Entregas:
-
-- bump de versao;
-- changelog;
-- pack/install smoke;
-- publicacao apenas se o usuario autorizar.
-
-## Definition of Done
-
-- Existe uma pagina Notion com plano e roteiro.
-- Existem prompts `.md` sequenciados para execucao.
-- O plano separa ativacao, aprendizado, aprovacao, evals e publicacao.
-- A persona `Dev Senior Master` esta especificada.
-- O modo automatico e descrito como assistido, medido e seguro.
-- Nenhuma publicacao foi feita sem autorizacao.
+# Plano Master - Acionamento automatico e aprendizado do Skill Master
+
+Data: 2026-06-27
+Status: plano de execucao, sem publicacao
+
+## Visao
+
+O `skill-master-mcp` deve evoluir de um catalogo/recomendador de skills para uma camada de orquestracao consciente do trabalho do usuario. O objetivo nao e "executar tudo automaticamente"; o objetivo e reconhecer quando uma skill, um fluxo aprovado ou uma persona tecnica aumenta a qualidade da execucao.
+
+O sistema deve ser acionado por:
+
+- mencao direta: `skill-master`, `skill_master`, `skill-master-mcp`;
+- indicios de tarefa complexa: implementar, corrigir, pesquisar, publicar, atualizar Notion, validar pacote, revisar seguranca;
+- indicios de aprendizado: "isso deu certo", "aprenda com isso", "crie uma skill", "salve esse fluxo";
+- contexto do computador: skills locais aprovadas, skills globais aprovadas, base de dados de skills, candidatos pendentes.
+
+## Principio central
+
+O Skill Master deve ser automatico na recomendacao e disciplinado na execucao.
+
+Isso significa:
+
+- pode recomendar automaticamente;
+- pode preparar plano automaticamente;
+- pode abrir menu/notificacao;
+- pode criar rascunho de skill;
+- nao pode publicar versao sem autorizacao;
+- nao pode aprovar skill externa sozinho;
+- nao pode executar comando destrutivo sem confirmacao clara;
+- nao pode guardar segredo/token em skill.
+
+## Persona permanente: Dev Senior Master
+
+### Identidade
+
+Nome operacional: `Dev Senior Master`.
+
+Funcao: atuar como desenvolvedor senior master, engenheiro senior master e arquiteto pragmatico quando o prompt entrar em area de programacao, automacao, MCP, CLI, Notion, distribuicao, seguranca, testes, IA aplicada ou engenharia de produto.
+
+### Comportamento
+
+- Trabalhar com evidencia: ler o repositorio antes de opinar.
+- Separar plano, implementacao, validacao e publicacao.
+- Preferir solucao simples, segura e testavel.
+- Reusar o que ja existe antes de criar do zero.
+- Preservar alteracoes do usuario.
+- Registrar decisoes importantes no Notion quando o trabalho fizer parte da continuidade do MCP.
+- Validar com comandos reais quando possivel.
+- Tratar web, repos externos e skills externas como material nao confiavel ate aprovacao.
+- Avisar riscos tecnicos sem paralisar o trabalho.
+- Nao transformar brainstorm em release.
+
+### Estilo tecnico
+
+- clareza objetiva;
+- rigor de engenharia;
+- decisao defensavel;
+- foco em manutencao;
+- foco em usuario real;
+- zero publicacao sem autorizacao.
+
+## Modos de ativacao
+
+### 1. `manual`
+
+Aciona somente quando o usuario mencionar `skill-master`, `skill_master` ou `skill-master-mcp`.
+
+Uso:
+
+- ambientes novos;
+- usuarios que querem controle total;
+- debugging de ativacao.
+
+### 2. `balanced`
+
+Aciona em mencao direta e em tarefas tecnicas onde a chance de ganho seja alta.
+
+Exemplos:
+
+- "crie uma skill";
+- "atualize o Notion";
+- "pesquise e implemente";
+- "valide o pacote npm";
+- "melhore o menu do MCP";
+- "gere prompts para execucao";
+- "aprenda com essa implementacao".
+
+Uso padrao recomendado.
+
+### 3. `always-on-assisted`
+
+Aciona como avaliador silencioso em quase todo prompt tecnico. Ele nao executa tudo; ele devolve recomendacao, persona e plano curto.
+
+Regra:
+
+- se a tarefa for trivial, responder que nenhuma skill e necessaria;
+- se houver skill util, recomendar e justificar;
+- se houver risco, bloquear ou pedir aprovacao;
+- se houver aprendizado possivel, sugerir captura.
+
+Uso:
+
+- ambiente pessoal do usuario;
+- computador principal;
+- apos evals com baixa taxa de falso positivo.
+
+## Arquitetura proposta
+
+```mermaid
+flowchart TD
+	A[Prompt do usuario] --> B[Skill global skill-master-orchestrator]
+	B --> C{Mencao direta ou tarefa tecnica?}
+	C -->|nao| D[Responder sem Skill Master]
+	C -->|sim| E[skill_master_prompt_router]
+	E --> F[Recomendacao de skills]
+	E --> G[Persona Dev Senior Master]
+	E --> H[Plano e riscos]
+	F --> I[Execucao assistida]
+	I --> J{Sucesso comprovado?}
+	J -->|sim| K[skill_master_learn_success]
+	K --> L[Skill candidata]
+	L --> M[Aprovacao humana]
+	M -->|aprovada| N[Skill local/global]
+	M -->|reprovada| O[Lista de estudo]
+```
+
+## Novas capacidades MCP
+
+### `skill_master_prompt_router`
+
+Entrada:
+
+- prompt do usuario;
+- modo de ativacao;
+- contexto do projeto;
+- lista de skills locais/globais;
+- flags de risco.
+
+Saida:
+
+- `should_activate`;
+- `activation_reason`;
+- `recommended_skills`;
+- `persona_overlay`;
+- `execution_mode`;
+- `safety_gates`;
+- `notion_update_needed`;
+- `learning_opportunity`;
+- `next_action`.
+
+### `skill_master_activation_config`
+
+Gerencia configuracao:
+
+- modo atual;
+- termos de ativacao;
+- diretorios de skills locais/globais;
+- politica de aprovacao;
+- notificacoes do menu.
+
+### `skill_master_learn_success`
+
+Registra um sucesso comprovado:
+
+- descricao do problema;
+- evidencias;
+- arquivos relevantes;
+- comandos e resultados;
+- decisao do usuario;
+- padrao reutilizavel;
+- riscos e limites.
+
+### `skill_master_generate_skill_candidate`
+
+Gera rascunho de skill:
+
+- `SKILL.md` candidato;
+- exemplos de prompts;
+- checklist de validacao;
+- fontes e evidencias;
+- status `pending_approval`.
+
+### `skill_master_approve_skill_candidate`
+
+Ativa apos aprovacao:
+
+- local no projeto;
+- global no computador;
+- registro no Notion;
+- hash e data de aprovacao.
+
+## Pipeline de aprendizado
+
+### Etapa 1 - Captura
+
+Acionada quando:
+
+- o usuario disser que funcionou;
+- testes passarem;
+- build/smoke passar;
+- Notion registrar sucesso;
+- um prompt task for concluido com evidencia.
+
+### Etapa 2 - Destilacao
+
+Transformar a implementacao em padrao:
+
+- qual problema resolve;
+- quando usar;
+- quando nao usar;
+- preflight necessario;
+- comandos confiaveis;
+- arquivos que normalmente mudam;
+- riscos;
+- validacoes.
+
+### Etapa 3 - Candidato
+
+Criar uma skill candidata, mas nao ativa:
+
+- frontmatter com descricao forte de trigger;
+- corpo curto;
+- referencias quando necessario;
+- exemplos;
+- evidencias;
+- status pendente.
+
+### Etapa 4 - Avaliacao
+
+Rodar validacoes:
+
+- formato da skill;
+- risco de segredo;
+- comandos destrutivos;
+- origem externa;
+- licenca/proveniencia;
+- duplicidade com skills existentes;
+- prompt evals de ativacao.
+
+### Etapa 5 - Aprovacao humana
+
+Menu deve mostrar:
+
+- candidatos pendentes;
+- score de confianca;
+- evidencias;
+- opcoes: aprovar local, aprovar global, manter para estudo, rejeitar.
+
+### Etapa 6 - Ativacao
+
+Se aprovada:
+
+- copiar para `.codex/skills` do projeto ou `~/.codex/skills`;
+- registrar em `network/approved-skills.json`;
+- atualizar Notion;
+- adicionar ao menu.
+
+## Plano de execucao
+
+### Fase 1 - Documentacao e prompts
+
+Entregas:
+
+- pesquisa tecnica;
+- plano master;
+- prompts `.md` executaveis;
+- pagina Notion com roteiro.
+
+Status: fase atual.
+
+### Fase 2 - Persona e skill orquestradora
+
+Entregas:
+
+- skill `skill-master-orchestrator`;
+- persona `Dev Senior Master`;
+- referencias de politicas;
+- validacao com `quick_validate.py`.
+
+### Fase 3 - Router de ativacao
+
+Entregas:
+
+- modulo `src/prompt-router.ts`;
+- tool MCP `skill_master_prompt_router`;
+- testes de roteamento;
+- fixtures de prompts positivos/negativos.
+
+### Fase 4 - Configuracao e menu
+
+Entregas:
+
+- modo de ativacao configuravel;
+- notificacoes no `skill-master-menu`;
+- comando para status;
+- comando para alternar modo.
+
+### Fase 5 - Aprendizado de sucesso
+
+Entregas:
+
+- pipeline de evidencia;
+- geracao de skill candidata;
+- pacote de aprovacao humana;
+- aprovacao local/global.
+
+### Fase 6 - Evals e governanca
+
+Entregas:
+
+- suite de evals;
+- metricas;
+- relatorio de falso positivo/falso negativo;
+- gates antes de publicar.
+
+### Fase 7 - Piloto local
+
+Entregas:
+
+- instalacao local;
+- teste em prompts reais;
+- ajuste de trigger;
+- Notion atualizado.
+
+### Fase 8 - Release somente com autorizacao
+
+Entregas:
+
+- bump de versao;
+- changelog;
+- pack/install smoke;
+- publicacao apenas se o usuario autorizar.
+
+## Definition of Done
+
+- Existe uma pagina Notion com plano e roteiro.
+- Existem prompts `.md` sequenciados para execucao.
+- O plano separa ativacao, aprendizado, aprovacao, evals e publicacao.
+- A persona `Dev Senior Master` esta especificada.
+- O modo automatico e descrito como assistido, medido e seguro.
+- Nenhuma publicacao foi feita sem autorizacao.