Shaelz/codebase-trellis-skill

Codebase Trellis

Estructura, respalda e integra de manera segura los cambios de código asistidos por IA.

Ecosistema:

• codebase-orient entiende la base de código.
• codebase-visualize mapea la base de código.
• codebase-trellis respalda el crecimiento seguro y la integración de cambios.

---

Cuándo usar esta skill

Usa esta skill cuando

• Los archivos han cambiado y necesitan un staging, planificación de commit o ejecución de commit seguros.
• Una rama o worktree necesita ser configurada, finalizada o limpiada.
• Un push, PR o estado de CI necesita inspección o preparación.
• La postura del repositorio Git/GitHub necesita una auditoría.
• Una sesión de agente de larga duración necesita una revisión de estado estructurada antes de continuar.
• El árbol de trabajo está sucio y el siguiente paso correcto no está claro.

Salta esta skill cuando

• La tarea es un arreglo pequeño, de un solo archivo, conocido y no hay incertidumbre en el estado de Git.
• Se está realizando una exploración de solo lectura y no se planea ningún trabajo de commit/push/limpieza.
• Otra skill (codebase-orient, codebase-visualize) acaba de ser invocada y no le sigue ningún trabajo de Git.

---

Clasificación simple vs. estructurada

Clasifica cada invocación antes de ejecutar cualquier flujo de trabajo.

Pase simple:

• corrección de errores localizada
• cambio solo de documentación o solo de copia
• actualización de dependencia
• refactorización pequeña
• cambio solo de pruebas
• preparación de commit ya delimitado

Pase estructurado:

• cambio amplio en múltiples archivos
• múltiples paquetes
• UI más API más pruebas
• migración o archivos generados
• trabajo de agente de larga duración
• se esperan múltiples commits
• probablemente se necesite reanudación o traspaso

Por defecto, asume simple cuando no estés seguro. Promueve a estructurado si la inspección demuestra que el trabajo es más grande de lo que parecía. Nunca degradar de estructurado después de que se haya establecido el estado de seguridad.

---

Capas de cumplimiento

Trellis opera dentro de un modelo de seguridad de 4 capas. Estas capas no son equivalentes y ninguna capa sustituye a otra.

Capa 1: Disciplina de la skill (capa central v1)

La skill inspecciona, informa y controla operaciones riesgosas. Funciona en cualquier repositorio Git normal sin necesidad de hooks adicionales ni acceso a GitHub. Esto es conductual: depende de que el agente siga la skill.

Capa 2: Hooks locales de Git

Los hooks locales del repositorio pueden ejecutarse durante un commit o push. Trellis puede recomendar hooks pero no los requiere ni los instala en v1. Los hooks pueden faltar, omitirse con --no-verify o no compartirse entre clones.

Capa 3: Hooks de Claude Code

Los hooks a nivel de host pueden actuar en torno al uso de herramientas, cambios de archivos y permisos. Endurecimiento opcional únicamente: no es necesario para el núcleo independiente. No asumas que están instalados.

Capa 4: Protecciones de GitHub

Aplicación del lado de GitHub: protección de ramas, conjuntos de reglas, comprobaciones requeridas, revisiones requeridas, commits firmados, restricciones de push forzado, cola de fusiones, escaneo de secretos, escaneo de código, Dependabot. Inspecciona e informa cuando el acceso a la API lo permita; nunca asumas que existen protecciones.

Regla de no equivalencia:

• La disciplina de la skill no es un hook.
• Un hook local no es la protección de rama de GitHub.
• Un grep local que pasa no es el escaneo de secretos.
• Las comprobaciones de la PR no son las comprobaciones de la cola de fusiones.
• Una marca verde visible no es prueba de que todas las comprobaciones requeridas pasaron para el SHA relevante.

Si una capa no está disponible o no está verificada, dilo claramente.

---

Límite de interoperabilidad

Núcleo independiente

Codebase Trellis debe funcionar en cualquier repositorio Git normal sin requerir artefactos de skills hermanas. Es responsable de:

• Inspección del estado de Git y del estado sucio
• Detección de cambios staged, unstaged, untracked, ignorados, generados, sensibles y preexistentes
• Agrupación de commits y traspaso del plan de commit
• Seguridad de ramas/worktrees
• Puertas de push/PR/CI
• Reglas de limpieza
• Salida del informe Trellis

Lecturas asesoras opcionales

