audit-tools
One npm package shipping two independent code tools over a shared library. Each has its own CLI and host slash-command, and each is useful on its own:
- audit-code (/audit-code) — audits a repository/project and produces a findings report.
- remediate-code (/remediate-code) — implements changes from findings and/or free-form intent.
They compose but don't depend on each other: audit-code's findings are clean input to remediate-code, but you can run either alone. Audit a repo and stop. Or point remediate-code at a plain-English request with no audit in sight - or hand it audit findings and extra suggestions at the same time.
Each tool writes its results to .audit-tools/ as a machine contract (JSON) plus a human-readable render (markdown):
| Tool | Machine contract | Human render | |---|---|---| | audit-code | audit-findings.json | audit-report.md | | remediate-code | remediation-outcomes.json | remediation-report.md |
Philosophy
- The tool must be trustworthy even when the host agent is weak. Correctness is guaranteed by the tool,
never by the host being careful or clever.
- Use mechanical, deterministic tools wherever one does the job as well as or better than a model.
- Use LLM judgment where it clearly lifts quality — bounded, scoped and recorded. The project is not
"100% deterministic", and it is not trying to be.
- Whatever can be enforced in tooling must be, regardless of who does the work.
- Don't grade your own homework: anything important or complex gets an independent adversarial check
that is allowed to refuse.
- Keep tasks tightly bound and well defined, so the gap between weak and strong models shrinks.
- Batch work into logical units of reasonable size — rigor balanced against token cost, not 100 agents
for 100 files.
- Keep everything IDE-, provider-, model-, OS-, shell- and language-agnostic: discovered at runtime or
abstracted behind a contract, never baked in. Detecting a repo's structure and pulling in useful tools for it is how that is honored — their output is normalized into shared contracts, never forked per ecosystem.
- Auditing and remediating are not two tools — they are two cases of ONE logical core, drawn read-only or