don-cheli-sdd 1.13.0

package/reglas/reglas-trabajo-globales.md

@@ -0,0 +1,171 @@
+# Reglas de Trabajo Globales
+
+## Cómo Mejoran el Framework
+
+Estas reglas establecen un **estándar profesional de desarrollo** que se aplica a todos los proyectos que usen Don Cheli. Mientras que la constitución define los *principios*, estas reglas definen las *prácticas* concretas. El framework las carga automáticamente y las aplica en cada sesión, eliminando la necesidad de repetir instrucciones manualmente.
+
+> **Uso:** Estas reglas se cargan automáticamente al ejecutar `/especdev:iniciar`. Se pueden personalizar por proyecto en `.especdev/config.yaml`.
+
+---
+
+## Principios Generales
+
+- Todo desarrollo debe ser **retrocompatible** a menos que se indique explícitamente lo contrario.
+- Responder de forma directa y concisa, sin preámbulos innecesarios.
+
+---
+
+## Idioma
+
+| Contexto | Idioma |
+|----------|--------|
+| Código (variables, funciones, comentarios) | **Inglés** |
+| Commits y PR descriptions | **Español** |
+| Respuestas al usuario | **Español** (salvo que pida otro) |
+| Documentación (spec.md, tech.md) | **Español** |
+
+---
+
+## Precedencia de Configuración
+
+```
+.especdev/config.yaml (proyecto) > reglas-trabajo-globales.md (framework)
+```
+
+Si el proyecto tiene su propio `.especdev/config.yaml` o `CLAUDE.md`, sus reglas **prevalecen** sobre este archivo en caso de conflicto.
+
+---
+
+## Contexto del Repositorio
+
+- Antes de empezar cualquier tarea, buscar y leer el `CLAUDE.md` del proyecto si existe.
+- Si el repo tiene un `docs/index.md`, consultarlo como mapa de navegación antes de buscar archivos sueltos.
+
+---
+
+## Branches y Naming
+
+| Tipo | Formato | Origen |
+|------|---------|--------|
+| Feature | `feature/<nombre-abreviado>` | `develop` (o rama principal) |
+| Fix | `fix/<nombre>` | `develop` |
+| Hotfix | `hotfix/<nombre>` | `main`/`production` |
+
+---
+
+## Commits
+
+```
+<type>: <descripción corta en español>
+```
+
+**Types válidos:** `feat`, `fix`, `hotfix`, `refactor`, `docs`, `test`, `chore`
+
+Ejemplo: `feat: agregar componente carrusel de productos`
+
+---
+
+## Tamaño de PRs
+
+- Un PR = **un único cambio lógico**.
+- Si el scope crece → proponer al usuario dividir en PRs incrementales.
+
+---
+
+## Documentación Obligatoria por PR
+
+| Tipo de PR | Documentación Requerida |
+|-----------|------------------------|
+| Feature con lógica de negocio o cambio de arquitectura | `spec.md` + `tech.md` en `/docs/specs/<feature>/` |
+| Feature menor (<3 archivos, sin lógica nueva) | Descripción del PR es suficiente |
+| Fixes, bumps de versión, config, wordings | **Exentos** de spec/tech |
+
+- Antes de redactar el spec, **aclarar todas las dudas con el usuario**.
+- Todo PR debe evaluar si los cambios requieren **actualizar `.md` existentes**.
+
+---
+
+## Cobertura de Código
+
+- Mínimo **85% de coverage** sobre el código introducido en el PR (unit tests).
+- El `.especdev/config.yaml` del proyecto puede definir otro umbral o eximirlo.
+
+---
+
+## Verificaciones de Calidad
+
+### Antes de cada commit
+- [ ] Ejecutar linter y corregir errores
+- [ ] Ejecutar tests y verificar que pasen
+- [ ] Verificar que compile sin errores
+
+### Antes de abrir PR (adicional)
+- [ ] Revisar diff completo: code smells, variables sin usar, imports innecesarios
+- [ ] Verificar coherencia con `spec.md` (si existe)
+- [ ] Verificar coverage mínimo sobre código introducido
+
+---
+
+## Tareas Complejas
+
+- Refactors >5 archivos, cambios de arquitectura o migraciones → **presentar plan y esperar confirmación** antes de ejecutar.
+- Paralelizar subtareas independientes siempre que sea posible.
+
+---
+
+## Límites de Autonomía
+
+| Situación | Acción |
+|-----------|--------|
+| Cambios afectan >10 archivos no previstos | **Confirmar con el usuario** |
+| Ambigüedad significativa | **Preguntar**, no asumir |
+| Test no pasa después de 2 intentos de fix | Reportar con error completo |
+| Dependencia no resuelve | Preguntar, no buscar workarounds |
+| Build falla por razones externas | Notificar y continuar |
+
+---
+
+## Subagentes y Selección de Modelos
+
+| Tipo de Tarea | Modelo |
+|--------------|--------|
+| Q&A, formateo, resúmenes, scripting, batch | `haiku` |
+| Código, bug fixes, tests, code review | `sonnet` |
+| Arquitectura, razonamiento complejo, seguridad | `opus` |
+
+**Reglas:**
+- **Default: Haiku.** Subir solo si la calidad del output es insuficiente.
+- **Nunca** usar Opus sin confirmación explícita del usuario.
+- Subtareas independientes → subagentes **en paralelo** (nunca secuenciales).
+- Subagente de exploración/búsqueda → siempre Haiku.
+
+---
+
+## Gestión de Contexto y Tokens
+
+- **Leer archivos bajo demanda**: no cargar lo que no sea necesario.
+- **No re-leer lo que ya está en contexto**: referenciar, no repetir.
+- **System prompts < 500 tokens**: mover reglas poco usadas a skills.
+- **Outputs estructurados desde el inicio**: JSON o formato concreto = menos iteraciones.
+- **Subagente para contexto grande**: si un resultado supera ~10K tokens, aislarlo en subagente.
+
+---
+
+## Dependencias
+
+- Antes de agregar una dependencia externa, buscar alternativas internas.
+- Si no existe alternativa, documentar la justificación en la descripción del PR.
+
+---
+
+## Seguridad
+
+- **Nunca** exponer credenciales en código fuente.
+- Usar siempre herramientas de gestión de secretos.
+
+---
+
+## Documentación Generada
+
+- Archivos `.md` concisos: preferir bullets sobre párrafos, máximo ~200 líneas.
+- No duplicar información entre archivos. Un dato en un solo lugar; en los demás, referenciar.

