codetools / Plugin

codetools Claude Code plugin

The plugin packages codetools for Claude Code: skills that teach Claude the verbs, slash commands, the "non-negotiable gates" as hooks, and the Prolog rule files the gates consult. Its README describes it as "for a work computer whose only agent is Claude Code", so codetools "runs with no opencode, no qwen, and no system SWI-Prolog install". The source is plugins/codetools/ in the codetools repo, added in commit 84ec9bd7 on 2026-10-20.

The facts below were measured on 2026-10-23 from:

the installed copy ~/.claude/plugins/cache/codetools/codetools/0.1.0;
~/.claude/plugins/installed_plugins.json and known_marketplaces.json;
the enabledPlugins key of the settings files;
a diff -rq against the repo.

What is in it

Skills

Skill	Description (frontmatter)
`snapshot`	Byte-exact source snapshot and AST over a checkout. Run this before any change so verify can compute an affected set and blast radius. Produces the SymbolSnapshot and Prolog facts.
`blast-radius`	Knowledge graph and affected-set blast radius. Given changed files or symbols, compute exactly which tests and modules are affected for run-once selection.
`realize`	The design to code to verify generator. Turn an OpenSpec change into skeletons, generated tests, and implemented code placed into an existing package, then run the verify gates.
`verify`	Run the verification gates with run-once test selection over the blast radius. Cites RTM requirements only on green, leaves complete evidence, and refuses below the coverage floor.
`rtm`	Requirements traceability matrix. Mint REQ ids, tag scenarios, and produce the evidence a gate cites so every requirement traces to a BDD scenario and a test.
`deploy`	Release, promote and install codetools with versioned identity. Build the wheel, verify identity, promote a release, and roll back a tag.
`diagram`	Bidirectional code to diagram generation and round-trip verification using codetools code2diagram and mermaid.

Slash commands

Command	Runs
`/snapshot <path>`	`ct snapshot <path>`, then commit the snapshot JSON and Prolog facts
`/verify <baseline> <changed...>`	`ct verify <baseline> <changed...>`; refuse below the coverage floor, cite RTM only on green
`/realize <change> --into <checkout>`	`ct realize <change> --into <checkout>`, then `/verify`
`/diagram class <ClassName>`, `/diagram full`, `/diagram roundtrip <file.mmd>`	`ct diagram --class <ClassName>`, `ct diagram --full`
`/coverage`	`ct coverage`; report against "the 97.80 percent floor"; "Never re-seed the baseline to pass"

The README also lists /rtm. No rtm.md command file exists.

Hooks (`hooks/hooks.json`)

Event	Matcher	Command	What it does (docstring or comment)
SessionStart	-	`bash ${CLAUDE_PLUGIN_ROOT}/runtime/swipl/ensure-swipl.sh` (timeout 15 s)	puts a vendored `swipl` on `PATH` if there is one; fails with "no SWI-Prolog found" if no `swipl` resolves
PreToolUse	`Write\|Edit\|MultiEdit`	`python3 .../hooks/block_except_pass.py`	"Block error-swallowing exception patterns in changed Python code."
PreToolUse	`Write\|Edit\|MultiEdit`	`python3 .../hooks/error_gate.py`	"Error gate hook: refuse Python files that do not parse or declare bad structure."
Stop	-	`python3 .../hooks/coverage_gate.py`	"Coverage gate hook: refuse when measured line coverage is below the floor."
Stop	-	`bash .../hooks/decision_adr_trigger.sh`	when the turn's input mentions decision, ADR, ruling, ratify or one-way-door, it returns `{"decision":"allow"}` with the reminder "Every decision is an ADR: mint it Proposed or flip it Accepted in docs/adr and commit it this turn."

The hooks run python3 from PATH. In a Claude shell on 2026-10-23, python3 resolves to ~/.venv/bin/python3 (3.14.7, GIL off). The PATH the hooks themselves get was not measured.

The wrapper and the Prolog runtime

bin/ct prepends runtime/swipl/bin to PATH when it holds an executable swipl, then runs exec codetools "$@".
runtime/prolog/ holds 14 rule files: answer.pl, blast.pl, collect.pl, facts.pl, gates.pl, rtm.pl, rtm_text.pl, select.pl, select_escalate.pl, select_forced.pl, select_nochange.pl, select_paths.pl, select_reasons.pl and select_unnamed.pl.
runtime/swipl/bin/ is empty. No SWI-Prolog is bundled. On this host, swipl resolves to ~/.guix-profile/bin/swipl. The repo's newer runtime/swipl/README.md says the system swipl is now "the primary runtime - no bundling required". The installed copy still says "Bundled SWI-Prolog (PROLOG INCLUDED)". That README is the only file where the cache differs from the repo.

How it is installed on this host

Item	Measured
Plugin id	`codetools@codetools`, version `0.1.0`
Marketplace	`codetools`, source `{"source": "directory", "path": "/home/mohamed/workspace/orchestrata.codetools"}`
Scope	`local`, `projectPath: /home/mohamed/workspace`
Installed	`2026-10-20T12:32:46Z`
Recorded commit	`gitCommitSha 00b1304c35d4`
Enabled in	`~/workspace/.claude/settings.local.json` (`enabledPlugins: {"codetools@codetools": true}`); not in `~/.claude/settings.json`, which enables `orchestrata@orchestrata` and two tmux plugins

The recorded commit 00b1304c (2026-10-20 06:24) has no plugins/ directory. The plugin was committed later that morning, in 84ec9bd7 at 08:50 EDT, about 18 minutes after the install at 08:32 EDT. A directory marketplace reads the working tree, so the install copied files that were not yet committed and recorded the HEAD of that moment. That is a deploy from a live checkout, which the platform conventions forbid (no deploy-in-place). The orchestrata plugin, by contrast, installs from its GitLab remote at a pushed commit (Deployment).

Gaps (2026-10-23)

Gap	Evidence	Options
The skills and commands call verbs the CLI does not have	`ct snapshot`, `ct verify`, `ct diagram`, `ct rtm`, `ct coverage` and `ct blast` are not verbs; the CLI has `ast snapshot`, `graph blast`, `render` and no verify, rtm or coverage verb (verbs)	(a) rewrite the skills and commands to the real verbs and drop `/coverage` and `/verify`, or route them to `deploy install` or `gate run`; (b) add the missing verbs to the CLI. Recommendation: (a) now, because the verbs already exist; (b) only where an activity truly lacks a verb (ADR-0020 rule 3)
`bin/ct` cannot find `codetools`	`command -v codetools` returns nothing in a Claude shell; codetools lives at `/opt/codetools/bin/codetools`, which is not on `PATH`	(a) `bin/ct` execs `/opt/codetools/bin/codetools` (or `$CODETOOLS_BIN`) with `env -u PYTHONPATH`; (b) put `/opt/codetools/bin` on `PATH`. Recommendation: (a), because it is explicit and does not leak dependency scripts onto `PATH`
Installed from a working tree	`directory` marketplace; recorded sha `00b1304c` predates the plugin	give the repo a remote and switch the marketplace to a git source (Option A on codetools deploy); then `claude plugin uninstall` + `install` to re-pin, because `claude plugin update` compares version strings only
No bundled Prolog	`runtime/swipl/bin/` is empty while the installed README says "PROLOG INCLUDED"	reinstall from the current repo, whose README matches reality; vendor a relocatable `swipl` only for a machine without one
`/rtm` is advertised but missing	README lists `/rtm`; no `commands/rtm.md`	add it with the real verb, or remove it from the README