Lord1Egypt/awesome-skill-forge

Modo Plano

Use este skill quando o usuário quiser um plano em vez de execução.

Comportamento principal

Neste turno, você está apenas planejando.

• Não implemente código.
• Não edite arquivos do projeto, exceto o arquivo de plano markdown.
• Não execute comandos mutantes no terminal, nem commit, push ou ações externas.
• Você pode inspecionar o repositório ou outro contexto com comandos/ferramentas somente leitura quando necessário.
• Sua entrega é um plano markdown salvo dentro do workspace ativo em .hermes/plans/.

Requisitos de saída

Escreva um plano markdown que seja concreto e acionável.

Inclua, quando relevante:

• Objetivo
• Contexto atual / premissas
• Abordagem proposta
• Plano passo a passo
• Arquivos que provavelmente serão alterados
• Testes / validação
• Riscos, trade-offs e perguntas em aberto

Se a tarefa for relacionada a código, inclua caminhos exatos de arquivos, prováveis alvos de teste e etapas de verificação.

Local de salvamento

Salve o plano com write_file em:

• .hermes/plans/YYYY-MM-DD_HHMMSS-<slug>.md

Trate isso como relativo ao diretório de trabalho ativo / workspace do backend. As ferramentas de arquivo do Hermes são cientes do backend, então usar esse caminho relativo mantém o plano no workspace com os backends local, docker, ssh, modal e daytona.

Se o runtime fornecer um caminho de destino específico, use esse caminho exato. Se não, crie você mesmo um nome de arquivo com timestamp sensato em .hermes/plans/.

Estilo de interação

• Se a solicitação for clara o suficiente, escreva o plano diretamente.
• Se nenhuma instrução explícita acompanhar /plan, infira a tarefa a partir do contexto atual da conversa.
• Se for genuinamente subespecificada, faça uma breve pergunta esclarecedora em vez de adivinhar.
• Após salvar o plano, responda brevemente com o que você planejou e o caminho salvo.

---

Escrevendo o Plano Bem

O restante deste skill é a arte de criar um bom plano de implementação — o conteúdo que vai dentro do arquivo markdown acima.

Visão geral

Escreva planos de implementação abrangentes assumindo que o implementador não tem contexto algum sobre a base de código e tem gosto questionável. Documente tudo o que ele precisa: quais arquivos tocar, código completo, comandos de teste, docs para consultar, como verificar. Dê a ele tarefas pequenas. DRY. YAGNI. TDD. Commits frequentes.

Assuma que o implementador é um desenvolvedor habilidoso, mas sabe quase nada sobre o conjunto de ferramentas ou domínio do problema. Assuma que ele não conhece bem design de testes.

Princípio central: Um bom plano torna a implementação óbvia. Se alguém tem que adivinhar, o plano está incompleto.

Quando um Plano de Implementação Completo Ajuda

Sempre use antes de:

• Implementar funcionalidades de múltiplas etapas
• Decompor requisitos complexos
• Delegar para subagentes via desenvolvimento orientado a subagentes

Não pule quando:

• A funcionalidade parece simples (suposições causam bugs)
• Você planeja implementá-la você mesmo (você do futuro precisa de orientação)
• Trabalhando sozinho (documentação importa)

Granularidade de Tarefas Pequenas

Cada tarefa = 2 a 5 minutos de trabalho focado.

Cada etapa é uma ação:

• "Escrever o teste com falha" — etapa
• "Executá-lo para garantir que falha" — etapa
• "Implementar o código mínimo para fazer o teste passar" — etapa
• "Executar os testes e garantir que passam" — etapa
• "Commit" — etapa

Grande demais:

### Tarefa 1: Construir sistema de autenticação
[50 linhas de código em 5 arquivos]

Tamanho certo:

### Tarefa 1: Criar modelo User com campo email
[10 linhas, 1 arquivo]

### Tarefa 2: Adicionar campo hash de senha ao User
[8 linhas, 1 arquivo]

### Tarefa 3: Criar utilitário de hash de senha
[15 linhas, 1 arquivo]

Estrutura do Documento do Plano

Cabeçalho (Obrigatório)

Todo plano DEVE começar com:

# [Nome da Funcionalidade] — Plano de Implementação

> **Para Hermes:** Use o skill de desenvolvimento orientado a subagentes para implementar este plano tarefa por tarefa.

**Objetivo:** [Uma frase descrevendo o que isso constrói]

**Arquitetura:** [2 a 3 frases sobre a abordagem]

**Stack Tecnológico:** [Principais tecnologias/bibliotecas]

---

Estrutura da Tarefa

Cada tarefa segue este formato:

### Tarefa N: [Nome Descritivo]

**Objetivo:** O que esta tarefa realiza (uma frase)

**Arquivos:**
- Criar: `caminho/exato/para/novo_arquivo.py`
- Modificar: `caminho/exato/para/existente.py:45-67` (números de linha, se conhecidos)
- Teste: `tests/path/to/test_file.py`

**Passo 1: Escrever teste com falha**

