FASE. v5.1.0

Framework de Automação Sem Enrolação

** Tradução brasileira do get-shit-done para Claude Code, OpenCode, Gemini, Codex e Qwen Code.**

Spec-driven development, context engineering e meta-prompting — agora em português brasileiro.

Funciona no Mac e Linux. Node.js 20+

"Chega de enrolação. Descreve o que quer e FASE acontecer."

Visite a Landing Page — Conheça o projeto de forma visual

Documentação Completa — Guias, referência e exemplos

---

O Que É Isso?

O FASE. é a versão em português brasileiro do Get Shit Done (GSD) — um sistema de meta-prompting e context engineering que faz os assistentes de IA (Claude Code, OpenCode, Gemini, Codex, Qwen Code) funcionarem de verdade em projetos de software.

Ele traz:

• Spec-driven development — descreva o que quer, o AI constrói
• Context engineering avançado — organize prompts para máximo proveito
• Meta-prompting — direcione o AI com precisão
• Workflow estruturado — 13 agentes especializados
• 34 comandos em português brasileiro para um fluxo contínuo

Traduzimos:

• 13 agentes de prompt (pesquisadores, verificadores, planejadores, executores)
• 34 comandos interativos
• Documentação completa
• Mensagens e outputs

Mantivemos em inglês:

• Termos técnicos consolidados (ex: "context window", "checkpoint", "hooks")
• Comandos de terminal e código-fonte
• Nomes de pacotes npm e APIs

Suportados agora:

• 6 provedores de IA: Claude Code, OpenCode, Gemini, Codex, GitHub Copilot, Qwen Code
• ⌨ Navegação interativa com setas (↑↓) no menu
• Opção de saída graceful do instalador

---

Instalação Rápida

Instalação Interativa (Recomendado)

npx fase-ai

O instalador perguntará:

1. Runtime — qual assistente você quer usar (Claude Code, OpenCode, Gemini, Codex, Qwen Code, ou todos)
2. Escopo — local (apenas projeto atual)

Instalação Direta por Runtime

# Claude Code
npx fase-ai --claude

# OpenCode
npx fase-ai --opencode

# Gemini
npx fase-ai --gemini

# Codex
npx fase-ai --codex

# Qwen Code
npx fase-ai --qwen

# Todos os runtimes
npx fase-ai --all

Instalação via Dependência de Desenvolvimento (Recomendado para Times)

Para projetos em equipe, instale FASE como dev dependency para garantir versão consistente entre todos os desenvolvedores:

# Instalar como dev dependency
npm install --save-dev fase-ai@4.0.0

# Ou com yarn
yarn add --dev fase-ai@4.0.0

# Ou com pnpm
pnpm add --save-dev fase-ai@4.0.0

O FASE será instalado automaticamente via postinstall após o npm install. Para configurar quais runtimes instalar, crie .fase-ai/config.json:

{
"runtimes": ["claude", "opencode"],
"auto_install": true
}

Benefícios:

• Versão fixa no package.json — todo time usa a mesma versão
• Funciona offline após instalação inicial
• CI/CD friendly — instalação automática no pipeline
• Sem conflitos — cada projeto pode usar versão diferente

Verificar Instalação

Após instalar, teste o comando de ajuda:

# Claude Code / OpenCode / Gemini / Qwen Code
/fase-ajuda

# Codex
$fase-ajuda

Se vir a mensagem de boas-vindas, FASE foi instalado com sucesso!

Desinstalação

# Remove FASE do seu sistema
npx fase-ai --uninstall

Atualizar FASE

# Dentro do Claude Code / assistente
/fase-atualizar

Ou via npx (sempre usa a versão mais recente):

npx fase-ai@latest

Verificação Automática de Versão

O FASE verifica automaticamente por atualizações em cada sessão:

• Hook em background: Um hook SessionStart verifica silenciosamente se há novas versões no npm
• Notificação: Quando há atualização disponível, você verá uma mensagem ao iniciar
• Prompt interativo: O FASE pergunta se deseja atualizar automaticamente
• Statusline: A versão disponível também aparece na statusline ( /fase:atualizar)

