plugin-dev

1. Missão

Este meta-skill garante a governança técnica completa do ecossistema de IA: a concepção, criação e refinamento contínuo dos Skills compartilhados (.agents/skills/), das Regras de Ouro e Diretivas Permanentes (.agents/rules/), bem como a capitalização contínua de conhecimento de pacote ([NomePkg]_IA_CONTEXT.md).

Princípios Fundadores Invioláveis:

• Single Source of Truth (SSOT): Toda regra, especificação ou diretiva deve residir em um único local de autoridade. A duplicação de instruções em múltiplos arquivos é formalmente proibida.
• DRY (Don't Repeat Yourself): Nunca reescrever ou duplicar uma instrução existente. Todo skill ou documento deve explorar a regra existente por simples referência ou link.
• Ele aplica sistematicamente os patterns de referência da Anthropic (feature-dev, claude-code-setup, pr-review-toolkit), zela pela não contradição das regras, documenta novos fluxos de trabalho e registra feedbacks na forma de fichas de incidentes YAML.

2. Acionamento & Limites

• Quando ativar:
  • Fim de conversa / Retrospectiva de sessão: Invocado por /plugin-dev para propor um plano de enriquecimento do arquivo [NomePkg]_IA_CONTEXT.md do pacote tratado e das competências mobilizadas, registrando descobertas, armadilhas e mecânicas aprendidas durante a sessão.
  • Solicitação de criação de um novo skill ("Crie um skill para gerenciar testes automatizados", "Adicione um skill projetar-arquitetura").
  • Refinamento ou correção de um skill existente com base em feedback ("Modifique o skill feature-dev para proibir X").
  • Criação, atualização ou auditoria de uma Regra comportamental ("Adicione uma regra para exibir os skills utilizados", "Modifique a regra crítica sobre migrações em critical-rules.md").
  • Documentação de um novo fluxo de trabalho.
  • Auditoria de conformidade das competências, coerência das diretivas, eliminação de duplicações (DRY/SSOT) e controle SemVer.
• Quando NÃO ativar:
  • Redação ou simplificação de tutoriais ➔ Usar tutorial-writer.
  • Desenvolvimento de componentes ou estilos Jekyll ➔ Usar dev-jekyll.
  • Sincronização da base técnica compartilhada (Core Theme) ➔ Usar sync-theme.
  • Inicialização de agente ou diagnóstico de projeto ➔ Usar project-setup.

3. Entradas & Recursos a Carregar

• Prioridade 1: .agents/skills/plugin-dev/resources/anthropic-skill-patterns.md (Patterns oficiais da Anthropic encapsulados).
• Prioridade 2: Arquivos de regras:
  • .agents/rules/critical-rules.md (Regras críticas invariáveis).
  • .agents/rules/*.md (Diretivas de execução e estilo).
• Prioridade 3: .agents/templates/generic-skill.md (Template em 10 seções) e .agents/templates/workflow-blueprint.md (Modelo de fluxo).
• Prioridade 4: Registro catalog.yaml e CHANGELOG.md do Hub Global.

4. Restrições & Regras Invioláveis

• Princípios Cardeais SSOT (Single Source of Truth) & DRY:
  • Toda convenção, diretiva ou especificação deve existir em um único e exclusivo local.
  • As regras comportamentais residem em .agents/rules/[nome].md. As competências nunca devem duplicar o texto dessas regras, mas sim referenciá-las diretamente.
• Formato Padrão dos Arquivos de Contexto de Pacote:
  • Todo arquivo de contexto de pacote deve obrigatoriamente ser nomeado modules/[NomePkg]/[NomePkg]_IA_CONTEXT.md (ex: PkgRealizacaoTarefa_IA_CONTEXT.md).
• Minimalismo Estrito de .agents/references/ (Encapsulamento Mono-Competência):
  • O diretório transversal .agents/references/ deve conter o mínimo estrito de arquivos, reservado exclusivamente para convenções e padrões compartilhados por pelo menos 2 competências.
  • Todo arquivo metodológico, guia, catálogo ou template usado por uma única competência DEVE OBRIGATORIAMENTE ser movido e encapsulado em <skill>/resources/ (princípio de divulgação progressiva da Anthropic).
• Bloco inspiration Obrigatório: Todo skill criado ou modificado DEVE imperativamente conter a metadado inspiration: em seu frontmatter YAML com sua fonte, plugin de referência e pattern.
• Respeito Estrito às 10 Seções: Nenhum skill pode ser publicado se omitir uma das 10 seções padrão.
• Hierarquia e Não Contradição das Regras:
  • Uma regra local (.agents/rules/) prevalece sobre uma recomendação geral, mas nunca deve violar uma regra crítica de segurança (critical-rules.md) sem arbitragem explícita.
  • Cada regra deve ser concisa, inequívoca e conter um gatilho explícito (trigger: always_on ou condicional).
• Validação Automatizada: Toda modificação de skill deve ser validada por node scripts/validate-skills.js.
• Ficha de Incidente YAML: Toda correção decorrente de um bug do agente deve gerar uma ficha em tests/feedbacks/INC-xxx.yaml.

5. Procedimento Passo a Passo (Workflow de Projeto & Refinamento)

Percurso A: Criação de um Novo Skill

1. Etapa 1: Análise da Necessidade & Pattern Anthropic:
   • Consultar resources/anthropic-skill-patterns.md para selecionar o pattern mais próximo (feature-dev, setup, review, etc.).
2. Etapa 2: Redação do SKILL.md:
   • Preencher o template de 10 seções.
   • Formular a descrição na 3ª pessoa, especificando claramente os casos de ativação e exclusão.
   • Preencher o bloco YAML inspiration.
   • Encapsular os eventuais recursos de acompanhamento próprios ao skill em seu subdiretório resources/.
3. Etapa 3: Controle Determinístico:
   • Executar node scripts/validate-skills.js.
4. Etapa 4: Registro no Catálogo:
   • Adicionar a entrada em catalog.yaml e documentar em CHANGELOG.md.

Percurso B: Refinamento de um Skill Existente

1. Etapa 1: Diagnóstico & Ficha YAML:
   • Criar tests/feedbacks/INC-[NUM].yaml com o contexto, o comportamento observado e a correção visada.
2. Etapa 2: Correção Cirúrgica:
   • Adicionar a regra na Seção #4 (Restrições) ou um teste binário na Seção #8 (Checklist).
3. Etapa 3: Incremento SemVer:
   • Atualizar a versão (ex: 1.0.1) e registrar em CHANGELOG.md.

Percurso C: Criação ou Modificação de uma Regra (Rules)

1. Etapa 1: Qualificação do Nível da Regra:
   • Regra global de engenharia / segurança ➔ Adicionar em .agents/rules/critical-rules.md ou .agents/rules/general-principles.md.
   • Regra comportamental de agente de projeto ➔ Adicionar em .agents/rules/[nome-da-regra].md.
2. Etapa 2: Redação Concisa & Inviolável:
   • Formular imperativos claros ("O agente deve...", "Proibição formal de...").
   • Dar um exemplo direto do formato esperado.
   • Respeitar o princípio SSOT: se a regra já existir, nunca duplicá-la.
3. Etapa 3: Sincronização & Notificação:
   • Refletir a modificação no Hub ou projeto local e registrar a evolução em CHANGELOG.md.

Percurso D: Capitalização Contínua no Fim da Conversa (/plugin-dev)

1. Etapa 1: Retrospectiva & Identificação de Descobertas:
   • Identificar o(s) pacote(s) tratado(s) durante a sessão recente.
   • Extrair as mecânicas específicas que o agente teve que investigar ou deduzir:
     • Tabelas e modelos envolvidos, relações e hooks de negócio.
     • Particularidades do ViewStateService ou dos filtros da tabela.
     • Serviços temporais, jobs ou observers recém-introduzidos.
     • Armadilhas ou edge cases resolvidos (ex: cálculos distorcidos por omissão de filtros pai).
2. Etapa 2: Avaliação das Lacunas Documentais:
   • Comparar essas descobertas com o conteúdo existente de modules/[NomePkg]/[NomePkg]_IA_CONTEXT.md.
   • Verificar se competências (feature-dev) ou regras se beneficiariam de uma diretiva adicional.
3. Etapa 3: Proposta de Plano de Enriquecimento:
   • Submeter ao projetista um plano claro e estruturado detalhando as adições propostas:
     • Para [NomePkg]_IA_CONTEXT.md (novos serviços, filtros chave, seção Armadilhas & Recomendações).
     • Para as competências, se aplicável.
4. Etapa 4: Execução após Validação:
   • Após validação, enriquecer o arquivo [NomePkg]_IA_CONTEXT.md para que toda futura sessão de manutenção disponha imediatamente desse conhecimento capitalizado.

6. Gestão de Ambiguidades & Decisões

• Arbitragem de Localização de Recursos (Skill vs Agente):
  • Se o recurso for explorado exclusivamente por um skill particular (ex: templates editoriais de um redator, catálogo técnico próprio) ➔ Localização obrigatória: <skill>/resources/[arquivo].md (carregado sob demanda na seção 3 do skill).
  • Se o recurso definir um padrão de engenharia transversal compartilhado por 2 competências ou mais ➔ Localização: .agents/references/conventions/ ou .agents/references/architecture/.
• Arbitragem Skill vs Regra:
  • Se a instrução for uma restrição permanente ou um guarda-corpo transversal (ex: exibição das competências, estilo de resposta, proibição de migração) ➔ Criar uma Regra (.agents/rules/).
  • Se a instrução descrever uma sequência instrumentalizada com acionamento sob demanda, entradas, lógica passo a passo e entregáveis ➔ Criar um Skill (SKILL.md).
• Se a regra solicitada for exclusiva do Solicode LMS: não modificar o padrão do Hub global, mas registrá-la em .agents/rules/ e .agents/references/conventions/project-conventions.md.

7. Formato de Saída & Entregáveis

• O arquivo SKILL.md completo ou o arquivo de regra (.agents/rules/*.md).
• A atualização de catalog.yaml e CHANGELOG.md.
• O resultado da execução do script validate-skills.js (0 erros).

8. Controle de Qualidade (Checklist Binário)

• O frontmatter YAML do skill contém o bloco inspiration completo (fonte, plugin, pattern)?
• A descrição está na 3ª pessoa e especifica quando ativar e quando não ativar?
• As 10 seções padrão estão todas presentes e preenchidas?
• O princípio SSOT (Single Source of Truth) e a regra DRY são respeitados (nenhuma instrução duplicada entre arquivos)?
• O diretório .agents/references/ é mínimo e livre de qualquer recurso mono-competência?
• Os recursos mono-competência estão rigorosamente encapsulados em <skill>/resources/?
• Se for uma regra, ela é concisa, não contraditória com critical-rules e acompanhada de um exemplo claro?
• O script node scripts/validate-skills.js passa com sucesso?

9. Gestão de Erros Frequentes

Erro Típico	Causa	Solução Imediata
Depositar um recurso específico no nível Agente	Falta de granularidade no encapsulamento	Mover o arquivo para <skill>/resources/ e referenciar como recurso interno
Criar um skill para uma simples regra passiva	Confusão entre regra e fluxo instrumentalizado	Migrar a instrução para .agents/rules/
Esquecimento da metadado de inspiração	Desatenção	Adicionar sistematicamente o bloco inspiration no frontmatter
Regra local em conflito com o padrão Hub	Falta de auditoria prévia	Auditar .agents/rules/critical-rules.md antes de formalizar a regra

10. Exemplos Concretos (Few-Shot)

Exemplo de invocação A (Skill): "Crie o skill tutorial-writer inspirado em content-authoring." Comportamento: O agente carrega anthropic-skill-patterns.md, extrai o pattern de redação estruturada, redige as 10 seções com inspiration: { plugin: "content-authoring" }, isola os templates didáticos em tutorial-writer/resources/, e registra a competência em catalog.yaml.

Exemplo de invocação B (Regra): "Adicione uma regra que imponha a exibição dos skills utilizados ao final de cada mensagem." Comportamento: O agente aplica o Percurso C de plugin-dev, redige .agents/rules/exibicao-skills.md, atualiza .agents/rules/critical-rules.md, e aplica imediatamente o formato requisitado.