Saltar a contenido

Herramientas de producción

Cómo se organiza el trabajo de MUSIC LIFE: dónde vive cada cosa, qué automatiza GitHub Actions, cómo se ve el tablero Kanban y cómo se publica el portal documental en privado. Decisión de referencia: 0032.

1. Qué hace cada pieza

Componente Responsabilidad Estado
Repositorio GitHub (ealvarpe/music-life, privado) Fuente de verdad del contenido: guía, decisiones, entregables, código En marcha
GitHub Issues Tareas ejecutables: un issue por paso del apéndice C (246), más los que se abran a mano Se crean con el workflow Board sync
GitHub Projects Kanban y roadmap de todas las fases (F0–F8): estado, asignación, fechas Necesita el secreto PROJECT_TOKEN (§4.1)
GitHub Wiki No se usa. La documentación vive versionada en docs/ y en las carpetas del apéndice F —
Claude Code local Trabajo interactivo en el ordenador de ENR o DAV Disponible
Claude Code cloud Delegación de tareas: una sesión toma un issue, trabaja en una rama y abre un PR con Closes #N Disponible
GitHub Actions CI/CD: valida el plan, construye el portal, sincroniza el tablero y lo publica Workflows en .github/workflows/
MkDocs Material Portal documental con buscador, generado desde el repositorio Se construye en cada PR
Autenticación del portal Acceso privado Cloudflare Access (§4.2); mientras tanto, artefacto privado del workflow

2. Qué es fuente de qué

  • Contenido de cada paso (qué hay que hacer, responsable, revisor, dependencias, criterio de Hecho): el apéndice C de la guía aplicada. Los issues lo copian; si hay que cambiar un paso, se cambia la guía por PR y Board sync actualiza el issue.
  • Estado, asignación y fechas: el proyecto de GitHub (campo Status, assignees, Start date y Target date).
  • Registro detallado de cada paso (rondas de revisión, procedencia, entregables): la tarjeta en Markdown de board/cards/, cuando la tiene. Si el estado escrito en la tarjeta no coincide con el proyecto, manda el proyecto.
  • Decisiones: docs/decisions/, como siempre.

3. El tablero Kanban

3.1 Campos del proyecto

Campo Tipo Qué guarda
Status selección Pendiente, Listo, En curso, En revisión, Bloqueado, Hecho (apéndice B.3): las columnas del Kanban
Phase selección F0 … F8
Step número Número del paso (para ordenar)
Level número Longitud de la cadena de dependencias hasta el paso (los del mismo nivel van en paralelo)
Owner texto Responsable del apéndice C (agente o persona)
Reviewers texto Revisa / aprueba
Needs texto Pasos previos imprescindibles
Human action selección Sí si lleva 👤
Gate texto G0 … G5 si el paso es una puerta
Start date, Target date fecha Los rellena PROD al planificar cada fase; alimentan la vista Roadmap
Assignees personas Quién responde del paso ante el equipo: ealvarpe (ENR) o David (DAV) cuando tenga cuenta

Además, cada issue lleva etiquetas (step, phase/f0 … phase/f8, human-action, gate) y el hito de su fase (F0 · Cierre del concepto, …).

3.2 Vistas recomendadas

GitHub no deja crear vistas por API, así que se crean a mano una vez (cinco minutos):

  1. Kanban · diseño Board, columnas por Status, filtro phase:F0 (cambiar la fase cuando toque), agrupar por nada, ordenar por Step.
  2. Todas las fases · diseño Board, columnas por Status, agrupar (swimlanes) por Phase.
  3. Roadmap · diseño Roadmap, fechas Start date → Target date, agrupar por Phase, marcadores de hitos.
  4. Plan completo · diseño Table, campos Step, Phase, Owner, Reviewers, Needs, Status, Assignees, ordenar por Step.
  5. Mis tareas · diseño Table, filtro assignee:@me -status:Hecho.
  6. Acciones humanas · diseño Table, filtro "Human action":Sí -status:Hecho: lo que solo puede hacer una persona.

3.3 Cómo se mueve una tarjeta

Quién Cómo
Una persona Arrastra la tarjeta en el proyecto, o cierra o reabre el issue
Un agente (Claude Code cloud o local) Añade al issue la etiqueta set-status/ready, set-status/in-progress, set-status/in-review, set-status/blocked, set-status/done o set-status/pending. El workflow Board events pone el Status y quita la etiqueta. Al añadirla, conserva las etiquetas que ya tiene el issue
Un PR Si su descripción lleva Closes #N, al fusionarlo el issue se cierra y la tarjeta pasa a Hecho

Un issue cerrado como not planned no cambia de estado. Un issue nuevo que no sea un paso del plan entra en el proyecto en Listo.