Para verificar manualmente:

node ./.claude/fase-ai/hooks/fase-check-update.js

---

Exemplos de Uso

Quer ver FASE em ação? Temos 3 exemplos reais mostrando diferentes níveis de complexidade:

Iniciante: CLI Pomodoro Timer

Construir uma ferramenta de linha de comando simples com FASE.

Intermediário: Refatoração de Código Legacy

Refatorar um script grande em partes menores e testáveis.

Avançado: JWT Authentication Feature

Implementar uma feature completa com testes, documentação e múltiplas dependências.

Explorar todos os exemplos →

---

Em Ação

Veja FASE em ação. Abaixo estão gravações de terminal mostrando workflows reais:

Instalação e Configuração

# Grave sua sessão de instalação
asciinema rec assets/demo-install.cast

# Depois incorpore no README como:
# <asciinema-player src="assets/demo-install.cast"></asciinema-player>

Workflow Completo: Da Ideia ao Deploy

# Grave uma sessão de workflow com estes passos:
# 1. /fase-novo-projeto
# 2. /fase-planejar-etapa 1
# 3. /fase-executar-etapa 1
# 4. /fase-validar-etapa 1

asciinema rec assets/demo-workflow.cast

Ferramentas para gravar seus próprios demos:

• asciinema — Gravações interativas, incorporáveis e compartilháveis

npm install -g asciinema
asciinema rec my-recording.cast
asciinema upload my-recording.cast

• termtosvg — Gera animações SVG

pip install termtosvg
termtosvg record my-recording.svg

---

Novidades em v5.1.0

