Añadidos arhcivos basicos de repos
This commit is contained in:
@@ -0,0 +1,275 @@
|
||||
---
|
||||
version: 2.0.0
|
||||
updated: 2026-03-11
|
||||
tags: [issues, documentation, workflow, automation]
|
||||
---
|
||||
|
||||
# Command: auto-create-issue
|
||||
|
||||
Crea un issue nuevo en `dev/issues/` y lo integra automáticamente a master **sin pedir confirmación**.
|
||||
|
||||
## Para el usuario
|
||||
|
||||
### Cuándo usar este comando
|
||||
|
||||
Usar cuando estés completamente seguro del contenido del issue y quieras saltear la confirmación manual. El comando ejecuta todo el flujo automáticamente sin pausar.
|
||||
|
||||
**⚠️ Advertencia:** Este comando no pide confirmación. Si no estás seguro, usa `/issues:create-issue` en su lugar.
|
||||
|
||||
### Sintaxis
|
||||
|
||||
```bash
|
||||
/issues:auto-create
|
||||
```
|
||||
|
||||
El comando preguntará interactivamente por los datos necesarios, pero NO pausará para confirmar.
|
||||
|
||||
### Ejemplos
|
||||
|
||||
**Ejemplo 1: Issue simple automatizado**
|
||||
```bash
|
||||
/issues:auto-create
|
||||
# Título: Actualizar dependencias
|
||||
# Descripción: Upgrade de módulos Go
|
||||
```
|
||||
|
||||
Crea, commitea, mergea y pushea automáticamente sin confirmación.
|
||||
|
||||
**Ejemplo 2: Issue multi-parte automatizado**
|
||||
```bash
|
||||
/issues:auto-create
|
||||
# Título: Sistema de notificaciones
|
||||
# Descripción: Email, SMS, y push notifications
|
||||
```
|
||||
|
||||
Crea sub-issues y feature flag, integra todo automáticamente.
|
||||
|
||||
## Para Claude
|
||||
|
||||
### Precondiciones
|
||||
|
||||
Verificar antes de ejecutar:
|
||||
|
||||
- [ ] Directorio `dev/issues/` existe
|
||||
- [ ] Archivo `dev/issues/README.md` existe
|
||||
- [ ] Template `.claude/templates/issue.md` existe
|
||||
- [ ] Working tree limpio (para poder crear rama)
|
||||
|
||||
### Inputs
|
||||
|
||||
Se necesitan los datos del issue. Si no se proporcionan, preguntar:
|
||||
|
||||
- `titulo`: título corto y descriptivo
|
||||
- `descripcion`: objetivo/descripción de lo que se quiere lograr
|
||||
- `dependencias` (opcional): issues de los que depende
|
||||
|
||||
### Flujo obligatorio
|
||||
|
||||
#### 1-7. Crear el issue (igual que `/issues:create-issue`)
|
||||
|
||||
{{include: issue-numbering}}
|
||||
|
||||
**Seguir los pasos 1-7 de `/issues:create-issue`:**
|
||||
1. Determinar número del issue
|
||||
2. Generar slug
|
||||
3. Evaluar tamaño (simple vs multi-issue)
|
||||
4. Crear issue desde template
|
||||
5. Agregar sección de desglose si es multi-issue
|
||||
6. Registrar feature flag si aplica
|
||||
7. Actualizar índice en `dev/issues/README.md`
|
||||
|
||||
**⚠️ DIFERENCIA CLAVE:** NO mostrar contenido ni pedir confirmación. Continuar directamente al paso 8.
|
||||
|
||||
#### 8. Integración automática a master
|
||||
|
||||
**SIN pedir confirmación**, ejecutar el flujo completo de git:
|
||||
|
||||
##### 8.1. Crear rama quick
|
||||
|
||||
{{include: git-update-master}}
|
||||
|
||||
```bash
|
||||
git checkout master
|
||||
git pull --rebase
|
||||
git checkout -b quick/issues:create-issue-<NNNN>
|
||||
```
|
||||
|
||||
##### 8.2. Crear commits atómicos
|
||||
|
||||
**Si es issue simple:**
|
||||
|
||||
```bash
|
||||
git add dev/issues/<NNNN>-<slug>.md dev/issues/README.md
|
||||
git commit -m "docs: crear issue <NNNN>-<slug>" -m "Crea issue <NNNN>: <titulo>
|
||||
|
||||
Objetivo: <resumen del objetivo>
|
||||
|
||||
Tipo: issue simple
|
||||
Archivos: dev/issues/<NNNN>-<slug>.md, dev/issues/README.md
|
||||
|
||||
Este issue define <descripción breve del alcance>."
|
||||
```
|
||||
|
||||
**Si es multi-issue:**
|
||||
|
||||
Commit 1 (archivos de issues - SOLO sub-issues, NO archivo principal):
|
||||
```bash
|
||||
git add dev/issues/<NNNN>*.md dev/issues/README.md
|
||||
git commit -m "docs: crear sub-issues para <NNNN>-<slug>" -m "Crea sub-issues <NNNN>a-<NNNN>d: <titulo>
|
||||
|
||||
Objetivo: <resumen>
|
||||
|
||||
Sub-issues creados (sin archivo principal):
|
||||
- <NNNN>a-<sub-slug>: <alcance>
|
||||
- <NNNN>b-<sub-slug>: <alcance>
|
||||
- <NNNN>c-<sub-slug>: <alcance>
|
||||
|
||||
Cada sub-issue es autocontenido con toda la información necesaria.
|
||||
Feature flag: <nombre-del-flag> (activado en último sub-issue)."
|
||||
```
|
||||
|
||||
Commit 2 (feature flag):
|
||||
```bash
|
||||
git add dev/feature_flags.json
|
||||
git commit -m "feat: agregar feature flag <nombre-del-flag>" -m "Agrega feature flag para issue multi-issue <NNNN>-<slug>
|
||||
|
||||
Flag: <nombre-del-flag>
|
||||
Estado inicial: disabled
|
||||
Issue: <NNNN>
|
||||
Descripción: <descripción>
|
||||
|
||||
Se activará cuando todos los sub-issues estén integrados y validados."
|
||||
```
|
||||
|
||||
##### 8.3. Ejecutar tests (si aplican)
|
||||
|
||||
{{include: run-tests}}
|
||||
|
||||
```bash
|
||||
go test -tags goolm ./...
|
||||
```
|
||||
|
||||
- Si fallan → **STOP** y reportar error al usuario
|
||||
- Si pasan o no aplican → continuar
|
||||
|
||||
##### 8.4. Merge a master
|
||||
|
||||
{{include: git-merge-to-master}}
|
||||
|
||||
```bash
|
||||
git checkout master
|
||||
git pull --rebase
|
||||
git merge --no-ff quick/issues:create-issue-<NNNN> -m "merge: quick/issues:create-issue-<NNNN> — crear issue <NNNN>-<slug>" -m "Integra issue <NNNN>: <titulo>
|
||||
|
||||
Tipo: [issue simple / issue multi-issue con N sub-issues]
|
||||
Archivos: dev/issues/<NNNN>*.md, dev/issues/README.md[, dev/feature_flags.json]
|
||||
|
||||
Listo para implementación con /issues:fix-issue <NNNN>[a/b/...]"
|
||||
```
|
||||
|
||||
##### 8.5. Push a remoto
|
||||
|
||||
```bash
|
||||
git push
|
||||
```
|
||||
|
||||
##### 8.6. Limpiar rama local
|
||||
|
||||
```bash
|
||||
git branch -d quick/issues:create-issue-<NNNN>
|
||||
```
|
||||
|
||||
### Verificación final
|
||||
|
||||
Informar al usuario:
|
||||
|
||||
**Issue simple:**
|
||||
```
|
||||
✓ Issue <NNNN>-<slug> creado e integrado a master automáticamente
|
||||
|
||||
Tipo: issue simple
|
||||
Rama: quick/issues:create-issue-<NNNN> (mergeada y limpiada)
|
||||
|
||||
Archivos creados:
|
||||
- dev/issues/<NNNN>-<slug>.md
|
||||
- dev/issues/README.md (actualizado)
|
||||
|
||||
Para implementar:
|
||||
/issues:fix-issue <NNNN>
|
||||
```
|
||||
|
||||
**Issue multi-issue:**
|
||||
```
|
||||
✓ Sub-issues <NNNN>a-<NNNN>d creados e integrados a master automáticamente
|
||||
|
||||
Tipo: issue multi-issue con N sub-issues (sin archivo principal)
|
||||
Rama: quick/issues:create-issue-<NNNN> (mergeada y limpiada)
|
||||
|
||||
Archivos creados:
|
||||
- dev/issues/<NNNN>a-<sub-slug>.md
|
||||
- dev/issues/<NNNN>b-<sub-slug>.md
|
||||
- dev/issues/<NNNN>c-<sub-slug>.md
|
||||
- dev/issues/README.md (actualizado)
|
||||
- dev/feature_flags.json (actualizado)
|
||||
|
||||
⚠️ NO se creó archivo principal <NNNN>-<slug>.md (solo sub-issues)
|
||||
|
||||
Para implementar:
|
||||
/issues:fix-issue <NNNN>a [implementar sub-issues en orden]
|
||||
/issues:fix-issue <NNNN>b
|
||||
/issues:fix-issue <NNNN>c
|
||||
```
|
||||
|
||||
## Convenciones
|
||||
|
||||
- **Sin confirmación**: diferencia clave con `/issues:create-issue`
|
||||
- **Flujo idéntico**: usa la misma lógica de creación de issues
|
||||
- **Trunk-based**: usa rama `quick/` y merge inmediato
|
||||
- **Commits atómicos**: separar issues de feature flags
|
||||
- **Mismo formato**: sigue template y convenciones estándar
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "Working tree not clean"
|
||||
|
||||
**Causa:** Hay cambios pendientes que impiden crear rama.
|
||||
|
||||
**Solución:**
|
||||
```bash
|
||||
git status
|
||||
# Commitear o hacer stash de cambios primero
|
||||
git stash
|
||||
/issues:auto-create
|
||||
git stash pop
|
||||
```
|
||||
|
||||
### Error: "Tests failing"
|
||||
|
||||
**Causa:** Los tests fallan después de crear el issue (raro pero posible si se modificó feature_flags.json).
|
||||
|
||||
**Solución:**
|
||||
El comando se detiene automáticamente. Revisar logs de tests, corregir problema, y ejecutar `/git:push` manualmente para completar la integración.
|
||||
|
||||
### Error: "Merge conflict"
|
||||
|
||||
**Causa:** Alguien más modificó `dev/issues/README.md` o `dev/feature_flags.json` simultáneamente.
|
||||
|
||||
**Solución:**
|
||||
1. Resolver conflictos manualmente:
|
||||
```bash
|
||||
git status
|
||||
# Editar archivos en conflicto
|
||||
git add <archivos-resueltos>
|
||||
git commit
|
||||
git push
|
||||
git branch -d quick/issues:create-issue-<NNNN>
|
||||
```
|
||||
|
||||
## Reglas críticas
|
||||
|
||||
- **NO pedir confirmación**: este es el comportamiento esperado y correcto
|
||||
- **MISMO formato que /issues:create-issue**: no tomar atajos en la calidad del issue
|
||||
- **STOP si tests fallan**: no integrar issues que rompan el build
|
||||
- **Informar claramente al usuario**: mostrar qué se creó y cómo continuar
|
||||
- **Trunk-based estricto**: siempre usar rama quick/ y merge inmediato
|
||||
- **Commits descriptivos**: seguir convención de mensajes de commit
|
||||
@@ -0,0 +1,270 @@
|
||||
---
|
||||
version: 2.0.0
|
||||
updated: 2026-03-11
|
||||
tags: [issues, implementation, workflow, automation]
|
||||
---
|
||||
|
||||
# Command: auto-fix-issue
|
||||
|
||||
Implementa un issue completo automáticamente **sin pedir confirmación** antes de integrar a master.
|
||||
|
||||
## Para el usuario
|
||||
|
||||
### Cuándo usar este comando
|
||||
|
||||
Usar cuando estés completamente seguro de que el issue puede implementarse automáticamente sin revisión manual. El comando ejecuta todo el flujo (crear rama, implementar, testear, cerrar issue, integrar) sin pausar para confirmación.
|
||||
|
||||
**⚠️ Advertencia:** Este comando no pide confirmación antes de integrar a master. Si no estás seguro, usa `/issues:fix-issue` en su lugar.
|
||||
|
||||
### Sintaxis
|
||||
|
||||
```bash
|
||||
/issues:auto-fix <NNNN>
|
||||
/issues:auto-fix <NNNN>-<slug>
|
||||
```
|
||||
|
||||
### Ejemplos
|
||||
|
||||
**Ejemplo 1: Issue simple automatizado**
|
||||
```bash
|
||||
/issues:auto-fix 0013
|
||||
```
|
||||
|
||||
Implementa issue 0013 completo y lo integra a master sin pausar.
|
||||
|
||||
**Ejemplo 2: Por slug completo**
|
||||
```bash
|
||||
/issues:auto-fix 0013-hot-reload
|
||||
```
|
||||
|
||||
Implementa exactamente `dev/issues/0013-hot-reload.md` automáticamente.
|
||||
|
||||
## Para Claude
|
||||
|
||||
### Precondiciones
|
||||
|
||||
Verificar antes de ejecutar:
|
||||
|
||||
- [ ] Directorio `dev/issues/` existe
|
||||
- [ ] Directorio `dev/issues/completed/` existe
|
||||
- [ ] Archivo `dev/issues/README.md` existe
|
||||
- [ ] Tests configurados (go test disponible)
|
||||
- [ ] Working tree limpio
|
||||
|
||||
### Inputs
|
||||
|
||||
Se necesita el issue objetivo. Si no se proporciona, preguntar:
|
||||
|
||||
- `issue`: número o nombre (ej: `0010` o `0010-access-control`)
|
||||
|
||||
### Flujo obligatorio
|
||||
|
||||
#### 1-9. Implementar el issue (igual que `/issues:fix-issue`)
|
||||
|
||||
**Seguir los pasos 1-9 de `/issues:fix-issue`:**
|
||||
|
||||
1. Resolver el issue objetivo (verificar que existe)
|
||||
2. Leer completo el issue y extraer información
|
||||
3. Crear rama de trabajo `issue/<NNNN>-<slug>`
|
||||
4. Planificar con TodoWrite
|
||||
5. Implementar el issue completo (todas las tareas)
|
||||
6. Ejecutar tests obligatorios
|
||||
7. Evaluar feature flags (si aplica)
|
||||
8. Cerrar el issue (mover a completed/)
|
||||
9. ~~Mostrar resumen y confirmar~~ → **SKIP**
|
||||
|
||||
**⚠️ DIFERENCIA CLAVE:** NO mostrar resumen ni pedir confirmación. Continuar directamente al paso 10.
|
||||
|
||||
#### 10. Integración automática a master
|
||||
|
||||
**SIN pedir confirmación**, ejecutar el flujo completo de integración:
|
||||
|
||||
{{include: git-update-master}}
|
||||
{{include: run-tests}}
|
||||
{{include: git-merge-to-master}}
|
||||
|
||||
##### 10.1. Verificar estado final de la rama
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
git log --oneline master..HEAD
|
||||
```
|
||||
|
||||
Asegurar que:
|
||||
- No hay cambios pendientes (todo commiteado)
|
||||
- Hay al menos 1 commit (la implementación)
|
||||
- Tests pasaron en paso 6
|
||||
|
||||
##### 10.2. Checkout a master y actualizar
|
||||
|
||||
```bash
|
||||
git checkout master
|
||||
git pull --rebase
|
||||
```
|
||||
|
||||
##### 10.3. Re-ejecutar tests (verificación final)
|
||||
|
||||
```bash
|
||||
go test -tags goolm ./...
|
||||
```
|
||||
|
||||
**Si fallan:**
|
||||
- ✗ **STOP** y reportar error al usuario
|
||||
- No integrar código roto
|
||||
- Usuario debe revisar y corregir manualmente
|
||||
|
||||
**Si pasan o no aplican:**
|
||||
- ✓ Continuar
|
||||
|
||||
##### 10.4. Merge a master con --no-ff
|
||||
|
||||
```bash
|
||||
git merge --no-ff issue/<NNNN>-<slug> -m "merge: issue/<NNNN>-<slug> — <título del issue>" -m "Implementa issue <NNNN>: <título>
|
||||
|
||||
Todas las tareas completadas:
|
||||
<lista breve de lo implementado>
|
||||
|
||||
Tests: pasando
|
||||
Issue: movido a dev/issues/completed/
|
||||
|
||||
Integración automática via /issues:auto-fix"
|
||||
```
|
||||
|
||||
##### 10.5. Push a remoto
|
||||
|
||||
```bash
|
||||
git push
|
||||
```
|
||||
|
||||
**Si falla:**
|
||||
- Error "rejected - non-fast-forward" → alguien pusheó antes
|
||||
- Solución: `git pull --rebase && git push`
|
||||
- Si hay conflictos, reportar al usuario para resolución manual
|
||||
|
||||
##### 10.6. Limpiar rama local
|
||||
|
||||
```bash
|
||||
git branch -d issue/<NNNN>-<slug>
|
||||
```
|
||||
|
||||
### Verificación final
|
||||
|
||||
Informar al usuario con resumen completo:
|
||||
|
||||
```
|
||||
✓ Issue <NNNN>-<slug> completado e integrado a master automáticamente
|
||||
|
||||
Rama: issue/<NNNN>-<slug> (mergeada y limpiada)
|
||||
Commits integrados: <N>
|
||||
Tests: pasando
|
||||
Issue: movido a dev/issues/completed/
|
||||
|
||||
Archivos modificados:
|
||||
<lista de archivos principales>
|
||||
|
||||
Master actualizado y sincronizado con remoto.
|
||||
|
||||
NOTA: Integración automática sin confirmación previa.
|
||||
```
|
||||
|
||||
## Convenciones
|
||||
|
||||
- **Sin confirmación**: diferencia clave con `/issues:fix-issue`
|
||||
- **Flujo idéntico**: usa la misma lógica de implementación
|
||||
- **Tests obligatorios**: STOP si fallan, no integrar código roto
|
||||
- **Commits durante implementación**: no al final
|
||||
- **Mismas reglas de calidad**: no tomar atajos por ser automático
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "Issue not found"
|
||||
|
||||
**Causa:** El archivo del issue no existe en `dev/issues/`
|
||||
|
||||
**Solución:**
|
||||
```bash
|
||||
ls dev/issues/
|
||||
# Verificar número o slug correcto
|
||||
# O crear el issue primero con /issues:create-issue
|
||||
```
|
||||
|
||||
### Error: "Tests failing during merge"
|
||||
|
||||
**Causa:** Tests fallaron en la verificación final antes de merge
|
||||
|
||||
**Solución:**
|
||||
El comando se detiene automáticamente. La rama `issue/<NNNN>-<slug>` sigue existiendo con todos los cambios.
|
||||
|
||||
Para continuar:
|
||||
1. Cambiar a la rama:
|
||||
```bash
|
||||
git checkout issue/<NNNN>-<slug>
|
||||
```
|
||||
|
||||
2. Ver qué tests fallan:
|
||||
```bash
|
||||
go test -v -tags goolm ./...
|
||||
```
|
||||
|
||||
3. Corregir el problema y commitear fix
|
||||
|
||||
4. Ejecutar `/git:push` manualmente para completar integración
|
||||
|
||||
### Error: "Merge conflict during rebase/merge"
|
||||
|
||||
**Causa:** Alguien más modificó archivos que también modificaste
|
||||
|
||||
**Solución:**
|
||||
El comando se detiene. Resolver manualmente:
|
||||
|
||||
1. Ver conflictos:
|
||||
```bash
|
||||
git status
|
||||
```
|
||||
|
||||
2. Resolver conflictos en cada archivo
|
||||
|
||||
3. Completar merge:
|
||||
```bash
|
||||
git add <archivos-resueltos>
|
||||
git commit
|
||||
git push
|
||||
git branch -d issue/<NNNN>-<slug>
|
||||
```
|
||||
|
||||
### Error: "Working tree not clean at start"
|
||||
|
||||
**Causa:** Hay cambios sin commitear al iniciar el comando
|
||||
|
||||
**Solución:**
|
||||
```bash
|
||||
git status
|
||||
# Commitear o hacer stash de cambios
|
||||
git stash
|
||||
/issues:auto-fix <NNNN>
|
||||
git stash pop
|
||||
```
|
||||
|
||||
### Advertencia: "Implementation incomplete"
|
||||
|
||||
**Causa:** El comando implementó parcialmente pero no todas las tareas del issue
|
||||
|
||||
**Solución:**
|
||||
Esto NO debería ocurrir. Si ocurre:
|
||||
1. Revisar el issue para ver qué faltó
|
||||
2. Completar manualmente las tareas faltantes
|
||||
3. Usar `/git:push` para integrar
|
||||
4. Reportar el problema para mejorar el comando
|
||||
|
||||
## Reglas críticas
|
||||
|
||||
- **NO pedir confirmación**: este es el comportamiento esperado
|
||||
- **MISMA calidad que /issues:fix-issue**: no tomar atajos
|
||||
- **STOP si tests fallan**: no integrar código roto nunca
|
||||
- **Implementar TODAS las tareas**: no parcial
|
||||
- **Respetar arquitectura**: pure core / impure shell
|
||||
- **Commits atómicos**: durante implementación, no al final
|
||||
- **SIEMPRE usar -tags goolm**: en build y test
|
||||
- **Informar claramente**: mostrar qué se hizo y resultado
|
||||
- **NO inventar soluciones**: seguir tareas del issue estrictamente
|
||||
- **Manejo de errores**: si algo falla, detener y reportar al usuario
|
||||
@@ -0,0 +1,236 @@
|
||||
---
|
||||
version: 1.0.0
|
||||
updated: 2026-03-13
|
||||
tags: [issues, workspace, batch, orchestration]
|
||||
---
|
||||
|
||||
# Command: create-batch
|
||||
|
||||
Crea múltiples issues en workspaces hijos a partir de un archivo YAML, pidiendo confirmación antes de proceder.
|
||||
|
||||
## Para el usuario
|
||||
|
||||
### Cuándo usar este comando
|
||||
|
||||
Usar cuando necesites crear la misma issue (o issues relacionadas) en múltiples workspaces simultáneamente. Ideal para migraciones, estandarizaciones o lanzamientos coordinados.
|
||||
|
||||
### Sintaxis
|
||||
|
||||
```bash
|
||||
/issues:create-batch <path-to-yaml>
|
||||
```
|
||||
|
||||
### Formato YAML esperado
|
||||
|
||||
```yaml
|
||||
# migration-issues.yaml
|
||||
issues:
|
||||
- workspace: auth-service
|
||||
number: "0010"
|
||||
slug: migrate-to-v2-schema
|
||||
title: Migrate to v2 database schema
|
||||
description: Update database schema to v2 with new user fields
|
||||
tags: [database, migration]
|
||||
status: pending
|
||||
|
||||
- workspace: payment-service
|
||||
number: "0008"
|
||||
slug: migrate-to-v2-schema
|
||||
title: Migrate to v2 database schema
|
||||
description: Update database schema to v2 with new payment fields
|
||||
tags: [database, migration]
|
||||
status: pending
|
||||
|
||||
- workspace: notification-service
|
||||
number: "0005"
|
||||
slug: migrate-to-v2-schema
|
||||
title: Migrate to v2 database schema
|
||||
description: Update database schema to v2 with new notification fields
|
||||
tags: [database, migration]
|
||||
status: pending
|
||||
```
|
||||
|
||||
**Campos obligatorios por entry:** `workspace`, `number`, `slug`, `title`
|
||||
**Campos opcionales:** `description`, `tags`, `status` (default: `pending`)
|
||||
|
||||
**Restricciones de formato:**
|
||||
- `number`: exactamente 4 dígitos opcionalmente seguidos de una letra minúscula (ej: `0001`, `0012a`)
|
||||
- `slug`: lowercase alfanumérico con guiones, sin guiones al inicio o final (ej: `implement-auth`)
|
||||
- `status`: `pending`, `in_progress`, o `completed`
|
||||
|
||||
### Ejemplos
|
||||
|
||||
**Ejemplo 1: Creación batch de migración**
|
||||
```bash
|
||||
/issues:create-batch migration-issues.yaml
|
||||
```
|
||||
|
||||
Crea la misma issue de migración en tres workspaces diferentes.
|
||||
|
||||
**Ejemplo 2: Onboarding de nuevos servicios**
|
||||
```bash
|
||||
/issues:create-batch new-services-setup.yaml
|
||||
```
|
||||
|
||||
## Para Claude
|
||||
|
||||
### Precondiciones
|
||||
|
||||
Verificar antes de ejecutar:
|
||||
|
||||
- [ ] El argumento del comando es un path a un archivo YAML
|
||||
- [ ] El archivo YAML existe y es legible
|
||||
- [ ] `dev/feature_flags.json` tiene `centralized_issue_orchestration` habilitado (opcional, advertir si no)
|
||||
|
||||
### Inputs
|
||||
|
||||
- `yamlPath`: path al archivo YAML (argumento obligatorio del comando)
|
||||
|
||||
Si no se proporciona el path, solicitarlo al usuario.
|
||||
|
||||
### Flujo obligatorio
|
||||
|
||||
#### 1. Leer y validar el archivo YAML
|
||||
|
||||
Leer el archivo YAML indicado y parsearlo. Verificar:
|
||||
- El archivo existe
|
||||
- El YAML es sintácticamente válido
|
||||
- La estructura tiene clave `issues` con al menos una entrada
|
||||
- Cada entrada tiene campos obligatorios (`workspace`, `number`, `slug`, `title`)
|
||||
|
||||
Si hay errores de validación, mostrarlos todos antes de detenerse.
|
||||
|
||||
#### 2. Mostrar plan de creación
|
||||
|
||||
Mostrar al usuario lo que se va a crear:
|
||||
|
||||
```
|
||||
Plan de creación:
|
||||
workspace-1: 0010-migrate-to-v2-schema
|
||||
workspace-2: 0008-migrate-to-v2-schema
|
||||
workspace-3: 0005-migrate-to-v2-schema
|
||||
|
||||
Total: 3 issues en 3 workspaces
|
||||
```
|
||||
|
||||
#### 3. Verificar workspaces disponibles
|
||||
|
||||
Para cada workspace en el YAML, verificar que existe en `config.ReposBasePath`.
|
||||
Si algún workspace no existe, advertir al usuario pero no detener el proceso (se reportará como fallo en el reporte final).
|
||||
|
||||
#### 4. Pedir confirmación
|
||||
|
||||
```
|
||||
¿Proceder con la creación? (s/n):
|
||||
```
|
||||
|
||||
- Si responde afirmativo → continuar
|
||||
- Si responde negativo → **STOP**: "Operación cancelada. No se crearon issues."
|
||||
|
||||
#### 5. Ejecutar creación via app.CreateIssuesBatchCommand
|
||||
|
||||
Invocar la lógica app layer para crear cada issue:
|
||||
- Validar spec con `core.ValidateIssueSpec()`
|
||||
- Verificar workspace existe con `shell.WorkspaceExists()`
|
||||
- Verificar issue no existe con `shell.IssueExists()`
|
||||
- Crear issue con `shell.CreateIssueFile()`
|
||||
|
||||
El proceso continúa aunque fallen issues individuales (partial failure).
|
||||
|
||||
#### 6. Mostrar reporte detallado
|
||||
|
||||
```
|
||||
Creando issues...
|
||||
✓ auth-service/0010-migrate-to-v2-schema.md
|
||||
✓ payment-service/0008-migrate-to-v2-schema.md
|
||||
✗ notification-service: workspace no existe
|
||||
|
||||
Resultado:
|
||||
2/3 issues creadas exitosamente
|
||||
1 fallo(s):
|
||||
- notification-service/0005-migrate-to-v2-schema: workspace no existe
|
||||
```
|
||||
|
||||
#### 7. Si hubo fallos, indicar cómo resolver
|
||||
|
||||
Para cada fallo:
|
||||
- Si es "workspace no existe": `dataforge workspace create <nombre>`
|
||||
- Si es "issue ya existe": verificar con `ls workspaces/<nombre>/dev/issues/`
|
||||
- Si es error de validación: corregir el YAML y reintentar
|
||||
|
||||
### Verificación final
|
||||
|
||||
Informar al usuario:
|
||||
|
||||
```
|
||||
✓ Batch completado: X/Y issues creadas
|
||||
|
||||
Archivos creados:
|
||||
workspaces/<workspace>/dev/issues/<number>-<slug>.md
|
||||
...
|
||||
|
||||
Para ejecutarlas en paralelo: /issues:execute-parallel <plan.yaml>
|
||||
```
|
||||
|
||||
## Convenciones
|
||||
|
||||
- **Partial failure**: nunca abortar el batch por fallos individuales — reportar al final
|
||||
- **Confirmación obligatoria**: siempre pedir confirmación antes de crear
|
||||
- **Sin auto-commit**: no hacer commit automático, dejar que el usuario gestione git
|
||||
- **Idempotente**: si el issue ya existe, reportar como fallo, no sobrescribir
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "YAML parse error"
|
||||
|
||||
**Causa:** El archivo YAML tiene errores de sintaxis.
|
||||
|
||||
**Solución:**
|
||||
```bash
|
||||
# Verificar sintaxis con un linter
|
||||
cat batch.yaml
|
||||
# Revisar indentación y caracteres especiales
|
||||
```
|
||||
|
||||
Errores comunes:
|
||||
- Números sin comillas: `number: 0001` → `number: "0001"`
|
||||
- Tags sin lista: `tags: backend,auth` → `tags: [backend, auth]`
|
||||
|
||||
### Error: "workspace X does not exist"
|
||||
|
||||
**Causa:** El workspace no está creado en el sistema.
|
||||
|
||||
**Solución:**
|
||||
```bash
|
||||
# Crear el workspace primero
|
||||
/workspace:create-repo <nombre>
|
||||
# O importarlo si ya existe en Gitea
|
||||
/workspace:import-repo <nombre>
|
||||
```
|
||||
|
||||
### Error: "issue already exists"
|
||||
|
||||
**Causa:** Ya existe un issue con ese número en el workspace.
|
||||
|
||||
**Solución:**
|
||||
```bash
|
||||
# Ver issues existentes en el workspace
|
||||
ls workspaces/<nombre>/dev/issues/
|
||||
# Usar un número diferente o verificar si ya está implementado
|
||||
```
|
||||
|
||||
### Error: "batch file contains no issues"
|
||||
|
||||
**Causa:** El archivo YAML está vacío o tiene `issues: []`.
|
||||
|
||||
**Solución:**
|
||||
Agregar al menos una entrada al archivo YAML con todos los campos obligatorios.
|
||||
|
||||
## Reglas críticas
|
||||
|
||||
- **Confirmación obligatoria**: nunca crear sin confirmación del usuario
|
||||
- **Partial failure permitido**: continuar aunque fallen issues individuales
|
||||
- **Sin sobrescritura**: nunca sobrescribir issues existentes
|
||||
- **Validación completa**: validar YAML y specs antes de mostrar el plan
|
||||
- **Reporte detallado**: siempre mostrar qué se creó y qué falló
|
||||
- **Sin auto-commit**: dejar git al usuario
|
||||
@@ -0,0 +1,289 @@
|
||||
---
|
||||
version: 2.0.0
|
||||
updated: 2026-03-11
|
||||
tags: [issues, documentation, workflow]
|
||||
---
|
||||
|
||||
# Command: create-issue
|
||||
|
||||
Crea un issue nuevo en `dev/issues/` con confirmación del usuario. Si el issue es grande, lo desglosa automáticamente en sub-issues con feature flags.
|
||||
|
||||
## Para el usuario
|
||||
|
||||
### Cuándo usar este comando
|
||||
|
||||
Usar cuando necesites documentar una nueva tarea, feature o fix antes de implementarlo. El comando crea la estructura completa del issue y pide confirmación antes de integrarlo.
|
||||
|
||||
### Sintaxis
|
||||
|
||||
```bash
|
||||
/issues:create-issue
|
||||
```
|
||||
|
||||
El comando preguntará interactivamente por los datos necesarios.
|
||||
|
||||
### Ejemplos
|
||||
|
||||
**Ejemplo 1: Issue simple**
|
||||
```bash
|
||||
/issues:create-issue
|
||||
# Título: Hot reload de configuración
|
||||
# Descripción: Permitir recargar config sin reiniciar
|
||||
```
|
||||
|
||||
Crea `dev/issues/NNNN-hot-reload.md` y pide confirmación.
|
||||
|
||||
**Ejemplo 2: Issue multi-parte**
|
||||
```bash
|
||||
/issues:create-issue
|
||||
# Título: Integración completa con Telegram
|
||||
# Descripción: Cliente, listener, y handlers para Telegram
|
||||
```
|
||||
|
||||
Detecta que es grande y crea sub-issues (NNNN a, b, c...) con feature flag.
|
||||
|
||||
## Para Claude
|
||||
|
||||
### Precondiciones
|
||||
|
||||
Verificar antes de ejecutar:
|
||||
|
||||
- [ ] Directorio `dev/issues/` existe
|
||||
- [ ] Archivo `dev/issues/README.md` existe
|
||||
- [ ] Template `.claude/templates/issue.md` existe
|
||||
|
||||
### Inputs
|
||||
|
||||
Se necesitan los datos del issue. Si no se proporcionan, preguntar:
|
||||
|
||||
- `titulo`: título corto y descriptivo (ej: "Hot reload de configuración")
|
||||
- `descripcion`: objetivo/descripción de lo que se quiere lograr
|
||||
- `dependencias` (opcional): issues de los que depende (ej: "Requiere issue 0010")
|
||||
|
||||
### Flujo obligatorio
|
||||
|
||||
#### 1. Determinar el número del issue
|
||||
|
||||
{{include: issue-numbering}}
|
||||
|
||||
```bash
|
||||
ls dev/issues/ dev/issues/completed/ | grep -oP '^\d{4}' | sort -rn | head -1
|
||||
```
|
||||
|
||||
El próximo issue será: número_más_alto + 1 (formato 4 dígitos)
|
||||
|
||||
#### 2. Generar slug
|
||||
|
||||
A partir del título:
|
||||
- Lowercase
|
||||
- Palabras separadas por guiones
|
||||
- Conciso (2-4 palabras)
|
||||
- Ejemplo: "Hot reload de configuración" → `hot-reload`
|
||||
|
||||
#### 3. Evaluar tamaño del issue
|
||||
|
||||
Analizar el alcance y determinar si cabe en **una sola rama corta (horas)**.
|
||||
|
||||
**Criterios para desglosar en sub-issues:**
|
||||
- Toca más de 2 capas del patrón (core/ + shell/ + app/)
|
||||
- Requiere más de ~3 fases de implementación
|
||||
- El usuario lo indica explícitamente
|
||||
- La descripción implica múltiples componentes independientes
|
||||
|
||||
**Si es issue simple:**
|
||||
- Crear un solo archivo `dev/issues/<NNNN>-<slug>.md`
|
||||
- Continuar al paso 4
|
||||
|
||||
**Si es issue grande:**
|
||||
- NO crear archivo principal (no se necesita `dev/issues/<NNNN>-<slug>.md`)
|
||||
- Crear SOLO sub-issues `dev/issues/<NNNN><letra>-<sub-slug>.md`
|
||||
- Cada sub-issue debe ser autocontenido con toda la información necesaria
|
||||
- Agregar feature flag para coordinar sub-issues
|
||||
- Continuar al paso 4
|
||||
|
||||
#### 4. Crear el issue desde el template
|
||||
|
||||
Copiar `.claude/templates/issue.md` y rellenar **todas** las secciones:
|
||||
|
||||
- **Metadata**: ID, estado (pendiente), prioridad, tipo
|
||||
- **Objetivo**: 1-3 frases claras
|
||||
- **Contexto**: qué existe, qué falta, dependencias
|
||||
- **Arquitectura**: archivos afectados (marcar `NEW` los nuevos)
|
||||
- **Patrón pure/impure**: qué va en `core/` vs `shell/` vs `app/`
|
||||
- **Tareas**: fases con tareas numeradas (1.1, 1.2, etc.)
|
||||
- **Ejemplo de uso**: flujo concreto con código
|
||||
- **Decisiones de diseño**: justificaciones clave
|
||||
- **Prerequisitos**: qué debe existir antes
|
||||
- **Riesgos**: problemas potenciales y mitigación
|
||||
- **Criterios de aceptación**: checklist de completitud
|
||||
|
||||
#### 5. Para issues multi-issue — contenido en sub-issues
|
||||
|
||||
Ya que NO se crea archivo principal, cada sub-issue debe ser autocontenido:
|
||||
|
||||
**En cada sub-issue incluir:**
|
||||
- Objetivo específico del sub-issue
|
||||
- Contexto: parte de qué feature mayor (ej: "Parte 1 de 4 del sistema de distribución .claude")
|
||||
- Relación con otros sub-issues (dependencias, orden sugerido)
|
||||
- Tareas específicas de este sub-issue
|
||||
- Referencia al feature flag compartido
|
||||
|
||||
**En el PRIMER sub-issue (NNNNa) agregar tabla de coordinación:**
|
||||
|
||||
```markdown
|
||||
## Coordinación multi-issue
|
||||
|
||||
Este issue es parte de una implementación dividida en sub-issues:
|
||||
|
||||
| Sub-issue | Alcance | Estado |
|
||||
|-----------|---------|--------|
|
||||
| <NNNN>a-<slug> (este) | <qué cubre> | pendiente |
|
||||
| <NNNN>b-<slug> | <qué cubre> | pendiente |
|
||||
| <NNNN>c-<slug> | <qué cubre> | pendiente |
|
||||
|
||||
### Feature flag compartido
|
||||
|
||||
Nombre: `<nombre-del-flag>`
|
||||
Se activa en el último sub-issue (<NNNN>d) cuando todo está integrado.
|
||||
```
|
||||
|
||||
#### 6. Registrar feature flag (solo multi-issue)
|
||||
|
||||
Actualizar `dev/feature_flags.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"<nombre-del-flag>": {
|
||||
"enabled": false,
|
||||
"issue": "<NNNN>",
|
||||
"description": "<descripción breve>",
|
||||
"added": "<YYYY-MM-DD>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 7. Actualizar el índice
|
||||
|
||||
En `dev/issues/README.md`, agregar filas al final de la tabla.
|
||||
|
||||
**Issue simple:**
|
||||
```markdown
|
||||
| <N> | <Titulo> | [<NNNN>-<slug>.md](<NNNN>-<slug>.md) | pendiente |
|
||||
```
|
||||
|
||||
**Issue multi-issue (solo sub-issues, NO archivo principal):**
|
||||
```markdown
|
||||
| <N>a | <Titulo> (parte a) | [<NNNN>a-<slug>.md](<NNNN>a-<slug>.md) | pendiente |
|
||||
| <N>b | <Titulo> (parte b) | [<NNNN>b-<slug>.md](<NNNN>b-<slug>.md) | pendiente |
|
||||
| <N>c | <Titulo> (parte c) | [<NNNN>c-<slug>.md](<NNNN>c-<slug>.md) | pendiente |
|
||||
```
|
||||
|
||||
⚠️ **IMPORTANTE:** NO agregar fila para `<NNNN>-<slug>.md` ya que este archivo no se crea.
|
||||
|
||||
#### 8. Mostrar el issue creado y confirmar
|
||||
|
||||
{{include: ask-user-confirm}}
|
||||
|
||||
**Mostrar al usuario el contenido completo:**
|
||||
|
||||
**Issue simple:**
|
||||
```bash
|
||||
cat dev/issues/<NNNN>-<slug>.md
|
||||
```
|
||||
|
||||
**Issue multi-issue:**
|
||||
Mostrar resumen de sub-issues creados y el contenido del primer sub-issue:
|
||||
```bash
|
||||
echo "Sub-issues creados:"
|
||||
ls -1 dev/issues/<NNNN>*.md
|
||||
echo -e "\n=== Contenido del primer sub-issue (<NNNN>a) ==="
|
||||
cat dev/issues/<NNNN>a-<slug>.md
|
||||
```
|
||||
|
||||
**Pausar y preguntar:**
|
||||
|
||||
**Issue simple:**
|
||||
```
|
||||
Issue creado: <NNNN>-<slug>
|
||||
|
||||
¿Te parece bien el issue?
|
||||
- Si es correcto: se hará commit y push automáticamente
|
||||
- Si necesitas ajustes: puedes editarlo manualmente antes
|
||||
```
|
||||
|
||||
**Issue multi-issue:**
|
||||
```
|
||||
Issues creados: <NNNN>a, <NNNN>b, <NNNN>c (sin archivo principal)
|
||||
|
||||
¿Te parecen bien los sub-issues?
|
||||
- Si es correcto: se hará commit y push automáticamente
|
||||
- Si necesitas ajustes: puedes editarlos manualmente antes
|
||||
```
|
||||
|
||||
**Esperar respuesta del usuario:**
|
||||
- Si responde afirmativo → continuar al paso 9
|
||||
- Si responde negativo → **STOP**: "Edita los archivos y ejecuta `/git:push` cuando estés listo"
|
||||
|
||||
#### 9. Ejecutar /git:push automáticamente
|
||||
|
||||
Una vez confirmado, ejecutar `/git:push` para:
|
||||
1. Crear rama `quick/issues:create-issue-<NNNN>` automáticamente
|
||||
2. Commitear archivos (`dev/issues/<NNNN>*.md`, `dev/issues/README.md`, `dev/feature_flags.json` si aplica)
|
||||
3. Mergear a master con --no-ff
|
||||
4. Push a remoto
|
||||
5. Limpiar rama local
|
||||
|
||||
### Verificación final
|
||||
|
||||
Informar al usuario:
|
||||
|
||||
```
|
||||
✓ Issue <NNNN>-<slug> creado e integrado a master
|
||||
|
||||
Tipo: [issue simple / issue multi-issue con N sub-issues]
|
||||
Rama: quick/issues:create-issue-<NNNN> (mergeada y limpiada)
|
||||
|
||||
Para implementar:
|
||||
/issues:fix-issue <NNNN> [si es simple]
|
||||
/issues:fix-issue <NNNN>a [si es multi-issue, implementar sub-issues en orden]
|
||||
```
|
||||
|
||||
## Convenciones
|
||||
|
||||
- **Numeración continua**: nunca saltar números ni reusar
|
||||
- **Estado inicial**: siempre `pendiente`
|
||||
- **Issues cortos**: máximo horas de implementación por rama
|
||||
- **Sub-issues autocontenidos**: cada uno debe compilar y pasar tests independientemente
|
||||
- **Feature flags != WIP**: protegen código terminado, no código a medias
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "Template file not found"
|
||||
|
||||
**Causa:** No existe `.claude/templates/issue.md`
|
||||
|
||||
**Solución:**
|
||||
Crear el template desde el proyecto base o consultar documentación.
|
||||
|
||||
### Error: "Cannot determine next issue number"
|
||||
|
||||
**Causa:** No hay issues previos en `dev/issues/` o `dev/issues/completed/`
|
||||
|
||||
**Solución:**
|
||||
Comenzar con `0001` como primer issue.
|
||||
|
||||
### Advertencia: "Issue número ya existe"
|
||||
|
||||
**Causa:** Ya existe un archivo con ese número.
|
||||
|
||||
**Solución:**
|
||||
Verificar manualmente y usar el siguiente número disponible.
|
||||
|
||||
## Reglas críticas
|
||||
|
||||
- **Seguir template estrictamente**: no omitir secciones
|
||||
- **Patrón pure core / impure shell**: toda feature debe explicar qué va en `core/` vs `shell/`
|
||||
- **Tareas atómicas**: cada tarea debe ser implementable independientemente
|
||||
- **Numeración sin gaps**: siempre consecutiva
|
||||
- **Confirmación obligatoria**: siempre esperar aprobación del usuario antes de integrar
|
||||
- **Issues grandes**: desglosar en sub-issues con feature flags, nunca ramas de larga duración
|
||||
@@ -0,0 +1,359 @@
|
||||
---
|
||||
version: 1.0.0
|
||||
updated: 2026-03-11
|
||||
tags: [issues, parallel, execution, automation, worktree, golang]
|
||||
---
|
||||
|
||||
# Command: execute-parallel-issues
|
||||
|
||||
Ejecuta automáticamente las issues de un grupo paralelo del plan generado por `/issues:parallel`. Crea worktrees, ejecuta `/issues:fix-issue` en cada uno, mergea los cambios y limpia los worktrees al finalizar.
|
||||
|
||||
**Flujo completo:**
|
||||
1. Validar que existe `PARALLEL_EXECUTION_ORDER.md`
|
||||
2. Compilar programa Go si es necesario
|
||||
3. Ejecutar el orquestador Go para el grupo especificado
|
||||
4. El programa Go maneja:
|
||||
- Creación de worktrees y ramas
|
||||
- Ejecución paralela de `claude -p /issues:fix-issue`
|
||||
- Push de cada rama al completar
|
||||
- Limpieza de worktrees y ramas
|
||||
- Logging estructurado en `logs/`
|
||||
|
||||
## Para el usuario
|
||||
|
||||
### Cuándo usar este comando
|
||||
|
||||
- Después de ejecutar `/issues:parallel` y revisar el plan
|
||||
- Cuando quieres ejecutar issues automáticamente
|
||||
- Para aprovechar la ejecución paralela de issues independientes
|
||||
- Cuando prefieres automatización completa vs ejecutar manualmente cada issue
|
||||
|
||||
### Sintaxis
|
||||
|
||||
```bash
|
||||
# Ejecutar TODOS los grupos secuencialmente (por defecto)
|
||||
/issues:execute-parallel [--sequential]
|
||||
|
||||
# Ejecutar un grupo específico
|
||||
/issues:execute-parallel --group <numero> [--sequential]
|
||||
```
|
||||
|
||||
### Parámetros
|
||||
|
||||
- `--group <numero>` (opcional): Ejecutar solo un grupo específico (1, 2, 3, etc.). Si no se especifica, ejecuta TODOS los grupos.
|
||||
- `--sequential` (opcional): Ejecutar issues una por una en vez de en paralelo
|
||||
|
||||
### Ejemplos
|
||||
|
||||
**Ejemplo 1: Ejecutar TODOS los grupos (comportamiento por defecto)**
|
||||
|
||||
```bash
|
||||
/issues:execute-parallel
|
||||
```
|
||||
|
||||
**Ejemplo 2: Ejecutar solo el Grupo 1**
|
||||
|
||||
```bash
|
||||
/issues:execute-parallel --group 1
|
||||
```
|
||||
|
||||
**Ejemplo 3: Ejecutar TODOS los grupos secuencialmente (sin paralelismo)**
|
||||
|
||||
```bash
|
||||
/issues:execute-parallel --sequential
|
||||
```
|
||||
|
||||
Comportamiento por defecto:
|
||||
- Ejecuta todos los grupos secuencialmente: Grupo 1 → Grupo 2 → Grupo 3 → etc.
|
||||
- Dentro de cada grupo, las issues se ejecutan en paralelo
|
||||
- Genera resumen consolidado de TODOS los grupos al final
|
||||
- Log detallado en `logs/consolidated-summary.txt`
|
||||
|
||||
## Para Claude
|
||||
|
||||
### Precondiciones
|
||||
|
||||
Verificar antes de ejecutar:
|
||||
|
||||
- [ ] Si no existe `PARALLEL_EXECUTION_ORDER.md`, generarlo automáticamente con `/issues:parallel`
|
||||
- [ ] El usuario está en la rama correcta (usualmente `main`)
|
||||
- [ ] No hay cambios sin commitear que puedan causar conflictos
|
||||
|
||||
### Inputs
|
||||
|
||||
**Por defecto, ejecuta TODOS los grupos automáticamente.** No es necesario preguntar al usuario.
|
||||
|
||||
Parámetros opcionales:
|
||||
- `--group <numero>` (opcional): Ejecutar solo un grupo específico
|
||||
- `--sequential` (opcional): Ejecutar secuencialmente en vez de en paralelo
|
||||
|
||||
**IMPORTANTE:** Si no se especifica `--group`, ejecuta todos los grupos automáticamente.
|
||||
|
||||
### Flujo obligatorio
|
||||
|
||||
#### 1. Validar precondiciones
|
||||
|
||||
```bash
|
||||
# Verificar que existe el plan, si no existe, generarlo automáticamente
|
||||
if [ ! -f "PARALLEL_EXECUTION_ORDER.md" ]; then
|
||||
echo "📋 PARALLEL_EXECUTION_ORDER.md no existe, generando plan automáticamente..."
|
||||
echo ""
|
||||
|
||||
# Ejecutar /issues:parallel para generar el plan
|
||||
claude -p /issues:parallel
|
||||
|
||||
# Verificar que se generó correctamente
|
||||
if [ ! -f "PARALLEL_EXECUTION_ORDER.md" ]; then
|
||||
echo "❌ Error: No se pudo generar PARALLEL_EXECUTION_ORDER.md"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "✓ Plan de ejecución generado exitosamente"
|
||||
echo ""
|
||||
fi
|
||||
|
||||
# Verificar que no hay cambios sin commitear (solo advertir, no bloquear)
|
||||
UNCOMMITTED=$(git status --porcelain | wc -l)
|
||||
if [ "$UNCOMMITTED" -gt 0 ]; then
|
||||
echo "⚠️ Advertencia: Hay cambios sin commitear"
|
||||
git status --short
|
||||
echo ""
|
||||
echo "Continuando de todas formas..."
|
||||
echo ""
|
||||
fi
|
||||
```
|
||||
|
||||
#### 2. Parsear argumentos
|
||||
|
||||
```bash
|
||||
# Por defecto ejecutar todos los grupos
|
||||
GRUPO=""
|
||||
ALL_GROUPS=true
|
||||
SEQUENTIAL=false
|
||||
|
||||
# Parsear argumentos
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--group)
|
||||
if [ -z "$2" ] || [[ ! "$2" =~ ^[0-9]+$ ]]; then
|
||||
echo "Error: --group requiere un número"
|
||||
exit 1
|
||||
fi
|
||||
GRUPO=$2
|
||||
ALL_GROUPS=false
|
||||
shift 2
|
||||
;;
|
||||
--sequential)
|
||||
SEQUENTIAL=true
|
||||
shift
|
||||
;;
|
||||
*)
|
||||
echo "Error: Flag desconocido '$1'"
|
||||
echo "Uso: /issues:execute-parallel [--group <numero>] [--sequential]"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
done
|
||||
```
|
||||
|
||||
#### 3. Ejecutar programa Go
|
||||
|
||||
```bash
|
||||
echo ""
|
||||
|
||||
# Mensaje de inicio
|
||||
if [ "$ALL_GROUPS" = true ]; then
|
||||
echo "🚀 Iniciando ejecución de TODOS los grupos secuencialmente"
|
||||
else
|
||||
echo "🚀 Iniciando ejecución paralela del Grupo $GRUPO"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
|
||||
# Construir argumentos para el programa Go
|
||||
if [ "$ALL_GROUPS" = true ]; then
|
||||
ARGS="--all-groups"
|
||||
else
|
||||
ARGS="--group $GRUPO"
|
||||
fi
|
||||
|
||||
if [ "$SEQUENTIAL" = true ]; then
|
||||
ARGS="$ARGS --sequential"
|
||||
fi
|
||||
|
||||
# Ejecutar el orquestador
|
||||
./cmd/parallel-executor/parallel-executor $ARGS
|
||||
|
||||
EXIT_CODE=$?
|
||||
|
||||
# Verificar resultado
|
||||
if [ $EXIT_CODE -eq 0 ]; then
|
||||
echo ""
|
||||
echo "✓ Ejecución completada exitosamente"
|
||||
echo ""
|
||||
|
||||
if [ "$ALL_GROUPS" = true ]; then
|
||||
echo "Logs guardados en:"
|
||||
echo " - logs/parallel-execution-*.log (logs individuales)"
|
||||
echo " - logs/consolidated-summary.txt (resumen consolidado)"
|
||||
else
|
||||
echo "Logs guardados en: logs/parallel-execution-*.log"
|
||||
fi
|
||||
|
||||
# Eliminar el archivo PARALLEL_EXECUTION_ORDER.md después de ejecución exitosa
|
||||
if [ -f "PARALLEL_EXECUTION_ORDER.md" ]; then
|
||||
rm -f PARALLEL_EXECUTION_ORDER.md
|
||||
echo ""
|
||||
echo "✓ Plan de ejecución eliminado (PARALLEL_EXECUTION_ORDER.md)"
|
||||
fi
|
||||
else
|
||||
echo ""
|
||||
echo "❌ Ejecución falló con código $EXIT_CODE"
|
||||
echo ""
|
||||
echo "Revisa los logs para más detalles:"
|
||||
echo " ls -lt logs/parallel-execution-*.log | head -1"
|
||||
exit $EXIT_CODE
|
||||
fi
|
||||
```
|
||||
|
||||
#### 4. Mostrar resumen
|
||||
|
||||
```bash
|
||||
echo ""
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo "Resumen de ejecución:"
|
||||
echo ""
|
||||
|
||||
# El programa Go debe generar un archivo de resumen
|
||||
if [ -f "logs/last-execution-summary.txt" ]; then
|
||||
cat logs/last-execution-summary.txt
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "Estado de worktrees:"
|
||||
git worktree list | grep -v "(bare)" || echo " (ninguno - todos limpiados)"
|
||||
|
||||
echo ""
|
||||
echo "Próximos pasos:"
|
||||
echo " 1. Verificar que todas las issues fueron mergeadas"
|
||||
if [ "$ALL_GROUPS" = false ]; then
|
||||
echo " 2. Si el Grupo $GRUPO fue exitoso, ejecutar siguiente grupo"
|
||||
fi
|
||||
echo " 3. Si hubo errores, revisar logs y reintentar"
|
||||
```
|
||||
|
||||
### Arquitectura del programa Go
|
||||
|
||||
El comando invoca un programa Go en `cmd/parallel-executor/` con la siguiente estructura:
|
||||
|
||||
```
|
||||
cmd/parallel-executor/
|
||||
├── main.go → Entry point, parseo de CLI
|
||||
├── parser.go → Parse PARALLEL_EXECUTION_ORDER.md
|
||||
├── worktree.go → Git worktree operations (shell layer)
|
||||
├── executor.go → Execute claude commands (shell layer)
|
||||
├── logger.go → Structured logging
|
||||
├── orchestrator.go → Orchestration logic con goroutines
|
||||
└── types.go → Estructuras de datos (core types)
|
||||
```
|
||||
|
||||
**Responsabilidades del programa Go:**
|
||||
|
||||
1. **Parser** (`parser.go`):
|
||||
- Leer `PARALLEL_EXECUTION_ORDER.md`
|
||||
- Extraer issues del grupo especificado
|
||||
- Parsear archivos afectados, dependencias, etc.
|
||||
|
||||
2. **Worktree Manager** (`worktree.go`):
|
||||
- Crear worktrees: `git worktree add worktrees/issue-NNNN -b issue/NNNN-slug`
|
||||
- Eliminar worktrees después de merge
|
||||
- Verificar estado de worktrees
|
||||
|
||||
3. **Executor** (`executor.go`):
|
||||
- Ejecutar `claude -p /issues:fix-issue NNNN` en cada worktree
|
||||
- Capturar output en tiempo real
|
||||
- Detectar éxito/fallo del comando
|
||||
- Ejecutar `/git:push` al completar exitosamente
|
||||
|
||||
4. **Logger** (`logger.go`):
|
||||
- Logging estructurado con timestamps
|
||||
- Archivo por ejecución: `logs/parallel-execution-YYYYMMDD-HHMMSS.log`
|
||||
- Output a consola + archivo simultáneamente
|
||||
- Niveles: INFO, WARN, ERROR, SUCCESS
|
||||
|
||||
5. **Orchestrator** (`orchestrator.go`):
|
||||
- Coordinar goroutines para ejecución paralela
|
||||
- Manejar canales de comunicación entre workers
|
||||
- Recolectar resultados y errores
|
||||
- Implementar timeout por issue (configurable)
|
||||
- Rollback en caso de fallo crítico
|
||||
|
||||
**Flujo del programa Go:**
|
||||
|
||||
```
|
||||
1. Parse CLI args (grupo, flags)
|
||||
2. Parse PARALLEL_EXECUTION_ORDER.md
|
||||
3. Extraer issues del grupo especificado
|
||||
4. Para cada issue en el grupo:
|
||||
4.1. Crear worktree + rama
|
||||
4.2. En el worktree:
|
||||
→ cd worktrees/issue-NNNN
|
||||
→ claude -p /issues:fix-issue NNNN
|
||||
→ Esperar a que termine
|
||||
→ Si exitoso: ejecutar /git:push
|
||||
→ Si fallo: reportar error y continuar
|
||||
4.3. Limpiar worktree y rama
|
||||
5. Generar resumen de ejecución
|
||||
6. Return exit code (0 si todo OK, 1 si hubo errores)
|
||||
```
|
||||
|
||||
### Verificación final
|
||||
|
||||
El programa Go se encarga de limpiar los worktrees automáticamente. El resumen final mostrará el estado de todas las ejecuciones.
|
||||
|
||||
## Convenciones
|
||||
|
||||
- **Logs persistentes:** Cada ejecución genera un archivo en `logs/parallel-execution-YYYYMMDD-HHMMSS.log`
|
||||
- **Resumen ejecutivo:** Archivo `logs/last-execution-summary.txt` con métricas clave
|
||||
- **Timeouts:** 30 minutos por issue por defecto (configurable en código Go)
|
||||
- **Paralelismo:** Por defecto ejecuta issues en paralelo con `runtime.NumCPU()` goroutines
|
||||
- **Limpieza automática:** Siempre limpia worktrees al terminar (éxito o fallo)
|
||||
- **Eliminación del plan:** El archivo `PARALLEL_EXECUTION_ORDER.md` se elimina automáticamente al completar exitosamente
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "No existe PARALLEL_EXECUTION_ORDER.md"
|
||||
|
||||
**Causa:** No se ha generado el plan de ejecución paralela
|
||||
|
||||
**Solución:**
|
||||
El comando genera automáticamente el plan si no existe. Si este error persiste:
|
||||
```bash
|
||||
/issues:parallel
|
||||
```
|
||||
|
||||
### Advertencia: "Quedaron N worktrees sin limpiar"
|
||||
|
||||
**Causa:** Alguna issue falló y el worktree no pudo ser limpiado
|
||||
|
||||
**Solución:**
|
||||
```bash
|
||||
# Revisar el error en los logs
|
||||
cat logs/parallel-execution-*.log | grep ERROR
|
||||
|
||||
# Limpiar manualmente
|
||||
/workspace:cleanup-worktrees --all
|
||||
```
|
||||
|
||||
## Reglas críticas
|
||||
|
||||
- **SIEMPRE generar plan automáticamente** si no existe `PARALLEL_EXECUTION_ORDER.md`
|
||||
- **SIEMPRE ejecutar todos los grupos por defecto** - no preguntar al usuario
|
||||
- **SOLO advertir si hay cambios sin commitear** - nunca bloquear la ejecución
|
||||
- **SIEMPRE capturar logs** en archivo persistente
|
||||
- **SIEMPRE limpiar worktrees** incluso si hubo errores (usar defer en Go)
|
||||
- **NUNCA bloquear indefinidamente** - implementar timeouts razonables
|
||||
- **SIEMPRE reportar progreso** en tiempo real
|
||||
- **SIEMPRE eliminar el plan** después de ejecución exitosa
|
||||
- **VERIFICAR estado de git** antes de la ejecución (solo advertencia, no bloqueante)
|
||||
@@ -0,0 +1,387 @@
|
||||
---
|
||||
version: 2.0.0
|
||||
updated: 2026-03-11
|
||||
tags: [issues, implementation, workflow, trunk-based]
|
||||
---
|
||||
|
||||
# Command: fix-issue
|
||||
|
||||
Ejecuta de punta a punta el flujo de implementación/cierre de un issue siguiendo **estrictamente** la regla `fix_issue.md`.
|
||||
|
||||
## Para el usuario
|
||||
|
||||
### Cuándo usar este comando
|
||||
|
||||
Usar cuando quieras implementar un issue completo desde inicio hasta fin con confirmación antes de integrar. El comando maneja todo el ciclo: crear rama, implementar, testear, cerrar issue, pedir confirmación, e integrar a master.
|
||||
|
||||
### Sintaxis
|
||||
|
||||
```bash
|
||||
/issues:fix-issue <NNNN>
|
||||
/issues:fix-issue <NNNN>-<slug>
|
||||
```
|
||||
|
||||
### Ejemplos
|
||||
|
||||
**Ejemplo 1: Por número**
|
||||
```bash
|
||||
/issues:fix-issue 0013
|
||||
```
|
||||
|
||||
Busca `dev/issues/0013-*.md`, implementa todas las tareas, cierra el issue, pide confirmación, e integra.
|
||||
|
||||
**Ejemplo 2: Por slug completo**
|
||||
```bash
|
||||
/issues:fix-issue 0013-hot-reload
|
||||
```
|
||||
|
||||
Usa exactamente `dev/issues/0013-hot-reload.md`.
|
||||
|
||||
## Para Claude
|
||||
|
||||
### Precondiciones
|
||||
|
||||
Verificar antes de ejecutar:
|
||||
|
||||
- [ ] Directorio `dev/issues/` existe
|
||||
- [ ] Directorio `dev/issues/completed/` existe
|
||||
- [ ] Archivo `dev/issues/README.md` existe
|
||||
- [ ] Tests configurados (go test disponible)
|
||||
- [ ] Working tree limpio
|
||||
|
||||
### Inputs
|
||||
|
||||
Se necesita el issue objetivo. Si no se proporciona, preguntar:
|
||||
|
||||
- `issue`: número o nombre (ej: `0010` o `0010-access-control`)
|
||||
|
||||
### Flujo obligatorio
|
||||
|
||||
#### 1. Resolver el issue objetivo
|
||||
|
||||
**Si viene solo número** (`0010`):
|
||||
```bash
|
||||
ls dev/issues/0010-*.md
|
||||
```
|
||||
|
||||
**Si viene slug completo** (`0010-access-control`):
|
||||
```bash
|
||||
ls dev/issues/0010-access-control.md
|
||||
```
|
||||
|
||||
**Validaciones:**
|
||||
- Si no existe en `dev/issues/` → ✗ **STOP**: "Issue no encontrado"
|
||||
- Si ya está en `dev/issues/completed/` → ✗ **STOP**: "Issue ya completado"
|
||||
|
||||
#### 2. Leer completo el issue y extraer información
|
||||
|
||||
```bash
|
||||
cat dev/issues/<NNNN>-<slug>.md
|
||||
```
|
||||
|
||||
Extraer:
|
||||
- **Objetivo**: qué se quiere lograr
|
||||
- **Tareas/fases**: lista completa de pasos
|
||||
- **Arquitectura**: archivos a crear/modificar
|
||||
- **Patrón pure/impure**: límites entre core/, shell/, app/
|
||||
- **Tests requeridos**: criterios de aceptación
|
||||
|
||||
#### 3. Crear rama de trabajo (inline)
|
||||
|
||||
{{include: git-verify-clean}}
|
||||
|
||||
Verificar rama actual:
|
||||
|
||||
```bash
|
||||
git branch --show-current
|
||||
```
|
||||
|
||||
**Si ya estamos en `issue/<NNNN>-<slug>`** que coincide:
|
||||
- ✓ Continuar directamente a paso 4
|
||||
|
||||
**Si estamos en master o cualquier otra rama:**
|
||||
|
||||
{{include: git-update-master}}
|
||||
|
||||
```bash
|
||||
git checkout master
|
||||
git pull --rebase
|
||||
git checkout -b issue/<NNNN>-<slug>
|
||||
```
|
||||
|
||||
**⚠️ IMPORTANTE:** Nunca trabajar directamente en `master`.
|
||||
|
||||
#### 4. Planificar con TodoWrite
|
||||
|
||||
Crear plan basado en las tareas del issue:
|
||||
|
||||
```markdown
|
||||
- [ ] Fase 1: <descripción>
|
||||
- [ ] Tarea 1.1
|
||||
- [ ] Tarea 1.2
|
||||
- [ ] Fase 2: <descripción>
|
||||
- [ ] Tarea 2.1
|
||||
- [ ] Tarea 2.2
|
||||
- [ ] Fase N: Tests y validación
|
||||
- [ ] Cerrar issue
|
||||
```
|
||||
|
||||
**Principios:**
|
||||
- Respetar el orden de fases del issue
|
||||
- Incluir siempre fase de tests
|
||||
- Marcar progreso al completar cada bloque
|
||||
|
||||
#### 5. Implementar el issue completo
|
||||
|
||||
**Ejecutar tareas en orden:**
|
||||
|
||||
Para cada tarea:
|
||||
1. Implementar cambios requeridos
|
||||
2. Seguir patrón **pure core / impure shell**:
|
||||
- `core/` → funciones puras, sin side effects
|
||||
- `shell/` → I/O, filesystem, network, APIs
|
||||
- `app/` → orquestación de core + shell
|
||||
3. Compilar frecuentemente:
|
||||
```bash
|
||||
go build -tags goolm ./...
|
||||
```
|
||||
4. Marcar progreso en TodoWrite
|
||||
5. Crear commits atómicos por bloque lógico (no al final, durante la implementación)
|
||||
|
||||
**Commits durante implementación:**
|
||||
```bash
|
||||
git add <archivos_del_bloque>
|
||||
git commit -m "<tipo>: <resumen>" -m "<descripción larga en español>"
|
||||
```
|
||||
|
||||
Tipos: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`
|
||||
|
||||
#### 6. Tests obligatorios
|
||||
|
||||
{{include: run-tests}}
|
||||
|
||||
```bash
|
||||
go test -tags goolm ./...
|
||||
```
|
||||
|
||||
**Casos:**
|
||||
- Tests **pasan** → ✓ Continuar a paso 7
|
||||
- Tests **fallan** → ✗ **STOP**: corregir antes de continuar
|
||||
```bash
|
||||
go test -v -tags goolm ./... # Ver detalles
|
||||
# Corregir errores
|
||||
# Crear commit con fix
|
||||
# Re-ejecutar tests
|
||||
```
|
||||
- No hay tests aplicables → ℹ Indicar al usuario, continuar
|
||||
|
||||
**⚠️ CRÍTICO:** No cerrar el issue sin tests pasando.
|
||||
|
||||
#### 7. Feature flags (si aplica)
|
||||
|
||||
Evaluar si es feature multi-issue o despliegue gradual:
|
||||
|
||||
**Si aplica feature flag:**
|
||||
1. Actualizar `dev/feature_flags.json`:
|
||||
```json
|
||||
{
|
||||
"<nombre-del-flag>": {
|
||||
"enabled": false, // o true si es el último sub-issue
|
||||
"issue": "<NNNN>",
|
||||
"description": "<descripción>",
|
||||
"updated": "2026-03-11"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. Incluir en commit correspondiente (no commit separado solo para flags)
|
||||
|
||||
**Si NO aplica:**
|
||||
- Feature autocontenida que no necesita coordinación
|
||||
- ✓ Saltar este paso
|
||||
|
||||
**⚠️ Recordatorio:** Feature flag ≠ WIP. Los flags protegen código terminado y testeado, no código a medias.
|
||||
|
||||
#### 8. Cerrar el issue
|
||||
|
||||
Mover issue a completed:
|
||||
|
||||
```bash
|
||||
mv dev/issues/<NNNN>-<slug>.md dev/issues/completed/
|
||||
```
|
||||
|
||||
Actualizar índice en `dev/issues/README.md`:
|
||||
|
||||
Cambiar la línea del issue:
|
||||
- Link: de `[<NNNN>-<slug>.md](<NNNN>-<slug>.md)` a `[completed/<NNNN>-<slug>.md](completed/<NNNN>-<slug>.md)`
|
||||
- Estado: de `pendiente` o `en progreso` a `completado`
|
||||
|
||||
Crear commit:
|
||||
```bash
|
||||
git add dev/issues/completed/<NNNN>-<slug>.md dev/issues/README.md
|
||||
git commit -m "docs: cerrar issue <NNNN>-<slug>" -m "Issue <NNNN> completado y movido a completed/
|
||||
|
||||
Todas las tareas implementadas y tests pasando.
|
||||
Ready to merge to master."
|
||||
```
|
||||
|
||||
#### 9. Mostrar resumen de cambios y confirmar
|
||||
|
||||
{{include: ask-user-confirm}}
|
||||
|
||||
**Mostrar al usuario un resumen completo:**
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
git diff --stat master
|
||||
git log --oneline master..HEAD
|
||||
```
|
||||
|
||||
**Mostrar tareas completadas del TodoWrite.**
|
||||
|
||||
**Pausar y preguntar:**
|
||||
|
||||
```
|
||||
✓ Issue <NNNN>-<slug> completado
|
||||
|
||||
Resumen de cambios:
|
||||
- <N> archivos modificados/creados
|
||||
- <N> commits realizados
|
||||
- Tests: [pasando / no aplica]
|
||||
- Issue movido a completed/
|
||||
|
||||
Commits:
|
||||
- <commit 1>
|
||||
- <commit 2>
|
||||
- ...
|
||||
|
||||
¿Está todo bien para integrar a master?
|
||||
- Si es correcto: se hará merge y push automáticamente
|
||||
- Si necesitas ajustes: puedes hacer cambios adicionales antes
|
||||
```
|
||||
|
||||
**Esperar respuesta del usuario:**
|
||||
- Si responde **SI** / afirmativo → continuar a paso 10
|
||||
- Si responde **NO** / necesita cambios → **STOP**: "Haz los ajustes necesarios y cuando estés listo ejecuta `/git:push`"
|
||||
|
||||
#### 10. Ejecutar /git:push automáticamente
|
||||
|
||||
Una vez confirmado por el usuario, ejecutar `/git:push` para:
|
||||
|
||||
1. Verificar que estamos en la rama correcta
|
||||
2. Re-ejecutar tests (verificación final)
|
||||
3. Checkout a master y actualizar
|
||||
4. Merge --no-ff:
|
||||
```bash
|
||||
git merge --no-ff issue/<NNNN>-<slug> -m "merge: issue/<NNNN>-<slug> — <título del issue>"
|
||||
```
|
||||
5. Push a remoto
|
||||
6. Limpiar rama local
|
||||
|
||||
El comando `/git:push` maneja todo el flujo de integración automáticamente.
|
||||
|
||||
### Verificación final
|
||||
|
||||
Informar al usuario:
|
||||
|
||||
```
|
||||
✓ Issue <NNNN>-<slug> completado e integrado a master
|
||||
|
||||
Rama: issue/<NNNN>-<slug> (mergeada y limpiada)
|
||||
Commits integrados: <N>
|
||||
Tests: pasando
|
||||
Issue: movido a dev/issues/completed/
|
||||
|
||||
Master actualizado y sincronizado con remoto.
|
||||
```
|
||||
|
||||
## Convenciones
|
||||
|
||||
- **Issue completo**: implementar todas las tareas, no parcial
|
||||
- **Commits atómicos**: durante implementación, no al final
|
||||
- **Tests obligatorios**: no cerrar sin tests pasando
|
||||
- **Pure core / impure shell**: respetar arquitectura estrictamente
|
||||
- **Feature flags solo si aplica**: no usar para ocultar trabajo incompleto
|
||||
- **Confirmación obligatoria**: siempre pedir antes de integrar
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "Issue not found"
|
||||
|
||||
**Causa:** El archivo del issue no existe en `dev/issues/`
|
||||
|
||||
**Solución:**
|
||||
```bash
|
||||
ls dev/issues/
|
||||
# Verificar número o slug correcto
|
||||
# O crear el issue primero con /issues:create-issue
|
||||
```
|
||||
|
||||
### Error: "Issue already completed"
|
||||
|
||||
**Causa:** El issue ya está en `dev/issues/completed/`
|
||||
|
||||
**Solución:**
|
||||
El issue ya fue implementado. Si necesitas modificarlo:
|
||||
1. Crear nuevo issue que referencia el anterior
|
||||
2. O mover de vuelta a `dev/issues/` si realmente no estaba completo
|
||||
|
||||
### Error: "Tests failing during implementation"
|
||||
|
||||
**Causa:** Los cambios rompieron tests existentes
|
||||
|
||||
**Solución:**
|
||||
1. Ver detalles:
|
||||
```bash
|
||||
go test -v -tags goolm ./...
|
||||
```
|
||||
|
||||
2. Identificar qué test falló y por qué
|
||||
3. Corregir el código o actualizar el test si es legítimo
|
||||
4. Crear commit con el fix
|
||||
5. Continuar implementación
|
||||
|
||||
### Error: "Cannot create branch, working tree not clean"
|
||||
|
||||
**Causa:** Hay cambios sin commitear
|
||||
|
||||
**Solución:**
|
||||
```bash
|
||||
git status
|
||||
# Opción 1: Commitear cambios primero
|
||||
git add . && git commit -m "mensaje"
|
||||
# Opción 2: Hacer stash
|
||||
git stash
|
||||
# Luego ejecutar /issues:fix-issue nuevamente
|
||||
```
|
||||
|
||||
### Error: "go build failed"
|
||||
|
||||
**Causa:** Errores de compilación en el código
|
||||
|
||||
**Solución:**
|
||||
1. Leer el error de compilación cuidadosamente
|
||||
2. Corregir el error en el código
|
||||
3. Intentar compilar de nuevo
|
||||
4. No continuar hasta que compile correctamente
|
||||
|
||||
### Advertencia: "Feature flag needed but not found"
|
||||
|
||||
**Causa:** El issue es parte de feature multi-issue pero no tiene flag
|
||||
|
||||
**Solución:**
|
||||
1. Revisar si realmente necesita feature flag
|
||||
2. Si sí: agregar a `dev/feature_flags.json`
|
||||
3. Si no: continuar sin flag
|
||||
|
||||
## Reglas críticas
|
||||
|
||||
- **Seguir fix_issue.md estrictamente**: no saltear pasos
|
||||
- **NO saltear tareas del issue**: implementar todas
|
||||
- **NO hacer commits WIP**: cada commit debe ser atómico y completo
|
||||
- **SIEMPRE usar -tags goolm**: en build y test
|
||||
- **SIEMPRE ejecutar tests**: antes de cerrar issue
|
||||
- **Confirmación obligatoria**: esperar aprobación del usuario antes de integrar
|
||||
- **Flujo automático post-confirmación**: ejecutar `/git:push` para integrar
|
||||
- **Respetar arquitectura**: core/ puro, shell/ impuro, app/ orquestación
|
||||
- **NO inventar soluciones**: seguir las tareas del issue al pie de la letra
|
||||
@@ -0,0 +1,481 @@
|
||||
---
|
||||
version: 1.0.0
|
||||
updated: 2026-03-11
|
||||
tags: [issues, parallel, development, worktree]
|
||||
---
|
||||
|
||||
# Command: parallel-issues
|
||||
|
||||
Analiza las issues pendientes en `dev/issues/` y genera un plan de ejecución paralela (`PARALLEL_EXECUTION_ORDER.md`) agrupando issues independientes que no tienen conflictos entre sí.
|
||||
|
||||
## Para el usuario
|
||||
|
||||
### Cuándo usar este comando
|
||||
|
||||
- Cuando quieres identificar qué issues puedes desarrollar en paralelo sin conflictos
|
||||
- Para acelerar el desarrollo trabajando en múltiples issues simultáneamente
|
||||
- Antes de iniciar una sesión de desarrollo intensivo con múltiples desarrolladores
|
||||
- Para planificar el uso de git worktrees con issues independientes
|
||||
|
||||
### Sintaxis
|
||||
|
||||
```bash
|
||||
/issues:parallel [--dry-run]
|
||||
```
|
||||
|
||||
### Ejemplos
|
||||
|
||||
**Ejemplo 1:**
|
||||
```bash
|
||||
/issues:parallel
|
||||
```
|
||||
|
||||
Analiza todas las issues pendientes y genera el archivo `PARALLEL_EXECUTION_ORDER.md` con grupos de issues paralelizables.
|
||||
|
||||
**Ejemplo 2:**
|
||||
```bash
|
||||
/issues:parallel --dry-run
|
||||
```
|
||||
|
||||
Muestra el análisis de paralelización en consola sin crear el archivo (útil para vista previa).
|
||||
|
||||
## Para Claude
|
||||
|
||||
### Precondiciones
|
||||
|
||||
Verificar antes de ejecutar:
|
||||
|
||||
- [ ] Existe el directorio `dev/issues/`
|
||||
- [ ] Hay al menos una issue pendiente en formato `NNNN-*.md`
|
||||
- [ ] El proyecto sigue la estructura funcional (core/shell/app)
|
||||
|
||||
### Inputs
|
||||
|
||||
Se necesitan los siguientes datos. Si no se proporcionan, preguntar al usuario:
|
||||
|
||||
- `--dry-run` (opcional): Si está presente, solo muestra el análisis sin crear archivo
|
||||
|
||||
### Flujo obligatorio
|
||||
|
||||
#### 1. Detectar contexto del proyecto
|
||||
|
||||
Determinar si estamos en el proyecto padre (Dataforge) o en un proyecto hijo (workspaces/).
|
||||
|
||||
```bash
|
||||
# Verificar si estamos en un proyecto hijo
|
||||
if [[ "$PWD" == *"/workspaces/"* ]]; then
|
||||
PROJECT_TYPE="child"
|
||||
PROJECT_NAME=$(basename "$PWD")
|
||||
else
|
||||
PROJECT_TYPE="parent"
|
||||
PROJECT_NAME="Dataforge"
|
||||
fi
|
||||
|
||||
echo "Analizando issues en proyecto: $PROJECT_NAME ($PROJECT_TYPE)"
|
||||
```
|
||||
|
||||
Verificar que existe `dev/issues/`:
|
||||
|
||||
```bash
|
||||
if [ ! -d "dev/issues" ]; then
|
||||
echo "Error: No existe el directorio dev/issues/"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
#### 2. Listar issues pendientes
|
||||
|
||||
Obtener todas las issues que no están marcadas como completadas:
|
||||
|
||||
```bash
|
||||
# Listar archivos de issues
|
||||
ls -1 dev/issues/*.md | grep -E '[0-9]{4}-.*\.md$' | sort
|
||||
```
|
||||
|
||||
Para cada issue, extraer:
|
||||
- **Número de issue** (NNNN)
|
||||
- **Título** (del nombre del archivo)
|
||||
- **Estado** (revisar si está en el índice como completada)
|
||||
- **Archivos mencionados** (parsear el contenido del issue)
|
||||
- **Dependencias explícitas** (buscar referencias a `#NNNN`)
|
||||
|
||||
**Parseo de archivos mencionados:**
|
||||
|
||||
Buscar patrones como:
|
||||
- `core/archivo.go`
|
||||
- `shell/archivo.go`
|
||||
- `app/archivo.go`
|
||||
- Cualquier path con extensión de código
|
||||
|
||||
**Parseo de dependencias:**
|
||||
|
||||
Buscar patrones como:
|
||||
- "depende de #0001"
|
||||
- "requiere #0002"
|
||||
- "bloqueado por #0003"
|
||||
|
||||
#### 3. Analizar conflictos y dependencias
|
||||
|
||||
Para cada par de issues (A, B), determinar si son **paralelizables**:
|
||||
|
||||
**Criterios de conflicto (NO paralelizables):**
|
||||
1. **Archivos compartidos:** Si ambas issues modifican el mismo archivo
|
||||
2. **Dependencias explícitas:** Si A menciona "#B" o viceversa
|
||||
3. **Dependencias transitivas:** Si A depende de C y B depende de C
|
||||
|
||||
**Criterios de paralelización (SÍ paralelizables):**
|
||||
1. **Archivos disjuntos:** Modifican archivos completamente diferentes
|
||||
2. **Capas diferentes:** Una toca `core/` y otra `shell/` sin archivos comunes
|
||||
3. **Sin referencias cruzadas:** Ninguna menciona a la otra
|
||||
|
||||
**Estructura de datos sugerida:**
|
||||
|
||||
```
|
||||
Issue #0001:
|
||||
- Archivos: [core/types.go, core/workspace.go]
|
||||
- Depende de: []
|
||||
- Capa principal: core
|
||||
|
||||
Issue #0002:
|
||||
- Archivos: [shell/gitea.go, shell/http.go]
|
||||
- Depende de: [#0001]
|
||||
- Capa principal: shell
|
||||
|
||||
Conflictos detectados:
|
||||
- #0002 → #0001 (dependencia explícita)
|
||||
```
|
||||
|
||||
#### 4. Agrupar issues por independencia
|
||||
|
||||
Usar algoritmo de agrupación por grafos:
|
||||
|
||||
1. **Construir grafo de dependencias:**
|
||||
- Nodos = issues
|
||||
- Aristas = conflictos/dependencias
|
||||
|
||||
2. **Detectar componentes independientes:**
|
||||
- Issues sin aristas entre sí → mismo grupo paralelo
|
||||
- Issues con aristas → grupos secuenciales
|
||||
|
||||
3. **Priorizar grupos:**
|
||||
- Grupo 1: Issues sin dependencias (pueden ejecutarse YA)
|
||||
- Grupo 2: Issues que dependen solo de Grupo 1
|
||||
- Grupo N: Issues que dependen de grupos anteriores
|
||||
|
||||
**Algoritmo simple:**
|
||||
|
||||
```
|
||||
Grupo_actual = 1
|
||||
Issues_restantes = todas las issues pendientes
|
||||
Issues_completadas = []
|
||||
|
||||
while Issues_restantes no está vacío:
|
||||
Grupo[Grupo_actual] = []
|
||||
|
||||
for issue in Issues_restantes:
|
||||
tiene_conflictos = false
|
||||
|
||||
# Verificar conflictos con issues ya en el grupo actual
|
||||
for otra in Grupo[Grupo_actual]:
|
||||
if conflicto(issue, otra):
|
||||
tiene_conflictos = true
|
||||
break
|
||||
|
||||
# Verificar dependencias no resueltas
|
||||
for dep in issue.dependencias:
|
||||
if dep not in Issues_completadas:
|
||||
tiene_conflictos = true
|
||||
break
|
||||
|
||||
if not tiene_conflictos:
|
||||
Grupo[Grupo_actual].append(issue)
|
||||
|
||||
# Si no pudimos agregar ninguna issue al grupo, hay dependencias circulares
|
||||
if Grupo[Grupo_actual] está vacío:
|
||||
ERROR: "Dependencias circulares detectadas"
|
||||
break
|
||||
|
||||
# Marcar issues del grupo como completadas para próxima iteración
|
||||
Issues_completadas += Grupo[Grupo_actual]
|
||||
Issues_restantes -= Grupo[Grupo_actual]
|
||||
Grupo_actual++
|
||||
```
|
||||
|
||||
#### 5. Estimar tiempos de desarrollo
|
||||
|
||||
Para cada issue, calcular complejidad basada en:
|
||||
|
||||
**Factores:**
|
||||
1. **Cantidad de archivos:**
|
||||
- 1-2 archivos = Simple (1-2 horas)
|
||||
- 3-5 archivos = Moderada (2-4 horas)
|
||||
- 6+ archivos = Compleja (4-8 horas)
|
||||
|
||||
2. **Capa afectada:**
|
||||
- Solo `core/` = Moderada (requiere tests extensivos)
|
||||
- Solo `shell/` = Alta (I/O, manejo de errores)
|
||||
- `app/` = Baja (orquestación)
|
||||
- Múltiples capas = Alta (integración compleja)
|
||||
|
||||
3. **Palabras clave en descripción:**
|
||||
- "refactor", "reestructurar" = +50% tiempo
|
||||
- "nuevo", "implementar" = tiempo base
|
||||
- "fix", "corregir" = -30% tiempo
|
||||
- "documentar" = tiempo muy bajo
|
||||
|
||||
**Estimación por grupo:**
|
||||
- Tiempo de grupo = MAX(tiempos individuales) ← porque se ejecutan en paralelo
|
||||
- Tiempo total = SUM(tiempos de grupos) ← porque los grupos son secuenciales
|
||||
|
||||
#### 6. Generar archivo PARALLEL_EXECUTION_ORDER.md
|
||||
|
||||
Crear el archivo con la siguiente estructura:
|
||||
|
||||
```markdown
|
||||
# Plan de Ejecución Paralela
|
||||
|
||||
**Proyecto:** {{PROJECT_NAME}}
|
||||
**Fecha de análisis:** {{FECHA}}
|
||||
**Issues analizadas:** {{TOTAL_ISSUES}}
|
||||
**Grupos paralelos:** {{TOTAL_GRUPOS}}
|
||||
|
||||
---
|
||||
|
||||
## Grupo 1: Issues Independientes (ejecutar en paralelo)
|
||||
|
||||
### Issue #0003 - Implementar shell/gitea.go
|
||||
- **Archivos afectados:**
|
||||
- `shell/gitea.go`
|
||||
- `shell/gitea_test.go`
|
||||
- **Capa:** shell
|
||||
- **Complejidad:** Moderada
|
||||
- **Tiempo estimado:** 3 horas
|
||||
- **Dependencias:** Ninguna
|
||||
- **Worktree sugerido:** `worktrees/issue-0003`
|
||||
- **Branch sugerida:** `quick/issues:fix-issue-0003`
|
||||
|
||||
### Issue #0006 - Añadir logging estructurado
|
||||
- **Archivos afectados:**
|
||||
- `shell/logger.go`
|
||||
- `app/main.go`
|
||||
- **Capa:** shell, app
|
||||
- **Complejidad:** Simple
|
||||
- **Tiempo estimado:** 2 horas
|
||||
- **Dependencias:** Ninguna
|
||||
- **Worktree sugerido:** `worktrees/issue-0006`
|
||||
- **Branch sugerida:** `quick/issues:fix-issue-0006`
|
||||
|
||||
### Issue #0008 - Documentación de módulos
|
||||
- **Archivos afectados:**
|
||||
- `README.md`
|
||||
- `docs/architecture.md`
|
||||
- **Capa:** docs
|
||||
- **Complejidad:** Simple
|
||||
- **Tiempo estimado:** 1.5 horas
|
||||
- **Dependencias:** Ninguna
|
||||
- **Worktree sugerido:** `worktrees/issue-0008`
|
||||
- **Branch sugerida:** `quick/issues:fix-issue-0008`
|
||||
|
||||
**Tiempo estimado del grupo:** 3 horas (máximo en paralelo)
|
||||
|
||||
---
|
||||
|
||||
## Grupo 2: Issues Dependientes (ejecutar después de Grupo 1)
|
||||
|
||||
### Issue #0004 - Implementar app/orchestrator.go
|
||||
- **Archivos afectados:**
|
||||
- `app/orchestrator.go`
|
||||
- `app/orchestrator_test.go`
|
||||
- **Capa:** app
|
||||
- **Complejidad:** Alta
|
||||
- **Tiempo estimado:** 5 horas
|
||||
- **Dependencias:**
|
||||
- `#0003` (requiere shell/gitea.go)
|
||||
- **Worktree sugerido:** `worktrees/issue-0004`
|
||||
- **Branch sugerida:** `quick/issues:fix-issue-0004`
|
||||
|
||||
**Tiempo estimado del grupo:** 5 horas
|
||||
|
||||
---
|
||||
|
||||
## Grupo 3: Issues Finales
|
||||
|
||||
### Issue #0005 - Integración completa
|
||||
- **Archivos afectados:**
|
||||
- `app/main.go`
|
||||
- `cmd/dataforge/main.go`
|
||||
- **Capa:** app
|
||||
- **Complejidad:** Moderada
|
||||
- **Tiempo estimado:** 3 horas
|
||||
- **Dependencias:**
|
||||
- `#0004` (requiere orchestrator)
|
||||
- **Worktree sugerido:** `worktrees/issue-0005`
|
||||
- **Branch sugerida:** `quick/issues:fix-issue-0005`
|
||||
|
||||
**Tiempo estimado del grupo:** 3 horas
|
||||
|
||||
---
|
||||
|
||||
## Conflictos Detectados
|
||||
|
||||
### Conflictos por archivos compartidos:
|
||||
- `#0002` y `#0003`: ambos modifican `core/types.go`
|
||||
- **Solución:** Ejecutar secuencialmente (están en grupos diferentes)
|
||||
|
||||
### Dependencias explícitas:
|
||||
- `#0004` depende de `#0003`
|
||||
- `#0005` depende de `#0004`
|
||||
|
||||
### Advertencias:
|
||||
- Ninguna circular detectada ✓
|
||||
|
||||
---
|
||||
|
||||
## Resumen
|
||||
|
||||
| Métrica | Valor |
|
||||
|---------|-------|
|
||||
| Issues totales | 8 |
|
||||
| Issues en Grupo 1 (paralelas) | 3 |
|
||||
| Issues secuenciales | 5 |
|
||||
| Grupos paralelos | 3 |
|
||||
| Tiempo total secuencial | 28 horas |
|
||||
| Tiempo total paralelo | 11 horas |
|
||||
| **Ahorro de tiempo** | **61%** |
|
||||
|
||||
---
|
||||
|
||||
## Recomendaciones
|
||||
|
||||
1. **Ejecutar Grupo 1 en paralelo:** Usar git worktrees para trabajar en las 3 issues simultáneamente
|
||||
2. **Esperar a Grupo 2:** No iniciar #0004 hasta que #0003 esté mergeada
|
||||
3. **Validar integraciones:** Después de cada grupo, ejecutar tests completos
|
||||
4. **Monitoring:** Si encuentras nuevas dependencias durante desarrollo, actualiza el plan
|
||||
|
||||
---
|
||||
|
||||
## Comandos para Setup de Worktrees
|
||||
|
||||
```bash
|
||||
# Grupo 1 - Crear worktrees para issues paralelas
|
||||
git worktree add worktrees/issue-0003 -b quick/issues:fix-issue-0003
|
||||
git worktree add worktrees/issue-0006 -b quick/issues:fix-issue-0006
|
||||
git worktree add worktrees/issue-0008 -b quick/issues:fix-issue-0008
|
||||
|
||||
# Ejecutar /issues:fix-issue en cada worktree (manual)
|
||||
# cd worktrees/issue-0003 && /issues:fix-issue 0003
|
||||
# cd worktrees/issue-0006 && /issues:fix-issue 0006
|
||||
# cd worktrees/issue-0008 && /issues:fix-issue 0008
|
||||
|
||||
# Después de mergear Grupo 1, crear worktree para Grupo 2
|
||||
git worktree add worktrees/issue-0004 -b quick/issues:fix-issue-0004
|
||||
|
||||
# Limpiar worktrees después de merge
|
||||
git worktree remove worktrees/issue-0003
|
||||
git worktree remove worktrees/issue-0006
|
||||
git worktree remove worktrees/issue-0008
|
||||
```
|
||||
```
|
||||
|
||||
**Notas importantes:**
|
||||
|
||||
- Usar formato markdown claro y estructurado
|
||||
- Incluir tabla de resumen con métricas
|
||||
- Calcular ahorro de tiempo (tiempo secuencial vs paralelo)
|
||||
- Sugerir comandos de worktree para facilitar setup
|
||||
- Documentar advertencias y conflictos detectados
|
||||
|
||||
#### 7. Mostrar resultado
|
||||
|
||||
Si se ejecutó con `--dry-run`:
|
||||
- Mostrar todo el contenido en consola
|
||||
- NO crear archivo
|
||||
- Terminar aquí
|
||||
|
||||
Si se ejecutó sin flags:
|
||||
- Crear archivo `PARALLEL_EXECUTION_ORDER.md`
|
||||
- Mostrar resumen en consola
|
||||
|
||||
```bash
|
||||
cat PARALLEL_EXECUTION_ORDER.md
|
||||
```
|
||||
|
||||
### Verificación final
|
||||
|
||||
```bash
|
||||
# Verificar que el archivo fue creado
|
||||
ls -lh PARALLEL_EXECUTION_ORDER.md
|
||||
|
||||
# Contar grupos generados
|
||||
grep -c "^## Grupo" PARALLEL_EXECUTION_ORDER.md
|
||||
```
|
||||
|
||||
Informar al usuario:
|
||||
|
||||
```
|
||||
✓ Plan de ejecución paralela generado
|
||||
|
||||
Archivo: PARALLEL_EXECUTION_ORDER.md
|
||||
|
||||
Resumen:
|
||||
- Issues analizadas: {{N}}
|
||||
- Grupos paralelos: {{M}}
|
||||
- Ahorro estimado: {{X}}%
|
||||
|
||||
Próximos pasos:
|
||||
1. Revisar el plan generado
|
||||
2. Crear worktrees para Grupo 1
|
||||
3. Ejecutar /issues:fix-issue en cada worktree
|
||||
4. Mergear y continuar con siguientes grupos
|
||||
```
|
||||
|
||||
## Convenciones
|
||||
|
||||
- **Nombres de grupo:** "Grupo N" donde N empieza en 1
|
||||
- **Worktrees sugeridos:** Siempre bajo `worktrees/issue-NNNN`
|
||||
- **Branches sugeridas:** Formato `quick/issues:fix-issue-NNNN`
|
||||
- **Estimación de tiempo:** En horas, redondeado a .5 (ej: 2.5h, 3h, 4.5h)
|
||||
- **Conflictos:** Documentar TODOS los conflictos detectados aunque estén resueltos en el plan
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "No se encontraron issues pendientes"
|
||||
|
||||
**Causa:** No hay archivos `.md` en `dev/issues/` o todos están marcados como completados
|
||||
|
||||
**Solución:**
|
||||
```bash
|
||||
# Verificar issues existentes
|
||||
ls -1 dev/issues/*.md
|
||||
|
||||
# Verificar índice de issues completadas
|
||||
cat dev/issues/README.md
|
||||
```
|
||||
|
||||
### Error: "Dependencias circulares detectadas"
|
||||
|
||||
**Causa:** Las issues tienen dependencias que forman un ciclo (A→B→C→A)
|
||||
|
||||
**Solución:**
|
||||
1. Revisar manualmente las dependencias en los archivos de issues
|
||||
2. Identificar el ciclo
|
||||
3. Romper una de las dependencias refactorizando el alcance de una issue
|
||||
4. Re-ejecutar el comando
|
||||
|
||||
### Warning: "Múltiples issues modifican el mismo archivo"
|
||||
|
||||
**Causa:** Varias issues tocan el mismo archivo pero no tienen dependencias explícitas
|
||||
|
||||
**Solución:**
|
||||
1. El algoritmo las colocará en grupos secuenciales automáticamente
|
||||
2. Considerar refactorizar las issues para que sean más granulares
|
||||
3. O agregar dependencias explícitas si hay un orden lógico
|
||||
|
||||
## Reglas críticas
|
||||
|
||||
- **NUNCA ejecutar issues en paralelo si comparten archivos** - causará conflictos de merge
|
||||
- **SIEMPRE respetar dependencias explícitas** - aunque no compartan archivos
|
||||
- **NUNCA asumir independencia sin analizar el contenido** - leer cada issue completamente
|
||||
- **SIEMPRE calcular el tiempo del grupo como MAX(tiempos)** - no como suma (son paralelas)
|
||||
- **NUNCA crear el archivo si hay errores en el análisis** - informar al usuario y terminar
|
||||
- **SIEMPRE documentar conflictos detectados** - transparencia total en el análisis
|
||||
@@ -0,0 +1,212 @@
|
||||
---
|
||||
version: 1.0.0
|
||||
updated: 2026-03-15
|
||||
tags: [issues, quick, automation, tui]
|
||||
---
|
||||
|
||||
# Command: quick-issue
|
||||
|
||||
Crea un issue nuevo automáticamente desde la TUI con detección automática de workspace y número de issue.
|
||||
|
||||
## Para el usuario
|
||||
|
||||
### Cuándo usar este comando
|
||||
|
||||
Este comando es invocado automáticamente por la TUI cuando el usuario presiona la opción "Create Issue". **No se debe invocar manualmente** desde la línea de comandos.
|
||||
|
||||
### Sintaxis
|
||||
|
||||
```bash
|
||||
/issues:quick-issue --text "descripción del issue"
|
||||
```
|
||||
|
||||
El comando auto-detecta el próximo número de issue disponible y crea el archivo automáticamente.
|
||||
|
||||
## Para Claude
|
||||
|
||||
### Precondiciones
|
||||
|
||||
Verificar antes de ejecutar:
|
||||
|
||||
- [ ] Directorio `dev/issues/` existe
|
||||
- [ ] Parámetro `--text` fue proporcionado
|
||||
- [ ] Working tree limpio
|
||||
|
||||
### Inputs
|
||||
|
||||
**Obligatorios:**
|
||||
- `--text`: Texto descriptivo del issue (se usará como título y descripción)
|
||||
|
||||
**Auto-detectados:**
|
||||
- Número de issue: Siguiente disponible en `dev/issues/`
|
||||
- Workspace: Proyecto padre (Dataforge)
|
||||
|
||||
### Flujo obligatorio
|
||||
|
||||
#### 1. Determinar número del issue
|
||||
|
||||
```bash
|
||||
# Listar issues existentes
|
||||
ls -1 dev/issues/*.md | grep -E '^dev/issues/[0-9]{4}[a-z]?-' | sort -V
|
||||
|
||||
# Extraer último número
|
||||
# Si el último es 0023-foo.md, siguiente es 0024
|
||||
# Si el último es 0023c-bar.md, siguiente es 0024
|
||||
```
|
||||
|
||||
Regla: **SIEMPRE incrementar el número base**, ignorar letras.
|
||||
|
||||
#### 2. Generar título y slug
|
||||
|
||||
- **Título**: Usar `--text` directamente
|
||||
- **Slug**: Convertir título a kebab-case
|
||||
|
||||
Ejemplo:
|
||||
```
|
||||
--text "Agregar soporte para temas oscuros"
|
||||
→ Título: "Agregar soporte para temas oscuros"
|
||||
→ Slug: "agregar-soporte-para-temas-oscuros"
|
||||
```
|
||||
|
||||
#### 3. Crear archivo de issue
|
||||
|
||||
Usar template `.claude/templates/issue.md` y completar:
|
||||
|
||||
```markdown
|
||||
# NNNN — [Título]
|
||||
|
||||
## Metadata
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | NNNN |
|
||||
| **Estado** | 🟡 pendiente |
|
||||
| **Prioridad** | media |
|
||||
| **Tipo** | feature |
|
||||
|
||||
## Dependencias
|
||||
|
||||
| ID | Título | Estado | Requerido |
|
||||
|----|--------|--------|-----------|
|
||||
| - | - | - | - |
|
||||
|
||||
**Bloqueada por:** Ninguna
|
||||
|
||||
**Desbloquea:** (a determinar)
|
||||
|
||||
---
|
||||
|
||||
## Objetivo
|
||||
|
||||
[Texto del parámetro --text]
|
||||
|
||||
## Contexto
|
||||
|
||||
(A completar durante implementación)
|
||||
|
||||
## Tareas
|
||||
|
||||
- [ ] (A detallar durante implementación con /issues:fix-issue)
|
||||
|
||||
---
|
||||
|
||||
## Criterios de aceptación
|
||||
|
||||
- [ ] Tests pasando
|
||||
- [ ] Documentación actualizada
|
||||
- [ ] Issue movida a completed/
|
||||
|
||||
---
|
||||
|
||||
## Notas de implementación
|
||||
|
||||
[Notas que surjan durante la implementación]
|
||||
```
|
||||
|
||||
#### 4. Actualizar índice
|
||||
|
||||
Agregar línea en `dev/issues/README.md`:
|
||||
|
||||
```markdown
|
||||
- [ ] [NNNN](NNNN-slug.md) — [Título] (pendiente)
|
||||
```
|
||||
|
||||
#### 5. Crear commits y mergear
|
||||
|
||||
**Sin pedir confirmación**, ejecutar:
|
||||
|
||||
```bash
|
||||
# Crear rama
|
||||
git checkout -b quick/issues:quick-issue-NNNN
|
||||
|
||||
# Commitear
|
||||
git add dev/issues/NNNN-slug.md dev/issues/README.md
|
||||
git commit -m "docs: crear issue NNNN-slug" -m "Issue NNNN: [Título]
|
||||
|
||||
Creado desde TUI con quick-issue.
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||||
|
||||
# Mergear
|
||||
git checkout master
|
||||
git pull --rebase
|
||||
git merge --no-ff quick/issues:quick-issue-NNNN -m "merge: quick/issues:quick-issue-NNNN — [título]"
|
||||
|
||||
# Push
|
||||
git push
|
||||
|
||||
# Limpiar
|
||||
git branch -d quick/issues:quick-issue-NNNN
|
||||
```
|
||||
|
||||
#### 6. Reportar resultado
|
||||
|
||||
Informar al usuario con formato claro:
|
||||
|
||||
```
|
||||
✓ Issue NNNN-slug creado e integrado
|
||||
|
||||
Título: [Título]
|
||||
Archivo: dev/issues/NNNN-slug.md
|
||||
|
||||
Para implementar:
|
||||
/issues:fix-issue NNNN
|
||||
```
|
||||
|
||||
## Convenciones
|
||||
|
||||
- **Auto-detección**: workspace y número de issue
|
||||
- **Sin confirmación**: flujo completamente automático
|
||||
- **Trunk-based**: rama quick/ y merge inmediato
|
||||
- **Template simple**: detalles se completan durante /fix-issue
|
||||
- **Commits atómicos**: issue + índice en un solo commit
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "Missing --text parameter"
|
||||
|
||||
**Causa:** El comando fue invocado sin el parámetro `--text`.
|
||||
|
||||
**Solución:** Este comando debe ser invocado automáticamente por la TUI. No invocar manualmente.
|
||||
|
||||
### Error: "Working tree not clean"
|
||||
|
||||
**Causa:** Hay cambios pendientes.
|
||||
|
||||
**Solución:**
|
||||
```bash
|
||||
git status
|
||||
git stash
|
||||
# Reintentar desde TUI
|
||||
git stash pop
|
||||
```
|
||||
|
||||
## Reglas críticas
|
||||
|
||||
- **SIEMPRE auto-detectar número de issue** - no pedirlo
|
||||
- **USAR --text como título completo** - no truncar
|
||||
- **NO pedir confirmación** - flujo automático
|
||||
- **Template minimalista** - los detalles se agregan en /fix-issue
|
||||
- **REPORTAR resultado claramente** - mostrar número y path del issue
|
||||
@@ -0,0 +1,103 @@
|
||||
---
|
||||
version: 1.0.0
|
||||
updated: 2026-03-15
|
||||
tags: [issues, planning, dependencies, order]
|
||||
---
|
||||
|
||||
# Command: sort-issues (issues)
|
||||
|
||||
Analiza las issues en `dev/issues/` del repositorio Dataforge (parent), construye el grafo de dependencias y muestra el orden de ejecución recomendado. Detecta dependencias circulares y las reporta claramente.
|
||||
|
||||
## Para el usuario
|
||||
|
||||
### Cuándo usar este comando
|
||||
|
||||
- Cuando quieres saber en qué orden ejecutar las issues del proyecto padre
|
||||
- Antes de empezar a trabajar para entender el flujo crítico
|
||||
- Cuando hay dudas sobre bloqueos entre issues
|
||||
- Invocado desde TUI con la tecla `s` en el selector de issues
|
||||
|
||||
### Sintaxis
|
||||
|
||||
```bash
|
||||
/issues:sort-issues
|
||||
```
|
||||
|
||||
## Para Claude
|
||||
|
||||
### Precondiciones
|
||||
|
||||
- [ ] Directorio `dev/issues/` existe
|
||||
- [ ] Hay archivos `.md` en `dev/issues/` (al menos uno)
|
||||
|
||||
### Flujo obligatorio
|
||||
|
||||
#### 1. Listar todas las issues pendientes
|
||||
|
||||
```bash
|
||||
ls dev/issues/*.md | grep -E '^dev/issues/[0-9]{4}[a-z]?-.*\.md$' | sort
|
||||
```
|
||||
|
||||
Excluir `README.md` y otros archivos que no sean issues numeradas.
|
||||
|
||||
#### 2. Para cada issue, extraer dependencias
|
||||
|
||||
Leer cada archivo y buscar:
|
||||
|
||||
1. **Tabla "## Dependencias"**: filas con IDs en primera columna
|
||||
2. **Línea "Bloqueada por"**: `**Bloqueada por:** \`#NNNN, #NNNN\``
|
||||
|
||||
Construir lista: `{id: "0003", deps: ["0001", "0002"]}`
|
||||
|
||||
#### 3. Construir grafo y detectar ciclos
|
||||
|
||||
Verificar si hay dependencias circulares (A → B → A).
|
||||
|
||||
**Si hay ciclos:**
|
||||
|
||||
```
|
||||
❌ Dependencias circulares detectadas:
|
||||
|
||||
0010 → 0011 → 0012 → 0010
|
||||
|
||||
Solución: Revisar dependencias en:
|
||||
- dev/issues/0010-*.md
|
||||
- dev/issues/0011-*.md
|
||||
- dev/issues/0012-*.md
|
||||
```
|
||||
|
||||
**Si no hay ciclos:** continuar al paso 4.
|
||||
|
||||
#### 4. Calcular orden topológico
|
||||
|
||||
Aplicar Kahn's algorithm o DFS post-order. Criterios de desempate:
|
||||
1. Número de issue menor primero
|
||||
2. Issues sin dependencias primero (nivel 0)
|
||||
|
||||
#### 5. Mostrar resultado
|
||||
|
||||
```
|
||||
Orden de ejecución recomendado para Dataforge:
|
||||
|
||||
1. [0001] Título issue 1
|
||||
2. [0002] Título issue 2
|
||||
3. [0003] Título issue 3 (depende de: 0001, 0002)
|
||||
4. [0004] Título issue 4 (depende de: 0002, 0003)
|
||||
5. [0005] Título issue 5 (depende de: 0004)
|
||||
|
||||
⚠️ Issues con dependencias circulares: Ninguna
|
||||
✓ Todas las issues pueden ejecutarse en este orden
|
||||
|
||||
Issues paralelizables (misma capa):
|
||||
- Capa 1 (sin deps): 0001
|
||||
- Capa 2: 0002
|
||||
- Capa 3: 0003, 0004
|
||||
- Capa 4: 0005
|
||||
```
|
||||
|
||||
## Convenciones
|
||||
|
||||
- **Solo leer**: nunca modificar los archivos de issues
|
||||
- **Análisis exhaustivo**: leer TODAS las issues antes de generar el orden
|
||||
- **Detectar ambos formatos**: tabla Dependencias + línea Bloqueada por
|
||||
- **Reportar claramente** los ciclos con los IDs involucrados
|
||||
@@ -0,0 +1,233 @@
|
||||
---
|
||||
version: 1.0.0
|
||||
updated: 2026-03-11
|
||||
tags: [issues, planning, order]
|
||||
---
|
||||
|
||||
# Command: sort-issues
|
||||
|
||||
Analiza las issues en `dev/issues/` y genera un archivo `dev/EXECUTION_ORDER.md` con el orden óptimo de ejecución basado en dependencias y relaciones entre issues.
|
||||
|
||||
## Para el usuario
|
||||
|
||||
### Cuándo usar este comando
|
||||
|
||||
- Cuando quieres planificar el orden de trabajo de las issues disponibles
|
||||
- Después de crear nuevas issues y necesitas priorizar
|
||||
- Antes de empezar una fase de desarrollo para entender el flujo crítico
|
||||
- Cuando hay cambios en dependencias entre issues
|
||||
|
||||
### Sintaxis
|
||||
|
||||
```bash
|
||||
/issues:sort
|
||||
```
|
||||
|
||||
### Ejemplos
|
||||
|
||||
**Ejemplo 1:**
|
||||
```bash
|
||||
/issues:sort
|
||||
```
|
||||
|
||||
Analiza todas las issues en `dev/issues/` y crea `dev/EXECUTION_ORDER.md` con el orden recomendado.
|
||||
|
||||
**Ejemplo 2:**
|
||||
```bash
|
||||
/issues:sort
|
||||
```
|
||||
|
||||
Actualiza el orden de ejecución después de completar algunas issues.
|
||||
|
||||
## Para Claude
|
||||
|
||||
### Precondiciones
|
||||
|
||||
Verificar antes de ejecutar:
|
||||
|
||||
- [ ] Directorio `dev/issues/` existe
|
||||
- [ ] Hay archivos `.md` en `dev/issues/` (al menos uno)
|
||||
- [ ] Tienes permisos de escritura en `dev/`
|
||||
|
||||
### Inputs
|
||||
|
||||
No requiere inputs del usuario. Analiza automáticamente todas las issues en `dev/issues/`.
|
||||
|
||||
### Flujo obligatorio
|
||||
|
||||
#### 1. Listar todas las issues disponibles
|
||||
|
||||
Obtener lista de todas las issues en `dev/issues/`:
|
||||
|
||||
```bash
|
||||
ls -1 dev/issues/*.md | grep -E '[0-9]{4}-.*\.md$' | sort
|
||||
```
|
||||
|
||||
Excluir `README.md` y otros archivos que no sean issues numeradas.
|
||||
|
||||
#### 2. Analizar cada issue para extraer dependencias
|
||||
|
||||
Para cada archivo de issue encontrado:
|
||||
|
||||
1. Leer el contenido completo del archivo
|
||||
2. Buscar secciones que indiquen dependencias:
|
||||
- "Depends on", "Requires", "Prerequisites"
|
||||
- Referencias a otras issues (#NNNN)
|
||||
- Menciones en "Critical Path" o "Execution Order"
|
||||
3. Identificar el tipo de issue (foundational, feature, infrastructure)
|
||||
4. Analizar complejidad y alcance
|
||||
|
||||
**Patrones a buscar:**
|
||||
- `#0001`, `issue #0001`, `0001-nombre`
|
||||
- "must be completed before"
|
||||
- "blocks", "required for"
|
||||
- "depends on"
|
||||
|
||||
#### 3. Construir grafo de dependencias
|
||||
|
||||
Crear una representación mental del grafo:
|
||||
|
||||
- Nodos: cada issue
|
||||
- Aristas: relaciones de dependencia (A → B significa "A debe completarse antes que B")
|
||||
- Identificar:
|
||||
- Issues raíz (sin dependencias)
|
||||
- Issues bloqueadas (muchas dependencias)
|
||||
- Camino crítico
|
||||
- Issues paralelas (pueden ejecutarse simultáneamente)
|
||||
|
||||
#### 4. Calcular orden óptimo
|
||||
|
||||
Aplicar ordenamiento topológico considerando:
|
||||
|
||||
1. **Prioridad primaria:** Dependencias explícitas (hard dependencies)
|
||||
2. **Prioridad secundaria:** Dependencias implícitas (una issue menciona conceptos de otra)
|
||||
3. **Prioridad terciaria:** Orden lógico (fundamentos antes que features)
|
||||
4. **Desempate:** Número de issue (menor primero)
|
||||
|
||||
Estrategia:
|
||||
- Agrupar issues por "capas" (todas las de una capa pueden ejecutarse en paralelo)
|
||||
- Identificar camino crítico explícitamente
|
||||
- Sugerir paralelización cuando sea posible
|
||||
|
||||
#### 5. Generar archivo EXECUTION_ORDER.md
|
||||
|
||||
Crear archivo con formato muy sencillo:
|
||||
|
||||
```markdown
|
||||
# Execution Order for Issues
|
||||
|
||||
Last updated: YYYY-MM-DD
|
||||
|
||||
## Recommended Order
|
||||
|
||||
1. #0001 - <nombre> — <razón breve>
|
||||
2. #0002 - <nombre> — <razón breve>
|
||||
3. #0003 - <nombre> — <razón breve>
|
||||
...
|
||||
|
||||
## Critical Path
|
||||
|
||||
Issues que bloquean otras:
|
||||
- #0001 → #0002, #0003
|
||||
- #0005 → #0008
|
||||
|
||||
## Parallelizable Groups
|
||||
|
||||
### Group 1 (after #0001)
|
||||
- #0002
|
||||
- #0003
|
||||
|
||||
### Group 2 (after #0005)
|
||||
- #0006
|
||||
- #0007
|
||||
|
||||
## Notes
|
||||
|
||||
- <Nota importante sobre el orden>
|
||||
- <Consideraciones especiales>
|
||||
```
|
||||
|
||||
Escribir el archivo:
|
||||
|
||||
```bash
|
||||
cat > dev/EXECUTION_ORDER.md << 'EOF'
|
||||
<contenido-generado>
|
||||
EOF
|
||||
```
|
||||
|
||||
#### 6. Mostrar resumen al usuario
|
||||
|
||||
```
|
||||
✓ Archivo dev/EXECUTION_ORDER.md creado
|
||||
|
||||
Issues analizadas: N
|
||||
Camino crítico identificado: #XXXX → #YYYY → #ZZZZ
|
||||
Grupos paralelizables: M
|
||||
|
||||
Próxima issue recomendada: #NNNN - <nombre>
|
||||
```
|
||||
|
||||
### Verificación final
|
||||
|
||||
```bash
|
||||
cat dev/EXECUTION_ORDER.md
|
||||
```
|
||||
|
||||
Informar al usuario:
|
||||
|
||||
```
|
||||
✓ Orden de ejecución de issues generado en dev/EXECUTION_ORDER.md
|
||||
|
||||
Próximos pasos:
|
||||
1. Revisar el orden propuesto
|
||||
2. Comenzar con la primera issue del orden
|
||||
3. Actualizar con /issues:sort cuando completes issues o agregues nuevas
|
||||
```
|
||||
|
||||
## Convenciones
|
||||
|
||||
- **Formato simple**: Solo líneas numeradas con issues y razón breve
|
||||
- **Razones concisas**: Máximo 1 línea explicando por qué ese orden
|
||||
- **Actualización frecuente**: Re-ejecutar después de completar issues
|
||||
- **Nombres consistentes**: Usar formato `#NNNN - nombre-descriptivo`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "No issues found"
|
||||
|
||||
**Causa:** No hay archivos `.md` con formato de issue en `dev/issues/`
|
||||
|
||||
**Solución:**
|
||||
```bash
|
||||
ls -la dev/issues/
|
||||
# Verificar que existan archivos NNNN-nombre.md
|
||||
```
|
||||
|
||||
### Error: "Circular dependency detected"
|
||||
|
||||
**Causa:** Issue A depende de B, y B depende de A (ciclo)
|
||||
|
||||
**Solución:**
|
||||
1. Revisar manualmente las issues involucradas
|
||||
2. Romper la dependencia circular
|
||||
3. Actualizar la documentación de al menos una issue
|
||||
4. Re-ejecutar /issues:sort
|
||||
|
||||
### Error: "Permission denied writing to dev/"
|
||||
|
||||
**Causa:** No tienes permisos de escritura en el directorio `dev/`
|
||||
|
||||
**Solución:**
|
||||
```bash
|
||||
chmod u+w dev/
|
||||
# O verificar permisos del directorio
|
||||
ls -ld dev/
|
||||
```
|
||||
|
||||
## Reglas críticas
|
||||
|
||||
- **No modificar issues**: Solo leer, nunca modificar los archivos de issues
|
||||
- **Análisis exhaustivo**: Leer TODAS las issues antes de generar el orden
|
||||
- **Formato consistente**: Mantener estructura simple y legible
|
||||
- **Actualización atómica**: Sobrescribir el archivo completo, no editar parcialmente
|
||||
- **Documentar razonamiento**: Cada issue en el orden debe tener su justificación breve
|
||||
@@ -0,0 +1,119 @@
|
||||
# Command: issues:status
|
||||
|
||||
Muestra un dashboard global de todas las issues en todos los workspaces, con métricas,
|
||||
filtros y sugerencias de próximas issues a ejecutar.
|
||||
|
||||
## Para el usuario
|
||||
|
||||
### Cuándo usar este comando
|
||||
|
||||
Usar para obtener una vista consolidada del estado de todas las issues en todos los workspaces.
|
||||
Útil para planificar qué ejecutar a continuación y ver el progreso general.
|
||||
|
||||
### Sintaxis
|
||||
|
||||
```bash
|
||||
/issues:status # Dashboard global completo
|
||||
/issues:status <workspace> # Detalle de un workspace específico
|
||||
/issues:status --status pending # Filtrar por estado
|
||||
/issues:status --tag backend # Filtrar por tag
|
||||
/issues:status --export json # Exportar a JSON
|
||||
/issues:status --export csv # Exportar a CSV
|
||||
```
|
||||
|
||||
### Ejemplos
|
||||
|
||||
**Dashboard global:**
|
||||
```bash
|
||||
/issues:status
|
||||
```
|
||||
|
||||
**Ver solo issues pendientes:**
|
||||
```bash
|
||||
/issues:status --status pending
|
||||
```
|
||||
|
||||
**Ver detalle de un workspace:**
|
||||
```bash
|
||||
/issues:status my-api
|
||||
```
|
||||
|
||||
**Exportar métricas:**
|
||||
```bash
|
||||
/issues:status --export json
|
||||
```
|
||||
|
||||
## Para Claude
|
||||
|
||||
### Inputs
|
||||
|
||||
Parsear argumentos del usuario:
|
||||
|
||||
- Primer argumento posicional (sin `--`) → `filterWorkspace`
|
||||
- `--status <value>` → `filterStatus` (pending | in_progress | completed)
|
||||
- `--tag <value>` → `filterTag`
|
||||
- `--export <format>` → `exportFormat` (json | csv)
|
||||
|
||||
### Flujo
|
||||
|
||||
1. **Parsear argumentos** del comando según la sintaxis arriba
|
||||
2. **Llamar `app.IssuesDashboardCommand(config, filterWorkspace, filterStatus, filterTag, exportFormat)`**
|
||||
3. Si se solicitó dashboard global (sin filtros), después de mostrar el dashboard preguntar:
|
||||
- "¿Ver detalle de algún workspace? (nombre o 'n')"
|
||||
- Si el usuario ingresa un nombre válido, llamar `app.RenderWorkspaceDetail()`
|
||||
|
||||
### Parseo de argumentos
|
||||
|
||||
```
|
||||
/issues:status → filterWorkspace="", filterStatus="", filterTag="", exportFormat=""
|
||||
/issues:status my-api → filterWorkspace="my-api"
|
||||
/issues:status --status pending → filterStatus="pending"
|
||||
/issues:status --tag backend → filterTag="backend"
|
||||
/issues:status my-api --status pending → filterWorkspace="my-api", filterStatus="pending"
|
||||
/issues:status --export json → exportFormat="json"
|
||||
```
|
||||
|
||||
### Lógica de llamada Go
|
||||
|
||||
```go
|
||||
// Cargar config
|
||||
config, err := app.LoadConfig()
|
||||
if err != nil {
|
||||
// Reportar error
|
||||
}
|
||||
|
||||
// Ejecutar dashboard
|
||||
err = app.IssuesDashboardCommand(config, filterWorkspace, filterStatus, filterTag, exportFormat)
|
||||
```
|
||||
|
||||
### Comandos sugeridos al final
|
||||
|
||||
Siempre mostrar al final:
|
||||
```
|
||||
Commands:
|
||||
/issues:status <workspace> # Detalle de workspace específico
|
||||
/issues:status --status pending # Solo pendientes
|
||||
/app:launch <workspace> <issue> # Lanzar una issue sugerida
|
||||
```
|
||||
|
||||
### Modo interactivo (dashboard global)
|
||||
|
||||
Cuando se muestra el dashboard global sin filtros:
|
||||
1. Mostrar el dashboard completo con sugerencias
|
||||
2. Preguntar: "¿Ver detalle de un workspace? (nombre o 'n' para salir)"
|
||||
3. Si el usuario responde con un nombre de workspace:
|
||||
- Obtener issues del workspace con `shell.ListIssuesInWorkspace(workspacePath)`
|
||||
- Renderizar con `app.RenderWorkspaceDetail(workspace, issues)`
|
||||
4. Si responde 'n' o vacío, terminar
|
||||
|
||||
### Manejo de errores
|
||||
|
||||
- Si `ReposBasePath` no existe: "No se encontraron workspaces. ¿Está configurado DATAFORGE_REPOS?"
|
||||
- Si no hay issues en ningún workspace: Mostrar dashboard vacío con sugerencia de crear issues
|
||||
- Si exportación falla: Reportar error específico
|
||||
|
||||
### Notas
|
||||
|
||||
- Las stats se calculan escaneando el filesystem y sincronizando con la BD
|
||||
- La BD actúa como cache — si está desactualizada, el scan la actualiza
|
||||
- Para workspaces con muchas issues, el scan puede tardar segundos
|
||||
Reference in New Issue
Block a user