Imported from soutecdev/souclaude-harness (.claude/skills/soutec-github/SKILL.md). Install upstream with npx skills add soutecdev/souclaude-harness --skill soutec-github. Copyright stays with the author.

SOUTEC — Git & GitHub

"Primero disciplina, luego automatización. Automatizar el desorden solo produce caos más rápido." — Guía Operativa v2.0

Reglas inviolables

Estas no se negocian, ni siquiera en un hotfix.

• Nunca git push origin main. main es producción. Nadie trabaja directo sobre main — tampoco el coordinador ni los administradores.
• main solo recibe merges desde dev. Las ramas de trabajo nacen de dev y su PR apunta a dev; el paso dev → main es el release, también por PR. Ninguna rama de trabajo mergea directo a main.
• Nunca hacer merge de un PR propio. El autor del cambio no mergea. El squash & merge lo hace el coordinador o el aprobador suplente.
• Nunca aprobar un PR. Nadie aprueba lo suyo.
• Nunca git push --force. Solo --force-with-lease, solo sobre rama propia, y solo si se usó rebase. Con la política por defecto (merge) no hay force-push nunca.
• Nunca commitear secretos: .env, *.pem, *.key, *.pfx, credentials.json, secrets.json, tokens, contraseñas, llaves privadas.
• Nunca crear una rama sin nombre descriptivo. Formato tipo/descripcion-corta. Si el trabajo tiene un ID rastreable — milestone del Vault, o tarea de un tracker externo — va como prefijo del slug (feature/M7-playbook-adopcion, feature/REA-123-captura-lead); si no lo hay, el slug solo. No inventes IDs.
• Una rama por milestone, no por tarea. Las tareas del kanban del Vault son commits en la rama de su milestone; el ID -T<nnn> nunca va en el nombre de la rama. Ver "Ciclo de vida de la rama del milestone".
• Nunca crear repositorios. Eso es del coordinador. Los tags de versión (vX.Y.Z y el tag móvil por major) los crea el workflow tag-release.yml al mergear el PR de release dev → main; en repos sin ese workflow instalado, el agente puede crearlos a mano en su lugar, únicamente al publicar y después del merge.
• Un hotfix NO es un bypass. Aun en máxima criticidad: rama + Pull Request.

Antes de tocar código

git checkout dev
git pull origin dev           # siempre partir de dev actualizado
git checkout -b tipo/descripcion-corta

Chequeo previo: ¿leíste el README? ¿tienes el .env local configurado?

Nombre de rama

tipo/descripcion-corta          # o tipo/ID-descripcion-corta si hay ID rastreable

El ID va en mayúsculas como prefijo del slug y es uno de estos (no inventes IDs):

• Milestone del Vault (el caso normal con Vault conectado): feature/M7-playbook-adopcion. Una rama por milestone; las tareas del milestone (SHS-M7-T001, T002, ...) se hacen como commits en esa rama. El ID de tarea -T<nnn> nunca va en el nombre de la rama. La clave del proyecto tampoco (M7-, no SHS-M7-): el repo ya pertenece a un solo proyecto del Vault (project en .claude/vault.local.json), y el monitor la completa solo al inferir el milestone. El número de milestone va en mayúscula (M7).
• Tracker externo (sin Vault): feature/REA-123-captura-lead
• Sin ID rastreable: feature/captura-lead

Ciclo de vida de la rama del milestone

Con Vault conectado, la rama y el milestone viven juntos:

