agim-orchestrator 0.0.0-stage → 1.1.2

package/.opencode/skills/analise-de-legado/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: analise-de-legado
+description: "Inspeciona arquitetura, módulos, dependências e riscos antes de refatorações. Preserva funcionalidades e NÃO modifica código quando a solicitação for somente de análise. Baseada em reverse-engineer-anything, code-simplification e graphify."
+argument-hint: "[caminho-projeto] [foco-opcional]"
+license: MIT
+metadata:
+  author: meu-padrao-de-desenvolvimento
+  version: "1.0.0"
+  domains: ["analise-legado", "engenharia-reversa", "refatoracao", "arquitetura"]
+  triggers: ["analisar legado", "entender código existente", "riscos refatoração", "mapear dependências", "documentar arquitetura"]
+---
+
+# Skill: Análise de Legado
+
+## Objetivo
+Compreender profundamente um código existente (legado ou não) antes de propor mudanças, identificando arquitetura, módulos, dependências, dívida técnica, riscos e oportunidades - **sem modificar o código** a menos que explicitamente solicitado para correção pontual.
+
+## Quando Ativar
+- Antes de refatorar/migrar sistema existente
+- Onboarding em código desconhecido
+- Auditoria técnica ou due diligence
+- Documentação de arquitetura atual
+- Investigação de bugs recorrentes
+- Planejamento de migração/strangler fig
+
+## Pré-condições
+- Acesso ao código fonte (repositório local)
+- `graphify` disponível (se instalado) para grafo de dependências
+- Permissão de leitura em todo o projeto
+- AGENTS.md e docs/ARQUITETURA.md lidos
+
+## Procedimento de Execução
+
+### Passo 1: Reconhecimento Inicial
+1. **Estrutura geral**: `ls -la`, `tree` ou `glob` para mapear diretórios
+2. **Arquivos de configuração**: package.json, tsconfig, prisma/schema, docker, CI/CD
+3. **Entry points**: main, server, app, routes, index
+3. **Documentação existente**: README, ARCHITECTURE, ADRs, comentários de arquitetura
+
+### Passo 2: Mapear Arquitetura (Graphify + Inspeção)
+**Se graphify disponível:**
+- `graphify build` (se não existe `graphify-out/`)
+- `graphify query "arquitetura geral do projeto"`
+- `graphify query "módulos principais e dependências"`
+- `graphify query "fluxo de dados: request → response"`
+
+**Inspeção manual complementar:**
+- Identificar camadas: routes → controllers → services → repositories → DB
+- Padrões: modular, layered, feature-based, clean architecture
+- Convenções: naming, estrutura pastas, imports, exports
+
+### Passo 3: Analisar Módulos e Dependências
+Para cada módulo principal:
+| Módulo | Responsabilidade | Arquivos-chave | Dependências Internas | Dependências Externas | Acoplamento |
+|--------|-----------------|----------------|----------------------|----------------------|-------------|
+
+**Métricas de acoplamento:**
+- Import fan-in/out
+- Dependências circulares (`madge --circular` ou similar)
+- Uso de `any`, `unknown`, type assertions excessivas
+- God classes/modules (arquivos > 500 linhas, muitas responsabilidades)
+
+### Passo 4: Identificar Dívida Técnica e Riscos
+**Checklist sistemático:**
+- [ ] **Arquivos grandes** (>300 linhas) sem separação clara
+- [ ] **Dependências circulares** entre módulos
+- [ ] **Duplicação de código** (funções, validações, tipos)
+- [ ] **`any` excessivo** / tipagem fraca
+- [ ] **Testes ausentes** ou insuficientes (cobertura < 70%)
+- [ ] **Segredos no código** / `.env` commitado
+- [ ] **Logs de debug** em produção
+- [ ] **Tratamento de erro inconsistente** / `try/catch` vazio
+- [ ] **Validação apenas no frontend** (sem backend)
+- [ ] **Queries N+1** / performance suspeita
+- [ ] **Migrações perigosas** (drop column, rename sem expand/contract)
+- [ ] **Dependências desatualizadas/vulneráveis** (`npm audit`)
+- [ ] **Código morto** / imports não utilizados / feature flags órfãs
+- [ ] **Segurança**: authZ ausente, SQL injection, XSS, CSRF
+
+### Passo 5: Analisar Fluxos Críticos
+Para cada fluxo principal (ex: login, criar pedido, pagamento):
+1. Rastrear: Route → Controller → Service → Repository → DB → Response
+2. Identificar: validações, transações, eventos, side effects
+3. Verificar: idempotência, rollback, observabilidade, timeouts
+
+### Passo 6: Avaliar Testabilidade
+- Cobertura atual (unit, integration, e2e)
+- Mocks necessários vs dependências reais
+- Fixtures/factories existentes
+- CI/CD pipeline funcionando
+
+### Passo 7: Documentar Achados
+**Relatório de Análise:**
+```
+## Análise de Legado: [Projeto/Sistema]
+
+### Visão Geral
+- Stack: ...
+- Tamanho: X arquivos, Y linhas, Z módulos
+- Arquitetura: [modular/layered/monolito/outro]
+
+### Módulos Principais
+| Módulo | Arquivos | Responsabilidade | Riscos |
+
+### Dependências Críticas
+- Circulares: ...
+- Externas desatualizadas: ...
+- Acoplamento forte: ...
+
+### Dívida Técnica (Priorizada)
+1. [Crítico] ...
+2. [Alto] ...
+3. [Médio] ...
+4. [Baixo] ...
+
+### Riscos de Refatoração
+| Risco | Probabilidade | Impacto | Mitigação |
+
+### Oportunidades de Melhoria
+- Quick wins: ...
+- Médio prazo: ...
+- Arquitetural: ...
+
+### Recomendações
+1. Não tocar em: [módulos estáveis]
+2. Refatorar primeiro: [módulos de alto risco/valor]
+3. Testes necessários antes: ...
+4. Estrangulamento sugerido: ...
+```
+
+### Passo 8: Entregar (Somente Análise)
+**Se solicitação for "apenas analisar":** Entregar relatório acima, **não modificar código**.
+**Se solicitação incluir correção:** Aplicar apenas correções pontuais acordadas (ex: remover `console.log`, corrigir typo em comentário, ajustar import), documentando cada mudança.
+
+## Ferramentas Necessárias
+- `graphify` (grafo conhecimento)
+- `madge` / `depcruise` (dependências circulares)
+- `grep`/`rg` (busca padrões)
+- `cloc` / `tokei` (estatísticas código)
+- `npm audit` / `pnpm audit` (vulnerabilidades)
+- `tools.context7` (docs libs externas encontradas)
+
+## Limites de Responsabilidade
+- **NÃO** refatora código (skill `code-simplification` ou implementação)
+- **NÃO** escreve testes (skill `testes-com-roteiro` + `test-driven-development`)
+- **NÃO** decide migração de stack (requer decisão arquitetural)
+- **SIM** identifica o que precisa ser feito, em que ordem, com que riscos
+- **SIM** preserva funcionalidades existentes como regra absoluta
+
+## Critérios de Aceitação
+- [ ] Arquitetura mapeada com módulos e responsabilidades
+- [ ] Dependências (internas/externas) documentadas
+- [ ] Dívida técnica priorizada com evidências
+- [ ] Riscos de refatoração identificados com mitigações
+- [ ] Recomendações acionáveis e priorizadas
+- [ ] Código **não modificado** (salvo correções pontuais acordadas)
+- [ ] Relatório salvo em `memoria/` ou `docs/` conforme acordado
+
+## Tratamento de Falhas
+| Falha | Ação |
+|-------|------|
+| Código muito grande para análise completa | Amostragem representativa + foco em áreas de mudança |
+| Graphify não disponível | Inspeção manual + `madge` + documentação existente |
+| Dependências circulares massivas | Documentar como risco crítico, sugerir estrangulamento gradual |
+| Código sem testes e alta complexidade | Recomendar testes de caracterização antes de qualquer mudança |
+| Segredos encontrados | Reportar imediatamente, não expor no relatório, sugerir rotação |
+
+## Formato de Entrega
+Relatório em Markdown salvo em `docs/ANALISE-LEGADO-[projeto]-[data].md` ou `memoria/ANALISE-LEGADO-[timestamp].md`
+
+## Referências
+- `docs/ARQUITETURA.md`, `docs/CODIGO-LIMPO.md`, `docs/SEGURANCA.md`
+- `graphify` plugin, `madge`, `depcruise`, `code-simplification` skill

