repo_Claude/.claude/commands/README.md

# Comandos Claude disponibles

Índice de comandos personalizados. Todos los comandos siguen trunk-based development y el patrón pure core / impure shell.

## Estructura de Comandos

Los comandos están organizados en subdirectorios temáticos:

- **`git/`** - Comandos de gestión de ramas y merge
- **`issues/`** - Comandos de gestión de issues del proyecto issues
- **`project/`** - Comandos de proyecto (crear comandos, etc.)
- **`workspace/`** - Comandos de workspace y worktrees

## Sistema de Inclusión

Los comandos pueden reutilizar fragmentos comunes usando el directorio `.claude/includes/`:

**Fragmentos disponibles:**
- `git-verify-clean` - Verificar working tree limpio
- `git-update-master` - Actualizar master desde remoto
- `git-merge-to-master` - Merge a master con --no-ff
- `ask-user-confirm` - Pedir confirmación al usuario
- `issue-numbering` - Sistema de numeración de issues
- `run-tests` - Ejecutar tests del proyecto

**Uso en comandos:**
```markdown
{{include: git-verify-clean}}
```

Esto expande automáticamente el contenido de `.claude/includes/git-verify-clean.md` cuando Claude lee el comando.

## Comandos de Git

### `/git:branch <tipo> <slug>`
Crea una rama de trabajo. Nunca trabajar directamente en master.

**Tipos:**
- `issue <NNNN> <slug>` - Para implementar un issue existente
- `quick <slug>` - Para cambios pequeños sin issue asociado

**Ejemplo:**
```bash
/git:branch issue 0013 hot-reload
/git:branch quick fix-typo-readme
```

### `/git:push`
Integra cambios a master y publica. Soporta ramas `issue/*` y `quick/*`.

**Flujo:**
1. Verifica rama y estado
2. Crea commits atómicos por bloque lógico
3. Ejecuta tests
4. Merge --no-ff a master
5. Push y limpieza

**Ejemplo:**
```bash
/git:push
```

## Comandos de Issues

### `/issues:create-issue`
Crea un issue nuevo en `dev/issues/` con confirmación del usuario.

**Características:**
- Desglose automático en sub-issues si es necesario
- Feature flags para issues multi-parte
- Actualiza índice automáticamente
- Pide confirmación antes de commit

**Ejemplo:**
```bash
/issues:create-issue
```

### `/issues:auto-create`
Crea un issue nuevo e integra automáticamente a master SIN pedir confirmación.

**Diferencia con `/issues:create-issue`:** No pausa para confirmación, ejecuta todo automáticamente.

**Ejemplo:**
```bash
/issues:auto-create
```

### `/issues:fix-issue <NNNN>`
Implementa un issue completo de punta a punta con confirmación.

**Flujo:**
1. Crea rama issue/NNNN-slug
2. Implementa todas las tareas
3. Ejecuta tests
4. Cierra el issue (mueve a completed/)
5. Pide confirmación
6. Integra a master

**Ejemplo:**
```bash
/issues:fix-issue 0013
/issues:fix-issue 0013-hot-reload
```

### `/issues:auto-fix <NNNN>`
Implementa un issue completo automáticamente SIN pedir confirmación.

**Ejemplo:**
```bash
/issues:auto-fix 0013
```

### `/issues:parallel`
Analiza issues pendientes y genera plan de ejecución paralela en `PARALLEL_EXECUTION_ORDER.md`.

**Flujo:**
1. Lee todas las issues en `dev/issues/`
2. Detecta conflictos por archivos compartidos
3. Detecta dependencias explícitas
4. Agrupa issues independientes
5. Genera plan con grupos paralelizables

**Ejemplo:**
```bash
/issues:parallel
/issues:parallel --dry-run  # Vista previa sin crear archivo
```

### `/issues:execute-parallel`
Ejecuta automáticamente issues del plan de ejecución paralela.

**Flujo:**
1. Lee `PARALLEL_EXECUTION_ORDER.md`
2. Crea worktrees para cada issue
3. Ejecuta `/issues:auto-fix` en paralelo
4. Merge y cleanup automático

**Ejemplo:**
```bash
/issues:execute-parallel 1              # Ejecutar Grupo 1
/issues:execute-parallel --all-groups   # Ejecutar TODOS los grupos
/issues:execute-parallel 2 --dry-run    # Vista previa del Grupo 2
```

### `/issues:sort`
Ordena issues en `dev/issues/README.md` según criterios específicos.

**Ejemplo:**
```bash
/issues:sort
```

## Comandos de Workspace

### `/workspace:create-repo`
Crea un nuevo subrepo (child repository) en `workspaces/` con estructura core/shell/app.

**Flujo:**
1. Solicita nombre, descripción, tipo y privacidad
2. Muestra resumen y pide confirmación
3. Crea directorio local con estructura Go estándar
4. Crea repositorio en Gitea
5. Push inicial y registro en SQLite

**Prerequisitos:** `GITEA_URL` y `GITEA_TOKEN` configurados, feature flag `workspace_commands` habilitado.

**Ejemplo:**
```bash
/workspace:create-repo
```