1. Nace de dev al tomar el milestone (tarjeta a En curso en milestones.md), con el nombre tipo/M<n>-slug. Anota la rama en la tarjeta del milestone.
2. Cada tarea terminada son commits pusheados a esa rama. Al pushear, la tarjeta de la tarea pasa a Hecho en kanban.md en ese momento (push inmediato al Vault, espejo en la skill de sincronización instalada). No hace falta esperar a que el PR se mergee. En review queda para las tareas que el usuario quiera dejar gateadas por un PR concreto (ahí sí se anota PR #N).
3. PRs parciales admitidos. Desde la misma rama se abren tantos PRs a dev como el usuario pida (uno abierto a la vez); cada PR lista en su descripción las tareas que cubre. Tras el squash & merge de un PR parcial, se sigue en la misma rama: git fetch origin && git merge origin/dev (mergea limpio: los cambios ya integrados son idénticos a ambos lados) y a continuar. Nunca borres ni recrees la rama entre PRs parciales, y nunca push --force.
4. El milestone se cierra cuando todas sus tareas están en Hecho y el último PR está mergeado: tarjeta a Hecho en milestones.md y recién ahí se borra la rama (git branch -d).

Si un milestone resulta demasiado grande para una rama, la solución es dividir el milestone (skill vault-milestones), no abrir ramas por tarea.

feature/captura-lead
fix/error-integracion-odoo
hotfix/correccion-produccion
refactor/mejorar-estructura-api
experiment/prueba-modelo-rag

Prohibidos: cambios, prueba, final, final-final, arreglo, o el nombre de una persona.

Commits

tipo: descripción breve del cambio

Sin scope. Sin ID en el título del commit (el ID del milestone va en la rama y en el PR). Si quieres dejar rastro de qué tarea del kanban cierra un commit, ponlo en el cuerpo del mensaje (Cierra SHS-M7-T003), nunca en el título. Descripciones en español.

feat: agregar endpoint de consulta de órdenes
fix: corregir error de autenticación con Odoo
refactor: reorganizar servicio de conexión a BD

Ojo: no existe el tipo de commit hotfix. Un hotfix se commitea como fix:.

Prohibidos: update, fix, cosas, ya, ahora sí. Git tiene memoria; no le demos material para novela de misterio.

Sincronizar con dev

Por defecto, merge. Simple, no reescribe historia, no requiere force-push.

git fetch origin
git merge origin/dev
# resolver conflictos si los hay
git push origin <tu-rama>

Rebase es opcional y solo para uso avanzado: nunca sobre rama compartida, y con --force-with-lease. Como el squash & merge descarta el historial granular de la rama igual, el rebase es esencialmente cosmético.

Pull Request

El PR se abre solo a pedido explícito del usuario. Terminar un cambio no implica abrir el PR: el agente lo crea únicamente cuando el usuario lo pide ("abre el PR") o dice que quiere mergear/integrar el trabajo. Mientras tanto: commit y push a la rama, y reportar que está listo para PR. Esto evita PRs de features a medio terminar.

Antes de pedir revisión:

• El proyecto corre localmente.
• El flujo afectado está probado.
• No hay .env ni credenciales en el commit.
• El README está actualizado si aplica.
• El PR indica si requiere versión/release.

Antes de abrir el PR, delegar el security review a un subagente (Agent, tipo general-purpose) en vez de correr /security-review inline. Instrúyelo a fondo: que corra /security-review sobre el diff de la rama y devuelva los hallazgos (o la ausencia de ellos) en un resumen claro. Mientras corre, el agente principal puede seguir armando el resto del PR (plantilla, checklist).

Esto no es un capricho de estilo: correr el review en el mismo hilo hace que, tras un volcado largo de resultados, el agente principal pierda el hilo y no retome el PR. Delegarlo a un subagente convierte el resultado en un tool-result concreto que exige una reacción explícita — no una instrucción de prosa que se puede diluir.

Al recibir el resultado del subagente:

• Documentar los hallazgos (o su ausencia) en la sección "Security review" de la plantilla del PR.
• Sin hallazgos bloqueantes: seguir directo con push/PR. El security review es un paso intermedio del mismo pedido, no un punto de checkpoint.
• Con hallazgos bloqueantes: parar y preguntar al usuario si quiere remediarlos antes de continuar. No abrir el PR con hallazgos sin remediar salvo que el usuario decida explícitamente continuar así — en ese caso, dejarlo registrado en el PR.

Completa .github/pull_request_template.md de verdad. Un PR cubre una o varias tareas del milestone de la rama: en "Milestone y tareas relacionadas" van el ID del milestone y la lista de tareas que este PR integra. Checkboxes tildadas porque se hizo, no por rellenar. Nada de "N/A" genéricos: si una sección no aplica, se omite entera (título incluido), no se deja con "N/A" ni vacía.

La plantilla no se aplica sola al abrir el PR por CLI. Solo la web de GitHub la precarga; gh pr create deja el cuerpo que le pases y nada más. El flujo correcto: escribir la plantilla ya completada en un archivo temporal y abrir el PR con gh pr create --body-file <archivo>. En repos con el check reglas-pr-metadata en CI, un PR con la plantilla cruda o incompleta falla el check (secciones con el texto guía intacto, casilla de versión sin marcar): la descripción queda bien desde el alta.

Si piden correcciones: pushear a la misma rama. El PR se actualiza solo. Crear un PR nuevo por cada corrección rompe la trazabilidad y duplica el ruido.

Al editar el body de un PR a pedido del usuario, re-lanza en el mismo paso los jobs de CI fallidos de ese PR. Cambiar la descripción no re-dispara CI, y un PR suele arrastrar checks en rojo por fallos transitorios que conviene reintentar. Detecta los fallidos con gh pr checks <pr> y relánzalos con gh run rerun <run-id> --failed — solo los jobs en estado failure, no el run completo. Si no hay jobs fallidos, edita el body y no hagas nada más: no re-corras lo que ya está en verde ni informes de sobra.

Integración: squash & merge, y la hace el coordinador. Para un refactor/ grande o una migración, el coordinador puede optar por merge commit y lo registra en el PR.

Después del merge de un PR parcial (el milestone sigue abierto), quédate en la rama y sincronízala:

git fetch origin && git merge origin/dev

Después del merge del último PR del milestone (esto sí lo puedes hacer):

git checkout dev && git pull origin dev && git branch -d <tu-rama>

Versionamiento

SemVer con prefijo v: v1.2.3.

El desarrollador propone la versión editando version en package.json como parte del PR de release. Ese bump se commitea directo en dev — nunca en una rama chore aparte solo para el bump; el PR de release dev → main ya lo lleva. Tras el merge dev → main, en repos con el workflow tag-release.yml instalado, este lee esa versión del commit de merge y crea/pushea el tag inmutable vX.Y.Z y el tag móvil de la serie (v3) — es idempotente: si el tag ya existe, no falla ni duplica. En repos sin el workflow, el agente puede crearlos y pushearlos a mano en el mismo momento. Los releases de GitHub siguen siendo del coordinador; ni el workflow ni el agente los crean.

Ficha del Observatorio (OBSERVATORIO.md en el Vault)

Esta sección aplica solo si el repo tiene el Vault conectado (.claude/vault.local.json existe y apunta a un Vault válido). Sin Vault no hay ficha y no hay nada que mantener.

npx souclaude siembra Project-<PREFIJO>/OBSERVATORIO.md en el Vault desde la plantilla canónica (00-System/templates/OBSERVATORIO.md). Tres reglas sobre ella:

• Al instalar el harness: si ya tienes contexto del proyecto — por la conversación, el README o el propio código — rellena la ficha en ese mismo momento (tagline, plataforma, resumen, por qué importa, equipo) y pushéala al Vault (push directo, sin PR). No la dejes vacía esperando a que el equipo la complete; solo queda vacía cuando de verdad no hay información.
• Al abrir el PR de release dev → main: agrega el hito del release en la sección "Hitos" de la ficha en ese mismo momento, con push directo al Vault — no esperes al merge: el coordinador mergea en un momento que no controlas y la sesión puede cerrarse antes de que llegue el aviso. Formato de la línea: - YYYY-MM-DD · vX.Y.Z · resumen breve del release (fecha del día, versión propuesta en package.json y resumen del cambio principal — CHANGELOG o descripción del PR de release).
• Al confirmarse el merge y el tag: verifica el hito y corrige fecha o resumen si difieren de lo publicado. Si el PR de release se rechaza o se descarta, elimina el hito en la sesión que lo detecte. El hito no es opcional: todo tag publicado tiene su línea en "Hitos", también los releases menores.
• Cuando detectes un cambio importante del proyecto — en un release o en cualquier otro momento: alcance, plataforma, resumen, por qué importa, equipo o próximos pasos que ya no reflejan la realidad — actualiza la sección afectada y pushea al Vault en el momento. La ficha no se revisa solo al taggear: se mantiene al día cuando el proyecto cambia de verdad. Los cambios menores sin impacto en la ficha no requieren tocarla.

Secretos

Nunca en el repo. .env.example sin valores. Si una credencial se expone por accidente: rotarla, no solo borrar el commit.

Lo que esta guía NO define

No lo inventes. Si hace falta, pregunta:

• Formato del título del PR.
• Scopes de commit (feat(api):) — el formato es solo tipo: descripción.
• Trailers de commit (Co-Authored-By, Signed-off-by).
• CHANGELOG.md — el changelog es el git log de main.
• Ramas release/* — no existen.
• BREAKING CHANGE / ! de Conventional Commits.
• Git hooks, --no-verify.
• Commits firmados: no son obligatorios hoy.