package/reglas/skills-best-practices.md

@@ -0,0 +1,109 @@
+# Best Practices para Skills (Anthropic Skills 2.0)
+
+## Compatibilidad de Formatos
+
+Don Cheli soporta dos formatos de skill:
+
+### Formato Anthropic (SKILL.md)
+```yaml
+---
+name: Skill Name
+description: What it does and when to trigger it
+---
+# Instructions...
+```
+
+### Formato Don Cheli (HABILIDAD.md)
+```yaml
+---
+nombre: Nombre de la Habilidad
+descripcion: Qué hace y cuándo se activa
+version: 1.0.0
+autor: Autor
+tags: [tag1, tag2]
+activacion: "keyword1", "keyword2"
+grado_libertad: alto | medio | bajo
+---
+# Instrucciones...
+```
+
+Ambos son leídos automáticamente. El formato Don Cheli tiene campos adicionales (version, tags, grado_libertad) que mejoran la gestión.
+
+## Reglas de Escritura
+
+### 1. Metadata es lo más importante
+La metadata (YAML frontmatter) determina si la skill se activa o no. Claude lee SOLO la metadata al inicio de sesión. El body se carga bajo demanda.
+
+**Buena metadata:**
+```yaml
+description: Generates weekly team reports from standup notes and PR activity. Triggers on "weekly report", "team update", "sprint summary", "what did we do this week".
+```
+
+**Mala metadata:**
+```yaml
+description: A useful skill for reports
+```
+
+### 2. Límite de 500 líneas
+Si el SKILL.md supera 500 líneas, separar:
+- `SKILL.md` — Instrucciones principales (< 500 líneas)
+- `templates/` — Archivos de plantilla
+- `reference.md` — Material de referencia detallado
+- `examples/` — Ejemplos completos
+
+Usar instrucciones en SKILL.md para guiar a Claude a cargar archivos adicionales solo cuando se necesiten (Progressive Disclosure).
+
+### 3. Solo incluir lo que Claude no sabe
+- No incluir: conocimiento general (lenguajes, frameworks, librerías populares)
+- No incluir: documentación que Claude ya tiene en su training data
+- Incluir: reglas específicas de la empresa/equipo
+- Incluir: formatos y templates propios
+- Incluir: quirks de herramientas internas
+- Incluir: workflows específicos del proyecto
+- Incluir: convenciones no estándar
+
+### 4. Grado de libertad
+Ajustar la granularidad de las instrucciones al tipo de tarea:
+
+| Grado | Tipo de tarea | Formato |
+|-------|--------------|---------|
+| **Alto** | Creativa (redacción, diseño, brainstorming) | Guidelines generales, principios |
+| **Medio** | Workflow con variaciones (code review, reportes) | Pseudocódigo, pasos con parámetros |
+| **Bajo** | Proceso crítico (deploy, migración, seguridad) | Script exacto, pocos parámetros |
+
+### 5. Progressive Disclosure (3 capas)
+```
+Capa 1: Metadata (YAML)     → Siempre cargada (~20 tokens por skill)
+Capa 2: Body (Markdown)     → Cargada al activar la skill
+Capa 3: File References     → Cargadas solo si se necesitan
+```
+
+Esto permite tener muchas skills sin impactar el context window.
+
+### 6. MCP + Skills = Cocina + Receta
+- **MCP** define QUÉ herramientas están disponibles (la cocina)
+- **Skills** enseñan CÓMO usar esas herramientas (las recetas)
+
+Si usas un MCP server, crea skills que orquesten sus herramientas.
+
+## Estructura de Directorio
+
+### Skills de Anthropic
+```
+.claude/skills/
+  mi-skill/
+    SKILL.md
+    templates/
+    reference.md
+```
+
+### Skills de Don Cheli
+```
+habilidades/
+  mi-habilidad/
+    HABILIDAD.md
+    plantillas/
+    referencia.md
+```
+
+Ambas ubicaciones son escaneadas automáticamente.

