237 lines
6.5 KiB
Markdown
237 lines
6.5 KiB
Markdown
---
|
|
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
|