project-baseline
Un estándar de preparación comprobable: 69 reglas, cada una respaldada por una verificación que un ejecutor Node sin dependencias realiza sobre un repositorio en reposo. Los bloqueos fallan en CI (código de salida 1); los juicios que un script no puede hacer se resuelven mediante un libro de registro de aprobaciones fechado. El objetivo principal: no confíes en una promesa escrita — haz que algo la verifique.
El conjunto de herramientas se encuentra junto a este archivo: check.mjs (ejecutor), rules.json (las 69 reglas), config.example.json, templates/, README.md (guía de inicio rápido), REFERENCE.md (referencia completa: tabla de reglas, categorías, diagramas de arquitectura, configuración de CI) y GLOSSARY.md (definiciones en lenguaje sencillo de términos de DevOps/cadena de suministro).
Resuelve primero el directorio del skill. $SKILL_DIR a continuación significa la ruta absoluta del directorio que contiene este SKILL.md — resuélvela a una ruta concreta antes de ejecutar cualquier comando (no pases la cadena literal $SKILL_DIR al shell). Normalmente es ~/.claude/skills/baseline. check.mjs carga rules.json desde su propio directorio, por lo que ambos deben permanecer juntos; invoca siempre el ejecutor mediante su ruta absoluta (node "<abs>/check.mjs" …) en lugar de copiarlo a otro lado. El ejecutor solo necesita Node ≥ 18 y git; si falta node, indícaselo al usuario en lugar de adivinarlo.
Al ser invocado
Determina la intención a partir de las palabras del usuario y elige un modo. Por defecto, usa score si no se especifica.
Modo: score (por defecto) — "ejecutar baseline", "/baseline", "verificar este repositorio"
- Selecciona el repositorio objetivo: una ruta explícita en la solicitud, o el directorio de trabajo actual. Confirma que parece un repositorio (tiene un manifiesto o
.git). - Ejecuta el ejecutor (legible para humanos):
node "$SKILL_DIR/check.mjs" --repo <destino>- Añade
--no-execsi NO debes ejecutar el comando de bootstrap/prueba del repositorio (BUILD-05) — por ejemplo, repositorio no confiable, sin tiempo para ejecutar pruebas, o el comando no está configurado. Prefiere ejecutarlo cuando sea seguro, ya que BUILD-05 es la verificación principal. - Añade
--profile advancedsi el usuario quiere las reglas expertas (SBOM, análisis de código, pruebas de mutación, integridad de símbolos, escaneo de vulnerabilidades de dependencias, cobertura mínima). El perfilservicese activa automáticamente paraproject_type=service. - Añade
--jsoncuando quieras analizar los resultados programáticamente en lugar de mostrar la puntuación.
- Añade
- Presenta el resultado al usuario, comenzando con los bloqueadores (estos fallan en CI), luego las advertencias que vale la pena corregir. Agrupa por categoría. No muestres las 69 filas completas — resume: % de preparación, número de bloqueadores y los FAIL/advertencias notables específicos con su detalle de una línea. Ofrece corregir o preparar el andamiaje.
Modo: init — "configurar baseline aquí", "adoptar el estándar", "preparar andamiaje baseline"
- Copia el conjunto de herramientas en el repositorio (sugiere
tools/baseline/), o haz referencia a él en su lugar. - Prepara los artefactos, solo si faltan (nunca sobrescribas sin preguntar):
cp "$SKILL_DIR/config.example.json" <repo>/baseline.config.json cp "$SKILL_DIR/templates/CLAIMS.json" <repo>/docs/CLAIMS.json # solo si el repositorio hace afirmaciones externas cp "$SKILL_DIR/templates/start-here.md" <repo>/docs/start-here.md # si no existe un documento de estado mkdir -p <repo>/.project-baseline && cp "$SKILL_DIR/templates/signoff.json" <repo>/.project-baseline/signoff.json - Edita
baseline.config.jsonsegún la realidad del repositorio: estableceproject_type,bootstrap_command(el comando de instalación+prueba para BUILD-05) ymakes_external_claims(falso omite las reglas CLAIM-*). Las claves opt-in*_globs(frescura/generados/fundamento) permanecen vacías hasta que el repositorio adopte esas convenciones. - Muéstrales la configuración de CI del
README.mdy convierte el trabajobaselineen una verificación obligatoria (esa es la regla BUILD-06). - Ejecuta una primera puntuación.
Modo: fix — "corregir los fallos del baseline", "poner esto en verde"
- Puntúa primero. Para cada bloqueador/advertencia que el usuario quiera abordar, aplica el campo
fixde la propia regla (léelo derules.json) como ediciones concretas en el repositorio — añade la licencia faltante, fija la acción a un SHA, añade el.enva.gitignorey rota el secreto, añade la prueba negativa, etc. - Para las reglas
manual(aprobación), no falsifiques una verificación — ayuda al usuario a hacer el juicio (radio de explosión, revisión de arte previo, cuña/foso) y registra una entrada fechada en.project-baseline/signoff.json. - Vuelve a puntuar para confirmar.
Modo: explain — "¿qué verifica SEC-03?", "¿por qué falló CTX-05?"
Lee la regla de rules.json (cada una tiene title, rationale, fix, source y la verificación check) y explícala claramente, además de lo que el ejecutor buscó realmente. Para jerga desconocida (SBOM, SLSA, procedencia, libro de registro de aprobaciones, …), GLOSSARY.md en este directorio tiene definiciones en lenguaje sencillo.
Cómo decide el ejecutor (para que puedas interpretar las líneas de detalle)
- PASS / FAIL / WARN / SIGN-OFF / SKIP por regla. Solo los FAIL de tipo
blockerestablecen el código de salida 1. - SKIP significa que la regla no aplicaba:
project_typeincorrecto (n/a for <type>), un perfil desactivado (profile 'advanced' off), una función opt-in no adoptada, o nada que verificar. Un SKIP nunca cuenta en contra de la preparación. - Perfiles:
coresiempre se ejecuta;servicese ejecuta automáticamente cuandoproject_type=service;advancedse ejecuta solo con--profile advancedoprofiles:["advanced"]en la configuración. - Las afirmaciones son opt-in: CLAIM-* solo se ejecutan si existe un registro de afirmaciones o
makes_external_claims:trueestá establecido explícitamente. Un repositorio sin registro de afirmaciones no es penalizado. - La configuración se autodetecta de forma sensata;
baseline.config.jsonen la raíz del repositorio la anula. Las claves están documentadas enconfig.example.json. - El ejecutor no tiene dependencias (Node ≥ 18 + git) y es resistente a fallos: una regla cuya verificación no puede evaluarse se degrada a SKIP, nunca interrumpe la ejecución.
Notas
- Nunca presentes una advertencia como un bloqueador ni viceversa — la gravedad está en
rules.jsony en la salida del ejecutor. - Prefiere ejecutar BUILD-05 realmente (omite
--no-exec) cuando el repositorio sea confiable y el comando de bootstrap esté configurado — una verificación principal en verde es la señal más fuerte. - La justificación completa, la tabla de reglas, las descripciones de categorías, los diagramas de arquitectura y el fragmento de CI están en
REFERENCE.mdde este directorio — léelo si el usuario quiere profundizar.