package/scripts/.claude/commands/bucle-completar.md

@@ -0,0 +1,13 @@
+---
+description: Completar bucle autónomo y generar reporte final
+---
+
+# /bucle-completar
+
+## Uso
+
+```
+/bucle-completar
+```
+
+Finaliza el bucle autónomo, genera reporte final y actualiza `.especdev/progreso.md`.

package/scripts/.claude/commands/bucle-estado.md

@@ -0,0 +1,13 @@
+---
+description: Estado actual del bucle autónomo
+---
+
+# /bucle-estado
+
+## Uso
+
+```
+/bucle-estado
+```
+
+Muestra el estado actual del bucle: historias completadas, pendientes y patrones aprendidos.

package/scripts/.claude/commands/bucle.md

@@ -0,0 +1,74 @@
+---
+description: Lanzar bucle autónomo para ejecutar historias del PRD
+---
+
+# /bucle
+
+## Objetivo
+
+Lanzar el bucle autónomo que ejecuta las historias de usuario una por una hasta completar o agotar iteraciones.
+
+## Uso
+
+```
+/bucle [max_iteraciones]
+```
+
+- `max_iteraciones`: Número máximo de iteraciones (default: 10)
+
+## Prerrequisitos
+
+- Archivo `.especdev/sesion/prd.json` existente
+- Al menos una historia con `pasa: false`
+
+## Comportamiento
+
+1. **Verificar** que prd.json existe
+2. **Contar** historias restantes
+3. **Lanzar** el script `bucle.sh`
+4. **Para cada iteración:**
+   - Seleccionar historia prioritaria no completada
+   - Ejecutar en **contexto fresco** (aislado)
+   - Verificar criterios de aceptación
+   - Actualizar prd.json
+   - Registrar en progreso.md
+5. **Terminar** cuando:
+   - Todas las historias pasan → `COMPLETO`
+   - Máximo iteraciones alcanzado → fallo
+   - Historia bloqueada 2 veces → saltar y continuar
+
+## Output
+
+```
+=== Bucle Don Cheli Iniciado ===
+Historias: 5 pendientes, 0 completadas
+Máximo iteraciones: 10
+
+--- Iteración 1/10 ---
+Historia: HU-001 [P1] Estructura de archivos
+Estado: PASÓ ✅
+
+--- Iteración 2/10 ---
+Historia: HU-002 [P2] Comando historias-generar
+Estado: PASÓ ✅
+
+...
+
+=== COMPLETO ===
+Las 5 historias pasaron en 5 iteraciones.
+Ver progreso: .especdev/progreso.md
+```
+
+## Gestión de Errores
+
+| Situación | Comportamiento |
+|-----------|---------------|
+| prd.json faltante | Error + sugerir /historias-generar |
+| Sin historias pendientes | Mensaje "Nada que hacer" |
+| Historia falla 1x | Reintentar en siguiente iteración |
+| Historia falla 2x | Saltar + registrar |
+| Máximo iteraciones | Salir con mensaje |
+
+## Contexto Fresco
+
+Cada historia se ejecuta en su propio contexto aislado. El agente NO acumula confusión de sesiones anteriores. Investigaciones muestran que las respuestas de LLM degradan notablemente en contextos largos. **Contexto fresco = agente más inteligente.**

