@fprad0/skill-master-mcp 0.0.12 → 1.0.1

package/docs/operations/token-economy-transfer/ANALISE_AVANCADA_ECONOMIA_TOKENS_2026-06-30.md

@@ -0,0 +1,141 @@
+# Analise Avancada - Economia de Tokens Multi-Agente
+
+Data: 2026-06-30
+Projeto: `@fprad0/skill-master-mcp`
+Escopo: Codex/OpenAI, Claude/Anthropic, Gemini/Google e Antigravity.
+
+## Objetivo
+
+Criar uma estrategia reutilizavel para reduzir consumo de tokens antes, durante e depois de cada prompt, sem reduzir qualidade, seguranca ou rastreabilidade.
+
+## Conclusao executiva
+
+Economia real de tokens nao vem de "prompt curto" isolado. Ela vem de governanca de contexto:
+
+1. medir antes de enviar;
+2. separar instrucao persistente de contexto descartavel;
+3. cachear blocos estaveis;
+4. resumir/compactar historico no momento certo;
+5. limitar ferramentas, arquivos e schemas carregados;
+6. roteiar modelo/cliente conforme risco;
+7. pedir resposta no formato minimo suficiente;
+8. registrar aprendizado em skills enxutas, nao em prompts gigantes.
+
+## Fontes oficiais consultadas
+
+- OpenAI prompt caching: `https://platform.openai.com/docs/guides/prompt-caching`
+- OpenAI Codex AGENTS.md: `https://developers.openai.com/codex/guides/agents-md`
+- OpenAI cookbook/tiktoken: `https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken`
+- Anthropic prompt caching: `https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching`
+- Anthropic token counting: `https://docs.anthropic.com/en/docs/build-with-claude/token-counting`
+- Anthropic token-efficient tool use: `https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/token-efficient-tool-use`
+- Anthropic Claude Code memory: `https://docs.anthropic.com/en/docs/claude-code/memory`
+- Gemini token counting: `https://ai.google.dev/gemini-api/docs/tokens`
+- Gemini context caching: `https://ai.google.dev/gemini-api/docs/caching`
+- Gemini thinking controls: `https://ai.google.dev/gemini-api/docs/thinking`
+- Antigravity rules/workflows: `https://antigravity.google/docs/rules-workflows`
+
+Observacao: a documentacao do Antigravity e parcialmente renderizada via pagina dinamica. A estrategia proposta para Antigravity usa somente principios confirmaveis de regras/workflows e praticas portaveis de agentes, sem presumir API interna nao documentada.
+
+## Alavancas por plataforma
+
+### Codex / OpenAI
+
+- Usar `AGENTS.md` para instrucoes persistentes do projeto, evitando repetir regras longas em cada prompt.
+- Manter `AGENTS.md` hierarquico e enxuto: regras globais no topo, detalhes locais perto do codigo.
+- Evitar colar arquivos inteiros quando `rg`, caminhos e trechos bastam.
+- Usar prompt caching para prefixos estaveis quando aplicavel em fluxos API.
+- Fazer resumo de estado antes de conversas longas: objetivo, decisoes, arquivos tocados, riscos e proximas acoes.
+- Separar mensagens de contexto estavel de contexto volatil.
+- Pedir respostas curtas por padrao e detalhadas apenas quando necessario.
+
+### Claude / Anthropic
+
+- Usar prompt caching para system prompts, tool definitions, documentos longos e exemplos estaveis.
+- Usar token counting antes de enviar payloads grandes.
+- Reduzir schemas de tools: descricoes curtas, parametros essenciais, sem exemplos redundantes no schema.
+- Usar token-efficient tool use quando disponivel.
+- Manter memoria/CLAUDE.md com fatos duraveis, nao logs longos.
+- Compactar historico quando a conversa passar de fase: descoberta -> plano -> implementacao -> validacao.
+
+### Gemini / Google
+
+- Usar `countTokens` para validar custo antes de prompts grandes.
+- Usar context caching para conteudo grande e reutilizado.
+- Controlar thinking budget quando a tarefa nao precisa raciocinio longo.
+- Remover anexos duplicados e converter contexto repetido em resumo estruturado.
+- Separar instrucoes permanentes, arquivos de referencia e pedido atual.
+
+### Antigravity
+
+- Colocar regras duraveis em rules/workflows, nao repetir no prompt.
+- Criar workflows pequenos por tipo de tarefa: investigar, planejar, implementar, revisar, publicar.
+- Usar arquivos de handoff compactos e caminhos precisos.
+- Evitar carregar contexto amplo do workspace sem objetivo e lista de arquivos.
+- Usar "checkpoint de contexto" antes de trocar de agente/maquina.
+
+## Padroes transversais
+
+### 1. Prompt Preflight
+
+Antes de enviar:
+
+- Qual e o objetivo em uma frase?
+- Qual e o menor conjunto de arquivos/fontes?
+- Precisa mesmo de resposta longa?
+- Existe contexto repetido que pode virar referencia por caminho?
+- Ha budget maximo de tokens/resposta?
+- Ha ferramenta ou skill que evita colar documentacao?
+
+### 2. Context Layering
+
+Separar:
+
+- `regras`: persistentes, raramente mudam;
+- `estado`: resumo do trabalho atual;
+- `evidencias`: links, arquivos, trechos;
+- `pedido`: acao atual;
+- `saida`: formato esperado.
+
+### 3. Compression Gates
+
+Compactar quando:
+
+- a conversa muda de fase;
+- ha mais de 8-12 arquivos mencionados;
+- ha logs repetidos;
+- ha docs oficiais longas;
+- o agente comeca a repetir contexto antigo;
+- o usuario vai transferir para outra maquina.
+
+### 4. Tool Diet
+
+Reduzir consumo escondido de tokens:
+
+- nao expor tools irrelevantes em prompts manuais;
+- resumir resultados de shell em vez de colar saida completa;
+- usar `rg` para localizar trechos antes de abrir arquivos;
+- limitar screenshots/logs a evidencias necessarias;
+- evitar subagentes para tarefas pequenas.
+
+### 5. Output Budget
+
+Definir padrao:
+
+- resposta curta para status;
+- bullet list para plano;
+- tabela apenas quando compara opcoes;
+- codigo somente quando necessario;
+- anexos grandes como arquivos `.md`, nao no chat.
+
+## Riscos
+
+- Economizar tokens demais pode remover evidencia critica.
+- Cache mal usado pode manter instrucao obsoleta.
+- Resumo agressivo pode perder restricoes de seguranca.
+- Token counting por provedor nao e perfeitamente intercambiavel.
+- Skills globais muito invasivas podem atrapalhar usuarios que precisam de contexto completo.
+
+## Principio de seguranca
+
+Economia de token e uma heuristica, nao uma ordem absoluta. Quando houver risco legal, financeiro, medico, seguranca, publicacao, delecao, credenciais ou autorizacao, preservar contexto e verificacao vale mais que economizar tokens.

