convez.ai
SkillAutomaçãoAvançado
JunbaoLiang

Auditoria Código ↔ Plano

JunbaoLiang/audit-with-plans

Auditoria bidirecional código ↔ plano com execução e contexto fresco

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill que audita automaticamente a consistência entre código e arquivos de planejamento (.planning), executando loops de auditoria-correção com subagentes de contexto fresco até convergência. Detecta discrepâncias reais (não por diff textual) comparando saída executada vs. documentação.

Instalação

$npx convez-ai JunbaoLiang/audit-with-plans

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á 3 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Validar conformidade entre código atual e documentação de planejamento
  • Detectar desvios (diretórios movidos, números desatualizados, outputs faltantes)
  • Convergir projeto a estado onde código e notas são 100% consistentes

Veredito

Ferramenta especializada e bem-pensada para manter sincronismo código-documentação via execução real, não diff. Requer projeto com planning-with-files prévio; o loop fresco-contexto é sua força, mas add overhead iterativo considerável.

README

A tradução para o português deste README ainda está na fila.

audit-with-plans

A Claude Code skill that checks whether your code and your planning-with-files notes actually agree — and fixes whichever side is wrong.

audit-with-plans is a companion to planning-with-files. It runs an automated audit–fix loop that drives a project to a state where the code and its planning files (task_plan.md, findings.md, progress.md) are fully consistent — verified by execution, not by guesswork.

The problem it solves

On any long project, the code and the notes describing it drift apart:

  • progress.md says "Phase 3 complete" but the output it claims was never produced.
  • A refactor moved a directory; a script still assembles the old path and silently breaks.
  • A number in findings.md no longer matches what the current code outputs.
  • A validator reports "OK" on a run that actually failed.

Plain text-diff audits miss these, because they read code instead of running it, and check only one direction (does the code match the docs?) instead of both. audit-with-plans catches them by executing every documented entry point and auditing in both directions.

How it works

audit  ->  fix  ->  audit (fresh, no memory of the last pass)  ->  fix  ->  ...  ->  0 findings  ->  exit

Each pass spawns an independent, fresh-context subagent that:

  1. Reads the planning files as the source of truth.
  2. Runs every documented entry point and compares real output to what the docs claim.
  3. Reports discrepancies as CRITICAL / HIGH / MEDIUM / LOW.

You fix whichever side is wrong — stale code or stale notes — and the loop re-audits from a clean slate. It exits only when a fresh audit returns 0/0/0/0. "I think I fixed it" never counts.

Why fresh context is the whole point: if you hand the auditor a list of what you just fixed, it stops auditing and starts verifying — it confirms your fixes landed and misses the bugs you introduced or never saw. Every pass starts cold.

Requirements

  • Claude Code
  • A project using planning-with-files — i.e. a .planning/<plan-id>/{task_plan,findings,progress}.md baseline to audit against. No plan yet? Start one with that skill first; the audit needs a baseline.

Installation

Plugin marketplace (recommended)

/plugin marketplace add JunbaoLiang/audit-with-plans
/plugin install audit-with-plans@audit-with-plans

Or via npx

npx skills add JunbaoLiang/audit-with-plans

Start a new Claude Code session and the skill loads automatically.

Usage

In a project that uses planning-with-files:

/audit-with-plans

Or just ask, while a plan exists:

audit this project / is this project consistent?

The skill resolves the active plan, spawns audit passes, and keeps fixing and re-auditing until a fresh pass is clean. It reports what converged and names anything left open by design.

Make it your own

This skill isn't meant to be frozen. The more projects you run it on, the more failure modes you'll find that are specific to your work — and the skill gets better when you fold those back in. The SKILL.md here is itself the product of ~12 audit passes on a real project that kept claiming it was done and wasn't; every anti-pattern in it maps to a real mistake that got corrected.

Here is the loop I use to evolve it — a cross-model adversarial audit:

  1. Run the audit in Claude Code until it converges to 0/0/0/0.

  2. Hand the same project to a second model (I use Codex) and ask it to audit again, cold. A different model is the strongest possible fresh lens — it does not share Claude's blind spots, so it catches what a same-model loop converges right past.

  3. If the second model finds anything, bring those findings back to Claude Code and fix them.

  4. Then synthesize the lesson back into the skill. I paste this prompt:

    Let's summarize: What steps did we take to accomplish the audit task? Why did you make mistakes earlier? How did I point out those errors? How did you respond? What should have been done? And why is that the correct approach? Now, let's synthesize these insights into our skill audit-with-plans, and make it better.

This turns every real audit into a new anti-pattern row or hook in SKILL.md. Over time the skill becomes yours — tuned to the bugs your projects actually produce.

This works because it is heterogeneous. A single prompt template run repeatedly converges to a fixed point that still contains whatever the template never looks at (SKILL.md calls this the "homogeneous-prompt fixed point"). Switching models — or varying the audit lens each pass — is how you break out of it.

To make your own variant: fork this repo, edit SKILL.md and templates/audit_subagent_prompt.md, and bump the version in the frontmatter. PRs with new anti-patterns are welcome.

What's in here

  • SKILL.md — the full skill: the loop, the subagent prompt structure, section-level audit hooks, and a long table of anti-patterns.
  • templates/audit_subagent_prompt.md — the parameterized prompt used for each audit pass.
  • README.md — this file.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados