@fprad0/skill-master-mcp 0.0.7 → 0.0.9

package/docs/architecture/APRENDIZADO_DE_IMPLEMENTACOES_BEM_SUCEDIDAS.md

@@ -0,0 +1,125 @@
+# Aprendizado de Implementacoes Bem-Sucedidas
+
+Este documento define como o `skill_master` deve aprender com implementacoes que deram certo sem transformar tentativa isolada em comportamento automatico perigoso.
+
+## Principio
+
+Uma implementacao bem-sucedida pode virar uma skill quando existe:
+
+- contexto claro do problema resolvido;
+- padrao reutilizavel, e nao apenas um comando pontual;
+- evidencias de validacao;
+- limites de uso;
+- revisao humana antes de ativacao, instalacao ou publicacao.
+
+O fluxo segue a mesma linha da rede segura de skills: catalogar, preparar rascunho, revisar, aprovar e so entao distribuir.
+
+## Referencias tecnicas pesquisadas
+
+- Claude Code Skills: uma skill deve ter `SKILL.md`, descricao para ativacao por relevancia e corpo carregado somente quando usado. Referencia: `https://docs.anthropic.com/en/docs/claude-code/skills`.
+- Model Context Protocol Tools: ferramentas MCP devem expor acoes com schemas claros e metadados, evitando efeitos colaterais implicitos. Referencia: `https://modelcontextprotocol.io/docs/concepts/tools`.
+- OpenAI Evals: mudancas de comportamento de IA devem ser avaliadas com exemplos, criterios e regressao antes de virarem comportamento confiavel. Referencia: `https://platform.openai.com/docs/guides/evals`.
+
+## Pipeline proposto
+
+1. Registrar o sucesso
+   - titulo da implementacao;
+   - resumo;
+   - arquivos ou links de origem;
+   - comandos de validacao;
+   - evidencias objetivas de que funcionou.
+
+2. Extrair o padrao reutilizavel
+   - quando usar;
+   - quando nao usar;
+   - passos essenciais;
+   - pre-condicoes;
+   - riscos conhecidos.
+
+3. Gerar rascunho local
+   - criar `SKILL.md` em uma pasta de staging;
+   - criar `manifest.json` com evidencias, hashes, riscos e origem;
+   - nao copiar para `~/.codex/skills`;
+   - nao publicar no npm;
+   - nao habilitar automaticamente.
+
+4. Revisar
+   - checar duplicidade por nome e hash;
+   - exigir evidencias;
+   - marcar conteudo arriscado;
+   - listar candidatos externos nao aprovados com link do criador.
+
+5. Aprovar manualmente
+   - somente depois da aprovacao humana a skill pode ser instalada em um diretorio ativo;
+   - publicacao para todos continua exigindo autorizacao explicita do usuario.
+
+6. Ativar em um escopo escolhido
+   - workspace-local: `.codex/skills` dentro do projeto atual;
+   - user-global: `${CODEX_HOME:-~/.codex}/skills`;
+   - custom: caminho informado explicitamente pelo operador.
+
+## Ferramentas MCP adicionadas
+
+- `skill_master_prepare_success_skill`
+  - gera pacote local com `SKILL.md` e `manifest.json`;
+  - registra evidencias, riscos e candidatos externos;
+  - nao instala nem ativa.
+
+- `skill_master_review_success_skill`
+  - revisa o manifesto;
+  - retorna recomendacao: `ready-for-human-approval`, `needs-more-evidence`, `needs-security-review` ou `invalid`.
+
+- `skill_master_list_unapproved_success_skills`
+  - lista rascunhos locais ainda nao aprovados;
+  - inclui candidatos externos, motivo e links do criador.
+
+- `skill_master_prepare_success_skill_approval_package`
+  - cria um pacote Markdown local com checklist de revisao humana;
+  - lista recomendacao, riscos, bloqueios e caminhos de cada draft.
+
+- `skill_master_activate_success_skill`
+  - ativa uma skill aprendida em escopo local, global ou customizado;
+  - exige `confirm_activation: true`;
+  - grava um registro de aprovacao junto da skill instalada.
+
+## Menu e notificacoes
+
+O `skill-master-menu` mostra notificacoes no banner quando existem:
+
+- drafts de skills aprendidas aguardando decisao;
+- skills externas para estudo ainda nao aprovadas.
+
+Acoes adicionadas:
+
+- `notifications`: mostra pendencias e acoes sugeridas;
+- `study-skills`: lista links de estudo e criadores;
+- `approval-package`: gera pacote de aprovacao humana;
+- `activate-learned-local`: ativa uma skill em `.codex/skills` do workspace;
+- `activate-learned-global`: ativa uma skill em `${CODEX_HOME:-~/.codex}/skills`.
+
+## Regra para candidatos externos
+
+Skills encontradas na web ou em repositorios externos podem ajudar, mas entram como `unapproved` ate passarem pelo fluxo interno.
+
+Campos minimos:
+
+- nome;
+- descricao;
+- link da skill;
+- nome do criador;
+- link do criador;
+- motivo de nao aprovacao;
+- flags de risco.
+
+## Estado atual da busca web pelo skill_master
+
+No estado atual, `sources.json` cataloga skills locais do usuario e tambem roots de workspace:
+
+- `.codex/skills`
+- `.agents/skills`
+
+Isso permite que uma skill aprendida e ativada no workspace apareca como fonte `workspace` no catalogo.
+
+`webSources` continua vazio por padrao. Portanto, `skill_master_refresh_catalog` com `include_web: true` nao encontra skills web enquanto nao houver fontes allowlisted.
+
+Isso e intencionalmente seguro: antes de usar skills externas, uma fonte GitHub precisa ser adicionada explicitamente, revisada e mantida como nao confiavel ate aprovacao.

