Install the skill above, then run this in your AI tool:
/plankton-code-quality <your description>
About
Integration reference for Plankton (credit: @alxfazio), a write-time code quality enforcement system for Claude Code. Plankton runs formatters and linters on every file edit via PostToolUse hooks, then spawns Claude subprocesses to fix violations the agent didn't catch.
Source
What gets added to your project
Preview every file this package writes on install before you run the command above.
Summary
Write-time code quality enforcement using Plankton — auto-formatting, linting, and Claude-powered fixes on every file edit via hooks. Use when setting up write-time formatting, linting, or auto-fix hooks on file edits.
Skill instructions
Plankton Code Quality Skill
Integration reference for Plankton (credit: @alxfazio), a write-time code quality enforcement system for Claude Code. Plankton runs formatters and linters on every file edit via PostToolUse hooks, then spawns Claude subprocesses to fix violations the agent didn't catch.
When to Use
You want automatic formatting and linting on every file edit (not just at commit time)
You need defense against agents modifying linter configs to pass instead of fixing code
You want tiered model routing for fixes (Haiku for simple style, Sonnet for logic, Opus for types)
You work with multiple languages (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile)
How It Works
Three-Phase Architecture
Every time Claude Code edits or writes a file, Plankton's multi_linter.sh PostToolUse hook runs:
code
Phase 1: Auto-Format (Silent)
├─ Runs formatters (ruff format, biome, shfmt, taplo, markdownlint)
├─ Fixes 40-50% of issues silently
└─ No output to main agent
Phase 2: Collect Violations (JSON)
├─ Runs linters and collects unfixable violations
├─ Returns structured JSON: {line, column, code, message, linter}
└─ Still no output to main agent
Phase 3: Delegate + Verify
├─ Spawns claude -p subprocess with violations JSON
├─ Routes to model tier based on violation complexity:
│ ├─ Haiku: formatting, imports, style (E/W/F codes) — 120s timeout
│ ├─ Sonnet: complexity, refactoring (C901, PLR codes, oxlint complexity) — 300s timeout
│ └─ Opus: type system, deep reasoning (unresolved-attribute) — 600s timeout
├─ Re-runs Phase 1+2 to verify fixes
└─ Exit 0 if clean, Exit 2 if violations remain (reported to main agent)
What the Main Agent Sees
Scenario
Agent sees
Hook exit
No violations
Nothing
0
All fixed by subprocess
Nothing
0
Violations remain after subprocess
[hook] N violation(s) remain
2
Advisory (duplicates, old tooling)
[hook:advisory] ...
0
The main agent only sees issues the subprocess couldn't fix. Most quality problems are resolved transparently.
Config Protection (Defense Against Rule-Gaming)
LLMs will modify .ruff.toml or biome.json to disable rules rather than fix code. Plankton blocks this with three layers:
PreToolUse hook — protect_linter_configs.sh blocks edits to all linter configs before they happen
Stop hook — stop_config_guardian.sh detects config changes via git diff at session end
Protected files list — .ruff.toml, biome.json, .shellcheckrc, .yamllint, .hadolint.yaml, and more
Package Manager Enforcement
A PreToolUse hook on Bash blocks legacy package managers:
No install command, no plugin config. The hooks in .claude/settings.json are picked up automatically when you run Claude Code in the Plankton directory.
Closes the JS/TS gap in the model-routing table above. Python complexity (ruff C901,
PLR) already routes to Sonnet. JS/TS had no equivalent rule turned on by default.
Turn on oxlint's complexity rule when using it
oxlint's complexity rule (source: eslint's complexity rule, ported) lives in the
"restriction" category, which oxlint does not enable by default. It must be turned on
by hand. Verified against Oxlint's complexity rule
(2026-08-27): default option is max: 20. The rule is available in oxlint >= 1.37.0.
The skill's Language-Specific Dependencies table keeps oxlint optional for TypeScript/JS
generally. When adopting the complexity rule, use oxlint >= 1.37.0 and treat it as a
required dependency. Add the rule to the supported oxlint configuration the project already
uses (.oxlintrc.json, .oxlintrc.jsonc, oxlint.config.ts, or oxlint.config.mts). If
none exists, create one; do not create a second configuration file in the same directory.
Measure the codebase's current worst complexity score before choosing the initial enforced
ceiling. The template below is intentionally incomplete: replace <MEASURED_CEILING> with
that score, optionally plus a small amount of headroom, before committing the "error" gate.
Oxlint's default of 20 is a long-term target, not a safe universal starting ceiling.
Replace the placeholder before running oxlint; it is not a valid numeric threshold until the
repository has been measured. See the ratchet section below for how the ceiling gets set on
a real codebase.
Model-routing row
Add oxlint complexity violations to the same row as the existing Python entry in the
Phase 3 subprocess table:
Same tier as Python's C901/PLR. A complexity violation is a refactoring job either way,
language does not change the model tier.
The ratchet-ceiling technique
Source: Hunk PR #861 (merged 2026-08-26, verified against
the PR's own diff and description via the GitHub API, not paraphrased from memory). Hunk
turned on oxlint's complexity rule with "error", { "max": 80 } in .oxlintrc.json.
Their own worst score at the time was 78 (App), next was 76
(validateFileViewLayout). From the PR body: "This is intentionally an initial
regression ceiling rather than the long-term target... so 80 adds enforcement without
grandfathering or suppressions. The ceiling can be ratcheted downward as existing
hotspots are simplified." And: "A global ceiling does not prevent a function below 80
from growing toward it."
The technique, as actually run in that PR:
Measure the current worst complexity score in the codebase (oxlint reports it when
the rule fires).
Set the ENFORCED ceiling to a value at least as high as that worst score, not to
oxlint's own default of 20. Add a small amount of headroom if needed so the initial
enable does not fail CI on a score you have not fixed yet (hunk used 80 against a
worst of 78).
Commit that as "error", wired into the existing lint CI step. This is a real gate
from the first commit, not a suggestion.
Never grandfather. The ceiling is global. A function sitting at 40 today is not
exempt, it still cannot cross the ceiling later. That is the whole point: catch
growth, not just today's worst offenders.
Never blanket-suppress. No per-file or per-function disable comments to make a
violation go away. Fix it or leave it under the ceiling.
Each time a flagged hotspot is refactored below the ceiling, re-measure the global
maximum across the whole codebase. Lower the ceiling by hand only to a value that
remains at least as high as every remaining function's score (plus any deliberate
headroom). This is a manual step done as its own commit, not automated. It is how the
ceiling moves toward the linter's real default of 20 over time instead of sitting at
the codebase's worst score forever.
One caveat, stated plainly: the PR itself went straight from "rule off" to "error"
enforcement in one commit. It did not stage through a report-only or warn-only phase
first. Starting with the rule set to "warn" for one CI run before flipping it to
"error" is a reasonable staging step if a team has never measured its own worst score
and does not want a surprise CI failure, but that staging step is Gabe's own prudent
practice, not something verified in hunk's PR. Say so if you use it, do not attribute it
to the source.
Add this badge to a GitHub README so readers can open the package page and install the same version.
[](https://www.aipm-registry.com/skills/affaan-m/plankton-code-quality/1.0.0?utm_source=github&utm_medium=readme&utm_campaign=package_badge)
This imported publisher has not claimed its AIPM account. A connected account confirms account control, but it does not guarantee that a package is safe.
AI assistant context
What this skill is for
@affaan-m/plankton-code-quality@1.0.0 is an AIPM skill package for All tools. Use it when a project needs the reusable AI behavior described as: Write-time code quality enforcement using Plankton — auto-formatting, linting, and Claude-powered fixes on every file edit via hooks. Use when setting up write-time formatting, linting, or auto-fix hooks on file edits.
Preview a UI component mockup in a local browser canvas where the human directly edits it (move, resize, edit text, delete, restyle), switches mobile/desktop/custom viewports, tests it, chats with you, and clicks Save and Finish. You the...
Run aipm add @affaan-m/plankton-code-quality@1.0.0 in a project that has AIPM initialized.
Supported tools
@affaan-m/plankton-code-quality@1.0.0 supports All tools.
Before installing
AIPM skills can add files to your project. Review the package name, target, description, license, and publisher before installing. Use a clean branch when trying a new skill.