Si existen artefactos de skills hermanas, Trellis puede leerlos como contexto asesor únicamente.

De codebase-orient (ejemplos: docs/ai/CODEBASE_MAP.md, docs/ai/CHANGE_SURFACES.md, docs/ai/OPEN_QUESTIONS.md):

• diseño del repositorio y estructura de paquetes/espacios de trabajo
• comprobaciones conocidas y política de documentos generados
• convenciones importantes y zonas peligrosas

De codebase-visualize (ejemplos: docs/ai/visualize/codebase-graph.json):

• radio de explosión y módulos afectados
• bordes de documentos a código y archivos de alta centralidad

Reglas:

• No requieras estos archivos.
• No los regeneres.
• No los modifiques silenciosamente.
• No bloquees la planificación rutinaria de commits porque falte la visualización.
• No los trates como más autoritativos que el código fuente, la configuración o los documentos canónicos.

Disparadores de traspaso

• Sugiere /codebase-orient cuando la estructura del repositorio no esté clara, se desconozcan las comprobaciones conocidas o el agente carezca de suficiente contexto para clasificar el riesgo.
• Sugiere /codebase-visualize cuando el impacto del cambio sea amplio o arquitectónico, las relaciones de dependencia importen o el radio de explosión mejore la decisión.

---

Reglas universales

Siempre:

1. Comienza identificando la raíz del repositorio, la rama y el estado sucio.
2. Muestra el estado antes de proponer comandos.
3. Separa archivos staged, unstaged, untracked, eliminados e ignorados.
4. Trata los archivos parcialmente staged como ambiguos y riesgosos.
5. Excluye archivos sensibles de todos los planes de commit.
6. Prefiere listas de archivos exactas sobre comandos de ruta amplia.
7. Detente ante un fallo de comando.
8. Indica cuando gh no esté disponible o carezca de permisos.
9. Mantén los informes breves y procesables.
10. Informa lo que se sabe y lo que se desconoce; no colapses desconocidos en seguridad asumida.

Nunca:

1. Ejecutes git add . sin la aprobación explícita de la lista exacta de archivos.
2. Hagas commit sin mostrar los archivos planificados y el mensaje de commit.
3. Hagas push como parte del commit.
4. Hagas merge como parte del push.
5. Uses git push --force.
6. Inferas --force-with-lease; debe ser solicitado explícitamente.
7. Elimines ramas sin confirmación escrita del nombre de la rama.
8. Elimines worktrees no creados por esta sesión o que no sean claramente worktrees desechables del proyecto local.
9. Incluyas .env, claves, tokens, credenciales o archivos ignorados en un plan de commit.
10. Afirmes que las pruebas, la CI o la configuración de GitHub pasaron a menos que estén verificadas.
11. Afirmes "no hay secretos" o "no hay vulnerabilidades" a partir de un grep local o comprobaciones visibles por sí solas.
12. Informes la CI como verde a menos que se conozcan tanto el SHA relevante como las comprobaciones requeridas.
13. Incluyas silenciosamente archivos sucios preexistentes.
14. Incluyas silenciosamente archivos untracked.

---

Puertas de riesgo

Solo lectura -- no se necesita aprobación:

• git status, git diff --stat, git log, git remote -v
• gh pr view, gh run list, gh repo view
• Cualquier comando de inspección o diagnóstico que no cambie el estado

Cambio de estado bajo -- se requiere plan visible y aprobación en modo de ejecución:

• Crear rama local
• Crear worktree local
• Hacer stage de archivos explícitamente listados
• Crear commit a partir de un plan aprobado

Cambio de estado alto -- se requiere aprobación explícita:

• Push (cualquier rama)
• Crear PR
• Fusionar rama
• Rebase de rama
• Editar protección de ramas o conjuntos de reglas
• Eliminar rama
• Eliminar worktree

Peligroso -- se requiere confirmación escrita y preferir mostrar comandos en lugar de ejecutarlos:

• Push a rama protegida (requiere nombre de rama escrito)
• Push --force-with-lease (debe ser solicitado explícitamente)
• git reset --hard
• git clean -fd o cualquier eliminación de archivos untracked
• Eliminar rama con commits sin fusionar
• Reescribir historial público
• Corrección de historial secreto

git push --force siempre está prohibido.

---

Patrones de archivos sensibles

