merge: issue/0021-dev-workflow-docs — documentación TBD y feature flags en reglas

.claude/CLAUDE.md

@@ -167,6 +167,100 @@ ANTHROPIC_API_KEY         # Anthropic/Claude
 
 Nunca commitear `.env`. Plantilla en `.env.example`.
 
+## Trunk-based development (TBD)
+
+El proyecto usa trunk-based development estricto. **master** es el único branch estable y siempre deployable.
+
+### Flujo de trabajo
+
+```
+master (trunk) ← siempre deployable, único branch permanente
+  ↑
+  └── issue/<NNNN>-<slug>  ← rama efímera (horas, no días)
+        ├── commit: feat: ...
+        ├── commit: test: ...
+        └── commit: docs: ...
+      merge --no-ff → master → push → delete branch
+```
+
+1. **`/git-branch`** — crea rama `issue/<NNNN>-<slug>` desde master actualizado
+2. Implementar en la rama con commits granulares por bloque lógico
+3. **`/git-push`** — tests → merge `--no-ff` a master → push → eliminar rama
+
+### Convención de commits
+
+Dentro de la rama, cada commit es **atómico por bloque lógico** (no mezclar feat + test en uno):
+
+| Prefijo | Uso |
+|---------|-----|
+| `feat:` | nueva funcionalidad |
+| `fix:` | corrección de error |
+| `refactor:` | cambio estructural sin cambio funcional |
+| `docs:` | documentación |
+| `chore:` | mantenimiento |
+| `test:` | tests nuevos o modificados |
+| `merge:` | commit de merge (generado por `--no-ff`) |
+
+- **Título** (`-m` corto): resumen del bloque
+- **Cuerpo** (`-m` largo): en español, explica qué, por qué, impacto y alcance
+- **No hacer commits WIP**: nada de "wip", "tmp", "fix fix" — cada commit debe tener mensaje real
+- **No squash**: `--no-ff` preserva los commits individuales; `git log --first-parent master` da la vista limpia (un merge = un issue)
+
+### Reglas de ramas
+
+- **Nunca trabajar directamente en master** — siempre crear rama con `/git-branch`
+- **Una rama por issue** — no mezclar issues en la misma rama
+- **Ramas cortas** — idealmente horas, no días
+- **Nunca pushear la rama** — solo se pushea master después del merge
+- **No rebase interactivo** — si los commits ya son limpios, no hay nada que reescribir
+
+### Feature flags — features grandes en TBD
+
+En TBD no existen ramas largas. Para features que no caben en una sola rama, se usan **feature flags**: código completo y testeado que se mergea a master pero desactivado hasta que todas las piezas estén listas.
+
+**Feature flag ≠ WIP.** Un flag protege código terminado; un WIP es código a medias. Nunca commitear código incompleto.
+
+**Cuándo usar feature flags:**
+- Feature multi-issue que requiere varias ramas para completarse
+- Cambio con riesgo que necesita poder desactivarse en producción
+- Despliegue gradual (activar para un agente primero, después para todos)
+
+**Cuándo NO usarlos:**
+- Issue autocontenido que se completa en una rama → mergear directo
+- Bug fix, refactor, docs → no necesitan flag
+
+**Flujo para features multi-issue:**
+
+```
+Feature grande (ej: 0015 Telegram)
+  ├── issue/0015a-telegram-types     → pkg/ types, flag OFF  → merge
+  ├── issue/0015b-telegram-client    → shell/ client, flag OFF → merge
+  ├── issue/0015c-telegram-listener  → integration, flag OFF → merge
+  └── issue/0015d-telegram-enable    → flag ON, cleanup → merge
+```
+
+Cada rama es corta, cada merge es seguro, master nunca se rompe.
+
+**Archivo:** `dev/feature_flags.json`
+
+```json
+{
+  "flags": {
+    "telegram-support": {
+      "enabled": false,
+      "issue": "0015",
+      "description": "Soporte multi-plataforma Telegram",
+      "added": "2026-03-07"
+    }
+  }
+}
+```
+
+### Comandos disponibles
+
+- `/git-branch` — crear rama de trabajo (`.claude/commands/git-branch.md`)
+- `/git-push` — integrar rama a master y publicar (`.claude/commands/git-push.md`)
+
 ## Preferencias del usuario
 
 - **Idioma**: español en configs/comentarios de dominio, inglés en código Go

