plankton-code-quality

Habilidad de Calidad de Código Plankton

Referencia de integración para Plankton (crédito: @alxfazio), un sistema de refuerzo 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 de PostToolUse, luego genera subprocesos de Claude para corregir violaciones que el agente no detectó.

Cuándo Usarlo

• Deseas formato y linting automáticos en cada edición de archivo (no solo al hacer commit)
• Necesitas defensa contra agentes que modifican configuraciones de linter para pasar pruebas en lugar de corregir código
• 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 PostToolUse multi_linter.sh de Plankton se ejecuta:

Fase 1: Autoformato (Silencioso)
├─ Ejecuta formateadores (ruff format, biome, shfmt, taplo, markdownlint)
├─ Corrige 40-50% de los problemas silenciosamente
└─ Sin salida al agente principal

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

Fase 3: Delegar + Verificar
├─ Genera subproceso 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 de espera 120s
│   ├─ Sonnet: complejidad, refactorización (códigos C901, PLR) — tiempo de espera 300s
│   └─ Opus: sistema de tipos, razonamiento profundo (unresolved-attribute) — tiempo de espera 600s
├─ Vuelve a ejecutar Fase 1+2 para verificar correcciones
└─ Salida 0 si está limpio, Salida 2 si quedan violaciones (reportado 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 LLM 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 ediciones a todas las configuraciones de linter antes de que ocurran
2. Hook Stop — stop_config_guardian.sh detecta cambios de configuración mediante git diff al final de la sesión
3. Lista de archivos protegidos — .ruff.toml, biome.json, .shellcheckrc, .yamllint, .hadolint.yaml y más

Refuerzo de Gestor de Paquetes

Un hook PreToolUse en Bash bloquea gestores de paquetes heredados:

• pip, pip3, poetry, pipenv → Bloqueados (usar uv)
• npm, yarn, pnpm → Bloqueados (usar 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 instalarlo.

# 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

No necesita comando de instalación ni configuración de plugin. Los hooks en .claude/settings.json se recogen automáticamente al ejecutar 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 linter (.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	—

Emparejamiento con ECC

Complementarios, No Superpuestos

Aspecto	ECC	Plankton
Refuerzo 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	Refuerzo (bloquea PMs heredados)
Integración CI	—	Hooks 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 refuerzo 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

Evitando Conflictos de Hooks

Si ejecutas ambos hooks (ECC y Plankton):

• El hook Prettier de ECC y el formateador biome de Plankton pueden entrar en conflicto en archivos JS/TS
• Resolución: desactiva el hook PostToolUse de Prettier de ECC al usar Plankton (biome de Plankton es más completo)
• Ambos pueden coexistir en diferentes tipos de archivos (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 usas para acelerar los hooks
• volume_threshold — violaciones > este número se escalan automáticamente a un nivel de modelo superior
• subprocess_delegation: false — saltar la Fase 3 por completo (solo reportar violaciones)

Sobrescrituras de Entorno

Variable	Propósito
HOOK_SKIP_SUBPROCESS=1	Saltar Fase 3, reportar violaciones directamente
HOOK_SUBPROCESS_TIMEOUT=N	Sobrescribir tiempo de espera del nivel
HOOK_DEBUG_MODEL=1	Registrar decisiones de selección de modelo
HOOK_SKIP_PM=1	Omitir el refuerzo 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

Establece 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 alternativa
• Python: Ruff format/check
• Go: gofmt

Guardián de Manipulación de Configuración

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

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

Si la configuración se cambia 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 los hooks locales:

1. ejecutar comprobaciones de formateo
2. ejecutar comprobaciones de lint/tipos
3. fallar rápidamente en modo estricto
4. publicar resumen de remediación

Métricas de Salud

Seguimiento de:

• ediciones marcadas por puertas
• tiempo promedio de remediación
• violaciones repetidas por categoría
• bloqueos de fusión debido a fallos en puertas