Nunca incluyas estos archivos en un plan de commit. Si el usuario anula después de una advertencia, advierte nuevamente y recomienda no hacerlo.

.env
.env.*
*.pem
*.key
*.p12
*.pfx
id_rsa*
*.cert
.aws/credentials
credentials.json
*.secret
token.txt
.npmrc
auth.json
service-account*.json

También excluye: archivos ignorados, resultados de compilación, cachés y carpetas de dependencias a menos que el repositorio los rastree intencionalmente.

Exclusiones comunes:

node_modules/
dist/
build/
.cache/
.svelte-kit/
.next/
coverage/
__pycache__/
*.pyc

---

Límite de visibilidad de seguridad

Trellis puede informar sobre señales de seguridad visibles. Trellis no es un escáner de seguridad completo.

Informa cuando sea visible:

• archivos con forma de secreto en el diff local (nombres de archivo o patrones que coincidan con .env, *.key, etc.)
• si el escaneo de secretos de GitHub y la protección de push parecen estar habilitados
• si CodeQL o el escaneo de código están configurados
• si las alertas de Dependabot o las actualizaciones de seguridad son visibles
• si los archivos de dependencias cambiaron en este diff

Nunca afirmes:

• "no se encontraron secretos" únicamente porque el grep local no encontró nada
• "no hay vulnerabilidades" únicamente porque las comprobaciones visibles de GitHub están en verde
• que la postura de seguridad está limpia a menos que se haya verificado a través de una herramienta de seguridad dedicada

---

Límite de visibilidad de GitHub/CI

Informa lo que se puede y no se puede verificar. No colapses el estado de protección desconocido en seguridad asumida.

Los modos de CI son preguntas diferentes; no los confundas:

Preparación a nivel de PR:

• ¿Está esta PR lista para fusionarse?
• ¿Están pasando las comprobaciones requeridas para este SHA?
• ¿Son relevantes las comprobaciones pendientes, saltadas o canceladas?

Inspección de ejecución de flujo de trabajo:

• ¿Por qué falló esta ejecución?
• ¿Qué trabajo o paso falló?
• ¿Están disponibles los registros o artefactos?

Estado de protección de GitHub -- informa uno de:

• Estado de protección: verificado -- <resumen de lo encontrado>
• Estado de protección: no verificado. No asumas que la rama principal está protegida.

Cola de fusiones -- si se requiere una cola de fusiones, las comprobaciones de la cabeza de la PR no son la señal final. Informa por separado:

• comprobaciones de la cabeza de la PR
• comprobaciones requeridas
• comprobaciones de la cola de fusiones o del grupo de fusiones si están presentes
• si el SHA comprobado coincide con el commit que se está discutiendo

Nunca agregues a la cola de fusiones, habilites la fusión automática o fusiones sin la aprobación explícita del usuario.

---

Informe Trellis

El informe Trellis es la salida característica de cada pase de inspección o planificación.

Formulario completo

Informe Trellis

Comprobación de raíz
- Raíz del repo:     <directorio de trabajo actual; si es un worktree vinculado, esta es la ruta del worktree>
- Repo principal:     <raíz del repositorio padre, derivada de GIT_COMMON si es un worktree vinculado; omitir si no es un worktree vinculado>
- Rama:
- Remoto/upstream:
- Estado del worktree: <worktree vinculado en <ruta> / checkout del repositorio principal / HEAD separado>
- Estado de identificación/firma:
- Archivos sucios de referencia (preexistentes):

Comprobación de enredo
- Cambios staged:
- Cambios unstaged:
- Archivos untracked:
- Archivos ignorados/generados notables:
- Archivos de aspecto sensible:
- Archivos parcialmente staged:
- Preocupaciones mixtas:

Plan de crecimiento
- Grupos de cambio sugeridos:
- Límites de commit sugeridos:
- Forma de PR sugerida:
- Archivos excluidos del alcance:
- Archivos que requieren decisión del usuario:

Comprobación de puerta
- Seguro para inspeccionar/leer: sí
- Requiere aprobación antes del staging:
- Requiere aprobación antes del commit:
- Requiere aprobación antes del push:
- Requiere aprobación antes de fusionar/fusión automática:
- Requiere aprobación antes de limpiar/eliminar:

Comprobación de dosel
- Visibilidad del repositorio/PR de GitHub:
- Comprobaciones requeridas:
- Estado de CI y SHA comprobado:
- Estado de protección de rama/conjunto de reglas:
- Estado de la cola de fusiones:
- Señales de seguridad visibles:
- Protecciones desconocidas/no verificadas:

Próxima acción segura
- Recomendación:
- Comandos exactos (solo de lectura, o con anotación de puerta):
- Decisión requerida del usuario:

Formulario abreviado

Úsalo para pases simples o árboles de trabajo pequeños.

Informe Trellis
- Raíz: <resumen del repo / rama / worktree>
- Enredo: <resumen de staged / unstaged / untracked / sensible / preocupación mixta>
- Crecimiento: <recomendación de agrupación de commit/PR>
- Puertas: <operaciones que requieren aprobación>
- Dosel: <estado de GitHub/CI/protección si se conoce, o "no verificado">
- Siguiente: <una próxima acción segura>

Formulario de parada

Úsalo cuando Trellis no pueda o no deba continuar.

Parada de Trellis
- Razón de parada:
- Evidencia:
- Riesgo si se ignora:
- Opciones de recuperación segura:
- Opción recomendada:

Las razones de parada incluyen:

• Se mostraría un archivo de aspecto sensible.
• Se incluiría silenciosamente un archivo sucio preexistente.
• Un archivo parcialmente staged hace que la intención sea ambigua.
• La rama de destino está protegida o es desconocida y se solicitó un push/fusión.
• Se solicitó una operación similar a forzada sin aceptación explícita del riesgo.
• El estado de push o CI afirmado se refiere a un SHA diferente.
• Otra rama, worktree o PR parece ser dueña de la misma tarea.

---

Enrutamiento de modo

Lee $ARGUMENTS.

Si no se proporciona ningún modo, ejecuta audit.

Modos admitidos:

• audit: revisión de postura local de Git y GitHub de solo lectura
• start: prepara trabajo aislado usando una rama o worktree
• commit: planifica o ejecuta commits cohesivos
• push: prepara o ejecuta push y monitoreo de CI
• finish: finaliza la rama a través de PR, fusión local, mantener o descartar
• recover: recupera de errores de Git

---

Modo audit

Ejecuta diagnósticos de solo lectura. Produce un informe Trellis. Nunca modifiques ningún estado local o remoto.

Verificación previa al vuelo de auditoría -- Git local

Ejecuta siempre primero, independientemente de la disponibilidad de gh:

git rev-parse --show-toplevel 2>/dev/null || echo "ERROR: no es un repositorio git"
git branch --show-current
git status --short
git diff --stat
git diff --cached --stat
git log --oneline -10
git remote -v
git config --show-origin --show-scope --get user.name 2>/dev/null || echo "sin establecer"
git config --show-origin --show-scope --get user.email 2>/dev/null || echo "sin establecer"
git config commit.gpgsign 2>/dev/null || echo "sin establecer"

Verificación previa al vuelo de auditoría -- comprobaciones de archivos comunitarios

Comprueba la presencia/ausencia de cada archivo localmente. La presencia/ausencia es un hecho verificado; la calidad del contenido no lo es:

test -f README.md && echo "presente" || echo "ausente"
test -f LICENSE && echo "presente" || echo "ausente"
test -f SECURITY.md && echo "presente" || echo "ausente"
test -f CODE_OF_CONDUCT.md && echo "presente" || echo "ausente"
test -f CONTRIBUTING.md || test -f .github/CONTRIBUTING.md && echo "presente" || echo "ausente"
test -f .github/PULL_REQUEST_TEMPLATE.md && echo "presente" || echo "ausente"
test -d .github/ISSUE_TEMPLATE && echo "presente" || echo "ausente"
test -f CODEOWNERS || test -f .github/CODEOWNERS || test -f docs/CODEOWNERS && echo "presente" || echo "ausente"
test -f .github/dependabot.yml || test -f .github/dependabot.yaml && echo "presente" || echo "ausente"
test -d .github/workflows && echo "presente" || echo "ausente"

Postura de GitHub -- puerta de disponibilidad

Antes de ejecutar cualquier comando gh:

1. Comprueba si hay un remoto de GitHub: git remote -v | grep github.com
2. Comprueba si gh está disponible: gh auth status 2>/dev/null

Si no se detecta ningún remoto de GitHub: informa todos los campos de postura de GitHub como no disponible -- remoto no es GitHub.

Si gh no está disponible

...

[truncado para traducción]