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

```bash
#!/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

```bash
#!/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