package/docs/architecture/ARQUITETURA_AUTO_UPDATE.md

@@ -0,0 +1,9 @@
+# Arquitetura de Atualizacao Automatica
+
+> STATUS: HISTORICO COM PARTES AINDA VALIDAS
+>
+> Este documento nasceu na fase `00.01`.
+> A base conceitual continua util, mas o estado operacional atual deve ser conferido junto com:
+> - `README.md`
+> - `docs/operations/GUIA_MULTI_COMPUTADOR.md`
+> - `docs/operations/GUIA_NPM_PUBLICO.md`

package/docs/architecture/PLANO_MASTER_ACIONAMENTO_AUTOMATICO_E_APRENDIZADO.md

@@ -0,0 +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.

package/docs/architecture/REDE_SEGURA_DE_SKILLS.md

@@ -0,0 +1,148 @@
+# Rede Segura de Skills do Skill Master
+
+## Objetivo
+
+Permitir que o `skill_master` fique cada vez melhor em varios computadores sem transformar o MCP em um coletor automatico de arquivos privados ou em um canal de execucao de conteudo desconhecido.
+
+O modelo correto e:
+
+1. cada instalacao aprende com as skills locais da propria maquina;
+2. a instalacao compara essas skills com um indice aprovado;
+3. o usuario gera um pacote local de contribuicao;
+4. o pacote e revisado antes de qualquer compartilhamento;
+5. somente skills aprovadas por revisao humana entram no indice compartilhado.
+
+## Principios de seguranca
+
+- Nenhuma skill desconhecida e executada automaticamente.
+- Nenhum arquivo e enviado automaticamente.
+- Caminhos absolutos da maquina nao entram no pacote de contribuicao.
+- O corpo completo da skill nao entra no pacote por padrao.
+- Previews de corpo, quando ativados, sao limitados e passam por redacao basica de segredos.
+- Skills vindas da web continuam marcadas como nao confiaveis.
+- Workspace e plugin entram em contribuicao apenas por opt-in.
+- Candidatos com sinais de risco exigem revisao humana de seguranca.
+
+## Arquitetura
+
+```mermaid
+flowchart TD
+  A["Notebook com skill_master"] --> B["Atualiza catalogo local"]
+  B --> C["Compara com network/approved-skills.json"]
+  C --> D["Gera contribution draft local"]
+  D --> E["Revisa duplicidade, privacidade e risco"]
+  E --> F{"Aprovado por humano?"}
+  F -- "Nao" --> G["Descarta ou corrige"]
+  F -- "Sim" --> H["Atualiza indice aprovado via PR/release"]
+  H --> I["Outros notebooks recebem pelo update normal"]
+```
+
+## Ferramentas MCP
+
+### `skill_master_refresh_catalog`
+
+Atualiza o catalogo local a partir das fontes configuradas em `sources.json`.
+
+Use quando:
+
+- instalar o MCP em uma maquina nova;
+- adicionar novas skills locais;
+- mudar fontes em `sources.json`;
+- preparar uma contribuicao.
+
+### `skill_master_prepare_skill_contribution`
+
+Cria um pacote JSON local com skills novas que ainda nao estao no indice aprovado.
+
+Parametros importantes:
+
+- `refresh_first`: atualiza o catalogo antes de preparar o pacote.
+- `include_body_preview`: inclui um preview curto e redigido do conteudo. Padrao: `false`.
+- `include_workspace`: permite incluir skills de workspace. Padrao: `false`.
+- `include_plugin`: permite incluir skills de plugin. Padrao: `false`.
+- `machine_label`: rotulo opcional da maquina, sem dados sensiveis.
+- `max_candidates`: limite de candidatos.
+- `output_dir`: pasta local para salvar o JSON.
+
+Resultado:
+
+- cria um arquivo `skill-contribution-*.json`;
+- informa quantos candidatos foram encontrados;
+- informa quantos foram ignorados por nome/hash conhecido;
+- informa quantos possuem flags de risco;
+- nao faz upload.
+
+### `skill_master_review_skill_contribution`
+
+Revisa um pacote JSON criado pela ferramenta anterior.
+
+Ela verifica:
+
+- schema do arquivo;
+- candidatos duplicados por hash;
+- candidatos duplicados por nome normalizado;
+- inclusao indevida de caminhos completos;
+- inclusao indevida de corpos completos;
+- flags de risco como comandos destrutivos, downloads pipeados para shell ou segredos aparentes.
+
+Resultado esperado:
+
+- `safe-to-review`: pode seguir para revisao humana comum;
+- `needs-human-security-review`: requer revisao de seguranca;
+- `invalid`: arquivo invalido ou schema nao suportado.
+
+## Indice aprovado
+
+Arquivo:
+
+```text
+network/approved-skills.json
+```
+
+Formato:
+
+```json
+{
+  "generatedAt": "2026-06-25T00:00:00.000Z",
+  "policyVersion": "safe-skill-network-v1",
+  "skills": [
+    {
+      "name": "example-skill",
+      "description": "Descricao aprovada.",
+      "contentHash": "sha256...",
+      "sourceKind": "network",
+      "approvedAt": "2026-06-25T00:00:00.000Z",
+      "approvedBy": "reviewer"
+    }
+  ]
+}
+```
+
+O indice nao precisa armazenar o corpo inteiro da skill. Ele funciona como uma lista de conhecimento aprovado para deduplicacao e governanca.
+
+## Fluxo recomendado
+
+1. No notebook novo, rode `skill_master_refresh_catalog`.
+2. Rode `skill_master_prepare_skill_contribution`.
+3. Revise o JSON local gerado.
+4. Rode `skill_master_review_skill_contribution` no arquivo gerado.
+5. Se estiver seguro, abra um PR atualizando o indice aprovado ou adicionando a skill em um pacote de distribuicao.
+6. Publique uma release/canal `stable`.
+7. Outros notebooks recebem a melhoria pelo fluxo normal de update.
+
+## O que nao fazer
+
+- Nao sincronizar skills desconhecidas automaticamente entre maquinas.
+- Nao copiar arquivos inteiros de skills sem revisao.
+- Nao aceitar scripts de instalacao embutidos em skills sem analise.
+- Nao transformar uma skill local em trusted apenas porque ela existe em uma maquina.
+- Nao publicar contribuicoes com caminhos absolutos do computador.
+- Nao publicar segredos, tokens, URLs privadas ou dados internos de clientes.
+
+## Proximas evolucoes
+
+- Adicionar aprovacao por assinatura de pacote.
+- Criar workflow de GitHub para validar `skill-contribution-*.json`.
+- Criar comando para promover candidatos aprovados ao indice.
+- Criar canal `beta` para skills experimentais.
+- Adicionar score de risco mais granular.