🤝 Guia de Contribuição

Versão: 3.2.0 | Última atualização: 2026-03-25

Obrigado por considerar contribuir ao FASE! Este documento oferece diretrizes e instruções para participar do projeto.

📋 Código de Conduta

Este projeto adere a um Código de Conduta. Ao participar, você concorda em manter um ambiente respeitoso e inclusivo. Comportamento abusivo deve ser reportado para maintainers.

🎯 Tipos de Contribuição

1. Traduções (Novos idiomas)

Se quiser traduzir FASE para outro idioma:

# Duplicar estrutura para novo idioma
cp -r bin/agentes bin/agentes-es    # Exemplo: espanhol
cp -r bin/comandos bin/comandos-es

1. Traduzir os arquivos .md no novo idioma
2. Criar issue descrevendo o idioma
3. Abrir PR com a tradução
4. Aguardar revisão

Estrutura esperada:

agentes-{idioma}/
  ├── fase-planejador.{idioma}.md
  ├── fase-executor.{idioma}.md
  └── ...

comandos-{idioma}/
  ├── ajuda.{idioma}.md
  ├── novo-projeto.{idioma}.md
  └── ...

2. Novos Comandos

Adicionar um novo comando ao FASE:

1. Criar arquivo em comandos/seu-comando.md

---
name: seu-comando
description: Descrição breve do que o comando faz
type: command
---

# /fase-seu-comando

Descrição detalhada.

## Uso

```bash
/fase-seu-comando [opções]

Opções

• --flag: Descrição

Exemplos

[Exemplos de uso]

2. **Atualizar** `bin/lib/commands.cjs` para registrar o comando
3. **Testar** localmente antes de submeter PR
4. **Documentar** em `docs/COMANDOS.md`

### 3. **Correções de Bugs**

1. Abrir issue descrevendo o bug
2. Forkar o repositório
3. Criar branch: `git checkout -b fix/descricao-do-bug`
4. Fazer commit com mensagem descritiva
5. Push para a branch: `git push origin fix/descricao-do-bug`
6. Abrir PR com detalhes

### 4. **Melhorias e Features**

1. Discutir no issue primeiro (para evitar trabalho duplicado)
2. Forkar e criar branch descritiva
3. Implementar com mensagens de commit claras
4. Adicionar testes se aplicável
5. Abrir PR com contextualização

## 🔧 Setup Local

### Pré-requisitos

- Node.js >= 14.0.0
- Git
- npm ou yarn

### Instalação

```bash
# Clonar repositório
git clone https://github.com/seu-usuario/FASE.git
cd FASE

# Instalar dependências
npm install

# Instalar git hooks
npx husky install

Teste o Instalador Localmente

# Teste com flags
node bin/install.js --help
node bin/install.js --claude --local

# Verifique se o pacote foi criado corretamente
npm run verificar

📝 Convenções de Commit

Siga o formato Conventional Commits:

<tipo>(<escopo>): <descrição curta>

<descrição detalhada opcional>

<footer opcional>

Tipos

• feat: Nova feature
• fix: Correção de bug
• docs: Mudanças em documentação
• style: Formatação, sem mudança lógica
• refactor: Refatoração de código
• test: Adicionar ou atualizar testes
• chore: Tarefas de build, dependências

Exemplos

# Feature nova
git commit -m "feat(comandos): adicionar /fase-novo-comando

Implementa novo comando que permite..."

# Correção
git commit -m "fix(install.js): corrigir bug ao criar diretório

Problema: o hook falhava ao criar .claude/
Solução: verificar se diretório existe antes"

# Documentação
git commit -m "docs: atualizar guia de instalação"

🧪 Testing

Verificar Integridade do Pacote

cd bin
npm pack --dry-run

Isso simula a publicação no npm e mostra:

• ✅ Quais arquivos serão inclusos
• ❌ Erros de configuração
• 📊 Tamanho do pacote

Testar Instalação

# Instalação local (projeto atual)
node bin/install.js --claude --local

# Instalar globalmente (seu computador)
node bin/install.js --claude --global

# Uninstall
node bin/install.js --uninstall

📖 Documentação

Padrão de Escrita

• Português brasileiro em toda documentação em .md
• Inglês apenas para termos técnicos consagrados
• Código e comandos sempre em inglês (invariável)

Estrutura de Documentação

docs/
├── guia-do-usuario.md       # Guia para usuários
├── COMANDOS.md              # Lista de comandos
├── HOOKS.md                 # Git hooks setup
├── CONTRIBUINDO.md          # Este arquivo
└── technical/
    └── padronizacao-caminhos.md     # Path standardization

✅ Checklist para PRs

Antes de submeter um PR, verifique:

• Branch criada a partir de main
• Commits seguem Conventional Commits
• Documentação atualizada
• Sem conflitos com main
• npm pack --dry-run passa sem erros
• Pre-commit hooks não falharam

🚀 Processo de Review

1. Automático: GitHub Actions verifica integridade do pacote
2. Automático: Pre-commit hooks validam mudanças
3. Manual: Um maintainer revisa o código
4. Merge: Se aprovado, seu PR será merged

📞 Precisa de Ajuda?

• Issues: GitHub Issues
• Discussões: GitHub Discussions
• Email: Abrir issue para contato

📜 Licença

Ao contribuir, você concorda que suas contribuições serão licenciadas sob a MIT License.

Obrigado por contribuir! 🙌

Cada contribuição, pequena ou grande, ajuda a melhorar FASE para a comunidade brasileira.