.claude/commands/git-branch.md

@@ -52,4 +52,20 @@ Puedes empezar a trabajar. Cuando termines, usa `/git-push` para integrar a mast
 - **Formato de rama**: `issue/<NNNN>-<slug>` (siempre 4 digitos)
 - **Ramas cortas**: idealmente horas, no dias
 - **Una rama por issue**: no mezclar issues en la misma rama
-- **Nunca pushear la rama al remoto**: el push se hace desde master despues del merge (a menos que se necesite un PR de un agente)
+- **Nunca pushear la rama al remoto**: el push se hace desde master despues del merge
+- **No rebase interactivo**: si los commits son limpios desde el inicio, no reescribir historia
+- **No commits WIP**: cada commit en la rama debe ser atomico y con mensaje real (ver convencion en `/git-push`)
+
+## Features multi-issue
+
+Para features que no caben en una sola rama, usar sub-issues con sufijo letra:
+
+```
+issue/0015a-telegram-types
+issue/0015b-telegram-client
+issue/0015c-telegram-listener
+issue/0015d-telegram-enable
+```
+
+Cada sub-rama sigue el mismo flujo: crear → implementar → merge --no-ff → delete.
+El codigo parcial se protege con **feature flags** en `dev/feature_flags.json` (no con commits WIP).

.claude/commands/git-push.md

@@ -41,7 +41,7 @@ git diff --stat
 git diff
 ```
 
-Si hay cambios de distinta naturaleza, crear varios commits separados por bloque logico:
+Crear commits **atomicos por bloque logico**. Cada commit agrupa cambios de la misma naturaleza:
 
 ```bash
 git add <archivos_del_bloque_1>
@@ -51,6 +51,12 @@ git add <archivos_del_bloque_2>
 git commit -m "<tipo>: <resumen breve>" -m "Descripcion larga en espanol."
 ```
 
+**Reglas criticas de commits:**
+- **No WIP**: nunca commitear "wip", "tmp", "fix fix" ni codigo a medias. Cada commit debe ser atomico y completo.
+- **No mezclar tipos**: no combinar `feat:` + `test:` en un mismo commit. Separar por bloque logico.
+- **No squash**: los commits individuales se preservan en master via `--no-ff`. Usar `git log --first-parent master` para ver solo merge commits.
+- **No rebase interactivo**: si los commits ya son limpios, no reescribir historia.
+
 ### 3. Ejecutar tests
 
 **Obligatorio antes de mergear.** Si el proyecto tiene tests, ejecutarlos:
@@ -65,13 +71,15 @@ go test -tags goolm ./...
 
 ### 4. Evaluar feature flags
 
+Feature flags se usan cuando el issue es **parte de una feature multi-issue** o el cambio tiene riesgo y necesita poder desactivarse. **Feature flag ≠ WIP** — un flag protege codigo terminado y testeado, no codigo a medias.
+
 Si se modifico `dev/feature_flags.json` o si los cambios son parte de una feature que se despliega en fases:
 
 1. Verificar que `dev/feature_flags.json` existe y esta actualizado.
 2. Confirmar que el flag correspondiente tiene el estado correcto (`enabled: true/false`).
 3. Incluir el archivo en el commit correspondiente (no crear commit separado solo para flags).
 
-Si no aplican feature flags, saltar este paso.
+Si el issue es autocontenido (se completa en esta rama), no necesita flag. Saltar este paso.
 
 ### 5. Actualizar master y hacer merge --no-ff
 

.claude/rules/create_issue.md

@@ -47,6 +47,27 @@ Agregar una fila al final de la tabla en `dev/issues/README.md`:
 | <N> | <Titulo> | [<NNNN>-<slug>.md](<NNNN>-<slug>.md) | pendiente |
 ```
 
