convez.ai
SkillAutomaçãoIntermediário
brunnocarpena

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 GitHub
InicialPluginScore · de 0 a 100

Skill 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-skill

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

PlatformAdapterStatus
Claude Code (CLI / IDE / web)root SKILL.md✅ Primary
Cursoradapters/cursor/✅ Supported
GitHub Copilotadapters/copilot/✅ Supported
Gemini CLI / Antigravityadapters/gemini/✅ Supported
OpenAI Codex CLIadapters/codex/✅ Supported
Aideradapters/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.devadapters/continue/✅ Supported
Zed Editoradapters/zed/✅ Supported
JetBrains Junieadapters/jetbrains-junie/✅ Supported
Sourcegraph Codyadapters/cody/✅ Supported
ChatGPT Custom GPTadapters/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

  1. Identifies files changed in the session
  2. Extracts verifiable claims from agent output
  3. Searches for evidence in source-of-truth hierarchy
  4. Classifies each claim: congruent / incongruent / partial / unverifiable
  5. Generates structured report
  6. Issues pre-deploy decision

Full workflow: SKILL.md.

Difference vs. other skills

SkillWhat it checks
congruenceSemantic truth: do claims match code?
verification-before-completionCode works: tests pass, build succeeds
requesting-code-reviewTechnical quality: bugs, patterns, maintainability
systematic-debuggingRoot 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:

  1. Read SKILL.md to understand the workflow
  2. If adding a new type of check, consider whether it fits in references/ or deserves its own file in checks/
  3. Examples must be generic (not specific to stack X or framework Y)
  4. Translations: keep all language versions in sync (PT-BR and EN are reference)

License

MIT — see LICENSE.

Inspiration

Patterns and structure inspired by:

Ver o original no GitHub

Bom para

Relacionados