### `/workspace:sync-repos`
Sincroniza workspaces locales con repositorios en Gitea.

**Flujo:**
1. Obtiene workspaces locales desde SQLite
2. Consulta repos en Gitea (organización o usuario)
3. Genera plan: repos a clonar, actualizar, y huérfanos
4. Muestra plan y pide confirmación
5. Clona repos faltantes y actualiza metadata

**Prerequisitos:** `GITEA_URL` y `GITEA_TOKEN` configurados, feature flag `workspace_commands` habilitado.

**Ejemplo:**
```bash
/workspace:sync-repos              # Sincronización con confirmación
/workspace:sync-repos --dry-run    # Solo análisis, sin cambios
```

### `/workspace:list-repos`
Lista todos los workspaces registrados en la BD local con soporte de filtro y ordenamiento.

**Flujo:**
1. Obtiene workspaces de SQLite
2. Aplica filtro si se especifica `--filter`
3. Ordena según `--sort` (name o date)
4. Muestra tabla ASCII con URLs de Gitea

**Prerequisitos:** Feature flag `workspace_commands` habilitado.

**Ejemplo:**
```bash
/workspace:list-repos
/workspace:list-repos --filter pipeline
/workspace:list-repos --sort name
```

### `/workspace:cleanup-worktrees`
Limpia worktrees obsoletos de git.

**Flujo:**
1. Lista todos los worktrees activos
2. Identifica worktrees sin rama asociada
3. Pide confirmación
4. Elimina worktrees y ramas

**Ejemplo:**
```bash
/workspace:cleanup-worktrees
/workspace:cleanup-worktrees --all  # Limpiar todos sin confirmación
```

## Otros Comandos

### `/btw`
Comando de contexto rápido ("by the way"). Permite agregar información contextual durante una conversación.

**Ejemplo:**
```bash
/btw
```

## Comandos de Proyecto

### `/project:create-command`
Crea un nuevo comando en `.claude/commands/` siguiendo la estructura estándar.

**Flujo:**
1. Solicita inputs del comando
2. Genera estructura desde template
3. Muestra contenido al usuario
4. Pide confirmación
5. Integra a master automáticamente

**Ejemplo:**
```bash
/project:create-command
```

## Convenciones Generales

### Mensajes estándar

**Éxito:**
```
✓ <acción> completada
<detalles>
```

**Error:**
```
✗ Error: <descripción>
Solución: <pasos para resolver>
```

**Advertencia:**
```
⚠ Advertencia: <descripción>
¿Continuar? (s/n)
```

### Estructura de comandos

Todos los comandos siguen esta estructura:

```markdown
---
version: X.Y.Z
updated: YYYY-MM-DD
tags: [categoria1, categoria2]
---

# Command: nombre

## Para el usuario
<Documentación de uso>

## Para Claude
<Implementación técnica>

## Precondiciones
<Verificaciones antes de ejecutar>

## Troubleshooting
<Problemas comunes y soluciones>
```

### Reglas de commits

- `feat:` nueva funcionalidad
- `fix:` corrección de error
- `refactor:` cambio estructural sin cambio funcional
- `docs:` documentación
- `chore:` mantenimiento
- `test:` tests nuevos o modificados
- `merge:` commit de merge (generado por --no-ff)

### Trunk-based development

- **Una rama por tarea**: corta (horas, no días)
- **Merge rápido**: integrar a master frecuentemente
- **No rebase interactivo**: preservar historia limpia
- **Feature flags**: para features grandes, no para WIP
- **Tests obligatorios**: siempre antes de merge

### Pure Core / Impure Shell

- **`core/`**: funciones puras, sin side effects
- **`shell/`**: I/O, filesystem, network, APIs
- **`app/`**: orquestación de core + shell

## Troubleshooting Global

### Error: "Rama ya existe"
**Solución:**
```bash
git branch -D <rama>  # Borrar rama local
git checkout master   # Volver a master
/git:branch ...       # Crear de nuevo
```

### Error: "Working tree not clean"
**Solución:**
```bash
git status            # Ver cambios pendientes
git add .             # Stagear cambios
git commit -m "..."   # Commitear antes de cambiar rama
```

### Error: "Tests failing"
**Solución:**
```bash
go test -v -tags goolm ./...  # Ver detalles de tests
# Corregir errores
# Re-ejecutar tests
```

### Error: "Merge conflicts"
**Solución:**
```bash
git status                    # Ver archivos en conflicto
# Editar archivos y resolver conflictos manualmente
git add <archivos-resueltos>
git commit                    # Sin -m para mantener mensaje de merge
```

### Error: "Cannot push to master directly"
**Solución:**
```bash
git checkout -b quick/fix-direct-push
# Ahora los cambios están en rama
/git:push
```

## Extensión de comandos

Para crear nuevos comandos, usar `/project:create-command` que genera la estructura estándar automáticamente.

Para modificar comandos existentes, seguir la estructura documentada en esta guía.

## Referencias

- Documentación de trunk-based: `CLAUDE.md`
- Gestión de issues: `dev/README.md`
- Roadmap del proyecto: `dev/ROADMAP.md`
- Feature flags: `dev/feature_flags.json`