descomplicar-meta-plugin/docs/05-CHECKLISTS.md

Checklists de Validação

Versão: 2.0 | Data: 2026-02-04 | Autor: Descomplicar®

---

Skills

Checklist: Criar Nova Skill

□ FRONTMATTER
  □ name: kebab-case, <64 chars, único
  □ description: <1024 chars
    □ Capacidade principal descrita
    □ "Use when..." com triggers
    □ 5+ keywords específicas
  □ version: semver (1.0.0)
  □ author: Descomplicar®
  □ desk_task: ID válido
  □ sdk: slug do SDK associado

□ ESTRUTURA
  □ Directório: skills/<nome>/
  □ SKILL.md <500 linhas
  □ Título = name
  □ Secções obrigatórias:
    □ Quando Usar
    □ Quando NÃO Usar
    □ Protocolo/Workflow
    □ Exemplos

□ CONTEÚDO
  □ Terceira pessoa na description
  □ Forma imperativa no body
  □ Limites claros definidos
  □ Exemplos input/output concretos
  □ Sem paths absolutos
  □ Sem info time-sensitive
  □ Links markdown para references

□ FICHEIROS AUXILIARES
  □ references/ - docs detalhadas
  □ scripts/ - código executável
  □ assets/ - templates output

□ QUALIDADE
  □ Testada com 3+ cenários reais
  □ Score >= 70
  □ allowed-tools mínimos

□ INTEGRAÇÃO
  □ Registada em cr_skills
  □ Relação cr_sdk_skills criada
  □ Tarefa Desk criada/actualizada
  □ Tags: skill(79), stackworkflow(75), claude-code(81)

Checklist: Actualizar Skill Existente

□ ANTES
  □ Ler versão actual
  □ Identificar alterações necessárias
  □ Verificar dependências

□ ALTERAÇÕES
  □ version bumped
  □ CHANGELOG actualizado
  □ Alterações documentadas

□ VALIDAÇÃO
  □ Testada após alterações
  □ Não quebrou funcionalidade existente
  □ Score mantido >= 70

□ INTEGRAÇÃO
  □ cr_skills actualizada
  □ Tarefa Desk comentada

---

Agents

Checklist: Criar Novo Agent

□ METADADOS
  □ name: slug único, kebab-case
  □ description: capacidades + triggers + keywords
  □ model: sonnet (default) ou opus/haiku
  □ tools: mínimos necessários
  □ allowed-mcps: lista de MCPs
  □ skills: skills preloaded
  □ category: dev|business|infra|research|content
  □ author: Descomplicar®
  □ version: 1.0.0
  □ desk_task: ID válido

□ ESTRUTURA
  □ Ficheiro: ~/.claude/agents/<nome>.md
  □ Identidade/persona definida
  □ Especialização clara
  □ Workflow documentado (4 passos)
  □ Limites explícitos

□ RELACIONAMENTOS
  □ MCPs mapeados:
    □ Primary (essenciais)
    □ Recommended (úteis)
    □ Available (opcionais)
  □ Skills associadas
  □ Colaborações definidas
  □ SDK associado

□ QUALIDADE
  □ Testado com 3+ cenários
  □ Colaborações testadas
  □ Limites respeitados
  □ Score >= 70

□ INTEGRAÇÃO
  □ Registado em cr_agents
  □ cr_sdk_agents criado
  □ cr_agent_mcps criados
  □ cr_agent_skills criados
  □ cr_agent_collaborations criados
  □ Tarefa Desk criada
  □ Tags: agent(80), stackworkflow(75), claude-code(81)

Checklist: Testar Agent

□ INVOCAÇÃO
  □ Task tool funciona com subagent_type
  □ Contexto correcto carregado
  □ MCPs disponíveis
  □ Skills carregadas
  □ Persona correcta

□ EXECUÇÃO
  □ Workflow seguido
  □ Output format correcto
  □ Confidence reportada
  □ Erros tratados

□ COLABORAÇÃO
  □ Parallel execution funciona
  □ Handoff para outro agent funciona
  □ Limites respeitados

---

Plugins

Checklist: Criar Novo Plugin

□ ESTRUTURA
  □ Directório criado
  □ .claude-plugin/plugin.json
  □ skills/ com pelo menos 1 skill
  □ README.md
  □ CHANGELOG.md
  □ LICENSE (MIT)

□ MANIFEST (plugin.json)
  □ name: kebab-case, único
  □ version: 1.0.0
  □ description: com contagem componentes
  □ author: nome, email, url
  □ license: MIT
  □ keywords: relevantes

□ COMPONENTES
  □ Skills criadas (ver checklist skills)
  □ Agents criados (ver checklist agents)
  □ Commands criados (se aplicável)
  □ MCPs declarados (se aplicável)

□ DOCUMENTAÇÃO
  □ README com:
    □ Instalação
    □ Lista componentes
    □ Exemplos de uso
  □ CHANGELOG inicial
  □ CLAUDE.md (regras dev)