package/docs/operations/token-economy-transfer/PLANO_DEV_SENIOR_MASTER_TOKEN_ECONOMY_2026-06-30.md

@@ -0,0 +1,171 @@
+# Plano Dev Senior Master - Token Economy Global Skills
+
+Data: 2026-06-30
+Projeto: `@fprad0/skill-master-mcp`
+
+## Visao
+
+Adicionar ao Skill Master uma camada global de economia de tokens que atua antes de prompts grandes, durante conversas longas e em handoffs entre maquinas/clientes.
+
+## Objetivos
+
+- Reduzir tokens repetidos em Codex, Claude, Gemini e Antigravity.
+- Manter qualidade e seguranca.
+- Criar skills globais reutilizaveis.
+- Integrar com `skill_master` sem bloquear o usuario.
+- Medir economia por estimativa, nao por promessa absoluta.
+
+## Nao objetivos
+
+- Nao burlar limites de contexto.
+- Nao reduzir contexto em tarefas de alto risco sem aviso.
+- Nao instalar skills globalmente sem aprovacao humana.
+- Nao depender de API privada de Antigravity.
+
+## Arquitetura proposta
+
+### Skill 1 - `token-economy-orchestrator`
+
+Skill principal. Decide quando ativar economia de tokens e qual modo usar.
+
+Modos:
+
+- `light`: respostas curtas e remocao de redundancia.
+- `balanced`: preflight completo, budget e compressao seletiva.
+- `aggressive`: usado apenas com confirmacao; gera handoff/resumo e evita contexto bruto.
+
+### Skill 2 - `prompt-budget-gate`
+
+Preflight antes do prompt:
+
+- classifica risco;
+- define budget de entrada/saida;
+- sugere arquivos/fontes minimos;
+- decide se deve usar cache, resumo ou busca incremental.
+
+### Skill 3 - `context-compression-handoff`
+
+Compacta contexto para:
+
+- continuar conversa;
+- transferir para outra maquina;
+- abrir outro cliente;
+- publicar release;
+- retomar task depois de dias.
+
+### Skill 4 futura - `tool-schema-diet`
+
+Revisar MCP tools e schemas para reduzir tokens:
+
+- descricoes enxutas;
+- parametros claros;
+- menos exemplos no schema;
+- paginacao e responses compactas.
+
+## Fluxo operacional
+
+1. Usuario manda prompt.
+2. `skill_master` detecta se ha risco de prompt longo, contexto repetido ou multi-cliente.
+3. `token-economy-orchestrator` decide modo.
+4. `prompt-budget-gate` gera recomendacao curta.
+5. Se necessario, `context-compression-handoff` cria resumo/handoff.
+6. Agente executa usando contexto minimo suficiente.
+7. Resultado final inclui somente detalhes relevantes.
+
+## Politica de ativacao
+
+Ativar quando:
+
+- prompt pede pesquisa, planejamento, migracao, review ou handoff;
+- ha muitos arquivos/anexos/logs;
+- usuario menciona economia de tokens;
+- conversa esta longa;
+- tarefa envolve Codex, Claude, Gemini ou Antigravity;
+- precisa transferir para outro computador.
+
+Nao ativar agressivamente quando:
+
+- tarefa e curta;
+- usuario pede explicacao completa;
+- ha alto risco e detalhes sao essenciais;
+- a fonte oficial precisa ser citada com precisao;
+- a conversa esta em fase de debugging sensivel.
+
+## Integracao com MCP
+
+### Fase 1 - Draft
+
+- Criar skills em `docs/skill-candidates/v0.0.12`.
+- Criar prompt task de implementacao.
+- Criar documento de pesquisa e plano.
+
+### Fase 2 - Review
+
+- Revisar duplicidade com skills existentes.
+- Validar linguagem de ativacao.
+- Rodar testes do pacote.
+- Confirmar que nenhuma skill promete economia exata sem medicao.
+
+### Fase 3 - Ativacao global
+
+Depois de aprovacao humana:
+
+```bash
+skill-master-install-global-skills
+```
+
+Ou ativar uma skill revisada especifica via fluxo de sucesso/aprovacao do `skill_master`.
+
+### Fase 4 - Evolucao de codigo
+
+Adicionar ao prompt router:
+
+- recomendacao automatica das skills de economia;
+- modo `token-budget`;
+- metricas de antes/depois estimadas;
+- menu action: `token-economy`.
+
+## Criterios de aceite
+
+- Skills tem frontmatter valido.
+- Cada skill e curta, acionavel e segura.
+- Plano cobre Codex, Claude, Gemini e Antigravity.
+- Documentos citam fontes oficiais.
+- `npm run check` passa.
+- `npm pack --dry-run` inclui os artefatos.
+- Nenhum segredo ou token e criado.
+
+## Metricas sugeridas
+
+- reducao estimada de caracteres do prompt;
+- numero de arquivos evitados no contexto;
+- numero de logs resumidos;
+- numero de regras movidas para skill/AGENTS/CLAUDE/rules;
+- taxa de tarefas que exigiram reenvio por contexto insuficiente;
+- tempo ate primeira acao util.
+
+## Roadmap
+
+### Sprint 1
+
+- Draft das 3 skills.
+- Prompt task 019.
+- Documentacao de pesquisa.
+
+### Sprint 2
+
+- Testar em 10 prompts reais.
+- Criar exemplos antes/depois.
+- Ajustar gatilhos de ativacao.
+
+### Sprint 3
+
+- Integrar no `skill_master_prompt_router`.
+- Adicionar menu/doctor para diagnostico de token economy.
+- Criar pacote de aprovacao.
+
+### Sprint 4
+
+- Instalar globalmente apos aprovacao.
+- Medir uso em Codex, Claude, Gemini e Antigravity.
+- Documentar ganhos e regressões.

