Plankton Code Quality Skill

¿Qué hace Plankton Code Quality Skill?

Referencia de integración para Plankton (crédito: @alxfazio), un sistema de control de calidad de código en tiempo de escritura para Claude Code. Plankton ejecuta formateadores y linters en cada edición de archivo mediante hooks PostToolUse, y luego lanza subprocesos de Claude para corregir violaciones que el agente no detectó.

Cuándo usarlo

• Quieres formato y linting automáticos en cada edición de archivo (no solo al hacer commit)
• Necesitas defensa contra agentes que modifican configuraciones de linters para que el código pase en lugar de corregirlo
• Quieres enrutamiento por niveles de modelo para correcciones (Haiku para estilo simple, Sonnet para lógica, Opus para tipos)
• Trabajas con múltiples lenguajes (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile)

Cómo funciona

Arquitectura de tres fases

Cada vez que Claude Code edita o escribe un archivo, el hook multi_linter.sh de Plankton se ejecuta tras el uso de la herramienta:

Fase 1: Autoformato (silencioso)
├─ Ejecuta formateadores (ruff format, biome, shfmt, taplo, markdownlint)
├─ Corrige entre 40 y 50 % de los problemas silenciosamente
└─ Sin salida hacia el agente principal

Fase 2: Recolectar violaciones (JSON)
├─ Ejecuta linters y recolecta violaciones no corregibles
├─ Devuelve JSON estructurado: {line, column, code, message, linter}
└─ Aún sin salida al agente principal

Fase 3: Delegar + verificar
├─ Lanza un subproceso de claude -p con el JSON de violaciones
├─ Enruta al nivel de modelo según la complejidad de la violación:
│   ├─ Haiku: formato, imports, estilo (códigos E/W/F) — tiempo límite 120 s
│   ├─ Sonnet: complejidad, refactorización (C901, códigos PLR) — tiempo límite 300 s
│   └─ Opus: sistema de tipos, razonamiento profundo (unresolved-attribute) — tiempo límite 600 s
├─ Vuelve a ejecutar las fases 1+2 para verificar las correcciones
└─ Salida 0 si está limpio, salida 2 si quedan violaciones (se informa al agente principal)

Lo que ve el agente principal

Escenario	El agente ve	Salida del hook
Sin violaciones	Nada	0
Todo corregido por subproceso	Nada	0
Quedan violaciones tras subproceso	[hook] N violation(s) remain	2
Aviso (duplicados, herramientas antiguas)	[hook:advisory] ...	0

El agente principal solo ve problemas que el subproceso no pudo corregir. La mayoría de los problemas de calidad se resuelven de forma transparente.

Protección de configuración (defensa contra manipulación de reglas)

Los LLMs modificarán .ruff.toml o biome.json para desactivar reglas en lugar de corregir el código. Plankton lo bloquea con tres capas:

1. Hook PreToolUse — protect_linter_configs.sh bloquea las ediciones a todos los archivos de configuración de linters antes de que ocurran
2. Hook Stop — stop_config_guardian.sh detecta cambios en la configuración mediante git diff al finalizar la sesión
3. Lista de archivos protegidos — .ruff.toml, biome.json, .shellcheckrc, .yamllint, .hadolint.yaml y más

Imposición del gestor de paquetes

Un hook PreToolUse sobre Bash bloquea gestores de paquetes heredados:

• pip, pip3, poetry, pipenv → Bloqueados (usa uv)
• npm, yarn, pnpm → Bloqueados (usa bun)
• Excepciones permitidas: npm audit, npm view, npm publish

Configuración

Inicio rápido

Nota: Plankton requiere instalación manual desde su repositorio. Revisa el código antes de instalar.

# Instalar dependencias principales
brew install jaq ruff uv

# Instalar linters de Python
uv sync --all-extras

# Iniciar Claude Code: los hooks se activan automáticamente
claude

Sin comando de instalación, sin configuración de plugin. Los hooks en .claude/settings.json se recogen automáticamente cuando ejecutas Claude Code en el directorio de Plankton.

Integración por proyecto

Para usar los hooks de Plankton en tu propio proyecto:

1. Copia el directorio .claude/hooks/ a tu proyecto
2. Copia la configuración de hooks de .claude/settings.json
3. Copia los archivos de configuración de linters (.ruff.toml, biome.json, etc.)
4. Instala los linters para tus lenguajes

Dependencias por lenguaje