3.4 Delegar un paso en Claude Code cloud

  1. En el proyecto, elige una tarjeta en Listo.
  2. Abre una sesión de Claude Code en la nube sobre el repositorio y pásale el enlace del issue.
  3. La sesión pone set-status/in-progress, trabaja en su rama, abre el PR con Closes #N y pone set-status/in-review.
  4. Revisas y fusionas: la tarjeta pasa a Hecho.

Las reglas de revisión del apéndice B (revisor distinto, dos rondas, acciones 👤) no cambian.

4. Puesta en marcha (lo que hace ENR)

4.1 Tablero (gratis)

  1. Crear un token personal en GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic). Nombre music-life-board, caducidad 1 año, permisos repo y project. Copiar el token.
  2. Guardarlo como secreto del repositorio: Settings → Secrets and variables → Actions → New repository secret, nombre PROJECT_TOKEN.
  3. Lanzar la carga: pestaña Actions → Board sync → Run workflow. Crea etiquetas, hitos, los 246 issues y el proyecto Music Life con sus campos. La primera vez tarda unos 30–40 minutos (va despacio a propósito por los límites de GitHub). Si se corta, se vuelve a lanzar y sigue donde lo dejó.
  4. Crear las vistas de §3.2 en el proyecto.
  5. David: cuando tenga cuenta de GitHub, invitarlo al repositorio (Settings → Collaborators → Add people) y al proyecto (⋯ → Settings → Manage access). Desde ese momento se le pueden asignar issues.

Sin el token, Board sync crea igualmente los issues, etiquetas e hitos; solo falta el proyecto.

4.2 Portal documental privado (gratis, con cuenta de Cloudflare)

  1. Crear una cuenta gratuita en Cloudflare (dash.cloudflare.com). No hace falta dominio propio: el portal queda en music-life-docs.pages.dev.
  2. Token de API: My Profile → API Tokens → Create Token → plantilla Edit Cloudflare Workers o personalizado con Account · Cloudflare Pages · Edit. Copiar el token y el Account ID (aparece en la página de inicio de la cuenta).
  3. Guardar dos secretos en el repositorio: CLOUDFLARE_API_TOKEN y CLOUDFLARE_ACCOUNT_ID.
  4. Primera publicación: Actions → Docs → Run workflow sobre main. Crea el proyecto de Pages music-life-docs y publica.
  5. Cerrar el acceso con Cloudflare Zero Trust (plan Free, hasta 50 usuarios): Zero Trust → Access → Applications → Add an application → Self-hosted:
  6. Dominios: music-life-docs.pages.dev y *.music-life-docs.pages.dev.
  7. Política Allow con Emails: el de Enrique y el de David.
  8. Método de acceso: One-time PIN (llega un código al correo) o GitHub como proveedor de identidad.
  9. En el proyecto de Pages: Settings → General → Access policy → Enable (protege también las vistas previas).
  10. Comprobar en una ventana privada que la URL pide código antes de enseñar nada.

Al activar Zero Trust, Cloudflare puede pedir una tarjeta aunque el plan sea gratuito. No cobra nada mientras el equipo sea de 50 personas o menos.

4.3 Sin Cloudflare

Cada ejecución de Docs deja el portal como artefacto docs-site (14 días) en la pestaña Actions; solo lo descarga quien tiene acceso al repositorio. Para verlo en local:

pip install -r .github/requirements-docs.txt
python .github/scripts/prepare_portal.py
mkdocs serve -f build/mkdocs.yml   # http://127.0.0.1:8000

5. Workflows

Workflow Cuándo corre Qué hace
docs.yml Cada PR y cada cambio en main Comprueba que el apéndice C se lee (246 pasos), construye el portal y lo sube como artefacto; en main lo publica en Cloudflare si hay secretos
board-sync.yml Cambios en la guía o en el tablero en main, o a mano Crea y actualiza issues, etiquetas, hitos y el proyecto. Idempotente. Opciones: dry run y refresh fields
board-events.yml Al abrir, etiquetar, cerrar o reabrir un issue Mueve la tarjeta en el proyecto

Los scripts están en .github/scripts/: board_steps.py lee el apéndice C y el tablero en Markdown, sync_board.py habla con GitHub y prepare_portal.py prepara el portal (incluida la página Plan y tablero del portal con los 246 pasos).

6. Costes

Pieza Plan Coste
GitHub (repositorio privado, Issues, Projects, colaboradores) Free 0 €
GitHub Actions Free: 2.000 minutos al mes en repositorios privados 0 € (cada ejecución de Docs gasta 1–2 minutos; la carga inicial del tablero, unos 40)
MkDocs Material Código abierto 0 €
Cloudflare Pages + Access Free (hasta 50 usuarios en Access) 0 €
Alternativa descartada: GitHub Pages privado Solo con GitHub Enterprise Cloud ≈ 21 $ por usuario y mes
Alternativa descartada: contraseña en Netlify o Vercel Netlify Pro / Vercel Pro con complemento ≈ 19 $ al mes / ≈ 150 $ al mes