package/.opencode/skills/auditoria-de-seguranca/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: auditoria-de-seguranca
+description: "Examina autenticação, autorização, validações, exposição de segredos, configuração, dependências e riscos relevantes. Baseada em security-and-hardening, code-review-and-quality e docs/SEGURANCA.md."
+argument-hint: "[caminho-projeto] [escopo: completa|auth|api|infra|deps]"
+license: MIT
+metadata:
+  author: meu-padrao-de-desenvolvimento
+  version: "1.0.0"
+  domains: ["seguranca", "auditoria", "auth", "autorizacao", "validacao", "secrets", "dependencias"]
+  triggers: ["auditoria segurança", "revisão segurança", "vulnerabilidades", "auth authorization", "secrets", "dependências"]
+---
+
+# Skill: Auditoria de Segurança
+
+## Objetivo
+Realizar auditoria sistemática de segurança em aplicações, identificando vulnerabilidades reais, classificando por severidade, apresentando evidências e recomendações de mitigação - **sem executar ações destrutivas ou não autorizadas**.
+
+## Quando Ativar
+- Pré-deploy / release candidato
+- Auditoria periódica (trimestral/semestral)
+- Implementação de auth/autorização/dados sensíveis
+- Code review com foco em segurança
+- Investigação de incidente suspeito
+- Compliance (LGPD, PCI-DSS, etc.)
+
+## Pré-condições
+- Acesso ao código fonte completo
+- `docs/SEGURANCA.md` e `checklists/SEGURANCA.md` lidos
+- `npm audit` / `pnpm audit` disponível
+- Permissão apenas de **leitura e análise** (não execução de exploits)
+
+## Procedimento de Execução
+
+### Passo 1: Definir Escopo e Limites
+| Escopo | Inclui |
+|--------|--------|
+| **completa** | Auth, AuthZ, Validação, Secrets, Config, Deps, Infra, Logs |
+| **auth** | Login, registro, tokens, sessões, MFA, recuperação senha |
+| **api** | Rate limit, CORS, headers, validação, authZ por endpoint |
+| **infra** | Headers, TLS, CSP, HSTS, cookies, deploy, secrets management |
+| **deps** | `npm audit`, Snyk, licenças, supply chain |
+
+**Limites obrigatórios:**
+- **NÃO** executar exploits, fuzzing, SQL injection real
+- **NÃO** acessar dados de produção/reais
+- **NÃO** modificar código (apenas relatar)
+- **NÃO** expor segredos encontrados no relatório (referenciar apenas)
+
+### Passo 2: Autenticação e Autorização (Auth/AuthZ)
+**Verificar com evidências (código + config):**
+
+| Item | Verificação | Evidência Esperada |
+|------|-------------|-------------------|
+| Hash senhas | Argon2id (preferencial) ou bcrypt ≥12 rounds | `argon2` ou `bcrypt` import, parâmetros |
+| Senhas texto puro | **NENHUMA** | Grep por `password`/`senha` em logs/DB/code |
+| JWT | RS256 (assimétrico) preferencial, expiração ≤15min | `jsonwebtoken` config, `JWT_PRIVATE_KEY` |
+| Refresh token | Rotação a cada uso, hash no DB, expiração ≤7d | Schema DB, rota `/refresh` |
+| Cookies | HttpOnly, Secure, SameSite=lax/strict | `cookieOptions` no código |
+| Rate limit auth | 5 tent/15min por IP + conta | `express-rate-limit` config |
+| MFA/2FA | TOTP ou WebAuthn (opcional mas recomendado) | `otplib`/`@simplewebauthn` |
+| Tentativas login | Bloqueio progressivo, reset após janela | Contador + timestamp no Redis/memória |
+
+**AuthZ (Autorização) - CRÍTICO:**
+- [ ] Middleware `autorizar` em **TODAS** rotas protegidas
+- [ ] RBAC: roles/permissions granulares (não apenas "admin/user")
+- [ ] Verificação propriedade recurso (IDOR prevention): `userId === resource.ownerId`
+- [ ] Admin bypass auditado (logs de ações admin)
+- [ ] Matriz permissão × endpoint documentada
+
+### Passo 3: Validação e Sanitização de Entrada
+| Vetor | Verificação | Ferramenta/Evidência |
+|-------|-------------|---------------------|
+| SQL Injection | Apenas Prisma/parameterized queries | Grep: `$queryRaw`, `$executeRaw`, string concat |
+| XSS (Reflected/Stored) | Zod validation + DOMPurify output | Zod schemas + `isomorphic-dompurify` |
+| CSRF | SameSite cookies + double-submit token | `csurf` ou custom token |
+| SSRF | Allowlist domínios fetch externo | Config fetch, validação URL |
+| Path Traversal | Validação path, `path.resolve()` + prefix check | Upload/download handlers |
+| Prototype Pollution | `Object.freeze()` config, validação keys | `lodash.merge`/`defaultsDeep` usage |
+| XXE | Parser XML seguro (se aplica) | `libxmljs` config |
+| File Upload | MIME real (magic bytes) + allowlist + sanitização | `file-type`, `sharp`, antivirus |
+
+**Validação backend = barreira obrigatória:**
+- [ ] Zod schemas em **TODOS** endpoints (body, params, query)
+- [ ] Rejeição campos extras (`strict()` ou `passthrough()` controlado)
+- [ ] Unicidade verificada no service **antes** de persistir
+- [ ] Integridade referencial (FKs) verificada no service
+
+### Passo 4: Proteção da Aplicação
+| Camada | Verificação | Config Esperada |
+|--------|-------------|----------------|
+| Rate Limiting | Global API + endpoints sensíveis | `express-rate-limit`: 100req/min global, 5/15min auth |
+| CORS | Allowlist explícita (não `*`) | `origin: ['https://app.dominio.com']` |
+| Headers Segurança | Helmet.js configurado | CSP, HSTS, X-Frame-Options, Referrer-Policy |
+| TLS | Apenas HTTPS em produção | `sslmode=require`, certificado válido |
+| Error Handling | Sem stack trace em produção | `NODE_ENV=production` → generic 500 |
+| Logging | Estruturado, sem segredos | Pino/Winston + sanitização (senhas, tokens, PII) |
+
+### Passo 5: Gestão de Segredos e Configuração
+| Item | Verificação | Evidência |
+|------|-------------|-----------|
+| `.env` no `.gitignore` | Sim | `git check-ignore .env` |
+| `.env.example` no Git | Sim, valores fictícios | Arquivo existe, sem valores reais |
+| Validação startup | Zod schema + fail fast | `getEnv()` com `safeParse` |
+| Segredos no frontend | **NENHUM** em `VITE_*` | Build analysis: `grep -r "VITE_" dist/` |
+| Chaves JWT | Assimétricas (RS256) | `JWT_PRIVATE_KEY`, `JWT_PUBLIC_KEY` env |
+| Secrets em logs | Sanitização automática | Pino/Winston + `serializers` deny list |
+
+### Passo 6: Banco de Dados (PostgreSQL + Prisma)
+| Item | Verificação |
+|-------|-------------|
+| Usuário DB | Role dedicada (`app_user`), **NÃO** superuser |
+| Permissões | Grants mínimos: SELECT/INSERT/UPDATE/DELETE apenas tabelas app |
+| Soft delete | `deletedAt` em tabelas sensíveis |
+| Constraints | `@unique`, `@relation(onDelete: Cascade/SetNull)`, `@@index` |
+| Transações | `$transaction` para operações multi-tabela atômicas |
+| Migrations | Versionadas no Git, revisadas antes de deploy |
+| Backup | Automático diário + PITR ≥ 7 dias + teste restore mensal |
+| Criptografia | Em repouso (AES-256) + trânsito (TLS 1.3) |
+
+### Passo 7: Dependências e Supply Chain
+- [ ] `npm audit --audit-level=high` → **0 high/critical**
+- [ ] Dependabot/Renovate configurado (PRs automáticos)
+- [ ] `package-lock.json` / `pnpm-lock.yaml` commitado
+- [ ] Lockfile versionado, sem `*` ou `^` em deps críticas
+- [ ] Auditoria mensal: `npm outdated`, revisar CHANGELOGS
+- [ ] Pacotes suspeitos: verificar mantenedores, downloads, última atualização
+
+### Passo 8: Infraestrutura e Deploy
+| Item | Verificação |
+|-------|-------------|
+| Variáveis produção | Validadas, separadas de dev/staging |
+| Segredos em CI/CD | GitHub Secrets / Vercel Env / Doppler (não no código) |
+| Deploy | Preview automático + aprovação manual para prod |
+| Rollback | Documentado, testado, < 5 min |
+| Monitoramento | Alertas: 5xx spike, auth failures, rate limit hits, latency p95 |
+| Logs agregados | Structured JSON, retenção ≥ 1 ano (segurança) |
+
+### Passo 9: Matriz de Riscos (Obrigatória)
+Para cada achado, preencher:
+| ID | Risco | Severidade | Impacto | Evidência (arquivo:linha) | Mitigação | Status |
+|----|-------|------------|---------|---------------------------|-----------|--------|
+| SEC-001 | JWT secret fraco | Crítico | Total conta compromise | `config/jwt.ts:12` (HS256) | Migrar RS256 + rotação | ABERTO |
+
+**Severidade:** Crítico > Alto > Médio > Baixo > Informativo
+**Status:** ABERTO | MITIGADO | ACEITO (com justificativa) | FALSO POSITIVO
+
+### Passo 10: Relatório de Auditoria
+```
+# Auditoria de Segurança: [Projeto] - [Data]
+
+## Escopo
+- Tipo: [completa|auth|api|infra|deps]
+- Arquivos analisados: X
+- Linhas de código: Y
+- Ferramentas: npm audit, grep, inspeção manual, Context7
+
+## Sumário Executivo
+- Total achados: X (Crítico: Y, Alto: Z, Médio: W, Baixo: V)
+- Riscos críticos não mitigados: [lista]
+- Conformidade geral: [Aprovado | Condicional | Reprovado]
+
+## Achados por Categoria
+### Autenticação/Autorização (Crítico: Y, Alto: Z)
+| ID | Achado | Severidade | Arquivo:Linha | Mitigação |
+
+### Validação Entrada
+...
+
+### Segredos/Config
+...
+
+### Dependências
+- npm audit: X high, Y critical
+- Dependabot: [configurado|não]
+
+### Infra/Deploy
+...
+
+## Riscos Críticos Não Mitigados
+[Lista - bloqueiam deploy se houver]
+
+## Recomendações Priorizadas
+1. **Imediato (Críticos)**: ...
+2. **Esta Sprint (Altos)**: ...
+3. **Backlog (Médios/Baixos)**: ...
+
+## Checklist de Conformidade (Anexo)
+- [ ] checklists/SEGURANCA.md completo
+```
+
+### Passo 11: Entregar
+**Somente relatório.** Não modificar código, não executar exploits, não expor segredos.
+
+## Ferramentas Necessárias
+- `npm audit` / `pnpm audit` / `yarn audit`
+- `grep`/`rg` para busca padrões inseguros
+- `tools.context7` para docs de libs (ex: configuração segura Prisma, Express)
+- `checklists/SEGURANCA.md` como guia
+- `docs/SEGURANCA.md` como referência técnica
+
+---
+
+## EXECUCAO OBRIGATORIA COM SUB-AGENTES (Shift-Left)
+
+> **REGRA AGIM:** 5 areas independentes + ganho >75% = **SUB-AGENTES OBRIGATORIOS**
+
+### Procedimento Padrao (SEMPRE usar quando escopo = "completa")
+
+```javascript
+// Em vez de sequencial (20s+):
+// Lance 5 sub-agentes PARALELOS (um por area)
+
+const AREAS = [
+  "Auth/AuthZ - middleware, RBAC, IDOR, tokens, rate limit, MFA, cookies",
+  "Validacao - Zod schemas, sanitizacao, SQLi, XSS, CSRF, SSRF, path traversal, prototype pollution, upload",
+  "Secrets/Config - .env, VITE_*, JWT keys, startup validation Zod, .gitignore, TLS",
+  "Dependencias - npm audit, Snyk, licencas, supply chain, versoes desatualizadas",
+  "Infra - Headers (CSP/HSTS/X-Frame), TLS, rate limit global, CORS, logs sanitizados, error handling"
+];
+
+const results = await Promise.all(
+  AREAS.map(area => subagent({
+    agent: "general",
+    description: `Security audit ${area.split("-")[0]}`,
+    prompt: `[AGIM SUB-AGENT PROTOCOL]
+Before starting: Read AGENTS.md (project root) → memoria/ESTADO-ATUAL.md → memoria/PROXIMO-PASSO.md
+Follow AGIM protocol: Use memoria/ for continuity, checklists/ for validation, docs/ for standards.
+
+Audit security for: ${area}. Use checklists/SEGURANCA.md, docs/SEGURANCA.md.
+Return findings with file:line evidence, severity (CRITICAL/HIGH/MEDIUM/LOW), mitigation.
+Log results to memoria/HISTORICO-DE-EXECUCAO.md when done.`
+  }))
+);
+
+// Agregue resultados
+const aggregated = aggregateSecurityResults(results);
+
+// LOG OBRIGATORIO
+await logToHistory("auditoria-de-seguranca", {
+  subAgents: 5,
+  timeTotal: "~5s",
+  estimatedSequential: "~20s",
+  savings: "75%",
+  findings: aggregated
+});
+
+return aggregated;
+```
+
+### Checklist de Execucao (OBRIGATORIO)
+
+- [ ] 5 sub-agentes lancados em paralelo (escopo = completa)
+- [ ] Cada um com area especifica e prompt detalhado
+- [ ] Timeout 60s configurado por sub-agente
+- [ ] Resultados agregados com matriz de riscos consolidada
+- [ ] Log no `memoria/HISTORICO-DE-EXECUCAO.md` com tempo economia
+
+---
+
+## Limites de Responsabilidade
+- **NÃO** executa pentest/DAST real (ex: OWASP ZAP, Burp Suite)
+- **NÃO** acessa ambiente de produção ou dados reais
+- **NÃO** modifica código (skill `security-and-hardening` para implementar correções)
+- **NÃO** decide aceitação de risco (apresenta, usuário decide)
+- **SIM** identifica com evidência código:linha, classifica, recomenda mitigação
+
+## Critérios de Aceitação
+- [ ] Escopo definido e comunicado
+- [ ] Todas categorias no escopo auditadas com evidência código:linha
+- [ ] Matriz de riscos preenchida com severidade, evidência, mitigação
+- [ ] Relatório entregue sem segredos expostos
+- [ ] Código **não modificado**
+- [ ] Checklist `checklists/SEGURANCA.md` usado como guia
+
+## Tratamento de Falhas
+| Falha | Ação |
+|-------|------|
+| Código muito grande para auditoria completa | Amostragem baseada em risco (auth, API, upload, payments) |
+| Segredo encontrado em código | Reportar IMEDIATAMENTE ao usuário, não incluir no relatório escrito, sugerir rotação |
+| Dependência crítica vulnerável sem patch | Documentar como risco aceito temporariamente, mitigação compensatória (WAF, monitoramento) |
+| AuthZ ausente em endpoints | Classificar como Crítico, bloquear deploy até correção |
+| Falso positivo `npm audit` | Verificar contexto, documentar como FALSO POSITIVO com justificativa |
+
+## Formato de Entrega
+Relatório em `docs/AUDITORIA-SEGURANCA-[projeto]-[data].md` (sem segredos)
+
+## Referências
+- `checklists/SEGURANCA.md` - Checklist executável completo
+- `docs/SEGURANCA.md` - Referência técnica detalhada
+- `security-and-hardening` skill (implementação correções)
+- `code-review-and-quality` skill (revisão qualidade + segurança)