```python
def test_comportamento_especifico():
    resultado = funcao(entrada)
    assert resultado == esperado
```

**Passo 2: Executar teste para verificar falha**

Executar: `pytest tests/path/test.py::test_comportamento_especifico -v`
Esperado: FAIL — "function not defined"

**Passo 3: Escrever implementação mínima**

```python
def funcao(entrada):
    return esperado
```

**Passo 4: Executar teste para verificar sucesso**

Executar: `pytest tests/path/test.py::test_comportamento_especifico -v`
Esperado: PASS

**Passo 5: Commit**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: adicionar funcionalidade específica"
```

Processo de Escrita

Passo 1: Entender Requisitos

Leia e entenda:

• Requisitos da funcionalidade
• Documentos de design ou descrição do usuário
• Critérios de aceitação
• Restrições

Passo 2: Explorar a Base de Código

Use ferramentas do Hermes para entender o projeto:

# Entender estrutura do projeto
search_files("*.py", target="files", path="src/")

# Olhar funcionalidades similares
search_files("padrao_similar", path="src/", file_glob="*.py")

# Verificar testes existentes
search_files("*.py", target="files", path="tests/")

# Ler arquivos-chave
read_file("src/app.py")

Passo 3: Projetar Abordagem

Decida:

• Padrão arquitetural
• Organização de arquivos
• Dependências necessárias
• Estratégia de teste

Passo 4: Escrever Tarefas

Crie tarefas em ordem:

1. Configuração/infraestrutura
2. Funcionalidade principal (TDD para cada)
3. Casos de borda
4. Integração
5. Limpeza/documentação

Passo 5: Adicionar Detalhes Completos

Para cada tarefa, inclua:

• Caminhos exatos de arquivos (não "o arquivo de configuração", mas src/config/settings.py)
• Exemplos completos de código (não "adicione validação", mas o código real)
• Comandos exatos com saída esperada
• Etapas de verificação que provem que a tarefa funciona

Passo 6: Revisar o Plano

Verifique:

• Tarefas são sequenciais e lógicas
• Cada tarefa é pequena (2 a 5 min)
• Caminhos de arquivos são exatos
• Exemplos de código são completos (copiáveis e coláveis)
• Comandos são exatos com saída esperada
• Nenhum contexto faltando
• Princípios DRY, YAGNI, TDD aplicados

Princípios

DRY (Don't Repeat Yourself — Não se Repita)

Ruim: Copiar e colar validação em 3 lugares Bom: Extrair função de validação, usar em todos os lugares

YAGNI (You Aren't Gonna Need It — Você Não Vai Precisar Disso)

Ruim: Adicionar "flexibilidade" para requisitos futuros Bom: Implementar apenas o que é necessário agora

# Ruim — violação de YAGNI
class Usuario:
    def __init__(self, nome, email):
        self.nome = nome
        self.email = email
        self.preferencias = {}  # Ainda não necessário!
        self.metadados = {}     # Ainda não necessário!

# Bom — YAGNI
class Usuario:
    def __init__(self, nome, email):
        self.nome = nome
        self.email = email

TDD (Test-Driven Development — Desenvolvimento Orientado a Testes)

Toda tarefa que produz código deve incluir o ciclo TDD completo:

1. Escrever teste com falha
2. Executar para verificar falha
3. Escrever código mínimo
4. Executar para verificar sucesso

Veja o skill test-driven-development para detalhes.

Commits Frequentes

Commite após cada tarefa:

git add [arquivos]
git commit -m "tipo: descrição"

Erros Comuns

Tarefas Vagas

Ruim: "Adicionar autenticação" Bom: "Criar modelo User com campos email e password_hash"

Código Incompleto

Ruim: "Passo 1: Adicionar função de validação" Bom: "Passo 1: Adicionar função de validação" seguido do código completo da função

Verificação Ausente

Ruim: "Passo 3: Testar se funciona" Bom: "Passo 3: Executar pytest tests/test_auth.py -v, esperado: 3 passed"

Caminhos de Arquivos Ausentes

Ruim: "Criar o arquivo de modelo" Bom: "Criar: src/models/user.py"

Entrega para Execução

Após salvar o plano, ofereça a abordagem de execução:

"Plano completo e salvo. Pronto para executar usando desenvolvimento orientado a subagentes — enviarei um subagente novo por tarefa com revisão em dois estágios (conformidade com especificação e qualidade de código). Devo prosseguir?"

Ao executar, use o skill subagent-driven-development:

• Um delegate_task novo por tarefa com contexto completo
• Revisão de conformidade com especificação após cada tarefa
• Revisão de qualidade de código após a especificação passar
• Prossiga apenas quando ambas as revisões aprovarem

Lembre-se

Tarefas pequenas (2 a 5 min cada)
Caminhos exatos de arquivos
Código completo (copiável e colável)
Comandos exatos com saída esperada
Etapas de verificação
DRY, YAGNI, TDD
Commits frequentes

Um bom plano torna a implementação óbvia.