The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs(pt-BR): add commands translation
Paulo Victor Gomes1ef8bc1e72a3
diff --git a/docs/pt-BR/commands/build-fix.md b/docs/pt-BR/commands/build-fix.mdnew file mode 100644index 000000000..feda490a3--- /dev/null+++ b/docs/pt-BR/commands/build-fix.md@@ -0,0 +1,62 @@+# Build e Correção++Corrija erros de build e de tipos incrementalmente com mudanças mínimas e seguras.++## Passo 1: Detectar Sistema de Build++Identifique a ferramenta de build do projeto e execute o build:++| Indicator | Build Command |+|-----------|---------------|+| `package.json` with `build` script | `npm run build` or `pnpm build` |+| `tsconfig.json` (TypeScript only) | `npx tsc --noEmit` |+| `Cargo.toml` | `cargo build 2>&1` |+| `pom.xml` | `mvn compile` |+| `build.gradle` | `./gradlew compileJava` |+| `go.mod` | `go build ./...` |+| `pyproject.toml` | `python -m py_compile` or `mypy .` |++## Passo 2: Parsear e Agrupar Erros++1. Execute o comando de build e capture o stderr+2. Agrupe erros por caminho de arquivo+3. Ordene por ordem de dependência (corrija imports/tipos antes de erros de lógica)+4. Conte o total de erros para acompanhamento de progresso++## Passo 3: Loop de Correção (Um Erro por Vez)++Para cada erro:++1. **Leia o arquivo** — Use a ferramenta Read para ver o contexto do erro (10 linhas ao redor do erro)+2. **Diagnostique** — Identifique a causa raiz (import ausente, tipo errado, erro de sintaxe)+3. **Corrija minimamente** — Use a ferramenta Edit para a menor mudança que resolve o erro+4. **Rode o build novamente** — Verifique que o erro sumiu e que nenhum novo erro foi introduzido+5. **Vá para o próximo** — Continue com os erros restantes++## Passo 4: Guardrails++Pare e pergunte ao usuário se:+- Uma correção introduz **mais erros do que resolve**+- O **mesmo erro persiste após 3 tentativas** (provavelmente há um problema mais profundo)+- A correção exige **mudanças arquiteturais** (não apenas correção de build)+- Os erros de build vêm de **dependências ausentes** (precisa de `npm install`, `cargo add`, etc.)++## Passo 5: Resumo++Mostre resultados:+- Erros corrigidos (com caminhos de arquivos)+- Erros restantes (se houver)+- Novos erros introduzidos (deve ser zero)+- Próximos passos sugeridos para problemas não resolvidos++## Estratégias de Recuperação++| Situation | Action |+|-----------|--------|+| Missing module/import | Check if package is installed; suggest install command |+| Type mismatch | Read both type definitions; fix the narrower type |+| Circular dependency | Identify cycle with import graph; suggest extraction |+| Version conflict | Check `package.json` / `Cargo.toml` for version constraints |+| Build tool misconfiguration | Read config file; compare with working defaults |++Corrija um erro por vez por segurança. Prefira diffs mínimos em vez de refatoração.diff --git a/docs/pt-BR/commands/checkpoint.md b/docs/pt-BR/commands/checkpoint.mdnew file mode 100644index 000000000..c69c1e6b9--- /dev/null+++ b/docs/pt-BR/commands/checkpoint.md@@ -0,0 +1,74 @@+# Comando Checkpoint++Crie ou verifique um checkpoint no seu fluxo.++## Uso++`/checkpoint [create|verify|list] [name]`++## Criar Checkpoint++Ao criar um checkpoint:++1. Rode `/verify quick` para garantir que o estado atual está limpo+2. Crie um git stash ou commit com o nome do checkpoint+3. Registre o checkpoint em `.claude/checkpoints.log`:++```bash+echo "$(date +%Y-%m-%d-%H:%M) | $CHECKPOINT_NAME | $(git rev-parse --short HEAD)" >> .claude/checkpoints.log+```++4. Informe que o checkpoint foi criado++## Verificar Checkpoint++Ao verificar contra um checkpoint:++1. Leia o checkpoint no log+2. Compare o estado atual com o checkpoint:+ - Arquivos adicionados desde o checkpoint+ - Arquivos modificados desde o checkpoint+ - Taxa de testes passando agora vs antes+ - Cobertura agora vs antes++3. Reporte:+```+CHECKPOINT COMPARISON: $NAME+============================+Files changed: X+Tests: +Y passed / -Z failed+Coverage: +X% / -Y%+Build: [PASS/FAIL]+```++## Listar Checkpoints++Mostre todos os checkpoints com:+- Nome+- Timestamp+- Git SHA+- Status (current, behind, ahead)++## Fluxo++Fluxo típico de checkpoint:++```+[Start] --> /checkpoint create "feature-start"+ |+[Implement] --> /checkpoint create "core-done"+ |+[Test] --> /checkpoint verify "core-done"+ |+[Refactor] --> /checkpoint create "refactor-done"+ |+[PR] --> /checkpoint verify "feature-start"+```++## Argumentos++$ARGUMENTS:+- `create <name>` - Criar checkpoint nomeado+- `verify <name>` - Verificar contra checkpoint nomeado+- `list` - Mostrar todos os checkpoints+- `clear` - Remover checkpoints antigos (mantém os últimos 5)diff --git a/docs/pt-BR/commands/code-review.md b/docs/pt-BR/commands/code-review.mdnew file mode 100644index 000000000..52b9e90d7--- /dev/null+++ b/docs/pt-BR/commands/code-review.md@@ -0,0 +1,40 @@+# Code Review++Revisão completa de segurança e qualidade das mudanças não commitadas:++1. Obtenha arquivos alterados: git diff --name-only HEAD++2. Para cada arquivo alterado, verifique:++**Problemas de Segurança (CRITICAL):**+- Credenciais, chaves de API ou tokens hardcoded+- Vulnerabilidades de SQL injection+- Vulnerabilidades de XSS+- Falta de validação de entrada+- Dependências inseguras+- Riscos de path traversal++**Qualidade de Código (HIGH):**+- Funções > 50 linhas+- Arquivos > 800 linhas+- Profundidade de aninhamento > 4 níveis+- Falta de tratamento de erro+- Statements de console.log+- Comentários TODO/FIXME+- Falta de JSDoc para APIs públicas++**Boas Práticas (MEDIUM):**+- Padrões de mutação (usar imutável no lugar)+- Uso de emoji em código/comentários+- Falta de testes para código novo+- Problemas de acessibilidade (a11y)++3. Gere relatório com:+ - Severidade: CRITICAL, HIGH, MEDIUM, LOW+ - Localização no arquivo e números de linha+ - Descrição do problema+ - Correção sugerida++4. Bloqueie commit se houver problemas CRITICAL ou HIGH++Nunca aprove código com vulnerabilidades de segurança!diff --git a/docs/pt-BR/commands/e2e.md b/docs/pt-BR/commands/e2e.mdnew file mode 100644index 000000000..41b77f5dd--- /dev/null+++ b/docs/pt-BR/commands/e2e.md@@ -0,0 +1,365 @@+---+description: Gere e rode testes end-to-end com Playwright. Cria jornadas de teste, executa testes, captura screenshots/videos/traces e faz upload de artefatos.+---++# Comando E2E++Este comando invoca o agente **e2e-runner** para gerar, manter e executar testes end-to-end usando Playwright.++## O Que Este Comando Faz++1. **Gerar Jornadas de Teste** - Cria testes Playwright para fluxos de usuário+2. **Rodar Testes E2E** - Executa testes em múltiplos navegadores+3. **Capturar Artefatos** - Screenshots, vídeos, traces em falhas+4. **Upload de Resultados** - Relatórios HTML e JUnit XML+5. **Identificar Testes Flaky** - Coloca testes instáveis em quarentena++## Quando Usar++Use `/e2e` quando:+- Testar jornadas críticas de usuário (login, trading, pagamentos)+- Verificar fluxos multi-etapa de ponta a ponta+- Testar interações de UI e navegação+- Validar integração entre frontend e backend+- Preparar para deploy em produção++## Como Funciona++O agente e2e-runner vai:++1. **Analisar o fluxo de usuário** e identificar cenários de teste+2. **Gerar teste Playwright** usando padrão Page Object Model+3. **Rodar testes** em múltiplos navegadores (Chrome, Firefox, Safari)+4. **Capturar falhas** com screenshots, vídeos e traces+5. **Gerar relatório** com resultados e artefatos+6. **Identificar testes flaky** e recomendar correções++## Exemplo de Uso++```+User: /e2e Test the market search and view flow++Agent (e2e-runner):+# E2E Test Generation: Market Search and View Flow++## Test Scenario Identified++**User Journey:** Market Search → View Results → Click Market → View Details++**Test Coverage:**+1. Navigate to markets page+2. Perform semantic search+3. Verify search results+4. Click on first result+5. Verify market details page loads+6. Verify chart renders++## Generated Test Code++```typescript+// tests/e2e/markets/search-and-view.spec.ts+import { test, expect } from '@playwright/test'+import { MarketsPage } from '../../pages/MarketsPage'+import { MarketDetailsPage } from '../../pages/MarketDetailsPage'++test.describe('Market Search and View Flow', () => {+ test('user can search markets and view details', async ({ page }) => {+ // 1. Navigate to markets page+ const marketsPage = new MarketsPage(page)+ await marketsPage.goto()++ // Verify page loaded+ await expect(page).toHaveTitle(/Markets/)+ await expect(page.locator('h1')).toContainText('Markets')++ // 2. Perform semantic search+ await marketsPage.searchMarkets('election')++ // Wait for API response+ await page.waitForResponse(resp =>+ resp.url().includes('/api/markets/search') && resp.status() === 200+ )++ // 3. Verify search results+ const marketCards = marketsPage.marketCards+ await expect(marketCards.first()).toBeVisible()+ const resultCount = await marketCards.count()+ expect(resultCount).toBeGreaterThan(0)++ // Take screenshot of search results+ await page.screenshot({ path: 'artifacts/search-results.png' })++ // 4. Click on first result+ const firstMarketTitle = await marketCards.first().textContent()+ await marketCards.first().click()++ // 5. Verify market details page loads+ await expect(page).toHaveURL(/\/markets\/[a-z0-9-]+/)++ const detailsPage = new MarketDetailsPage(page)+ await expect(detailsPage.marketName).toBeVisible()+ await expect(detailsPage.marketDescription).toBeVisible()++ // 6. Verify chart renders+ await expect(detailsPage.priceChart).toBeVisible()++ // Verify market name matches+ const detailsTitle = await detailsPage.marketName.textContent()+ expect(detailsTitle?.toLowerCase()).toContain(+ firstMarketTitle?.toLowerCase().substring(0, 20) || ''+ )++ // Take screenshot of market details+ await page.screenshot({ path: 'artifacts/market-details.png' })+ })++ test('search with no results shows empty state', async ({ page }) => {+ const marketsPage = new MarketsPage(page)+ await marketsPage.goto()++ // Search for non-existent market+ await marketsPage.searchMarkets('xyznonexistentmarket123456')++ // Verify empty state+ await expect(page.locator('[data-testid="no-results"]')).toBeVisible()+ await expect(page.locator('[data-testid="no-results"]')).toContainText(+ /no.*results|no.*markets/i+ )++ const marketCount = await marketsPage.marketCards.count()+ expect(marketCount).toBe(0)+ })++ test('can clear search and see all markets again', async ({ page }) => {+ const marketsPage = new MarketsPage(page)+ await marketsPage.goto()++ // Initial market count+ const initialCount = await marketsPage.marketCards.count()++ // Perform search+ await marketsPage.searchMarkets('trump')+ await page.waitForLoadState('networkidle')++ // Verify filtered results+ const filteredCount = await marketsPage.marketCards.count()+ expect(filteredCount).toBeLessThan(initialCount)++ // Clear search+ await marketsPage.searchInput.clear()+ await page.waitForLoadState('networkidle')++ // Verify all markets shown again+ const finalCount = await marketsPage.marketCards.count()+ expect(finalCount).toBe(initialCount)+ })+})+```++## Rodando os Testes++```bash+# Run the generated test+npx playwright test tests/e2e/markets/search-and-view.spec.ts++Running 3 tests using 3 workers++ ✓ [chromium] › search-and-view.spec.ts:5:3 › user can search markets and view details (4.2s)+ ✓ [chromium] › search-and-view.spec.ts:52:3 › search with no results shows empty state (1.8s)+ ✓ [chromium] › search-and-view.spec.ts:67:3 › can clear search and see all markets again (2.9s)++ 3 passed (9.1s)++Artifacts generated:+- artifacts/search-results.png+- artifacts/market-details.png+- playwright-report/index.html+```++## Relatório de Teste++```+╔══════════════════════════════════════════════════════════════╗+║ E2E Test Results ║+╠══════════════════════════════════════════════════════════════╣+║ Status: ✅ ALL TESTS PASSED ║+║ Total: 3 tests ║+║ Passed: 3 (100%) ║+║ Failed: 0 ║+║ Flaky: 0 ║+║ Duration: 9.1s ║+╚══════════════════════════════════════════════════════════════╝++Artifacts:+📸 Screenshots: 2 files+📹 Videos: 0 files (only on failure)+🔍 Traces: 0 files (only on failure)+📊 HTML Report: playwright-report/index.html++View report: npx playwright show-report+```++✅ E2E test suite ready for CI/CD integration!+```++## Artefatos de Teste++Quando os testes rodam, os seguintes artefatos são capturados:++**Em Todos os Testes:**+- Relatório HTML com timeline e resultados+- JUnit XML para integração com CI++**Somente em Falha:**+- Screenshot do estado de falha+- Gravação em vídeo do teste+- Arquivo de trace para debug (replay passo a passo)+- Logs de rede+- Logs de console++## Visualizando Artefatos++```bash+# View HTML report in browser+npx playwright show-report++# View specific trace file+npx playwright show-trace artifacts/trace-abc123.zip++# Screenshots are saved in artifacts/ directory+open artifacts/search-results.png+```++## Detecção de Teste Flaky++Se um teste falhar de forma intermitente:++```+⚠️ FLAKY TEST DETECTED: tests/e2e/markets/trade.spec.ts++Test passed 7/10 runs (70% pass rate)++Common failure:+"Timeout waiting for element '[data-testid="confirm-btn"]'"++Recommended fixes:+1. Add explicit wait: await page.waitForSelector('[data-testid="confirm-btn"]')+2. Increase timeout: { timeout: 10000 }+3. Check for race conditions in component+4. Verify element is not hidden by animation++Quarantine recommendation: Mark as test.fixme() until fixed+```++## Configuração de Navegador++Os testes rodam em múltiplos navegadores por padrão:+- ✅ Chromium (Desktop Chrome)+- ✅ Firefox (Desktop)+- ✅ WebKit (Desktop Safari)+- ✅ Mobile Chrome (optional)++Configure em `playwright.config.ts` para ajustar navegadores.++## Integração CI/CD++Adicione ao seu pipeline de CI:++```yaml+# .github/workflows/e2e.yml+- name: Install Playwright+ run: npx playwright install --with-deps++- name: Run E2E tests+ run: npx playwright test++- name: Upload artifacts+ if: always()+ uses: actions/upload-artifact@v3+ with:+ name: playwright-report+ path: playwright-report/+```++## Fluxos Críticos Específicos do PMX++Para PMX, priorize estes testes E2E:++**🔴 CRITICAL (Must Always Pass):**+1. User can connect wallet+2. User can browse markets+3. User can search markets (semantic search)+4. User can view market details+5. User can place trade (with test funds)+6. Market resolves correctly+7. User can withdraw funds++**🟡 IMPORTANT:**+1. Market creation flow+2. User profile updates+3. Real-time price updates+4. Chart rendering+5. Filter and sort markets+6. Mobile responsive layout++## Boas Práticas++**DO:**+- ✅ Use Page Object Model para manutenção+- ✅ Use atributos data-testid para seletores+- ✅ Aguarde respostas de API, não timeouts arbitrários+- ✅ Teste jornadas críticas de usuário end-to-end+- ✅ Rode testes antes de mergear em main+- ✅ Revise artefatos quando testes falharem++**DON'T:**+- ❌ Use seletores frágeis (classes CSS podem mudar)+- ❌ Teste detalhes de implementação+- ❌ Rode testes contra produção+- ❌ Ignore testes flaky+- ❌ Pule revisão de artefatos em falhas+- ❌ Teste todo edge case com E2E (use testes unitários)++## Notas Importantes++**CRITICAL para PMX:**+- Testes E2E envolvendo dinheiro real DEVEM rodar apenas em testnet/staging+- Nunca rode testes de trading em produção+- Defina `test.skip(process.env.NODE_ENV === 'production')` para testes financeiros+- Use carteiras de teste com fundos de teste pequenos apenas++## Integração com Outros Comandos++- Use `/plan` para identificar jornadas críticas a testar+- Use `/tdd` para testes unitários (mais rápidos e granulares)+- Use `/e2e` para integração e jornadas de usuário+- Use `/code-review` para verificar qualidade dos testes++## Agentes Relacionados++Este comando invoca o agente `e2e-runner` fornecido pelo ECC.++Para instalações manuais, o arquivo fonte fica em:+`agents/e2e-runner.md`++## Comandos Rápidos++```bash+# Run all E2E tests+npx playwright test++# Run specific test file+npx playwright test tests/e2e/markets/search.spec.ts++# Run in headed mode (see browser)+npx playwright test --headed++# Debug test+npx playwright test --debug++# Generate test code+npx playwright codegen http://localhost:3000++# View report+npx playwright show-report+```diff --git a/docs/pt-BR/commands/eval.md b/docs/pt-BR/commands/eval.mdnew file mode 100644index 000000000..438efda59--- /dev/null+++ b/docs/pt-BR/commands/eval.md@@ -0,0 +1,120 @@+# Comando Eval++Gerencie o fluxo de desenvolvimento orientado por evals.++## Uso++`/eval [define|check|report|list] [feature-name]`++## Definir Evals++`/eval define feature-name`++Crie uma nova definição de eval:++1. Crie `.claude/evals/feature-name.md` com o template:++```markdown+## EVAL: feature-name+Created: $(date)++### Capability Evals+- [ ] [Description of capability 1]+- [ ] [Description of capability 2]++### Regression Evals+- [ ] [Existing behavior 1 still works]+- [ ] [Existing behavior 2 still works]++### Success Criteria+- pass@3 > 90% for capability evals+- pass^3 = 100% for regression evals+```++2. Peça ao usuário para preencher os critérios específicos++## Verificar Evals++`/eval check feature-name`++Rode evals para uma feature:++1. Leia a definição de eval em `.claude/evals/feature-name.md`+2. Para cada eval de capability:+ - Tente verificar o critério+ - Registre PASS/FAIL+ - Salve tentativa em `.claude/evals/feature-name.log`+3. Para cada eval de regressão:+ - Rode os testes relevantes+ - Compare com baseline+ - Registre PASS/FAIL+4. Reporte status atual:++```+EVAL CHECK: feature-name+========================+Capability: X/Y passing+Regression: X/Y passing+Status: IN PROGRESS / READY+```++## Relatório de Evals++`/eval report feature-name`++Gere relatório completo de eval:++```+EVAL REPORT: feature-name+=========================+Generated: $(date)++CAPABILITY EVALS+----------------+[eval-1]: PASS (pass@1)+[eval-2]: PASS (pass@2) - required retry+[eval-3]: FAIL - see notes++REGRESSION EVALS+----------------+[test-1]: PASS+[test-2]: PASS+[test-3]: PASS++METRICS+-------+Capability pass@1: 67%+Capability pass@3: 100%+Regression pass^3: 100%++NOTES+-----+[Any issues, edge cases, or observations]++RECOMMENDATION+--------------+[SHIP / NEEDS WORK / BLOCKED]+```++## Listar Evals++`/eval list`++Mostre todas as definições de eval:++```+EVAL DEFINITIONS+================+feature-auth [3/5 passing] IN PROGRESS+feature-search [5/5 passing] READY+feature-export [0/4 passing] NOT STARTED+```++## Argumentos++$ARGUMENTS:+- `define <name>` - Criar nova definição de eval+- `check <name>` - Rodar e verificar evals+- `report <name>` - Gerar relatório completo+- `list` - Mostrar todos os evals+- `clean` - Remover logs antigos de eval (mantém as últimas 10 execuções)diff --git a/docs/pt-BR/commands/go-build.md b/docs/pt-BR/commands/go-build.mdnew file mode 100644index 000000000..2e620bf99--- /dev/null+++ b/docs/pt-BR/commands/go-build.md@@ -0,0 +1,183 @@+---+description: Corrija erros de build em Go, avisos de go vet e problemas de lint incrementalmente. Invoca o agente go-build-resolver para correções mínimas e cirúrgicas.+---++# Build e Correção Go++Este comando invoca o agente **go-build-resolver** para corrigir erros de build Go incrementalmente com mudanças mínimas.++## O Que Este Comando Faz++1. **Rodar Diagnósticos**: Executa `go build`, `go vet`, `staticcheck`+2. **Parsear Erros**: Agrupa por arquivo e ordena por severidade+3. **Corrigir Incrementalmente**: Um erro por vez+4. **Verificar Cada Correção**: Roda build de novo após cada mudança+5. **Reportar Resumo**: Mostra o que foi corrigido e o que resta++## Quando Usar++Use `/go-build` quando:+- `go build ./...` falhar com erros+- `go vet ./...` reportar problemas+- `golangci-lint run` mostrar avisos+- Dependências do módulo estiverem quebradas+- Após puxar mudanças que quebraram o build++## Comandos de Diagnóstico Executados++```bash+# Primary build check+go build ./...++# Static analysis+go vet ./...++# Extended linting (if available)+staticcheck ./...+golangci-lint run++# Module issues+go mod verify+go mod tidy -v+```++## Exemplo de Sessão++```text+User: /go-build++Agent:+# Go Build Resolution++## Initial Diagnostics++```bash+$ go build ./...+internal/service/user.go:25:15: undefined: UserRepository+internal/handler/api.go:42:9: cannot use x (type string) as type int+internal/handler/api.go:58:2: missing return at end of function+```++Errors found: 3++## Fix 1: Undefined Identifier++File: internal/service/user.go:25+Error: undefined: UserRepository+Cause: Missing import++```go+// Added import+import "project/internal/repository"++// Changed+var repo UserRepository+// To+var repo repository.UserRepository+```++```bash+$ go build ./...+# 2 errors remaining+```++## Fix 2: Type Mismatch++File: internal/handler/api.go:42+Error: cannot use x (type string) as type int++```go+// Changed+count := params.Get("count")+// To+countStr := params.Get("count")+count, _ := strconv.Atoi(countStr)+```++```bash+$ go build ./...+# 1 error remaining+```++## Fix 3: Missing Return++File: internal/handler/api.go:58+Error: missing return at end of function++```go+func GetUser(id string) (*User, error) {+ if id == "" {+ return nil, ErrInvalidID+ }+ user := findUser(id)+ // Added missing return+ return user, nil+}+```++```bash+$ go build ./...+# Build successful!+```++## Final Verification++```bash+$ go vet ./...+# No issues++$ go test ./...+ok project/internal/service 0.015s+ok project/internal/handler 0.023s+```++## Summary++| Metric | Count |+|--------|-------|+| Build errors fixed | 3 |+| Vet warnings fixed | 0 |+| Files modified | 2 |+| Remaining issues | 0 |++Build Status: ✅ SUCCESS+```++## Erros Comuns Corrigidos++| Error | Typical Fix |+|-------|-------------|+| `undefined: X` | Add import or fix typo |+| `cannot use X as Y` | Type conversion or fix assignment |+| `missing return` | Add return statement |+| `X does not implement Y` | Add missing method |+| `import cycle` | Restructure packages |+| `declared but not used` | Remove or use variable |+| `cannot find package` | `go get` or `go mod tidy` |++## Estratégia de Correção++1. **Erros de build primeiro** - O código precisa compilar+2. **Avisos do vet depois** - Corrigir construções suspeitas+3. **Avisos de lint por último** - Estilo e boas práticas+4. **Uma correção por vez** - Verificar cada mudança+5. **Mudanças mínimas** - Não refatorar, apenas corrigir++## Condições de Parada++O agente vai parar e reportar se:+- O mesmo erro persistir após 3 tentativas+- A correção introduzir mais erros+- Exigir mudanças arquiteturais+- Faltarem dependências externas++## Comandos Relacionados++- `/go-test` - Rode testes após o build passar+- `/go-review` - Revise qualidade do código+- `/verify` - Loop completo de verificação++## Relacionado++- Agent: `agents/go-build-resolver.md`+- Skill: `skills/golang-patterns/`diff --git a/docs/pt-BR/commands/go-review.md b/docs/pt-BR/commands/go-review.mdnew file mode 100644index 000000000..fb8e10d8e--- /dev/null+++ b/docs/pt-BR/commands/go-review.md@@ -0,0 +1,148 @@+---+description: Revisão completa de código Go para padrões idiomáticos, segurança de concorrência, tratamento de erro e segurança. Invoca o agente go-reviewer.+---++# Code Review Go++Este comando invoca o agente **go-reviewer** para revisão abrangente e específica de Go.++## O Que Este Comando Faz++1. **Identificar Mudanças Go**: Encontra arquivos `.go` modificados via `git diff`+2. **Rodar Análise Estática**: Executa `go vet`, `staticcheck` e `golangci-lint`+3. **Varredura de Segurança**: Verifica SQL injection, command injection e race conditions+4. **Revisão de Concorrência**: Analisa segurança de goroutines, uso de channels e padrões com mutex+5. **Checagem de Go Idiomático**: Verifica se o código segue convenções e boas práticas de Go+6. **Gerar Relatório**: Categoriza problemas por severidade++## Quando Usar++Use `/go-review` quando:+- Após escrever ou modificar código Go+- Antes de commitar mudanças Go+- Ao revisar pull requests com código Go+- Ao entrar em um novo codebase Go+- Ao aprender padrões idiomáticos Go++## Categorias de Revisão++### CRITICAL (Obrigatório Corrigir)+- Vulnerabilidades de SQL/Command injection+- Race conditions sem sincronização+- Vazamento de goroutine+- Credenciais hardcoded+- Uso inseguro de ponteiros+- Erros ignorados em caminhos críticos++### HIGH (Deve Corrigir)+- Falta de wrapping de erro com contexto+- Panic em vez de retorno de erro+- Context não propagado+- Canais não bufferizados causando deadlock+- Erros de interface não satisfeita+- Falta de proteção com mutex++### MEDIUM (Considere)+- Padrões não idiomáticos+- Falta de comentários godoc em exports+- Concatenação de string ineficiente+- Slice sem pré-alocação+- Table-driven tests não usados++## Checagens Automáticas Executadas++```bash+# Static analysis+go vet ./...++# Advanced checks (if installed)+staticcheck ./...+golangci-lint run++# Race detection+go build -race ./...++# Security vulnerabilities+govulncheck ./...+```++## Exemplo de Uso++```text+User: /go-review++Agent:+# Go Code Review Report++## Files Reviewed+- internal/handler/user.go (modified)+- internal/service/auth.go (modified)++## Static Analysis Results+✓ go vet: No issues+✓ staticcheck: No issues++## Issues Found++[CRITICAL] Race Condition+File: internal/service/auth.go:45+Issue: Shared map accessed without synchronization+```go+var cache = map[string]*Session{} // Concurrent access!++func GetSession(id string) *Session {+ return cache[id] // Race condition+}+```+Fix: Use sync.RWMutex or sync.Map+```go+var (+ cache = map[string]*Session{}+ cacheMu sync.RWMutex+)++func GetSession(id string) *Session {+ cacheMu.RLock()+ defer cacheMu.RUnlock()+ return cache[id]+}+```++[HIGH] Missing Error Context+File: internal/handler/user.go:28+Issue: Error returned without context+```go+return err // No context+```+Fix: Wrap with context+```go+return fmt.Errorf("get user %s: %w", userID, err)+```++## Summary+- CRITICAL: 1+- HIGH: 1+- MEDIUM: 0++Recommendation: ❌ Block merge until CRITICAL issue is fixed+```++## Critérios de Aprovação++| Status | Condition |+|--------|-----------|+| ✅ Approve | No CRITICAL or HIGH issues |+| ⚠️ Warning | Only MEDIUM issues (merge with caution) |+| ❌ Block | CRITICAL or HIGH issues found |++## Integração com Outros Comandos++- Use `/go-test` primeiro para garantir que os testes passam+- Use `/go-build` se houver erros de build+- Use `/go-review` antes de commitar+- Use `/code-review` para preocupações não específicas de Go++## Relacionado++- Agent: `agents/go-reviewer.md`+- Skills: `skills/golang-patterns/`, `skills/golang-testing/`diff --git a/docs/pt-BR/commands/go-test.md b/docs/pt-BR/commands/go-test.mdnew file mode 100644index 000000000..d608c8257--- /dev/null+++ b/docs/pt-BR/commands/go-test.md@@ -0,0 +1,268 @@+---+description: Impõe fluxo de TDD para Go. Escreva table-driven tests primeiro e depois implemente. Verifique cobertura de 80%+ com go test -cover.+---++# Comando TDD Go++Este comando impõe a metodologia de desenvolvimento orientado a testes para código Go usando padrões idiomáticos de teste em Go.++## O Que Este Comando Faz++1. **Definir Tipos/Interfaces**: Estrutura assinaturas de função primeiro+2. **Escrever Table-Driven Tests**: Criar casos de teste abrangentes (RED)+3. **Rodar Testes**: Verificar que os testes falham pelo motivo certo+4. **Implementar Código**: Escrever código mínimo para passar (GREEN)+5. **Refatorar**: Melhorar mantendo testes verdes+6. **Checar Cobertura**: Garantir 80%+ de cobertura++## Quando Usar++Use `/go-test` quando:+- Implementar novas funções Go+- Adicionar cobertura de testes a código existente+- Corrigir bugs (escreva primeiro o teste que falha)+- Construir lógica de negócio crítica+- Aprender fluxo TDD em Go++## Ciclo TDD++```+RED → Write failing table-driven test+GREEN → Implement minimal code to pass+REFACTOR → Improve code, tests stay green+REPEAT → Next test case+```++## Exemplo de Sessão++````+User: /go-test I need a function to validate email addresses++Agent:+# TDD Session: Email Validator++## Step 1: Define Interface++```go+// validator/email.go+package validator++// ValidateEmail checks if the given string is a valid email address.+// Returns nil if valid, error describing the issue otherwise.+func ValidateEmail(email string) error {+ panic("not implemented")+}+```++## Step 2: Write Table-Driven Tests (RED)++```go+// validator/email_test.go+package validator++import (+ "testing"+)++func TestValidateEmail(t *testing.T) {+ tests := []struct {+ name string+ email string+ wantErr bool+ }{+ // Valid emails+ {"simple email", "[email protected]", false},+ {"with subdomain", "[email protected]", false},+ {"with plus", "[email protected]", false},+ {"with dots", "[email protected]", false},++ // Invalid emails+ {"empty string", "", true},+ {"no at sign", "userexample.com", true},+ {"no domain", "user@", true},+ {"no local part", "@example.com", true},+ {"double at", "user@@example.com", true},+ {"spaces", "user @example.com", true},+ {"no tld", "user@example", true},+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ err := ValidateEmail(tt.email)+ if tt.wantErr && err == nil {+ t.Errorf("ValidateEmail(%q) = nil; want error", tt.email)+ }+ if !tt.wantErr && err != nil {+ t.Errorf("ValidateEmail(%q) = %v; want nil", tt.email, err)+ }+ })+ }+}+```++## Step 3: Run Tests - Verify FAIL++```bash+$ go test ./validator/...++--- FAIL: TestValidateEmail (0.00s)+ --- FAIL: TestValidateEmail/simple_email (0.00s)+ panic: not implemented++FAIL+```++✓ Tests fail as expected (panic).++## Step 4: Implement Minimal Code (GREEN)++```go+// validator/email.go+package validator++import (+ "errors"+ "regexp"+)++var emailRegex = regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)++var (+ ErrEmailEmpty = errors.New("email cannot be empty")+ ErrEmailInvalid = errors.New("email format is invalid")+)++func ValidateEmail(email string) error {+ if email == "" {+ return ErrEmailEmpty+ }+ if !emailRegex.MatchString(email) {+ return ErrEmailInvalid+ }+ return nil+}+```++## Step 5: Run Tests - Verify PASS++```bash+$ go test ./validator/...++PASS+ok project/validator 0.003s+```++✓ All tests passing!++## Step 6: Check Coverage++```bash+$ go test -cover ./validator/...++PASS+coverage: 100.0% of statements+ok project/validator 0.003s+```++✓ Coverage: 100%++## TDD Complete!+````++## Padrões de Teste++### Table-Driven Tests+```go+tests := []struct {+ name string+ input InputType+ want OutputType+ wantErr bool+}{+ {"case 1", input1, want1, false},+ {"case 2", input2, want2, true},+}++for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ got, err := Function(tt.input)+ // assertions+ })+}+```++### Testes Paralelos+```go+for _, tt := range tests {+ tt := tt // Capture+ t.Run(tt.name, func(t *testing.T) {+ t.Parallel()+ // test body+ })+}+```++### Helpers de Teste+```go+func setupTestDB(t *testing.T) *sql.DB {+ t.Helper()+ db := createDB()+ t.Cleanup(func() { db.Close() })+ return db+}+```++## Comandos de Cobertura++```bash+# Basic coverage+go test -cover ./...++# Coverage profile+go test -coverprofile=coverage.out ./...++# View in browser+go tool cover -html=coverage.out++# Coverage by function+go tool cover -func=coverage.out++# With race detection+go test -race -cover ./...+```++## Metas de Cobertura++| Code Type | Target |+|-----------|--------|+| Critical business logic | 100% |+| Public APIs | 90%+ |+| General code | 80%+ |+| Generated code | Exclude |++## Boas Práticas de TDD++**DO:**+- Escreva teste PRIMEIRO, antes de qualquer implementação+- Rode testes após cada mudança+- Use table-driven tests para cobertura abrangente+- Teste comportamento, não detalhes de implementação+- Inclua casos de borda (empty, nil, max values)++**DON'T:**+- Escrever implementação antes dos testes+- Pular a fase RED+- Testar funções privadas diretamente+- Usar `time.Sleep` em testes+- Ignorar testes flaky++## Comandos Relacionados++- `/go-build` - Corrigir erros de build+- `/go-review` - Revisar código após implementação+- `/verify` - Rodar loop completo de verificação++## Relacionado++- Skill: `skills/golang-testing/`+- Skill: `skills/tdd-workflow/`diff --git a/docs/pt-BR/commands/learn.md b/docs/pt-BR/commands/learn.mdnew file mode 100644index 000000000..6c6154d23--- /dev/null+++ b/docs/pt-BR/commands/learn.md@@ -0,0 +1,70 @@+# /learn - Extrair Padrões Reutilizáveis++Analise a sessão atual e extraia padrões que valem ser salvos como skills.++## Trigger++Rode `/learn` em qualquer ponto da sessão quando você tiver resolvido um problema não trivial.++## O Que Extrair++Procure por:++1. **Padrões de Resolução de Erro**+ - Qual erro ocorreu?+ - Qual foi a causa raiz?+ - O que corrigiu?+ - Isso é reutilizável para erros semelhantes?++2. **Técnicas de Debug**+ - Passos de debug não óbvios+ - Combinações de ferramentas que funcionaram+ - Padrões de diagnóstico++3. **Workarounds**+ - Quirks de bibliotecas+ - Limitações de API+ - Correções específicas de versão++4. **Padrões Específicos do Projeto**+ - Convenções de codebase descobertas+ - Decisões de arquitetura tomadas+ - Padrões de integração++## Formato de Saída++Crie um arquivo de skill em `~/.claude/skills/learned/[pattern-name].md`:++```markdown+# [Descriptive Pattern Name]++**Extracted:** [Date]+**Context:** [Brief description of when this applies]++## Problem+[What problem this solves - be specific]++## Solution+[The pattern/technique/workaround]++## Example+[Code example if applicable]++## When to Use+[Trigger conditions - what should activate this skill]+```++## Processo++1. Revise a sessão para identificar padrões extraíveis+2. Identifique o insight mais valioso/reutilizável+3. Esboce o arquivo de skill+4. Peça confirmação do usuário antes de salvar+5. Salve em `~/.claude/skills/learned/`++## Notas++- Não extraia correções triviais (typos, erros simples de sintaxe)+- Não extraia problemas de uso único (indisponibilidade específica de API etc.)+- Foque em padrões que vão economizar tempo em sessões futuras+- Mantenha skills focadas - um padrão por skilldiff --git a/docs/pt-BR/commands/orchestrate.md b/docs/pt-BR/commands/orchestrate.mdnew file mode 100644index 000000000..b192321ca--- /dev/null+++ b/docs/pt-BR/commands/orchestrate.md@@ -0,0 +1,231 @@+---+description: Orientação de orquestração sequencial e tmux/worktree para fluxos multiagente.+---++# Comando Orchestrate++Fluxo sequencial de agentes para tarefas complexas.++## Uso++`/orchestrate [workflow-type] [task-description]`++## Tipos de Workflow++### feature+Workflow completo de implementação de feature:+```+planner -> tdd-guide -> code-reviewer -> security-reviewer+```++### bugfix+Workflow de investigação e correção de bug:+```+planner -> tdd-guide -> code-reviewer+```++### refactor+Workflow de refatoração segura:+```+architect -> code-reviewer -> tdd-guide+```++### security+Revisão focada em segurança:+```+security-reviewer -> code-reviewer -> architect+```++## Padrão de Execução++Para cada agente no workflow:++1. **Invoque o agente** com contexto do agente anterior+2. **Colete saída** como documento estruturado de handoff+3. **Passe para o próximo agente** na cadeia+4. **Agregue resultados** em um relatório final++## Formato do Documento de Handoff++Entre agentes, crie um documento de handoff:++```markdown+## HANDOFF: [previous-agent] -> [next-agent]++### Context+[Summary of what was done]++### Findings+[Key discoveries or decisions]++### Files Modified+[List of files touched]++### Open Questions+[Unresolved items for next agent]++### Recommendations+[Suggested next steps]+```++## Exemplo: Workflow de Feature++```+/orchestrate feature "Add user authentication"+```++Executa:++1. **Planner Agent**+ - Analisa requisitos+ - Cria plano de implementação+ - Identifica dependências+ - Saída: `HANDOFF: planner -> tdd-guide`++2. **TDD Guide Agent**+ - Lê handoff do planner+ - Escreve testes primeiro+ - Implementa para passar testes+ - Saída: `HANDOFF: tdd-guide -> code-reviewer`++3. **Code Reviewer Agent**+ - Revisa implementação+ - Verifica problemas+ - Sugere melhorias+ - Saída: `HANDOFF: code-reviewer -> security-reviewer`++4. **Security Reviewer Agent**+ - Auditoria de segurança+ - Verificação de vulnerabilidades+ - Aprovação final+ - Saída: Relatório Final++## Formato do Relatório Final++```+ORCHESTRATION REPORT+====================+Workflow: feature+Task: Add user authentication+Agents: planner -> tdd-guide -> code-reviewer -> security-reviewer++SUMMARY+-------+[One paragraph summary]++AGENT OUTPUTS+-------------+Planner: [summary]+TDD Guide: [summary]+Code Reviewer: [summary]+Security Reviewer: [summary]++FILES CHANGED+-------------+[List all files modified]++TEST RESULTS+------------+[Test pass/fail summary]++SECURITY STATUS+---------------+[Security findings]++RECOMMENDATION+--------------+[SHIP / NEEDS WORK / BLOCKED]+```++## Execução Paralela++Para verificações independentes, rode agentes em paralelo:++```markdown+### Parallel Phase+Run simultaneously:+- code-reviewer (quality)+- security-reviewer (security)+- architect (design)++### Merge Results+Combine outputs into single report+```++Para workers externos em tmux panes com git worktrees separados, use `node scripts/orchestrate-worktrees.js plan.json --execute`. O padrão embutido de orquestração permanece no processo atual; o helper é para sessões longas ou cross-harness.++Quando os workers precisarem enxergar arquivos locais sujos ou não rastreados do checkout principal, adicione `seedPaths` ao arquivo de plano. O ECC faz overlay apenas desses caminhos selecionados em cada worktree do worker após `git worktree add`, mantendo o branch isolado e ainda expondo scripts, planos ou docs em andamento.++```json+{+ "sessionName": "workflow-e2e",+ "seedPaths": [+ "scripts/orchestrate-worktrees.js",+ "scripts/lib/tmux-worktree-orchestrator.js",+ ".claude/plan/workflow-e2e-test.json"+ ],+ "workers": [+ { "name": "docs", "task": "Update orchestration docs." }+ ]+}+```++Para exportar um snapshot do control plane para uma sessão tmux/worktree ao vivo, rode:++```bash+node scripts/orchestration-status.js .claude/plan/workflow-visual-proof.json+```++O snapshot inclui atividade da sessão, metadados de pane do tmux, estado dos workers, objetivos, overlays semeados e resumos recentes de handoff em formato JSON.++## Handoff de Command Center do Operador++Quando o workflow atravessar múltiplas sessões, worktrees ou panes tmux, acrescente um bloco de control plane ao handoff final:++```markdown+CONTROL PLANE+-------------+Sessions:+- active session ID or alias+- branch + worktree path for each active worker+- tmux pane or detached session name when applicable++Diffs:+- git status summary+- git diff --stat for touched files+- merge/conflict risk notes++Approvals:+- pending user approvals+- blocked steps awaiting confirmation++Telemetry:+- last activity timestamp or idle signal+- estimated token or cost drift+- policy events raised by hooks or reviewers+```++Isso mantém planner, implementador, revisor e loop workers legíveis pela superfície de operação.++## Argumentos++$ARGUMENTS:+- `feature <description>` - Workflow completo de feature+- `bugfix <description>` - Workflow de correção de bug+- `refactor <description>` - Workflow de refatoração+- `security <description>` - Workflow de revisão de segurança+- `custom <agents> <description>` - Sequência customizada de agentes++## Exemplo de Workflow Customizado++```+/orchestrate custom "architect,tdd-guide,code-reviewer" "Redesign caching layer"+```++## Dicas++1. **Comece com planner** para features complexas+2. **Sempre inclua code-reviewer** antes do merge+3. **Use security-reviewer** para auth/pagamento/PII+4. **Mantenha handoffs concisos** - foque no que o próximo agente precisa+5. **Rode verificação** entre agentes quando necessáriodiff --git a/docs/pt-BR/commands/plan.md b/docs/pt-BR/commands/plan.mdnew file mode 100644index 000000000..e21e2b4d7--- /dev/null+++ b/docs/pt-BR/commands/plan.md@@ -0,0 +1,115 @@+---+description: Reafirme requisitos, avalie riscos e crie plano de implementação passo a passo. ESPERE confirmação do usuário ANTES de tocar em qualquer código.+---++# Comando Plan++Este comando invoca o agente **planner** para criar um plano abrangente de implementação antes de escrever qualquer código.++## O Que Este Comando Faz++1. **Reafirmar Requisitos** - Esclarecer o que precisa ser construído+2. **Identificar Riscos** - Levantar problemas e bloqueios potenciais+3. **Criar Plano em Etapas** - Quebrar implementação em fases+4. **Aguardar Confirmação** - DEVE receber aprovação do usuário antes de prosseguir++## Quando Usar++Use `/plan` quando:+- Estiver iniciando uma nova feature+- For fazer mudanças arquiteturais significativas+- Estiver trabalhando em refatoração complexa+- Múltiplos arquivos/componentes serão afetados+- Requisitos estiverem pouco claros ou ambíguos++## Como Funciona++O agente planner vai:++1. **Analisar o pedido** e reafirmar os requisitos de forma clara+2. **Quebrar em fases** com etapas específicas e acionáveis+3. **Identificar dependências** entre componentes+4. **Avaliar riscos** e possíveis bloqueios+5. **Estimar complexidade** (High/Medium/Low)+6. **Apresentar o plano** e AGUARDAR sua confirmação explícita++## Exemplo de Uso++```+User: /plan I need to add real-time notifications when markets resolve++Agent (planner):+# Implementation Plan: Real-Time Market Resolution Notifications++## Requirements Restatement+- Send notifications to users when markets they're watching resolve+- Support multiple notification channels (in-app, email, webhook)+- Ensure notifications are delivered reliably+- Include market outcome and user's position result++## Implementation Phases++### Phase 1: Database Schema+- Add notifications table with columns: id, user_id, market_id, type, status, created_at+- Add user_notification_preferences table for channel preferences+- Create indexes on user_id and market_id for performance++### Phase 2: Notification Service+- Create notification service in lib/notifications.ts+- Implement notification queue using BullMQ/Redis+- Add retry logic for failed deliveries+- Create notification templates++### Phase 3: Integration Points+- Hook into market resolution logic (when status changes to "resolved")+- Query all users with positions in market+- Enqueue notifications for each user++### Phase 4: Frontend Components+- Create NotificationBell component in header+- Add NotificationList modal+- Implement real-time updates via Supabase subscriptions+- Add notification preferences page++## Dependencies+- Redis (for queue)+- Email service (SendGrid/Resend)+- Supabase real-time subscriptions++## Risks+- HIGH: Email deliverability (SPF/DKIM required)+- MEDIUM: Performance with 1000+ users per market+- MEDIUM: Notification spam if markets resolve frequently+- LOW: Real-time subscription overhead++## Estimated Complexity: MEDIUM+- Backend: 4-6 hours+- Frontend: 3-4 hours+- Testing: 2-3 hours+- Total: 9-13 hours++**WAITING FOR CONFIRMATION**: Proceed with this plan? (yes/no/modify)+```++## Notas Importantes++**CRITICAL**: O agente planner **NÃO** vai escrever código até você confirmar explicitamente o plano com "yes", "proceed" ou resposta afirmativa similar.++Se quiser mudanças, responda com:+- "modify: [your changes]"+- "different approach: [alternative]"+- "skip phase 2 and do phase 3 first"++## Integração com Outros Comandos++Após planejar:+- Use `/tdd` para implementar com test-driven development+- Use `/build-fix` se ocorrerem erros de build+- Use `/code-review` para revisar a implementação concluída++## Agentes Relacionados++Este comando invoca o agente `planner` fornecido pelo ECC.++Para instalações manuais, o arquivo fonte fica em:+`agents/planner.md`diff --git a/docs/pt-BR/commands/refactor-clean.md b/docs/pt-BR/commands/refactor-clean.mdnew file mode 100644index 000000000..cf8573d9a--- /dev/null+++ b/docs/pt-BR/commands/refactor-clean.md@@ -0,0 +1,80 @@+# Refactor Clean++Identifique e remova código morto com segurança, com verificação de testes em cada passo.++## Passo 1: Detectar Código Morto++Rode ferramentas de análise com base no tipo do projeto:++| Tool | What It Finds | Command |+|------|--------------|---------|+| knip | Unused exports, files, dependencies | `npx knip` |+| depcheck | Unused npm dependencies | `npx depcheck` |+| ts-prune | Unused TypeScript exports | `npx ts-prune` |+| vulture | Unused Python code | `vulture src/` |+| deadcode | Unused Go code | `deadcode ./...` |+| cargo-udeps | Unused Rust dependencies | `cargo +nightly udeps` |++Se nenhuma ferramenta estiver disponível, use Grep para encontrar exports com zero imports:+```+# Find exports, then check if they're imported anywhere+```++## Passo 2: Categorizar Achados++Classifique os achados em níveis de segurança:++| Tier | Examples | Action |+|------|----------|--------|+| **SAFE** | Unused utilities, test helpers, internal functions | Delete with confidence |+| **CAUTION** | Components, API routes, middleware | Verify no dynamic imports or external consumers |+| **DANGER** | Config files, entry points, type definitions | Investigate before touching |++## Passo 3: Loop de Remoção Segura++Para cada item SAFE:++1. **Rode a suíte completa de testes** — Estabeleça baseline (tudo verde)+2. **Delete o código morto** — Use a ferramenta Edit para remoção cirúrgica+3. **Rode a suíte de testes novamente** — Verifique se nada quebrou+4. **Se testes falharem** — Reverta imediatamente com `git checkout -- <file>` e pule este item+5. **Se testes passarem** — Vá para o próximo item++## Passo 4: Tratar Itens CAUTION++Antes de deletar itens CAUTION:+- Procure imports dinâmicos: `import()`, `require()`, `__import__`+- Procure referências em string: nomes de rota, nomes de componente em configs+- Verifique se é exportado por API pública de pacote+- Verifique ausência de consumidores externos (dependents, se publicado)++## Passo 5: Consolidar Duplicatas++Depois de remover código morto, procure:+- Funções quase duplicadas (>80% similares) — mesclar em uma+- Definições de tipo redundantes — consolidar+- Funções wrapper sem valor — inline+- Re-exports sem propósito — remover indireção++## Passo 6: Resumo++Reporte resultados:++```+Dead Code Cleanup+──────────────────────────────+Deleted: 12 unused functions+ 3 unused files+ 5 unused dependencies+Skipped: 2 items (tests failed)+Saved: ~450 lines removed+──────────────────────────────+All tests passing ✅+```++## Regras++- **Nunca delete sem rodar testes antes**+- **Uma remoção por vez** — Mudanças atômicas facilitam rollback+- **Se houver dúvida, pule** — Melhor manter código morto do que quebrar produção+- **Não refatore durante limpeza** — Separe responsabilidades (limpar primeiro, refatorar depois)diff --git a/docs/pt-BR/commands/setup-pm.md b/docs/pt-BR/commands/setup-pm.mdnew file mode 100644index 000000000..ca978774a--- /dev/null+++ b/docs/pt-BR/commands/setup-pm.md@@ -0,0 +1,80 @@+---+description: Configure seu package manager preferido (npm/pnpm/yarn/bun)+disable-model-invocation: true+---++# Configuração de Package Manager++Configure seu package manager preferido para este projeto ou globalmente.++## Uso++```bash+# Detect current package manager+node scripts/setup-package-manager.js --detect++# Set global preference+node scripts/setup-package-manager.js --global pnpm++# Set project preference+node scripts/setup-package-manager.js --project bun++# List available package managers+node scripts/setup-package-manager.js --list+```++## Prioridade de Detecção++Ao determinar qual package manager usar, esta ordem é verificada:++1. **Environment variable**: `CLAUDE_PACKAGE_MANAGER`+2. **Project config**: `.claude/package-manager.json`+3. **package.json**: `packageManager` field+4. **Lock file**: Presence of package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb+5. **Global config**: `~/.claude/package-manager.json`+6. **Fallback**: First available package manager (pnpm > bun > yarn > npm)++## Arquivos de Configuração++### Configuração Global+```json+// ~/.claude/package-manager.json+{+ "packageManager": "pnpm"+}+```++### Configuração do Projeto+```json+// .claude/package-manager.json+{+ "packageManager": "bun"+}+```++### package.json+```json+{+ "packageManager": "[email protected]"+}+```++## Variável de Ambiente++Defina `CLAUDE_PACKAGE_MANAGER` para sobrescrever todos os outros métodos de detecção:++```bash+# Windows (PowerShell)+$env:CLAUDE_PACKAGE_MANAGER = "pnpm"++# macOS/Linux+export CLAUDE_PACKAGE_MANAGER=pnpm+```++## Rodar a Detecção++Para ver os resultados atuais da detecção de package manager, rode:++```bash+node scripts/setup-package-manager.js --detect+```diff --git a/docs/pt-BR/commands/tdd.md b/docs/pt-BR/commands/tdd.mdnew file mode 100644index 000000000..341b98cf8--- /dev/null+++ b/docs/pt-BR/commands/tdd.md@@ -0,0 +1,328 @@+---+description: Impõe fluxo de desenvolvimento orientado a testes. Estruture interfaces, gere testes PRIMEIRO e depois implemente código mínimo para passar. Garanta cobertura de 80%+.+---++# Comando TDD++Este comando invoca o agente **tdd-guide** para impor a metodologia de desenvolvimento orientado a testes.++## O Que Este Comando Faz++1. **Estruturar Interfaces** - Definir tipos/interfaces primeiro+2. **Gerar Testes Primeiro** - Escrever testes que falham (RED)+3. **Implementar Código Mínimo** - Escrever apenas o suficiente para passar (GREEN)+4. **Refatorar** - Melhorar o código mantendo testes verdes (REFACTOR)+5. **Verificar Cobertura** - Garantir cobertura de testes de 80%+++## Quando Usar++Use `/tdd` quando:+- Implementar novas features+- Adicionar novas funções/componentes+- Corrigir bugs (escrever primeiro teste que reproduz o bug)+- Refatorar código existente+- Construir lógica de negócio crítica++## Como Funciona++O agente tdd-guide vai:++1. **Definir interfaces** para entradas/saídas+2. **Escrever testes que vão FALHAR** (porque o código ainda não existe)+3. **Rodar testes** e verificar que falham pelo motivo correto+4. **Escrever implementação mínima** para fazer testes passarem+5. **Rodar testes** e verificar que passam+6. **Refatorar** código mantendo testes verdes+7. **Checar cobertura** e adicionar mais testes se estiver abaixo de 80%++## Ciclo TDD++```+RED → GREEN → REFACTOR → REPEAT++RED: Write a failing test+GREEN: Write minimal code to pass+REFACTOR: Improve code, keep tests passing+REPEAT: Next feature/scenario+```++## Exemplo de Uso++```+User: /tdd I need a function to calculate market liquidity score++Agent (tdd-guide):+# TDD Session: Market Liquidity Score Calculator++## Step 1: Define Interface (SCAFFOLD)++```typescript+// lib/liquidity.ts+export interface MarketData {+ totalVolume: number+ bidAskSpread: number+ activeTraders: number+ lastTradeTime: Date+}++export function calculateLiquidityScore(market: MarketData): number {+ // TODO: Implementation+ throw new Error('Not implemented')+}+```++## Step 2: Write Failing Test (RED)++```typescript+// lib/liquidity.test.ts+import { calculateLiquidityScore } from './liquidity'++describe('calculateLiquidityScore', () => {+ it('should return high score for liquid market', () => {+ const market = {+ totalVolume: 100000,+ bidAskSpread: 0.01,+ activeTraders: 500,+ lastTradeTime: new Date()+ }++ const score = calculateLiquidityScore(market)++ expect(score).toBeGreaterThan(80)+ expect(score).toBeLessThanOrEqual(100)+ })++ it('should return low score for illiquid market', () => {+ const market = {+ totalVolume: 100,+ bidAskSpread: 0.5,+ activeTraders: 2,+ lastTradeTime: new Date(Date.now() - 86400000) // 1 day ago+ }++ const score = calculateLiquidityScore(market)++ expect(score).toBeLessThan(30)+ expect(score).toBeGreaterThanOrEqual(0)+ })++ it('should handle edge case: zero volume', () => {+ const market = {+ totalVolume: 0,+ bidAskSpread: 0,+ activeTraders: 0,+ lastTradeTime: new Date()+ }++ const score = calculateLiquidityScore(market)++ expect(score).toBe(0)+ })+})+```++## Step 3: Run Tests - Verify FAIL++```bash+npm test lib/liquidity.test.ts++FAIL lib/liquidity.test.ts+ ✕ should return high score for liquid market (2 ms)+ Error: Not implemented++1 test failed, 0 passed+```++✅ Tests fail as expected. Ready to implement.++## Step 4: Implement Minimal Code (GREEN)++```typescript+// lib/liquidity.ts+export function calculateLiquidityScore(market: MarketData): number {+ // Handle zero volume edge case+ if (market.totalVolume === 0) {+ return 0+ }++ // Calculate component scores (0-100 scale)+ const volumeScore = Math.min(market.totalVolume / 1000, 100)+ const spreadScore = Math.max(100 - (market.bidAskSpread * 1000), 0)+ const traderScore = Math.min(market.activeTraders / 10, 100)++ // Recent activity bonus+ const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) / (1000 * 60 * 60)+ const recencyScore = Math.max(100 - (hoursSinceLastTrade * 10), 0)++ // Weighted average+ const score = (+ volumeScore * 0.4 ++ spreadScore * 0.3 ++ traderScore * 0.2 ++ recencyScore * 0.1+ )++ return Math.min(Math.max(score, 0), 100) // Clamp to 0-100+}+```++## Step 5: Run Tests - Verify PASS++```bash+npm test lib/liquidity.test.ts++PASS lib/liquidity.test.ts+ ✓ should return high score for liquid market (3 ms)+ ✓ should return low score for illiquid market (2 ms)+ ✓ should handle edge case: zero volume (1 ms)++3 tests passed+```++✅ All tests passing!++## Step 6: Refactor (IMPROVE)++```typescript+// lib/liquidity.ts - Refactored with constants and better readability+const WEIGHTS = {+ VOLUME: 0.4,+ SPREAD: 0.3,+ TRADERS: 0.2,+ RECENCY: 0.1,+} as const++const SCALE_FACTORS = {+ VOLUME: 1000,+ SPREAD: 1000,+ TRADERS: 10,+ RECENCY_PENALTY: 10,+} as const++function clamp(value: number, min: number, max: number): number {+ return Math.min(Math.max(value, min), max)+}++export function calculateLiquidityScore(market: MarketData): number {+ if (market.totalVolume === 0) return 0++ const volumeScore = Math.min(market.totalVolume / SCALE_FACTORS.VOLUME, 100)+ const spreadScore = clamp(100 - (market.bidAskSpread * SCALE_FACTORS.SPREAD), 0, 100)+ const traderScore = Math.min(market.activeTraders / SCALE_FACTORS.TRADERS, 100)++ const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) / (1000 * 60 * 60)+ const recencyScore = clamp(100 - (hoursSinceLastTrade * SCALE_FACTORS.RECENCY_PENALTY), 0, 100)++ const weightedScore =+ volumeScore * WEIGHTS.VOLUME ++ spreadScore * WEIGHTS.SPREAD ++ traderScore * WEIGHTS.TRADERS ++ recencyScore * WEIGHTS.RECENCY++ return clamp(weightedScore, 0, 100)+}+```++## Step 7: Verify Tests Still Pass++```bash+npm test lib/liquidity.test.ts++PASS lib/liquidity.test.ts+ ✓ should return high score for liquid market (3 ms)+ ✓ should return low score for illiquid market (2 ms)+ ✓ should handle edge case: zero volume (1 ms)++3 tests passed+```++✅ Refactoring complete, tests still passing!++## Step 8: Check Coverage++```bash+npm test -- --coverage lib/liquidity.test.ts++File | % Stmts | % Branch | % Funcs | % Lines+---------------|---------|----------|---------|--------+liquidity.ts | 100 | 100 | 100 | 100++Coverage: 100% ✅ (Target: 80%)+```++✅ TDD session complete!+```++## Boas Práticas de TDD++**DO:**+- ✅ Escreva o teste PRIMEIRO, antes da implementação+- ✅ Rode testes e confirme que FALHAM antes de implementar+- ✅ Escreva código mínimo para fazer passar+- ✅ Refatore só depois que os testes estiverem verdes+- ✅ Adicione casos de borda e cenários de erro+- ✅ Mire 80%+ de cobertura (100% para código crítico)++**DON'T:**+- ❌ Escrever implementação antes de testes+- ❌ Pular execução de testes após cada mudança+- ❌ Escrever código demais de uma vez+- ❌ Ignorar testes falhando+- ❌ Testar detalhes de implementação (teste comportamento)+- ❌ Fazer mock de tudo (prefira testes de integração)++## Tipos de Teste a Incluir++**Testes Unitários** (nível de função):+- Cenários happy path+- Casos de borda (vazio, null, valores máximos)+- Condições de erro+- Valores de fronteira++**Testes de Integração** (nível de componente):+- Endpoints de API+- Operações de banco de dados+- Chamadas a serviços externos+- Componentes React com hooks++**Testes E2E** (use comando `/e2e`):+- Fluxos críticos de usuário+- Processos multi-etapa+- Integração full stack++## Requisitos de Cobertura++- **Mínimo de 80%** para todo o código+- **100% obrigatório** para:+ - Cálculos financeiros+ - Lógica de autenticação+ - Código crítico de segurança+ - Lógica de negócio central++## Notas Importantes++**MANDATÓRIO**: Os testes devem ser escritos ANTES da implementação. O ciclo TDD é:++1. **RED** - Escrever teste que falha+2. **GREEN** - Implementar para passar+3. **REFACTOR** - Melhorar código++Nunca pule a fase RED. Nunca escreva código antes dos testes.++## Integração com Outros Comandos++- Use `/plan` primeiro para entender o que construir+- Use `/tdd` para implementar com testes+- Use `/build-fix` se ocorrerem erros de build+- Use `/code-review` para revisar implementação+- Use `/test-coverage` para verificar cobertura++## Agentes Relacionados++Este comando invoca o agente `tdd-guide` fornecido pelo ECC.++A skill relacionada `tdd-workflow` também é distribuída com o ECC.++Para instalações manuais, os arquivos fonte ficam em:+- `agents/tdd-guide.md`+- `skills/tdd-workflow/SKILL.md`diff --git a/docs/pt-BR/commands/test-coverage.md b/docs/pt-BR/commands/test-coverage.mdnew file mode 100644index 000000000..e1c67d6d4--- /dev/null+++ b/docs/pt-BR/commands/test-coverage.md@@ -0,0 +1,69 @@+# Cobertura de Testes++Analise cobertura de testes, identifique lacunas e gere testes faltantes para alcançar cobertura de 80%+.++## Passo 1: Detectar Framework de Teste++| Indicator | Coverage Command |+|-----------|-----------------|+| `jest.config.*` or `package.json` jest | `npx jest --coverage --coverageReporters=json-summary` |+| `vitest.config.*` | `npx vitest run --coverage` |+| `pytest.ini` / `pyproject.toml` pytest | `pytest --cov=src --cov-report=json` |+| `Cargo.toml` | `cargo llvm-cov --json` |+| `pom.xml` with JaCoCo | `mvn test jacoco:report` |+| `go.mod` | `go test -coverprofile=coverage.out ./...` |++## Passo 2: Analisar Relatório de Cobertura++1. Rode o comando de cobertura+2. Parseie a saída (resumo em JSON ou saída de terminal)+3. Liste arquivos **abaixo de 80% de cobertura**, ordenados do pior para o melhor+4. Para cada arquivo abaixo da meta, identifique:+ - Funções ou métodos sem teste+ - Cobertura de branch faltante (if/else, switch, caminhos de erro)+ - Código morto que infla o denominador++## Passo 3: Gerar Testes Faltantes++Para cada arquivo abaixo da meta, gere testes seguindo esta prioridade:++1. **Happy path** — Funcionalidade principal com entradas válidas+2. **Tratamento de erro** — Entradas inválidas, dados ausentes, falhas de rede+3. **Casos de borda** — Arrays vazios, null/undefined, valores de fronteira (0, -1, MAX_INT)+4. **Cobertura de branch** — Cada if/else, caso de switch, ternário++### Regras para Geração de Testes++- Coloque testes adjacentes ao código-fonte: `foo.ts` → `foo.test.ts` (ou convenção do projeto)+- Use padrões de teste existentes do projeto (estilo de import, biblioteca de asserção, abordagem de mocking)+- Faça mock de dependências externas (banco, APIs, sistema de arquivos)+- Cada teste deve ser independente — sem estado mutável compartilhado entre testes+- Nomeie testes de forma descritiva: `test_create_user_with_duplicate_email_returns_409`++## Passo 4: Verificar++1. Rode a suíte completa de testes — todos os testes devem passar+2. Rode cobertura novamente — confirme a melhoria+3. Se ainda estiver abaixo de 80%, repita o Passo 3 para as lacunas restantes++## Passo 5: Reportar++Mostre comparação antes/depois:++```+Coverage Report+──────────────────────────────+File Before After+src/services/auth.ts 45% 88%+src/utils/validation.ts 32% 82%+──────────────────────────────+Overall: 67% 84% ✅+```++## Áreas de Foco++- Funções com branching complexo (alta complexidade ciclomática)+- Error handlers e blocos catch+- Funções utilitárias usadas em todo o codebase+- Handlers de endpoint de API (fluxo request → response)+- Casos de borda: null, undefined, string vazia, array vazio, zero, números negativosdiff --git a/docs/pt-BR/commands/update-codemaps.md b/docs/pt-BR/commands/update-codemaps.mdnew file mode 100644index 000000000..8a5cb90fe--- /dev/null+++ b/docs/pt-BR/commands/update-codemaps.md@@ -0,0 +1,72 @@+# Atualizar Codemaps++Analise a estrutura do codebase e gere documentação arquitetural enxuta em tokens.++## Passo 1: Escanear Estrutura do Projeto++1. Identifique o tipo de projeto (monorepo, app única, library, microservice)+2. Encontre todos os diretórios de código-fonte (src/, lib/, app/, packages/)+3. Mapeie entry points (main.ts, index.ts, app.py, main.go, etc.)++## Passo 2: Gerar Codemaps++Crie ou atualize codemaps em `docs/CODEMAPS/` (ou `.reports/codemaps/`):++| File | Contents |+|------|----------|+| `architecture.md` | High-level system diagram, service boundaries, data flow |+| `backend.md` | API routes, middleware chain, service → repository mapping |+| `frontend.md` | Page tree, component hierarchy, state management flow |+| `data.md` | Database tables, relationships, migration history |+| `dependencies.md` | External services, third-party integrations, shared libraries |++### Formato de Codemap++Cada codemap deve ser enxuto em tokens — otimizado para consumo de contexto por IA:++```markdown+# Backend Architecture++## Routes+POST /api/users → UserController.create → UserService.create → UserRepo.insert+GET /api/users/:id → UserController.get → UserService.findById → UserRepo.findById++## Key Files+src/services/user.ts (business logic, 120 lines)+src/repos/user.ts (database access, 80 lines)++## Dependencies+- PostgreSQL (primary data store)+- Redis (session cache, rate limiting)+- Stripe (payment processing)+```++## Passo 3: Detecção de Diff++1. Se codemaps anteriores existirem, calcule a porcentagem de diff+2. Se mudanças > 30%, mostre o diff e solicite aprovação do usuário antes de sobrescrever+3. Se mudanças <= 30%, atualize in-place++## Passo 4: Adicionar Metadados++Adicione um cabeçalho de freshness em cada codemap:++```markdown+<!-- Generated: 2026-02-11 | Files scanned: 142 | Token estimate: ~800 -->+```++## Passo 5: Salvar Relatório de Análise++Escreva um resumo em `.reports/codemap-diff.txt`:+- Arquivos adicionados/removidos/modificados desde o último scan+- Novas dependências detectadas+- Mudanças de arquitetura (novas rotas, novos serviços etc.)+- Alertas de obsolescência para docs sem atualização em 90+ dias++## Dicas++- Foque em **estrutura de alto nível**, não em detalhes de implementação+- Prefira **caminhos de arquivo e assinaturas de função** em vez de blocos de código completos+- Mantenha cada codemap abaixo de **1000 tokens** para carregamento eficiente de contexto+- Use diagramas ASCII para fluxo de dados em vez de descrições verbosas+- Rode após grandes adições de feature ou sessões de refatoraçãodiff --git a/docs/pt-BR/commands/update-docs.md b/docs/pt-BR/commands/update-docs.mdnew file mode 100644index 000000000..9563299c5--- /dev/null+++ b/docs/pt-BR/commands/update-docs.md@@ -0,0 +1,84 @@+# Atualizar Documentação++Sincronize a documentação com o codebase, gerando a partir de arquivos fonte da verdade.++## Passo 1: Identificar Fontes da Verdade++| Source | Generates |+|--------|-----------|+| `package.json` scripts | Available commands reference |+| `.env.example` | Environment variable documentation |+| `openapi.yaml` / route files | API endpoint reference |+| Source code exports | Public API documentation |+| `Dockerfile` / `docker-compose.yml` | Infrastructure setup docs |++## Passo 2: Gerar Referência de Scripts++1. Leia `package.json` (ou `Makefile`, `Cargo.toml`, `pyproject.toml`)+2. Extraia todos os scripts/comandos com suas descrições+3. Gere uma tabela de referência:++```markdown+| Command | Description |+|---------|-------------|+| `npm run dev` | Start development server with hot reload |+| `npm run build` | Production build with type checking |+| `npm test` | Run test suite with coverage |+```++## Passo 3: Gerar Documentação de Ambiente++1. Leia `.env.example` (ou `.env.template`, `.env.sample`)+2. Extraia todas as variáveis e seus propósitos+3. Categorize como required vs optional+4. Documente formato esperado e valores válidos++```markdown+| Variable | Required | Description | Example |+|----------|----------|-------------|---------|+| `DATABASE_URL` | Yes | PostgreSQL connection string | `postgres://user:pass@host:5432/db` |+| `LOG_LEVEL` | No | Logging verbosity (default: info) | `debug`, `info`, `warn`, `error` |+```++## Passo 4: Atualizar Guia de Contribuição++Gere ou atualize `docs/CONTRIBUTING.md` com:+- Setup do ambiente de desenvolvimento (pré-requisitos, passos de instalação)+- Scripts disponíveis e seus propósitos+- Procedimentos de teste (como rodar, como escrever novos testes)+- Enforcement de estilo de código (linter, formatter, hooks pre-commit)+- Checklist de submissão de PR++## Passo 5: Atualizar Runbook++Gere ou atualize `docs/RUNBOOK.md` com:+- Procedimentos de deploy (passo a passo)+- Endpoints de health check e monitoramento+- Problemas comuns e suas correções+- Procedimentos de rollback+- Caminhos de alerta e escalonamento++## Passo 6: Checagem de Obsolescência++1. Encontre arquivos de documentação sem modificação há 90+ dias+2. Cruze com mudanças recentes no código-fonte+3. Sinalize docs potencialmente desatualizadas para revisão manual++## Passo 7: Mostrar Resumo++```+Documentation Update+──────────────────────────────+Updated: docs/CONTRIBUTING.md (scripts table)+Updated: docs/ENV.md (3 new variables)+Flagged: docs/DEPLOY.md (142 days stale)+Skipped: docs/API.md (no changes detected)+──────────────────────────────+```++## Regras++- **Fonte única da verdade**: Sempre gere a partir do código, nunca edite manualmente seções geradas+- **Preserve seções manuais**: Atualize apenas seções geradas; mantenha prosa escrita manualmente intacta+- **Marque conteúdo gerado**: Use marcadores `<!-- AUTO-GENERATED -->` ao redor das seções geradas+- **Não crie docs sem solicitação**: Só crie novos arquivos de docs se o comando solicitar explicitamentediff --git a/docs/pt-BR/commands/verify.md b/docs/pt-BR/commands/verify.mdnew file mode 100644index 000000000..5916a529b--- /dev/null+++ b/docs/pt-BR/commands/verify.md@@ -0,0 +1,59 @@+# Comando Verification++Rode verificação abrangente no estado atual do codebase.++## Instruções++Execute a verificação nesta ordem exata:++1. **Build Check**+ - Rode o comando de build deste projeto+ - Se falhar, reporte erros e PARE++2. **Type Check**+ - Rode o TypeScript/type checker+ - Reporte todos os erros com file:line++3. **Lint Check**+ - Rode o linter+ - Reporte warnings e errors++4. **Test Suite**+ - Rode todos os testes+ - Reporte contagem de pass/fail+ - Reporte percentual de cobertura++5. **Console.log Audit**+ - Procure por console.log em arquivos de código-fonte+ - Reporte localizações++6. **Git Status**+ - Mostre mudanças não commitadas+ - Mostre arquivos modificados desde o último commit++## Saída++Produza um relatório conciso de verificação:++```+VERIFICATION: [PASS/FAIL]++Build: [OK/FAIL]+Types: [OK/X errors]+Lint: [OK/X issues]+Tests: [X/Y passed, Z% coverage]+Secrets: [OK/X found]+Logs: [OK/X console.logs]++Ready for PR: [YES/NO]+```++Se houver problemas críticos, liste-os com sugestões de correção.++## Argumentos++$ARGUMENTS podem ser:+- `quick` - Apenas build + types+- `full` - Todas as checagens (padrão)+- `pre-commit` - Checagens relevantes para commits+- `pre-pr` - Checagens completas mais security scan