+## Features multi-issue (feature flags)
+
+Si la feature es demasiado grande para completarse en una sola rama corta (horas), **desglosar en sub-issues** que se implementan y mergean por separado. Cada sub-issue debe:
+
+1. Ser autocontenido: compilar, pasar tests, no romper master
+2. Proteger el codigo parcial con un **feature flag** en `dev/feature_flags.json` (desactivado hasta que todo este listo)
+3. Usar numeracion con sufijo letra: `0015a`, `0015b`, etc.
+
+**Ejemplo:**
+
+```
+0015a-telegram-types       → tipos puros en pkg/
+0015b-telegram-client      → cliente en shell/
+0015c-telegram-listener    → integracion en agents/
+0015d-telegram-enable      → activar flag, cleanup
+```
+
+Indicar en el issue principal que es multi-issue y listar los sub-issues planificados.
+
+**Feature flag ≠ WIP.** Un flag protege codigo terminado y testeado; un WIP es codigo a medias. Nunca commitear codigo incompleto a master.
+
 ## Reglas
 
 - **Patron pure core / impure shell**: toda feature debe explicar que va en `pkg/` (puro) vs `shell/` (impuro).
@@ -54,6 +75,7 @@ Agregar una fila al final de la tabla en `dev/issues/README.md`:
 - **Numeracion continua**: nunca reusar numeros de issues eliminados.
 - **Estado**: los issues nuevos siempre empiezan como `pendiente`.
 - **Completados**: cuando se termine un issue, moverlo a `dev/issues/completed/` y actualizar el README.
+- **Issues grandes**: si no cabe en una rama corta, desglosar en sub-issues con feature flags.
 
 ## Verificacion
 
@@ -61,3 +83,4 @@ Agregar una fila al final de la tabla en `dev/issues/README.md`:
 - [ ] Todas las secciones del template rellenadas
 - [ ] Fila agregada en `dev/issues/README.md`
 - [ ] Numero de issue es consecutivo (no hay saltos ni duplicados)
+- [ ] Si es multi-issue: sub-issues planificados y feature flag definido

.claude/rules/fix_issue.md

@@ -39,6 +39,9 @@ Crear un plan con `TodoWrite` basado en las tareas del issue. Respetar el orden
 - Respetar **pure core / impure shell**: `pkg/` puro, `shell/` impuro
 - Marcar cada tarea como completada en el TodoWrite conforme se avanza
 - Compilar frecuentemente: `go build -tags goolm ./...`
+- **Commits atómicos por bloque lógico** — no mezclar `feat:` + `test:` en un commit
+- **No hacer commits WIP** — nada de "wip", "tmp", "fix fix". Si no hay un bloque lógico completo, no commitear todavía
+- Cada commit lleva título corto con prefijo (`feat:`, `fix:`, `test:`, `docs:`, `refactor:`, `chore:`) y cuerpo largo en español explicando qué, por qué e impacto
 
 ### 5. Tests — OBLIGATORIO
 
@@ -59,7 +62,20 @@ go test -tags goolm ./...
 
 ### 6. Feature flags (solo si aplica)
 
