repo_Claude/.claude/commands

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:

{{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:

/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:

/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:

/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:

/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:

/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:

/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:

/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:

/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:

/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:

/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:

/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:

/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:

/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:

/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:

/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:

---
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:

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:

git status            # Ver cambios pendientes
git add .             # Stagear cambios
git commit -m "..."   # Commitear antes de cambiar rama

Error: "Tests failing"

Solución:

go test -v -tags goolm ./...  # Ver detalles de tests
# Corregir errores
# Re-ejecutar tests

Error: "Merge conflicts"

Solución:

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:

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