Lista de verificación de despliegue

Pasos de verificación previos al despliegue del ecosistema Apothem en una máquina nueva, a su uso compartido con otras personas o a tratarlo como apto para producción.

1. Validez de YAMLCopy Anchor Link

• Todos los archivos de reglas se analizan sin errores de YAML — el bloque de frontmatter abre con ---, cierra con --- y no contiene contenido huérfano fuera del bloque
• Todos los archivos de trabajadores delegados se analizan sin errores de YAML
• Todos los archivos de comandos se analizan sin errores de YAML
• Todos los archivos SKILL.md de skills se analizan sin errores de YAML

Verificación: python scripts/dev/validate_ecosystem.py analiza el frontmatter de cada artefacto y marca los errores de YAML y los campos requeridos ausentes. Para detectar ad hoc elementos de lista huérfanos: rg -n "^- " src/apothem/rules/*.md.

2. Completitud del frontmatterCopy Anchor Link

Para cada tipo de artefacto, verifica que los campos requeridos estén presentes:

Reglas (src/apothem/rules/*.md)Copy Anchor Link

• name — identificador en kebab-case que coincide con el nombre del archivo
• description — resumen de una sola frase
• alwaysApply — true para las reglas siempre activas, false para las reglas filtradas por ruta
• pathFilter — presente en todas las reglas: "" para las reglas siempre activas (alwaysApply: true), una lista de globs separados por comas para las reglas filtradas por ruta (alwaysApply: false)

Las reglas no incluyen ninguna clave version, updated, scope ni portability.

Comandos (src/apothem/commands/*.md)Copy Anchor Link

• name — nombre del comando en kebab-case
• version, updated, description, argument-hint, portability, allowed-tools presentes
• disable-model-invocation presente e intencional (false para comandos de solo lectura o de asesoramiento; true solo cuando ejecutar el comando cambia el estado fuera del árbol de trabajo o depende de que el operador elija el momento)
• Sin clave effort: command.schema.json establece additionalProperties: false y no la admite

Trabajadores delegadosCopy Anchor Link

Ruta:

src/apothem/agents/*.md

• name, version, updated, description presentes
• tools — lista separada por comas de las herramientas permitidas
• disallowedTools — enumera explícitamente las herramientas no permitidas
• maxTurns — establecido (con un comentario que justifique el valor si es mayor que 10)
• permissionMode — NO debe ser "bypassPermissions"; deja la clave sin definir, ya que la postura agnóstica no preestablece ningún modo de permisos
• memory omitido salvo que la memoria persistente sea intencional; cuando se define, uno de user, project, local (no admite la forma booleana)

Skills (src/apothem/skills/*/SKILL.md)Copy Anchor Link

• name, version, updated, description, archetype, disable-model-invocation, allowed-tools presentes
• userInvocable declarado (true/false). La grafía en el origen es userInvocable; una skill incluye exactamente una de userInvocable o user-invocable (la forma que usa Claude Code).

3. SeguridadCopy Anchor Link

• Ningún trabajador delegado usa permissionMode: "bypassPermissions" — esto omite la confirmación interactiva para operaciones Write/Bash
• Las listas de tools del trabajador son mínimas — solo las herramientas que el trabajador realmente requiere
• Los trabajadores con acceso a Bash están justificados y tienen límites de maxTurns
• No hay rutas, tokens ni secretos codificados de forma fija en ningún artefacto
• Los hooks en settings.json tienen tiempos de espera razonables (≤ 60 segundos) y no ejecutan código arbitrario procedente de la entrada del usuario

4. Integridad de las referencias cruzadasCopy Anchor Link

• Cada regla listada en la tabla src/apothem/rules/ existe en disco en la ruta indicada
• Cada comando listado en la tabla src/apothem/commands/ existe en disco
• Cada trabajador delegado listado en la tabla del registro src/apothem/agents/ existe en disco
• Cada skill listada en la tabla src/apothem/skills/ existe en disco
• Cada hook en la tabla src/apothem/hooks/ tiene una entrada correspondiente en settings.json
• Todos los archivos src/apothem/rules/*.md existen y resuelven sus referencias cruzadas de Bindings

5. Cobertura de mandatosCopy Anchor Link

• Cada mandato CM-N tiene una ubicación de aplicación (ya sea un archivo de regla o una definición inline explícita)
• Ningún archivo de regla contradice a otro (especialmente en torno al escalado de seriedad)
• Se respeta la delineación de tres facetas de CM-21 — ninguna regla reclama la propiedad de la faceta CM-21 de otra regla

6. Pruebas de humo funcionalesCopy Anchor Link

Ejecuta primero la superficie de validación de Python — es rápida, sin conexión y detecta regresiones estructurales:

• pytest tests — pruebas unitarias del runtime de hooks, todas en verde
• python scripts/dev/validate_hooks.py — estructura de hooks + comprobación de higiene solo de Python superada
• python scripts/dev/validate_ecosystem.py — árbol completo + frontmatter + comprobaciones de hooks delegados superadas
• python scripts/dev/chaos_pass.py — cada comando de hook configurado devuelve un sobre JSON válido bajo entradas degradadas

Luego, escenarios en vivo:

• /plan-spec <sample-file> — completa la ingesta y la aclaración sin errores a nivel de comando
• /plan-generate --dry-run — produce una vista previa de la estructura sin escribir archivos
• /plan-status sobre una suite de plan completa — devuelve recuentos de fases precisos
• Despacho de trabajadores delegados: el trabajador codebase-explorer invocado con un alcance pequeño se completa dentro de maxTurns y devuelve salida estructurada

7. Vigencia de la documentaciónCopy Anchor Link

• CHANGELOG.md (en la raíz del ecosistema) refleja cada cambio de artefacto desde la última versión publicada; la sección de la próxima versión está poblada antes de que aterrice la etiqueta, o cada cambio ya está cortado en una sección publicada
• site/content/docs/developer-guide.mdx describe con precisión la estructura actual de los artefactos
• site/content/docs/reference/artifact-schema.mdx coincide con los campos de frontmatter realmente presentes en los artefactos
• site/content/docs/reference/settings-reference.mdx coincide con la configuración de hooks real en settings.json
• README.md es coherente con el árbol en disco

8. Portabilidad (si se comparte con otras personas)Copy Anchor Link

• Todas las rutas en los comandos de hooks son agnósticas respecto al entorno o usan expansión de ~
• Los comandos de hooks usan la forma exec y evitan cadenas de comandos específicas de un shell
• No hay rutas codificadas de forma fija C:\Users\username ni /home/username en ningún artefacto
• settings.json usa una única tabla de cobertura de eventos de hooks y la ruta canónica del módulo de despacho

9. Alineación de versionesCopy Anchor Link

• La version de CLAUDE.md es la más alta de cualquier artefacto del árbol (o igual a la versión del artefacto más recientemente actualizado, por convención)
• La version de cada artefacto coincide con el semver indicado (MAJOR.MINOR.PATCH)
• CHANGELOG.md contiene exactamente la entrada de la versión objetivo antes del etiquetado
• El campo updated de cada artefacto está en la fecha de su última edición que cambia el comportamiento, o después
• Ningún artefacto lleva una version inferior a la versión en la que se modificó por última vez (sin regresiones)
• src/apothem/skills/plan-suite/SKILL.md y src/apothem/skills/plan-suite/master-template.md están fijados a la misma línea de versión de plantilla

AprobaciónCopy Anchor Link

Despliegue aprobado por: ___________________ Fecha: ___________________ Versión del ecosistema desplegada: ___________________