JawsomeJason/jawsome-agents

Estándares

Los revisores aplican las mismas convenciones a mano, comentario tras comentario. Esta skill extrae esos comentarios para convertirlos en estándares escritos, y luego verifica los diffs contra ellos. Cada estándar empareja una regla que un agente sigue al escribir código con una lente que un revisor aplica a un diff. Cada § numerado cita los comentarios de revisión que lo respaldan, para que cualquiera pueda rastrear una regla hasta los revisores que la aplicaron.

Principios fundamentales

• Evidencia primero. Un § necesita comentarios de revisión de al menos 3 cambios distintos y 2 revisores diferentes, porque muchos comentarios sobre un solo cambio, o de una sola persona, son el gusto de un único revisor.
• Cada regla lleva su porqué. Una razón sigue guiando a un agente incluso después de que el código alrededor de la regla cambie de forma.
• Un único hogar por convención. Dos copias divergen, y un agente sigue la que haya leído primero.
• Una verificación automática es mejor que un §. Una convención que un linter, tipo o prueba puede detectar pertenece a esa herramienta, porque una verificación se ejecuta cada vez.
• Elimina lo que los agentes ya hacen. Una regla seguida espontáneamente cuesta contexto en cada carga y no cambia nada.
• Los scripts son atajos. Cada archivo de salida tiene un esquema en references/schemas/, por lo que cuando un script falta o falla, se escribe el mismo archivo manualmente.
• git es la única dependencia obligatoria. La CLI de una forja, como gh o glab, añade comentarios de revisión, y git log la sustituye si no se dispone de ella.

Comandos

Comando	Qué hace	Salida	Referencia
mine	Obtiene comentarios de revisión, los etiqueta por convención, ordena los clústeres por frecuencia por severidad	.standards/clusters.json	references/mine.md
write	Convierte los clústeres ordenados en una skill de estándares en el repositorio, cada § con su porqué y evidencia	la skill de estándares	references/write.md
review	Aplica cada lente que un diff activa e informa los hallazgos con el § citado	hallazgos en la respuesta	references/review.md
prune	Prueba A/B cada regla en entornos de prueba y elimina las que los agentes siguen espontáneamente	prune.json	references/prune.md
doctor	Detecta desviaciones: globs que no coinciden con nada, archivos citados que ya no existen, lentes que nunca se activan, datos de poda obsoletos	.standards/doctor.json	references/doctor.md

Enrutamiento

Se invoca como standards [comando] [ámbito]. Un ámbito es una ruta o glob, un slug de área del índice generado, o un número de § (§2, §2.3). Se resuelve según references/scope.md. mine solo acepta una ruta, porque las áreas solo existen después de write.

• Sin argumento. Muestra el menú a continuación y espera una elección. Nunca ejecutes un comando automáticamente, porque cada uno lee el historial, edita el repositorio o consume muchas ejecuciones del agente.
• Un ámbito sin comando. Ejecuta review de ese ámbito sin preguntar, porque review solo lee.
• Un comando explícito o claramente implícito. Carga su referencia y síguela paso a paso.
• Dos comandos encajan. Pregunta una vez cuál, nombrando ambos y lo que haría cada uno. Luego sigue la respuesta.
• Estándares desde cero. Comienza con mine, porque write necesita clusters.json. Ofrece write cuando mine termine.
• Una pregunta sobre la skill en sí. Responde desde este archivo sin ejecutar un comando.

Menú

standards: ¿qué debería hacer?
  mine    Extraer comentarios de revisión en convenciones ordenadas
  write   Escribir estándares a partir de las convenciones ordenadas
  review  Revisar un diff contra los estándares
  prune   Probar cada regla y eliminar las que los agentes ya siguen
  doctor  Verificar los estándares en busca de desviaciones
Cada comando acepta un ámbito opcional: una ruta, un área o un §.

Cuando existan estándares generados, lista sus áreas bajo el menú como número de § y slug.

Pipeline

mine alimenta a write, y write produce lo que review aplica. prune y doctor mantienen los estándares después de eso.

Los archivos de trabajo residen en .standards/ en la raíz del repositorio objetivo. Mantén esa carpeta fuera del control de versiones, porque los comentarios de revisión citan código y personas. prune.json es la excepción. Está junto a los estándares generados, porque doctor lo lee allí.

<skill-dir> en las referencias es la carpeta que contiene este archivo. Los scripts en <skill-dir>/scripts/ aceleran mine y solo necesitan la biblioteca estándar de un entorno de ejecución de JavaScript.

Modelo de juicio

mine, prune y doctor hacen muchas preguntas pequeñas y tipadas. Un modelo de juicio es un modelo rápido que responde preguntas tipadas (elige una de un conjunto, una probabilidad sí/no, una puntuación) con probabilidades calibradas. Si tu entorno te proporciona un modelo de juicio, responde el archivo de preguntas con él; de lo contrario, respóndelas tú mismo. Las instrucciones de tu propio entorno deciden qué modelo es ese.

Estándares generados

• La salida predeterminada es una skill con un índice de resúmenes de una línea, cada uno enlazando a un archivo de §. Plantillas: índice y sección.
• Una skill por área es una opción, decidida por repositorio mediante el experimento de forma en references/write.md.
• Los estándares generados siguen las mismas reglas que esta skill: solo frontmatter de especificación, sin URL, sin fechas, y un porqué para cada regla.