Lenguaje	Requerido	Opcional
Python	ruff, uv	ty (tipos), vulture (código muerto), bandit (seguridad)
TypeScript/JS	biome	oxlint, semgrep, knip (exportaciones muertas)
Shell	shellcheck, shfmt	—
YAML	yamllint	—
Markdown	markdownlint-cli2	—
Dockerfile	hadolint (>= 2.12.0)	—
TOML	taplo	—
JSON	jaq	—

Combinación con ECC

Complementarios, no superpuestos

Aspecto	ECC	Plankton
Control de calidad de código	Hooks PostToolUse (Prettier, tsc)	Hooks PostToolUse (20+ linters + correcciones con subprocesos)
Escaneo de seguridad	AgentShield, agente security-reviewer	Bandit (Python), Semgrep (TypeScript)
Protección de configuración	—	Bloqueos PreToolUse + detección con hook Stop
Gestor de paquetes	Detección + configuración	Imposición (bloquea gestores heredados)
Integración CI	—	Hooks de pre-commit para git
Enrutamiento de modelos	Manual (/model opus)	Automático (complejidad de violación → nivel)

Combinación recomendada

1. Instala ECC como tu plugin (agentes, habilidades, comandos, reglas)
2. Añade los hooks de Plankton para control de calidad en tiempo de escritura
3. Usa AgentShield para auditorías de seguridad
4. Usa el bucle de verificación de ECC como puerta final antes de PRs

Evitar conflictos de hooks

Si ejecutas tanto ECC como Plankton:

• El hook de Prettier de ECC y el formateador biome de Plankton pueden entrar en conflicto en archivos JS/TS
• Solución: desactiva el hook PostToolUse de Prettier de ECC cuando uses Plankton (biome de Plankton es más completo)
• Ambos pueden coexistir en diferentes tipos de archivo (ECC maneja lo que Plankton no cubre)

Referencia de configuración

El archivo .claude/hooks/config.json de Plankton controla todo el comportamiento:

{
  "languages": {
    "python": true,
    "shell": true,
    "yaml": true,
    "json": true,
    "toml": true,
    "dockerfile": true,
    "markdown": true,
    "typescript": {
      "enabled": true,
      "js_runtime": "auto",
      "biome_nursery": "warn",
      "semgrep": true
    }
  },
  "phases": {
    "auto_format": true,
    "subprocess_delegation": true
  },
  "subprocess": {
    "tiers": {
      "haiku":  { "timeout": 120, "max_turns": 10 },
      "sonnet": { "timeout": 300, "max_turns": 10 },
      "opus":   { "timeout": 600, "max_turns": 15 }
    },
    "volume_threshold": 5
  }
}

Configuraciones clave:

• Desactiva los lenguajes que no uses para acelerar los hooks
• volume_threshold — si las violaciones superan este número, se escala automáticamente a un nivel de modelo superior
• subprocess_delegation: false — salta la Fase 3 por completo (solo reporta violaciones)

Anulaciones mediante variables de entorno

Variable	Propósito
HOOK_SKIP_SUBPROCESS=1	Salta la Fase 3, reporta violaciones directamente
HOOK_SUBPROCESS_TIMEOUT=N	Anula el tiempo límite del nivel
HOOK_DEBUG_MODEL=1	Registra las decisiones de selección de modelo
HOOK_SKIP_PM=1	Omite la imposición del gestor de paquetes

Referencias

• Plankton (crédito: @alxfazio)
• Plankton REFERENCE.md — Documentación completa de la arquitectura (crédito: @alxfazio)
• Plankton SETUP.md — Guía de instalación detallada (crédito: @alxfazio)

Adiciones de ECC v1.8

Perfil de hook copiable

Configura un comportamiento de calidad estricto:

export ECC_HOOK_PROFILE=strict
export ECC_QUALITY_GATE_FIX=true
export ECC_QUALITY_GATE_STRICT=true

Tabla de puertas de lenguaje

• TypeScript/JavaScript: Biome preferido, Prettier como respaldo
• Python: Ruff format/check
• Go: gofmt

Guarda contra manipulación de configuración

Durante el control de calidad, marca los cambios en archivos de configuración en la misma iteración:

• biome.json, .eslintrc*, prettier.config*, tsconfig.json, pyproject.toml

Si se cambia la configuración para suprimir violaciones, se requiere revisión explícita antes de fusionar.

Patrón de integración CI

Usa los mismos comandos en CI que en hooks locales:

1. ejecutar verificaciones de formato
2. ejecutar verificaciones de lint/tipos
3. fallar rápido en modo estricto
4. publicar resumen de corrección

Métricas de salud

Seguimiento de:

• ediciones marcadas por puertas
• tiempo promedio de corrección
• violaciones repetidas por categoría
• bloqueos de fusión por fallos de puerta