package/scripts/.claude/commands/especdev/actualizar.md

@@ -0,0 +1,200 @@
+---
+description: Detectar actualizaciones del framework Don Cheli y aplicarlas
+i18n: true
+---
+
+# /especdev:actualizar
+
+## Objetivo
+
+Verificar si hay actualizaciones disponibles en el repositorio de Don Cheli y ofrecer aplicarlas.
+
+## Uso
+
+```
+/especdev:actualizar
+/especdev:actualizar --verificar    # Solo verificar, no aplicar
+/especdev:actualizar --forzar       # Aplicar sin confirmar
+```
+
+## Proceso
+
+### 1. Detectar instalación
+
+```bash
+# Verificar dónde está instalado
+GLOBAL="$HOME/.claude/don-cheli"
+LOCAL="./.claude/don-cheli"
+
+if [ -f "$GLOBAL/VERSION" ]; then
+  INSTALACION="$GLOBAL"
+elif [ -f "$LOCAL/VERSION" ]; then
+  INSTALACION="$LOCAL"
+else
+  echo "Don Cheli no está instalado"
+  exit 1
+fi
+
+VERSION_LOCAL=$(cat "$INSTALACION/VERSION")
+```
+
+### 2. Verificar versión remota
+
+```bash
+VERSION_REMOTA=$(curl -s https://raw.githubusercontent.com/doncheli/don-cheli-sdd/main/VERSION)
+```
+
+### 3. Comparar
+
+```
+=== Verificación de Actualización ===
+
+Versión instalada: 1.6.0
+Versión disponible: 1.7.0
+
+Estado: ⚠️ Actualización disponible
+```
+
+### 4. Mostrar cambios
+
+Obtener el changelog entre versiones:
+
+```bash
+# Mostrar commits entre versiones
+curl -s "https://api.github.com/repos/doncheli/don-cheli-sdd/compare/v${VERSION_LOCAL}...v${VERSION_REMOTA}" \
+  | jq '.commits[].commit.message'
+```
+
+### 5. Preguntar al usuario
+
+```
+¿Deseas actualizar Don Cheli de v1.6.0 a v1.7.0? (s/n)
+```
+
+### 6. Aplicar actualización
+
+```bash
+# Clonar versión nueva en temporal
+TEMP=$(mktemp -d)
+git clone --depth 1 https://github.com/doncheli/don-cheli-sdd.git "$TEMP"
+
+# Ejecutar instalador
+cd "$TEMP" && bash scripts/instalar.sh --global
+
+# Limpiar
+rm -rf "$TEMP"
+```
+
+## Output
+
+```
+=== Actualización Completada ===
+
+✅ Don Cheli actualizado: v1.6.0 → v1.7.0
+
+Cambios aplicados:
+- 3 habilidades nuevas
+- 2 comandos nuevos
+- 5 archivos actualizados
+
+Reinicia Claude Code para aplicar los cambios.
+```
+
+## Verificación de Anthropic Skills 2.0
+
+Además de actualizar el framework, este comando verifica la conformidad con el estándar Anthropic Agent Skills.
+
+### Proceso de verificación
+
+```
+1. FETCH — Obtener spec y template desde el repo oficial
+   ├── https://github.com/anthropics/skills/blob/main/spec/agent-skills-spec.md
+   ├── https://github.com/anthropics/skills/blob/main/template/SKILL.md
+   └── https://agentskills.io/specification (spec completa)
+
+2. COMPARE — Comparar con el formato actual del framework
+   ├── Campos requeridos en frontmatter (name, description)
+   ├── Campos nuevos agregados al spec
+   ├── Convenciones de naming (lowercase, hyphens, max 64 chars)
+   ├── Estructura de directorios (skill-name/SKILL.md)
+   └── Features nuevas (hooks, allowed-tools, model, effort, etc.)
+
+3. AUDIT — Validar archivos del framework
+   ├── Comandos en comandos/especdev/*.md → frontmatter válido
+   ├── Comandos en comandos/razonar/*.md → frontmatter válido
+   ├── Skills en .agent/skills/*/SKILL.md → conformidad Anthropic
+   ├── Habilidades en habilidades/*/HABILIDAD.md → formato extendido
+   └── Naming conventions en todos los archivos
+
+4. REPORT — Generar reporte de conformidad
+```
+
+### Output de verificación Skills 2.0
+
+```
+=== Anthropic Skills 2.0 — Verificación de Conformidad ===
+
+Spec source: https://agentskills.io/specification
+Template source: https://github.com/anthropics/skills/blob/main/template/SKILL.md
+Last check: 2026-03-24
+
+Campos requeridos:
+  ✅ name — presente en todos los skills
+  ✅ description — presente en todos los skills y comandos
+
+Campos opcionales detectados en spec:
+  ✅ allowed-tools — soportado
+  ✅ model — soportado
+  ✅ effort — soportado
+  ⚠️ hooks — no implementado en habilidades Don Cheli (solo en .agent/skills)
+  ⚠️ context: fork — no implementado
+
+Naming:
+  ✅ 125/125 archivos siguen convención lowercase-hyphens
+
+Novedades en el spec (si las hay):
+  ℹ️ Nuevo campo "argument-hint" detectado — considerar agregar
+  ℹ️ Nuevo campo "disable-model-invocation" — considerar agregar
+
+Resumen: 98% conformidad | 2 campos opcionales pendientes
+```
+
+### Qué se verifica contra el spec oficial
+
+| Check | Fuente | Qué valida |
+|-------|--------|------------|
+| Frontmatter YAML | Template oficial | `---` delimiters, campos `name` + `description` |
+| Naming | Spec | Solo lowercase, números, hyphens (max 64 chars) |
+| Estructura | Spec | `skill-name/SKILL.md` dentro del directorio de skills |
+| Campos opcionales | Spec en agentskills.io | Nuevos campos agregados al estándar |
+| Plugin format | `.claude-plugin` | Compatibilidad con marketplace oficial |
+| Description length | Spec | Max 1024 chars recomendado |
+
+### Comando combinado
+
+```bash
+/dc:actualizar                    # Actualiza framework + verifica Skills 2.0
+/dc:actualizar --solo-skills      # Solo verificar conformidad Skills 2.0
+/dc:actualizar --verificar        # Solo verificar, no aplicar nada
+/dc:actualizar --forzar           # Aplicar sin confirmar
+```
+
+## Verificación Automática
+
+Si se configura en `.especdev/config.yaml`:
+
+```yaml
+actualizaciones:
+  verificar_al_iniciar: true
+  frecuencia: semanal  # diario | semanal | nunca
+  verificar_skills_spec: true  # Verificar conformidad Anthropic Skills 2.0
+```
+
+El comando `/dc:continuar` verifica automáticamente si hay actualizaciones disponibles y notifica al usuario sin interrumpir el flujo.
+
+## Fuentes oficiales
+
+- Spec: https://agentskills.io/specification
+- Repo: https://github.com/anthropics/skills
+- Template: https://github.com/anthropics/skills/blob/main/template/SKILL.md
+- Docs: https://support.claude.com/en/articles/12512198-creating-custom-skills