package/docs/operations/token-economy-transfer/README_TRANSFERENCIA_TOKEN_ECONOMY.md

@@ -0,0 +1,31 @@
+# Transferencia - Token Economy Global Skills
+
+Use este pacote no computador autorizado para revisar e integrar as skills globais de economia de tokens.
+
+## Arquivos
+
+```text
+docs/operations/token-economy-transfer/ANALISE_AVANCADA_ECONOMIA_TOKENS_2026-06-30.md
+docs/operations/token-economy-transfer/PLANO_DEV_SENIOR_MASTER_TOKEN_ECONOMY_2026-06-30.md
+docs/skill-candidates/v0.0.12/token-economy-orchestrator/SKILL.md
+docs/skill-candidates/v0.0.12/prompt-budget-gate/SKILL.md
+docs/skill-candidates/v0.0.12/context-compression-handoff/SKILL.md
+docs/prompt-tasks/PROMPT_TASK_019_TOKEN_ECONOMY_GLOBAL_SKILLS.md
+```
+
+## Sequencia recomendada
+
+```bash
+npm install
+npm run check
+npm pack --dry-run
+```
+
+Depois, revisar manualmente as skills e so entao aprovar/instalar globalmente.
+
+## Nao fazer
+
+- Nao instalar globalmente sem revisao humana.
+- Nao usar modo agressivo em tarefas de alto risco sem confirmacao.
+- Nao remover contexto de seguranca para economizar tokens.
+- Nao prometer percentual fixo de economia.