Sua spec é a fonte da verdade.
Letra é um framework de Specification-Driven Development (SDD) agnóstico a ferramentas. Captura direção, intenção e contexto, enriquecendo prompts de agentes de código — funcionando como uma memória persistente do projeto.
- Spec-Code Drift: Especificações ficam desatualizadas conforme o código evolui.
- Markdown Madness: Specs de 50k+ tokens que ninguém lê.
- Perda de Contexto: Decisões vivem só no histórico do chat.
- Tool Lock-in: Ferramentas presas a um IDE ou modelo específico.
- Agentes ignoram specs: Seguem 70-90% e não dá pra ver o que faltou.
- Thin Specs: Máximo 1 página por feature.
- Spec-Anchored: Spec vive junto com o código, atualizada como parte do DoD.
- Context First: Intent, constraints e "porquês" — não markdown verbose.
- Agnóstico: Adapters para OpenCode, Cursor, VS Code e mais.
# Execução direta via npx
npx @letra-ai/cli init meu-projeto
# Ou instalação global
npm install -g @letra-ai/cli# Inicializar um projeto com .letra/ (modo interativo)
letra init
# Silent mode (usa defaults, sem perguntas)
letra init --yes
# Criar uma nova spec
letra spec minha-feature
# Criar spec com template específico
letra spec minha-feature --template web-api
letra spec minha-feature --template cli-tool
# Validar formato e completude das specs
letra lint
# Verificar acceptance criteria das specs
letra validate
letra validate --format github-annotation # formato para CI (GitHub Actions)
letra validate --format junit # formato XML (demais CIs)
letra validate --watch # re-valida automaticamente ao salvar
# Combinar flags
letra validate --watch --format github-annotation
# Registrar decisão arquitetural
letra decision new "Usar Commander em vez de Yargs"
letra decision list
# Definir foco da sessão
letra focus validate-conflict
letra focus # ver foco atual
letra focus --clear # limpar foco
# Gerenciar workflow (Flow MVP)
letra flow init --quick # wizard 3 perguntas
letra flow backlog add "Descrição" # adicionar item ao backlog
letra flow backlog list # listar todos os itens
letra flow move ITEM-1 --to Code # mover item por ID
letra flow move "Descrição" --to Review # mover por descrição
letra flow board # board visual por estágioO letra validate analisa automaticamente suas specs em busca de problemas comuns. São 7 verificações que rodam em toda spec:
| Verificação | O que ela pega | Exemplo real |
|---|---|---|
| Seções Vazias | Seções que ficaram com o texto do template ou quase vazias | Você cria uma spec, copia o template, esquece de preencher o "Outcome". A verificação avisa que aquela seção ainda tem o texto padrão. |
| Conteúdo Mínimo | Outcome muito curto, sem detalhe do que será feito | Escrever "Fazer o login" como Outcome não descreve o suficiente. A verificação sugere expandir. |
| ACs sem Métrica | Critérios de aceite vagos, que não dá pra saber se passaram ou falharam | Escrever "Melhorar a performance" não é mensurável. O certo seria "Tempo de resposta < 200ms". |
| Consistência de Terminologia | Termos definidos no glossário que não foram usados na spec | O glossário define "JWT" mas a spec chama de "token mágico". A verificação alerta para usar o termo oficial. |
| Detecção de Tom | Gírias e linguagem informal em specs que deveriam ser formais | Escrever "blz" ou "tipo" numa spec que descreve um sistema crítico. |
| Baixa Confiança | Palavras que mostram incerteza sobre o que está sendo especificado | "O sistema provavelmente valida o token" — não tem "provavelmente" numa especificação. É tudo certo ou não é. |
| Drift Temporal | Specs que não são atualizadas há mais de 30 dias | A spec de autenticação foi escrita em janeiro, mas o código foi alterado em maio. A verificação alerta que a spec pode estar desatualizada. |
letra init agora pergunta o tipo de projeto (web app, CLI, library, mobile) e qual agente IA você usa, adaptando os arquivos gerados. Use --yes para pular as perguntas.
letra spec <nome> --template <nome> cria specs com estrutura pré-definida para cada domínio:
| Template | Quando usar |
|---|---|
web-api |
Endpoints REST, GraphQL, websockets |
cli-tool |
Comandos, argumentos, exit codes |
mobile-feature |
Telas, navegação, estados |
| custom | Coloque arquivos .md em .letra/templates/ |
letra validate --format <formato> permite integrar com diferentes CIs:
text(default) — saída colorida para terminalgithub-annotation—::error/::warningcompatível com GitHub Actionsjunit— XML padrão para demais ferramentas de CI
letra validate --watch monitora alterações em specs e re-executa validação automaticamente com debounce de 300ms.
letra decision new <título> cria ADRs em .letra/decisions/ com template Contexto → Decisão → Consequências, data automática e status proposed. letra decision list lista todos os ADRs.
letra flow gerencia seu processo de trabalho com estágios, itens e adapters que mantêm agentes de IA sincronizados com o contexto atual.
letra flow init --quick
# → Wizard com 3 perguntas (nome, estágios, ferramentas)
# → Gera .letra/workflow.json com versão 1.0
letra flow backlog add "Implementar login"
# → Adiciona ITEM-1 ao primeiro estágio (Backlog)
# → IDs auto-incrementais: ITEM-1, ITEM-2, ITEM-3...
letra flow backlog list
# → Tabela com ID, descrição, estágio e idade de todos os itens
letra flow move ITEM-1 --to Code
letra flow move "Implementar login" --to Review
# → Move entre estágios por ID ou descrição
# → Regenera automaticamente AGENTS.md, .cursorrules, etc.
# → Adapters refletem estágio atual e itens ativos
letra flow board
# → Board visual: estágios, contagem de itens, itens ativos
# → Estágios vazios marcados como (empty)letra focus <spec> define qual spec está ativa na sessão atual, escrevendo .letra/focus.md. O adapter do letra init já referencia esse arquivo, então o agente sabe exatamente o que importa agora. Use letra focus para ver o foco atual e letra focus --clear para limpar.
A 8ª heurística do letra validate — detecta automaticamente ACs contraditórios entre specs diferentes (ex: "login com email" vs "login apenas com Google"), evitando que requisitos conflitantes virem bugs. Severidade configurável via config.json.
.letra/
├── context.md # Intent global, domínio, restrições reais
├── constitution.md # Regras não-negociáveis
├── glossary.md # Termos do domínio
├── lessons-learned.md # Erros recorrentes dos agentes
├── decisions/ # ADRs
├── specs/
│ └── minha-feature/
│ ├── spec.md # O que + porquê (1 página max)
│ ├── acceptance.md # Critérios binários
│ └── status.md # Sync status
└── adapters/
└── opencode.json # Configuração do adapter OpenCode
| Adapter | Status | Artefato Gerado |
|---|---|---|
| OpenCode | ✅ Completo | AGENTS.md |
| Codex CLI | ✅ Completo | AGENTS.md (compartilhado) |
| Claude Code | ✅ Completo | CLAUDE.md |
| Cursor | ✅ Completo | .cursorrules |
| Windsurf | ✅ Completo | .windsurfrules |
| VS Code (Copilot) | ✅ Completo | .github/copilot-instructions.md + .vscode/settings.json |
# Criar um novo projeto
mkdir meu-app
cd meu-app
# Inicializar o .letra/
npx @letra-ai/cli init
# Criar uma spec de autenticação
npx @letra-ai/cli spec auth
# Editar .letra/specs/auth/spec.md com sua intenção
# Desenvolver a funcionalidade...
# Validar se o código cumpre os acceptance criteria
npx @letra-ai/cli validate
# Ou usar o Flow para gerenciar o processo
npx @letra-ai/cli flow init --quick
npx @letra-ai/cli flow backlog add "Tela de login"
npx @letra-ai/cli flow move ITEM-1 --to Code
npx @letra-ai/cli flow move ITEM-1 --to Review
npx @letra-ai/cli flow board# Instalar dependências
npm install
# Rodar em dev
npm run dev
# Lint e formatação
npm run lint
# Type check
npm run typecheck
# Build
npm run build
# Testes
npm testMIT