package/scripts/.claude/commands/especdev/agente.md

@@ -0,0 +1,43 @@
+---
+description: Cargar un agente especializado para una tarea específica
+i18n: true
+---
+
+# /especdev:agente
+
+## Objetivo
+
+Cargar un agente especializado con el modelo óptimo para una tarea específica.
+
+## Uso
+
+```
+/especdev:agente <nombre>
+/especdev:agente restablecer
+```
+
+## Agentes Disponibles
+
+| Agente | Modelo | Rol |
+|--------|--------|-----|
+| `planificador` | opus | Planificación, descomposición de tareas |
+| `arquitecto` | opus | Diseño de sistemas, decisiones técnicas |
+| `ejecutor` | sonnet | Implementación, escritura de código |
+| `revisor` | opus | Revisión de código, validación de calidad |
+| `tester` | sonnet | Escritura y ejecución de tests |
+| `documentador` | haiku | Actualización de documentación |
+| `estimador` | opus | Estimados de desarrollo y esfuerzo |
+
+## Flujo de Trabajo
+
+```
+Modo Completo: planificador → arquitecto → ejecutor ↔ tester → revisor → documentador
+Modo Rápido:   ejecutor → tester → documentador
+```
+
+## Ahorro de Costos
+
+| Modo | Distribución | Ahorro vs Opus-solo |
+|------|--------------|---------------------|
+| Rápido | 80% sonnet, 20% haiku | ~60% |
+| Completo | 50% sonnet, 30% opus, 20% haiku | ~40% |