package/.opencode/skills/bible-rag-search/SKILL.md

@@ -0,0 +1,190 @@
+name: bible-rag-search
+description: Busca semântica no AGENT-BIBLE via ChromaDB local. Retorna apenas trechos relevantes (~2KB vs 50KB full docs). Reduz tokens 90%+. Indexa docs/, checklists/, templates/, skills/ na inicialização.
+
+---
+
+# Skill: bible-rag-search
+
+## Objetivo
+**Busca semântica eficiente no AGENT-BIBLE.** Em vez de carregar docs inteiros (27KB cada), retorna apenas os 3-5 trechos mais relevantes (~2KB total). Reduz contexto de 50-80K para 5-15K tokens por sessão.
+
+## Quando Ativar
+- **SEMPRE** que a IA precisar consultar o Bible para:
+  - "Como configurar X?"
+  - "Qual o padrão para Y?"
+  - "Exemplo de Z?"
+  - Qualquer dúvida técnica sobre padrões do Bible
+- Substitui leitura completa de `docs/*.md`, `checklists/*.md`, `templates/*.md`
+
+## Pré-condições
+- ChromaDB local em `~/.agent-bible/rag_index/`
+- Índice construído na primeira execução (auto)
+- `@xenova/transformers` para embeddings (local, sem API key)
+
+---
+
+## ARQUITETURA
+
+```
+~/.agent-bible/
+├── rag_index/                    # ChromaDB persistente
+│   ├── chroma.sqlite3
+│   └── <collection_bible>/
+├── bible_cache/                  # Cache de textos originais (opcional)
+│   └── <hash>.txt
+```
+
+**Fluxo:**
+1. **Indexação** (primeira vez / quando Bible atualiza):
+   - Varre `docs/`, `checklists/`, `templates/`, `.opencode/skills/*/SKILL.md`
+   - Chunk: 500 chars, overlap 50
+   - Embedding: `Xenova/all-MiniLM-L6-v2` (384 dim, ~80MB, CPU)
+   - Upsert no Chroma collection `agent-bible`
+2. **Busca** (cada query):
+   - Embedding da query
+   - `collection.query(query_embedding, n_results=5)`
+   - Retorna: trechos + metadados (arquivo, seção, score)
+
+---
+
+## API DA SKILL
+
+### `search(query, options?)`
+```javascript
+// Entrada
+{
+  query: "como configurar argon2id",
+  options: {
+    n_results: 5,           // default 5
+    min_score: 0.3,         // threshold relevância
+    sources: ["docs", "checklists", "templates", "skills"] // filter
+  }
+}
+
+// Saída
+{
+  results: [
+    {
+      text: "trecho relevante...",
+      metadata: {
+        file: "docs/SEGURANCA.md",
+        section: "Hash de senhas",
+        source: "docs",
+        score: 0.87
+      }
+    },
+    ...
+  ],
+  total_chunks_searched: 1247,
+  query_time_ms: 12
+}
+```
+
+### `rebuild_index()`
+Força reconstrução completa do índice.
+
+### `get_stats()`
+Retorna: total chunks, tamanho índice, última atualização.
+
+---
+
+## INTEGRAÇÃO NO BOOTSTRAP
+
+1. **Primeira execução**: detecta índice vazio → indexa Bible completo (~30s primeira vez)
+2. **Execuções subsequentes**: verifica `git status` do Bible → reindexa só mudanças (<5s)
+3. **Cache de embeddings**: modelo `Xenova/all-MiniLM-L6-v2` cacheado em `~/.cache/@xenova/transformers/`
+
+---
+
+## COMANDOS DISPONÍVEIS
+
+| Comando | Descrição |
+|---------|-----------|
+| `skill bible-rag-search "sua pergunta"` | Busca semântica |
+| `skill bible-rag-search --rebuild` | Reconstrói índice completo |
+| `skill bible-rag-search --stats` | Mostra estatísticas do índice |
+
+---
+
+## EXEMPLOS DE USO
+
+```bash
+# IA precisa saber como configurar rate limiting
+skill bible-rag-search "rate limiting configuração"
+
+# Retorna trechos de:
+# - docs/SEGURANCA.md (seção Rate Limiting)
+# - checklists/SEGURANCA.md (checklist rate limit)
+# - templates/PLANO-IMPLEMENTACAO.md (exemplo config)
+
+# IA precisa de template ADR
+skill bible-rag-search "template decisão técnica ADR"
+
+# Retorna:
+# - templates/DECISAO-TECNICA.md (template completo)
+# - docs/DECISOES-TECNICAS.md (exemplos)
+```
+
+---
+
+## MÉTRICAS DE ECONOMIA
+
+| Métrica | Sem RAG | Com RAG | Economia |
+|---------|---------|---------|----------|
+| Contexto "como configurar X" | 27KB (doc inteiro) | 2KB (trechos) | **93%** |
+| Contexto "nova feature" | 50KB (5 skills) | 5KB (trechos) | **90%** |
+| Tokens por sessão típica | 50-80K | 5-15K | **80-85%** |
+
+---
+
+## INTEGRAÇÃO COM OUTRAS SKILLS
+
+| Skill | Como usa bible-rag-search |
+|-------|---------------------------|
+| `entrevista-orquestradora` | Busca padrões para classificar pedido |
+| `planejamento-de-tarefas` | Busca templates/planos similares |
+| `analise-de-legado` | Busca padrões legacy conhecidos |
+| `auditoria-de-seguranca` | Busca checklists/riscos específicos |
+| `spec-driven-development` | Busca specs/ADRs similares |
+
+---
+
+## COMANDOS DE MANUTENÇÃO
+
+```bash
+# Reconstruir índice (após atualizar Bible)
+skill bible-rag-search --rebuild
+
+# Ver stats
+skill bible-rag-search --stats
+
+# Limpar cache (forçar rebuild)
+rm -rf ~/.agent-bible/rag_index && skill bible-rag-search "teste"
+```
+
+---
+
+## REFERÊNCIAS TÉCNICAS
+
+- **ChromaDB**: `chromadb` npm package (persistência local SQLite)
+- **Embeddings**: `@xenova/transformers` com `Xenova/all-MiniLM-L6-v2` (384 dim, CPU, ~80MB)
+- **Chunking**: 500 chars / 50 overlap (otimizado para docs técnicos)
+- **Coleção Chroma**: `agent-bible` (metadata: file, section, source, hash)
+
+---
+
+## TRATAMENTO DE FALHAS
+
+| Falha | Ação |
+|-------|------|
+| ChromaDB corrompido | `rm -rf ~/.agent-bible/rag_index && skill bible-rag-search --rebuild` |
+| Modelo embeddings não baixa | Verificar conexão / `~/.cache/@xenova/transformers/` |
+| Índice vazio | Auto-rebuild na primeira query |
+| Score muito baixo (<0.3) | Retornar "não encontrado" + sugerir termos alternativos |
+
+---
+
+## IMPLEMENTAÇÃO (Referência)
+
+Arquivo principal: `scripts/bible-rag-index.js` (indexação) + `scripts/bible-rag-search.js` (busca)
+Chamado via: `skill bible-rag-search <query>`