□ VERSIONAMENTO
  □ Seguir semver
  □ 3 ficheiros sincronizados:
    □ plugin.json
    □ CHANGELOG.md
    □ README.md

□ INTEGRAÇÃO
  □ Registado em cr_plugins
  □ cr_sdk_plugins criado
  □ Tarefa Desk criada

Checklist: Release de Plugin

□ PRÉ-RELEASE
  □ Todos os componentes testados
  □ Versão correcta em plugin.json
  □ CHANGELOG completo
  □ README actualizado
  □ Sem ficheiros temporários
  □ Links funcionais

□ RELEASE
  □ Git commit
  □ Git tag v1.0.0
  □ Push para repositório
  □ Package gerado (se distribuído)

□ PÓS-RELEASE
  □ Testar instalação limpa
  □ Verificar componentes carregados
  □ Actualizar Desk CRM

---

Commands

Checklist: Criar Novo Command

□ FRONTMATTER
  □ name: kebab-case ou namespace:nome
  □ description: breve
  □ argument-hint: descrição args

□ ESTRUTURA
  □ Ficheiro: commands/<nome>.md
  □ Ou: commands/<namespace>/<nome>.md
  □ Namespace usado se colisão possível

□ CONTEÚDO
  □ #$ARGUMENTS incluído
  □ Fallback se args vazios
  □ Workflow documentado
  □ Output format claro

□ INTEGRAÇÃO
  □ Versão plugin bumped
  □ CHANGELOG actualizado
  □ README actualizado

---

Quality Gates

Score Mínimo por Componente

Componente	Mínimo Beta	Mínimo Production
Skill	70	90
Agent	70	85
Plugin	70	80

Critérios de Score - Skill (100 pontos)

Critério	Pontos
Descrição optimizada (keywords, triggers)	25
Estrutura correcta (frontmatter, secções)	20
Tamanho adequado (<500 linhas)	15
Exemplos práticos (input/output)	15
Limites definidos	10
Tools mínimos	10
Testada 3+ cenários	5

Critérios de Score - Agent (100 pontos)

Critério	Pontos
Descrição completa	20
Tools apropriados	15
MCPs bem mapeados	15
Skills integradas	15
Workflow definido	10
Limites claros	10
Colaborações	10
Testado	5

---

Integração Desk CRM

Tags por Tipo

Componente	Tags Obrigatórias
Skill	skill(79), stackworkflow(75), claude-code(81)
Agent	agent(80), stackworkflow(75), claude-code(81)
MCP	MCP(58), stackworkflow(75), integracao(73)
Plugin	stackworkflow(75), claude-code(81)

Milestones

Componente	Milestone ID
Skill	294
Agent	274
MCP	256
Sistema	300

Responsáveis

• Emanuel: staff_id = 1
• AikTop: staff_id = 25

Adicionar ambos a todas as tarefas.

---

Validação Automatizada

Script: Validar Skill

#!/bin/bash
SKILL_DIR=$1

# Verificar SKILL.md existe
if [ ! -f "$SKILL_DIR/SKILL.md" ]; then
  echo "ERROR: SKILL.md não encontrado"
  exit 1
fi

# Verificar frontmatter
if ! grep -q "^name:" "$SKILL_DIR/SKILL.md"; then
  echo "ERROR: Falta campo 'name' no frontmatter"
  exit 1
fi

if ! grep -q "^description:" "$SKILL_DIR/SKILL.md"; then
  echo "ERROR: Falta campo 'description' no frontmatter"
  exit 1
fi

# Verificar tamanho
LINES=$(wc -l < "$SKILL_DIR/SKILL.md")
if [ "$LINES" -gt 500 ]; then
  echo "WARNING: SKILL.md tem $LINES linhas (max: 500)"
fi

# Verificar links para references
if grep -qE '`(references|assets|scripts)/[^`]+`' "$SKILL_DIR/SKILL.md"; then
  echo "WARNING: Usar markdown links em vez de backticks para references"
fi

echo "OK: Validação básica passou"

Script: Validar Plugin

#!/bin/bash
PLUGIN_DIR=$1

# Verificar plugin.json
if [ ! -f "$PLUGIN_DIR/.claude-plugin/plugin.json" ]; then
  echo "ERROR: plugin.json não encontrado"
  exit 1
fi

# Verificar campos obrigatórios
for field in name version description; do
  if ! jq -e ".$field" "$PLUGIN_DIR/.claude-plugin/plugin.json" > /dev/null 2>&1; then
    echo "ERROR: Falta campo '$field' em plugin.json"
    exit 1
  fi
done

# Verificar README
if [ ! -f "$PLUGIN_DIR/README.md" ]; then
  echo "WARNING: README.md não encontrado"
fi

# Verificar CHANGELOG
if [ ! -f "$PLUGIN_DIR/CHANGELOG.md" ]; then
  echo "WARNING: CHANGELOG.md não encontrado"
fi

echo "OK: Validação básica passou"

---

Descomplicar® | 2026-02-04