Error Handling Standardization (Issue #9)

Padronização completa de tratamento de erros em toda a codebase:

• Funções de biblioteca agora lançam erros tipados em vez de chamar process.exit()
• Melhor testabilidade separando lançamento de erros no nível da biblioteca do encerramento no nível do CLI
• 414/414 testes passando com 0 regressões

Agent Documentation Patterns

• Anti-heredoc instruction adicionada a 10 agentes que escrevem arquivos
• Hooks pattern documentation atualizado
• Referências de agent corrigidas em todos os comandos

Arquitetura Melhorada

• Sistema de erros tipado com 9 classes de erro especializadas
• Logging unificado com pino
• Integração de testes estruturada para todos os 6 provedores

---

Arquitetura

FASE é organizado em 4 camadas principais:

1. Agentes (12 especializados)

Cada agente tem um propósito específico no ciclo de desenvolvimento:

• Planejadores: fase-planejador, fase-roadmapper
• Pesquisadores: fase-pesquisador-fase, fase-pesquisador-projeto, fase-sintetizador-pesquisa
• Executores: fase-executor, fase-mapeador-codigo
• Verificadores: fase-verificador, fase-verificador-plano, fase-verificador-integracao
• Especialistas: fase-depurador, fase-auditor-nyquist

2. Comandos (32 operacionais)

Organize em categorias por função (planejamento, pesquisa, execução, verificação, debug, utilitários)

3. Sistema de Hooks

Monitoramento de contexto para gerenciar estado e histórico automaticamente via integração nativa (settings.json)

4. Instalador Universal

Suporta múltiplos runtimes (Claude Code, OpenCode, Gemini, Codex, Qwen Code) com detecção automática

Por Que "FASE."?

FASE. = Framework de Automação Sem Enrolação

É um trocadilho com "fases de desenvolvimento" porque cada entrega é uma fase concluída, sem burocracia.

A filosofia:

• Sem teatro enterprise (reunião que podia ser email)
• Sem burocracia desnecessária
• Sem story points, sprint ceremonies, retrospectives
• Só você, sua visão, e o assistente de IA construindo

---

Comandos Disponíveis

FASE oferece 34 comandos em português brasileiro, organizados por função:

Core / Inicialização

/fase-ajuda # Mostra ajuda completa
/fase-novo-projeto # Inicializa novo projeto com FASE
/fase-configuracoes # Abre painel de configurações

Planning & Roadmapping

/fase-novo-marco # Cria novo milestone
/fase-planejar-etapa # Detalha planejamento de uma fase
/fase-adicionar-etapa # Adiciona fase ao roadmap
/fase-inserir-etapa # Insere fase em posição específica
/fase-remover-etapa # Remove fase do plano
/fase-progresso # Mostra status de conclusão
/fase-roadmapper # Cria roadmap visual (via agente)

Research & Analysis

/fase-pesquisar-etapa # Pesquisa contexto para uma fase
/fase-mapear-codigo # Mapeia codebase existente
/fase-listar-premissas # Lista assunções da fase
/fase-planejar-lacunas # Identifica gaps no plano

Verification & Validation

/fase-verificar-trabalho # Valida código executado
/fase-validar-etapa # Verifica completude de fase
/fase-auditar-marco # Audita um milestone
/fase-checar-tarefas # Revisa task list

Execução e Desenvolvimento

/fase-executar-etapa # Executa uma fase completa
/fase-rapido # Modo fast-track para tarefas simples
/fase-adicionar-testes # Gera testes para código
/fase-adicionar-tarefa # Adiciona task ao histórico

Debug e Solução de Problemas

/fase-debug # Diagnostica problemas
/fase-depurador # Invoca agente debugger (via agente)
/fase-discutir-etapa # Abre discussão estruturada

Manutenção e Administração

/fase-pausar-trabalho # Pausa execução
/fase-retomar-trabalho # Continua de onde parou
/fase-completar-marco # Marca milestone como concluído
/fase-reaplicar-patches # Reaplica correções versionadas
/fase-definir-perfil # Configura perfil de modelo/agente
/fase-limpar # Remove arquivos temporários
/fase-saude # Checkup de saúde do projeto
/fase-atualizar # Atualiza FASE para versão latest
/fase-verificar-instalacao # Verifica instalação e sugere correções

→ Documentação completa: COMANDOS.md

---

Pra Quem É Isso?

Perfil Ideal

• Solo devs que não querem fingir que são uma empresa de 50 pessoas
• Devs brasileiros que preferem trabalhar em português
• Pessoas criativas que querem construir coisas que funcionam
• Quem cansou de descrever algo e receber respostas inconsistentes do AI

Casos de Uso

Projetos pessoais com requisitos bem definidos MVPs que precisam ir para produção rápido Refatorações estruturadas de legacies Automation scripts e ferramentas internas Prototipagem rápida de ideias Aprendizado de novas tecnologias/linguagens

O Que FASE Não É

Substituto para design de sistema em time Solução para requisitos vagos ou mal definidos Ferramenta para escrever documentação de produto Gerenciador de sprint/kanban (use Jira/Linear para isso)

---

Documentação Completa

Guias Essenciais

• Guia do Usuário — Como usar FASE passo-a-passo
• Todos os Comandos — Referência completa com exemplos
• System Hooks — Como adicionar automações

Para Contribuidores

• Como Contribuir — Instruções para contribuições
• Path Standardization — Como comandos funcionam em diferentes runtimes
• Testes — Guia de testes, como rodar e contribuir
• Resultados de Testes — Últimos resultados de validação

Compilação e Desenvolvimento

• Build: npm run build — Compila TypeScript e copia arquivos estáticos
• Teste: npm test — Executa testes de casos extremos
• Teste Tudo: npm run test:all — Executa todos os testes (legado + moderno)
• Estrutura: src/ (TypeScript) → dist/ (compilado com static files)

GitHub Actions e CI/CD

FASE possui um pipeline completo de CI/CD automatizado:

Testes Multi-Plataforma (test-multi-platform.yml)

• Plataformas suportadas: Linux (ubuntu-latest) e macOS (macos-latest)
• Versões Node.js: 20 e 22 (total de 4 combinações)
• Testes: Compilação, testes unitários e verificação de instalação
• Integração: Testa instalação multi-provider (--claude, --opencode)
• Performance: Matriz otimizada com 60% mais rápida que versões anteriores

Execução: Automaticamente em cada push para main ou pull request

Publicação npm Inteligente (publicar-npm.yml)

• Detecção de versão: Compara package.json com registro npm
• Publicação condicional: Só publica se versão mudou
• Git tags automáticos: Cria v{version} automaticamente
• GitHub Releases: Geradas automaticamente de CHANGELOG.md
• Sem erro em push sem versão: Skip silencioso se versão não mudou

Como usar:

# 1. Atualize versão em package.json
echo '"version": "4.0.3"' > package.json

# 2. Atualize CHANGELOG.md
echo '## 4.0.3\n- New feature' >> CHANGELOG.md

# 3. Commit e push
git add package.json CHANGELOG.md
git commit -m "chore: bump version 4.0.2 → 4.0.3"
git push origin main

# Workflow automaticamente:
# Detecta mudança de versão
# Publica no npm
# Cria tag v4.0.3
# Cria GitHub Release

Outras Workflows

• deploy-pages.yml: Deploy de documentação para GitHub Pages
• track-adoption.yml: Rastreamento de adoção e métricas

Documentação detalhada: Ver specs/PUBLICAR_NPM_WORKFLOW.md

Informações do Projeto

• Histórico de Mudanças — Todas as versões
• Maintainers — Quem cuida do projeto

---

Recursos Principais

Spec-Driven Development

Trabalhe com especificações claras e deixe o AI transformar em código funcional. Cada fase é uma entrega concreta.

Context Engineering

FASE organiza automaticamente o contexto da sua sessão para que o AI sempre tenha as informações certas no local certo.

Ciclo de Vida Estruturado

Pesquisa → Planejamento → Execução → Verificação → Iteração

Cada etapa tem seu agente especializado.

Rastreamento de Estado

Histórico automático de fases, tarefas e checkpoints. Retome trabalho de onde parou, semanas depois.

Extensível

Crie seus próprios hooks e customize o comportamento via settings.json nativa.

Multi-Runtime

Funciona com:

• Claude Code (Anthropic)
• OpenCode (OpenAI)
• Gemini Code (Google)
• Codex (Microsoft)

---

Créditos & Origem

FASE. é uma tradução comunitária em português brasileiro do projeto original:

• Original: gsd-build/get-shit-done por TÂCHES
• Tradução & Manutenção: Isaac Eliape
• Licença: MIT (mesma do original)

Sem o trabalho incrível da comunidade GSD, isso não existiria.

Compatibilidade com GSD: FASE mantém total compatibilidade com GSD — todos os agents e comandos usam a mesma arquitetura subjacente, apenas traduzidos para português.

---

Como Contribuir

Quer ajudar a traduzir ou melhorar o FASE.?

1. Fork este repo
2. Traduza um agent ou documento
3. Abra um PR descrevendo o que mudou

Precisa de ajuda? Abre uma issue no GitHub.

---

Quick Start

1. Instale FASE:

npx fase-ai

2. Abra seu IDE e inicie um novo projeto:

/fase-novo-projeto

3. Descreva o que quer construir:

• Use /fase-planejar-etapa para quebrar em fases
• Cada fase é uma entrega concreta

4. Execute as fases:

/fase-executar-etapa

5. Verifique o trabalho:

/fase-verificar-trabalho

Para mais detalhes, veja Guia do Usuário.

---

Comunidade & Suporte

Reportar Issues

• Bugs
• Sugestões
• Traduções

Discussões

• Discussions no GitHub
• Compartilhe workflows, dicas e best practices

---

Filosofia FASE

"Se você sabe claramente o que quer, isso VAI construir pra você. Sem burocracia, sem enrolação."

---

Feito com e para a comunidade brasileira de devs.

Dê uma star se FASE foi útil!