-Si el issue es parte de una feature mayor que se despliega en fases, actualizar `dev/feature_flags.json`:
+En TBD no existen ramas largas. Para features que no caben en un solo issue/rama, se usan **feature flags**: código completo y testeado que se mergea a master pero desactivado.
+
+**Feature flag ≠ WIP.** Un flag protege código terminado; un WIP es código a medias. Nunca commitear código incompleto.
+
+**Cuándo usar feature flags:**
+- Este issue es **parte de una feature multi-issue** (ej: issue 0015a, 0015b, 0015c)
+- El cambio tiene **riesgo** y necesita poder desactivarse en producción
+- Se quiere **despliegue gradual** (activar para un agente primero, después para todos)
+
+**Cuándo NO usarlos:**
+- Issue autocontenido que se completa en una rama → mergear directo, sin flag
+- Bug fix, refactor, docs → no necesitan flag
+
+Si aplica, actualizar `dev/feature_flags.json`:
 
 ```json
 {
@@ -76,6 +92,18 @@ Si el issue es parte de una feature mayor que se despliega en fases, actualizar
 
 Incluir el cambio en el commit correspondiente (no crear commit separado solo para flags).
 
+**Flujo para features multi-issue:**
+
+```
+Feature grande (ej: 0015 Telegram)
+  ├── issue/0015a-telegram-types     → pkg/ types, flag OFF  → merge
+  ├── issue/0015b-telegram-client    → shell/ client, flag OFF → merge
+  ├── issue/0015c-telegram-listener  → integration, flag OFF → merge
+  └── issue/0015d-telegram-enable    → flag ON, cleanup → merge
+```
+
+Cada rama es corta, cada merge es seguro, master nunca se rompe.
+
 ### 7. Verificar
 
 - [ ] `go build -tags goolm ./...` compila sin errores

.claude/rules/index.md

@@ -20,19 +20,44 @@ Guias operativas para LLMs que trabajan en este codebase. Cada regla describe co
 - **Crear issue**: cuando el usuario pida crear un nuevo issue, feature request o task. Usa el template en `.claude/templates/issue.md`.
 - **Arreglar issue**: cuando el usuario pida implementar, arreglar o trabajar en un issue existente. Incluye crear rama (`/git-branch`), implementar las tareas con tests, cerrar el issue, e integrar a master (`/git-push`).
 
-## Flujo de desarrollo (TBD)
+## Flujo de desarrollo — Trunk-based development (TBD)
 
-El proyecto usa trunk-based development. **Nunca trabajar directamente en master.**
+El proyecto usa TBD estricto. **master** es el unico branch estable y siempre deployable. **Nunca trabajar directamente en master.**
 
-1. `/git-branch` — crea rama `issue/<NNNN>-<slug>` desde master
+```
-2. Implementar cambios + tests en la rama
+master (trunk) ← siempre deployable
-3. `/git-push` — merge --no-ff a master, push, cleanup rama
+  ↑
+  └── issue/<NNNN>-<slug>  ← rama efimera (horas, no dias)
+        ├── commit: feat: ...
+        ├── commit: test: ...
+        └── commit: docs: ...
+      merge --no-ff → master → push → delete branch
+```
 
-Comandos disponibles en `.claude/commands/`:
+1. `/git-branch` — crea rama `issue/<NNNN>-<slug>` desde master actualizado
-- `git-branch.md` — crear rama de trabajo
+2. Implementar con commits atomicos por bloque logico (no WIP, no mezclar tipos)
-- `git-push.md` — integrar rama a master y publicar
+3. `/git-push` — tests → merge `--no-ff` a master → push → eliminar rama
 
-Feature flags opcionales en `dev/feature_flags.json` (solo para features que se despliegan en fases).
+### Commits
+
+- Cada commit es **atomico por bloque logico** con prefijo: `feat:`, `fix:`, `test:`, `docs:`, `refactor:`, `chore:`
+- Titulo corto + cuerpo largo en español
+- **No WIP**: nunca commitear "wip", "tmp", codigo a medias
+- **No squash**: `--no-ff` preserva commits; `git log --first-parent` da vista limpia
+- **No rebase -i**: commits limpios desde el inicio
+
+### Feature flags (para features multi-issue)
+
+Cuando una feature no cabe en una sola rama corta, desglosar en sub-issues. Cada sub-issue mergea codigo **completo y testeado** protegido por un feature flag (desactivado). **Feature flag ≠ WIP** — un flag protege codigo terminado, no codigo a medias.
+
+Archivo: `dev/feature_flags.json`
+
+### Comandos
+
+- `/git-branch` — crear rama de trabajo (`.claude/commands/git-branch.md`)
+- `/git-push` — integrar rama a master y publicar (`.claude/commands/git-push.md`)
+
+Filosofia completa documentada en `CLAUDE.md` seccion "Trunk-based development".
 
 ## Principio general