Congruence — Auditoria Semântica para Agentes IA
brunnocarpena/congruence-skill
Verifica congruência semântica entre claims e código real em projetos IA
Ver no GitHubSkill que verifica se o que um agente IA diz, documenta ou escreve realmente corresponde ao que o código faz. Detecta incongruências semânticas como READMEs desalinhados com a implementação, documentação inconsistente, claims falsos sobre integrações ou features, e inconsistências entre configurações e requisitos reais.
Instalação
npx convez-ai brunnocarpena/congruence-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Auditar documentação versus implementação real em projetos de agentes IA
- Detectar hallucinations e claims falsos em READMEs e FAQs gerados por IA
- Validar consistência entre configurações declaradas e requisitos reais (versões, dependências, preços)
Veredito

Ferramenta especializada e bem pensada que resolve um problema real em workflows com agentes IA: a lacuna entre o que é afirmado e o que é realmente implementado. Implementação multi-plataforma robusta, mas requer integração deliberada em cada projeto.
README
A tradução para o português deste README ainda está na fila.
Congruence — Semantic Truth Audit for AI Coding Agents
Semantic congruence auditing for AI coding agents. Verifies that what an AI agent says, writes, or documents actually matches what the project does. Not technical code review — checks whether claims about the code are true.
What it is
AI coding agents hallucinate. They generate code that looks correct but describes things that don't exist, write README files unaligned with the actual code, or invent integrations. This skill audits that class of error — semantic incongruence.
Core principle: No claim about the project is true without evidence in the project itself.
What it catches
Any divergence between what the agent (or the project's docs, UI, copy, configs) claims and what the code actually does — across any domain, stack, or language. Wherever a statement can be verified against source, congruence checks it.
A few illustrative examples (non-exhaustive): an FAQ describing a 3-step flow that's actually 5; a README documenting price $49 while Stripe charges $79; a landing announcing a "Stripe integration" that is only a // TODO; setup asking for Node 18 when the project requires Node 20; "123 active leads" counting deleted ones; a CTA "Get free spot" leading to a $497 checkout; a function renamed in 1 file with 47 callsites broken; a doc claiming a feature exists when only a mock returns success.
All of this passes any technical code review because the code compiles and runs. congruence is the barrier against this class of bug.
Supported AI platforms
| Platform | Adapter | Status |
|---|---|---|
| Claude Code (CLI / IDE / web) | root SKILL.md | ✅ Primary |
| Cursor | adapters/cursor/ | ✅ Supported |
| GitHub Copilot | adapters/copilot/ | ✅ Supported |
| Gemini CLI / Antigravity | adapters/gemini/ | ✅ Supported |
| OpenAI Codex CLI | adapters/codex/ | ✅ Supported |
| Aider | adapters/aider/ | ✅ Supported |
| Qwen Code CLI (Alibaba) | adapters/qwen/ | ✅ Supported |
| Kimi K2 (Moonshot AI) | adapters/kimi/ | ✅ Supported |
| Windsurf (Codeium) | adapters/windsurf/ | ✅ Supported |
| Cline (VS Code) | adapters/cline/ | ✅ Supported |
| Continue.dev | adapters/continue/ | ✅ Supported |
| Zed Editor | adapters/zed/ | ✅ Supported |
| JetBrains Junie | adapters/jetbrains-junie/ | ✅ Supported |
| Sourcegraph Cody | adapters/cody/ | ✅ Supported |
| ChatGPT Custom GPT | adapters/chatgpt-custom-gpt/ | ✅ Supported |
| Generic LLM (ChatGPT.com, Claude.ai, any chat) | adapters/generic-prompt/ | ✅ Supported |
Each adapter has its own INSTALL.md with platform-specific steps. |
Quick install (Claude Code)
# Project-local (recommended)
cd your-project/
mkdir -p .claude/skills
git clone https://github.com/brunnocarpena/congruence-skill.git .claude/skills/congruence
# Or global (all projects)
mkdir -p ~/.claude/skills
git clone https://github.com/brunnocarpena/congruence-skill.git ~/.claude/skills/congruence
Invoke in a session: /congruence or "audit congruence of this session's work".
For other platforms, see the relevant adapters/<platform>/INSTALL.md.
How it works
- Identifies files changed in the session
- Extracts verifiable claims from agent output
- Searches for evidence in source-of-truth hierarchy
- Classifies each claim:
congruent/incongruent/partial/unverifiable - Generates structured report
- Issues pre-deploy decision
Full workflow: SKILL.md.
Difference vs. other skills
| Skill | What it checks |
|---|---|
congruence | Semantic truth: do claims match code? |
verification-before-completion | Code works: tests pass, build succeeds |
requesting-code-review | Technical quality: bugs, patterns, maintainability |
systematic-debugging | Root cause of reproducible bugs |
Skills are complementary. congruence occupies the niche of drift between what is said and what code does — gap not covered by the others.
Repository structure
congruence-skill/
├── SKILL.md # Workflow + Iron Law + tables (EN primary)
├── SKILL.pt-BR.md # Portuguese (Brazil)
├── SKILL.es.md # Spanish
├── SKILL.fr.md # French
├── SKILL.de.md # German
├── SKILL.zh.md # Chinese
├── README.md / .pt-BR / .es / .fr / .de / .zh
├── auditor-prompt.md # Template for subagent dispatch (+ translations)
├── checks/ # Progressive disclosure by domain
│ ├── docs.md # README, CHANGELOG, /docs
│ ├── ui-copy.md # labels, buttons, headlines
│ ├── data-numbers.md # prices, dates, counts
│ ├── integrations.md # Stripe, OAuth, webhooks
│ └── features-flows.md # announced features and flows
├── references/ # Deep guides
├── examples/ # Case studies
├── hooks/ # OPTIONAL: Claude Code auto-suggestion
├── adapters/ # Other AI platforms
│ ├── cursor/
│ ├── github-copilot/
│ ├── gemini/
│ ├── openai-codex/
│ ├── aider/
│ └── generic-prompt/
└── scripts/
Contributing
Issues and PRs welcome. Before opening a PR:
- Read
SKILL.mdto understand the workflow - If adding a new type of check, consider whether it fits in
references/or deserves its own file inchecks/ - Examples must be generic (not specific to stack X or framework Y)
- Translations: keep all language versions in sync (PT-BR and EN are reference)
License
MIT — see LICENSE.
Inspiration
Patterns and structure inspired by:
- obra/superpowers — especially
verification-before-completionandwriting-skills - anthropics/skills —
skill-creatorand official best practices - Anthropic Agent Skills docs