specleap-framework 2.1.14 → 2.2.1

package/.commands/planificar.md

@@ -22,6 +22,30 @@ Esto incluye:
 
 ## Flujo
 
+### 0. Cargar credenciales desde .env
+
+**ANTES de cualquier comando que necesite Asana**, cargar las variables de entorno desde el `.env` del proyecto SpecLeap. `setup.sh` guarda allí `ASANA_ACCESS_TOKEN` y `ASANA_WORKSPACE_GID`, pero la shell de Claude Code no las carga automáticamente.
+
+```bash
+# Cargar .env si existe (no fallar si no existe)
+if [ -f .env ]; then
+  set -a
+  source .env
+  set +a
+fi
+
+# Verificar que el token quedó cargado
+if [ -z "${ASANA_ACCESS_TOKEN:-}" ]; then
+  echo "❌ ASANA_ACCESS_TOKEN no está configurado en .env ni en la shell"
+  echo "   Re-ejecuta bash setup.sh para configurar Asana, o exporta manualmente."
+  exit 1
+fi
+```
+
+**Importante:** los scripts `scripts/generate-asana-structure.sh` y `scripts/create-asana-tasks.sh` también cargan `.env` por su cuenta como red de seguridad. Pero comprobar aquí permite dar un mensaje claro al usuario antes de invocar el script.
+
+---
+
 ### 1. Identificar Proyecto
 
 Si no se especifica ruta:
@@ -29,9 +53,9 @@ Si no se especifica ruta:
 ¿Para qué proyecto quieres crear el backlog?
 
 **Proyectos disponibles:**
-1. app-tienda
-2. api-backend
-3. dashboard-analytics
+1. task-manager
+2. inventory-app
+3. crm-suite
 
 Responde con el número o nombre:
 ```
@@ -208,8 +232,14 @@ Edita `scripts/generate-asana-structure.sh`:
 ## Requisitos
 
 1. **CONTRATO.md** existente
-2. **ASANA_ACCESS_TOKEN** configurado en ~/.zshrc
-3. **ASANA_WORKSPACE_GID** configurado (o se detecta automáticamente)
+2. **ASANA_ACCESS_TOKEN** y **ASANA_WORKSPACE_GID** en `.env` del proyecto SpecLeap (`setup.sh` lo crea al instalar)
+
+Los scripts cargan `.env` automáticamente. Si necesitas verificar manualmente:
+
+```bash
+cd <ruta-proyecto-specleap>
+cat .env | grep ASANA
+```
 
 ---
 
@@ -218,20 +248,27 @@ Edita `scripts/generate-asana-structure.sh`:
 ### "Script no encontrado"
 
 ```bash
-cd ~/specleap-framework
 ls scripts/generate-asana-structure.sh
-# Si no existe, verifica instalación
+# Si no existe, verifica instalación o re-ejecuta setup.sh
 ```
 
 ### "ASANA_ACCESS_TOKEN no configurado"
 
+El `.env` del proyecto SpecLeap no existe o no contiene el token. Soluciones:
+
 ```bash
-# Verifica que está en tu ~/.zshrc
-grep ASANA_ACCESS_TOKEN ~/.zshrc
+# Verificar que existe el .env y tiene el token
+ls -la .env && grep ASANA .env
 
-# Si no está, agrégalo:
-echo 'export ASANA_ACCESS_TOKEN="tu-token-aqui"' >> ~/.zshrc
-source ~/.zshrc
+# Si falta o está vacío, re-ejecutar el paso de configuración Asana del setup
+bash setup.sh
+```
+
+Si por alguna razón prefieres exportar manualmente (sin pasar por `.env`):
+
+```bash
+export ASANA_ACCESS_TOKEN="tu-token-aqui"
+export ASANA_WORKSPACE_GID="tu-workspace-gid"
 ```
 
 ### "Error: Not Authorized"

package/CHANGELOG.md

@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.1] - 2026-05-22
+
+### Fixed
+
+- **Bug crítico: los Agent Skills no se cargaban en Claude Code.** `scripts/install-skills.sh` instalaba en `$HOME/.skills/`, que es un path obsoleto que Claude Code dejó de monitorizar. El path canónico que auto-descubre Claude Code es `$HOME/.claude/skills/`. Resultado del bug: todos los usuarios de SpecLeap (incluido Styng) tenían los 34 Agent Skills instalados pero **invisibles** para el runtime — ninguno se activaba por contexto. Detectado tras consultar la doc oficial de Claude Code: solo lee skills de `~/.claude/skills/` (user-level) y `.claude/skills/` (project-level).
+  - **Fix**: `scripts/install-skills.sh` ahora instala en `$HOME/.claude/skills/`. Si detecta una instalación legacy en `$HOME/.skills/` (de versiones ≤ 2.2.0), crea un symlink desde el path canónico apuntando al legacy. Así los usuarios existentes no tienen que mover archivos ni reinstalar — solo ejecutar `bash scripts/install-skills.sh` una vez para que el symlink se cree.
+  - **Migración manual** (alternativa al symlink automático): `ln -s ~/.skills ~/.claude/skills`.
+  - **Verificación**: tras el fix, decirle "Hola" a Claude Code dentro del proyecto y pedir algo que dispare un skill conocido (ej: "qué debo verificar antes de cerrar un ticket") debe activar `verification-before-completion`.
+
+### Changed
+
+- **`CLAUDE.md`, `README.md`, `SETUP.md`, `scripts/README.md`, `.commands/compliance.md`** actualizados para reflejar el path canónico `~/.claude/skills/` y documentar la compatibilidad con instalaciones legacy.
+
+## [2.2.0] - 2026-05-02
+
+### Changed
+
+- **`setup.sh` — el prompt del nombre de carpeta se movió a DESPUÉS del Paso 1 (idioma)**, antes del Paso 2 (GitHub). Ahora sale en el idioma elegido (sólo ES o sólo EN, no bilingüe a la vez como en v2.1.14). El comportamiento funcional es idéntico (Enter para mantener nombre actual con default `specleap-framework`, valida caracteres, renombra in-place si se cambia, salta si `SPECLEAP_INSTALL_PATH` ya está set por `bin/specleap`). Reportado por Styng tras testear v2.1.14: el bloque salía con texto bilingüe simultáneo porque se ejecutaba antes de saber qué idioma había elegido el usuario.
+
+- **`.commands/inicio.md` — nuevo Paso 0 (antes de listar proyectos) que ofrece instalar `markitdown`** (Microsoft, MIT, Python 3.10+) como herramienta opcional. Convierte PDF/Word/Excel/PowerPoint/HTML/CSV/JSON/XML/EPUB a Markdown. Cuando SpecLeap procesa documentos no-markdown durante el flujo conversacional, esta conversión previa baja el consumo de tokens entre 20% y 50%. El prompt se ejecuta UNA SOLA VEZ por sesión "Hola", es bilingüe (ES default, EN si el usuario habla en inglés), y nunca bloquea el flujo principal: si el usuario dice "No" o "Más tarde" se sigue normalmente con el listado de proyectos. Si dice "Sí", se verifica con `command -v markitdown` y se muestran instrucciones de instalación (`pip install 'markitdown[all]'` o `pipx install`) si no está. Pedido por Styng tras validar v2.1.14: quería que tras "Hola" se ofreciera la herramienta antes de empezar el primer proyecto.
+
+### Fixed
+
+- **Bug Asana: `.env` no se cargaba en sesiones nuevas de Claude Code.** `setup.sh` guarda `ASANA_ACCESS_TOKEN` y `ASANA_WORKSPACE_GID` en `.env` del proyecto SpecLeap, pero la shell que arranca Claude Code no lo carga automáticamente. Resultado: `crear-tickets` y `planificar` reportaban "ASANA_ACCESS_TOKEN no configurado" aunque el token sí existía en el `.env`.
+  - **Fix**: `scripts/generate-asana-structure.sh` y `scripts/create-asana-tasks.sh` cargan `.env` con `set -a && source .env && set +a` al inicio (red de seguridad).
+  - **Fix**: `.commands/planificar.md` instruye a la AI a hacer la misma carga ANTES de comprobar el token, dando un mensaje claro al usuario si falta.
+  - **Fix**: `setup.sh` exporta tanto `ASANA_WORKSPACE_ID` como `ASANA_WORKSPACE_GID` (mismo valor) en `.env`, porque distintos scripts usan distintos nombres y antes había que hacer un roundtrip a la API para resolverlo.
+  - **Reportado por Styng** durante test 2026-05-01 de v2.1.14.
+
+### Changed
+
+- **Ejemplos sesgados en cuestionario y comandos sustituidos por nombres genéricos neutros.** Antes los ejemplos eran `casa-de-peli`, `app-tienda`, `Mi Proyecto Awesome`, `Casa de Películas`, `Tienda Online de Café`, `Juan Pérez`, etc. Cambiados a `task-manager`, `inventory-app`, `crm-suite`, `Task Manager Pro`, `María García`, etc. Afecta: `scripts/lib/questions.es.json`, `scripts/lib/questions.en.json`, `.commands/inicio.md`, `.commands/explicar.md`, `.commands/implementar.md`, `.commands/planificar.md`, `.commands/nuevo/README.md`, `.commands/nuevo/responses-example.yaml`. Reportado por Styng: los ejemplos eran reconocibles como proyectos suyos y eso confunde a usuarios nuevos.
+- **Pregunta 9 (competidores) ahora explica el "para qué".** Antes el `help` decía solo "Productos similares que te sirven de inspiración" — el usuario no entendía por qué se preguntaba. Ahora dice "Si conoces apps similares, las usaré como referencia para sugerir features y patrones de UX. Si no, escribe `ninguno` o déjalo vacío".
+
+### Added
+
+- **Tres modos de cuestionario al inicio del Flujo A (proyecto nuevo): MVP, Proyecto serio, Modo creativo.** Después de pedir el nombre del proyecto, `.commands/inicio.md` lanza un `AskUserQuestion` (Paso A0) preguntando qué tipo de proyecto se va a montar:
+  - **MVP** (58 preguntas, 15-20 min) — proyecto pequeño / prototipo / 1 persona o equipo pequeño. Es el comportamiento histórico.
+  - **Proyecto serio** (93 preguntas, 25-35 min) — equipo + departamentos + compliance + SLAs. Las 58 base + 35 nuevas: governance (5), departamentos involucrados (3), integraciones empresariales (5: SSO, ERP, CRM, BI, payroll), SLAs y resiliencia (5: uptime/RTO/RPO/DR/on-call), compliance (4: frameworks, DPO, audit log retention, data residency), roadmap por fases (3), procesos de release (3: feature flags, deploy strategy, rollback), observabilidad (3: APM/alerting/dashboards), multi-X (4: idiomas, tenant, regiones, i18n strategy).
+  - **Modo creativo** (5-10 min) — el usuario describe el proyecto en un párrafo libre; la AI extrae lo dicho con razonamiento estructurado, muestra un resumen para validar, y solo pregunta los **campos críticos** que no fueron mencionados (`scripts/lib/critical_fields.json` define 18 críticos para MVP y 11 extra para Serio).
+
+- **Transiciones bidireccionales entre modos (Paso A9).** Tras generar el CONTRATO en cualquier modo, ofrecer al usuario:
+  - Mantener como está → seguir a `crear-tickets`.
+  - Pasar a Serio → contestar las 35 preguntas extra de governance/compliance/SLAs (manteniendo las respuestas existentes).
+  - Pasar a Creativo → describir matices en un párrafo libre que se añade como sección "Contexto Adicional" del CONTRATO.
+  El paso es iterativo: se puede repetir para ir construyendo el CONTRATO incrementalmente.
+
+- **`scripts/lib/questions.es.json` y `scripts/lib/questions.en.json` ahora marcan cada pregunta con un campo `modes`.** Las 58 base llevan `["mvp", "serio"]` (aparecen en ambos modos); las 35 nuevas llevan `["serio"]` (solo en modo serio). El cuestionario filtra por modo elegido antes de renderizar.
+
+- **Nuevo archivo `scripts/lib/critical_fields.json`** que define los campos mínimos que el modo creativo verifica tras la extracción del párrafo del usuario. Si falta alguno, la AI hace una pregunta dirigida con contexto explicando POR QUÉ se necesita.
+
+### Removed
+
+- **`composer.json`** — residual de un proyecto Laravel previo (`barryvdh/laravel-dompdf`). SpecLeap no usa Composer ni PHP en sus dependencias; el archivo nunca debió formar parte del paquete npm.
+- **`package-lock.json`** — sin sentido en un paquete que no declara `dependencies` ni `devDependencies` en `package.json`. Solo añadía ruido al diff.
+
 ## [2.1.14] - 2026-05-01
 
 ### Changed

package/CLAUDE.md

@@ -172,7 +172,7 @@ Read and follow these standards for ALL code:
 
 ## Agent Skills (Progressive Disclosure)
 
-If **20 Agent Skills TIER 1** are installed (`~/.skills/`), they activate automatically:
+If **Agent Skills TIER 1 + TIER 2 (34 total)** are installed (`~/.claude/skills/`, path that Claude Code auto-discovers), they activate automatically:
 
 ### Activation Triggers
 

package/README.md

@@ -96,7 +96,7 @@ bash setup.sh
 | **Trae los archivos** | npm los descarga | git los clona del repo |
 | **Ideal para** | Empezar rápido, no recordar el flujo de git | Devs que ya manejan git fluidamente |
 
-A partir de aquí ambos flows son idénticos: el `setup.sh` solicita los tokens de GitHub y Asana, instala los 34 Agent Skills en `~/.skills/` y genera la estructura base. Tiempo total: 10 a 15 minutos.
+A partir de aquí ambos flows son idénticos: el `setup.sh` solicita los tokens de GitHub y Asana, instala los 34 Agent Skills en `~/.claude/skills/` y genera la estructura base. Tiempo total: 10 a 15 minutos.
 
 **Requisitos previos:**
 
@@ -139,7 +139,7 @@ El prefijo `/` está reservado por Claude Code para sus propios slash commands (
 
 ## Agent Skills
 
-SpecLeap instala **34 Agent Skills profesionales** en `~/.skills/` durante el setup. Se activan automáticamente cuando el contexto lo requiere.
+SpecLeap instala **34 Agent Skills profesionales** en `~/.claude/skills/` (path canónico que Claude Code auto-descubre) durante el setup. Se activan automáticamente cuando el contexto lo requiere.
 
 ### TIER 1 — 20 skills base
 

package/SETUP.md

@@ -69,7 +69,7 @@ bash setup.sh
 **Qué hace `setup.sh`:**
 - Selecciona idioma (Español/English)
 - Pide tokens GitHub y Asana
-- Instala los 34 Agent Skills en `~/.skills/`
+- Instala los 34 Agent Skills en `~/.claude/skills/` (path canónico que Claude Code auto-descubre)
 - Configura CodeRabbit
 - Crea estructura base + archivos de configuración
 
@@ -233,7 +233,7 @@ Instalación:
 bash scripts/install-skills.sh
 ```
 
-Se descargan e instalan 34 skills en `~/.skills/` (20 TIER 1 más 14 TIER 2):
+Se descargan e instalan 34 skills en `~/.claude/skills/` (path canónico que Claude Code auto-descubre — desde v2.2.1; instalaciones legacy en `~/.skills/` siguen funcionando vía symlink automático). 20 TIER 1 más 14 TIER 2:
 
 - **Consistencia (6):** `verification-before-completion`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `code-reviewer`, `debugging-wizard`
 - **Backend (6):** `laravel-specialist`, `api-designer`, `database-optimizer`, `python-pro`, `react-expert`, `typescript-pro`
@@ -247,7 +247,7 @@ Se descargan e instalan 34 skills en `~/.skills/` (20 TIER 1 más 14 TIER 2):
 Verificar lo instalado:
 
 ```bash
-ls ~/.skills/
+ls ~/.claude/skills/
 ```
 
 ---
@@ -393,7 +393,7 @@ export PATH="$PATH:$(pwd)/openspec/cli"
 
 1. Verifica instalación:
 ```bash
-ls -la ~/.skills/
+ls -la ~/.claude/skills/
 ```
 
 2. Reinicia tu IDE (VSCode/Cursor/JetBrains)
@@ -439,7 +439,7 @@ chmod +x .git/hooks/pre-commit
 - [ ] IDE abierto (VSCode/Cursor) y chat con Claude funcional
 - [ ] Comando `ayuda` ejecutado exitosamente
 - [ ] **Asana configurado en `.env`** (OBLIGATORIO)
-- [ ] **20 Agent Skills instaladas en ~/.skills/** (OBLIGATORIO)
+- [ ] **34 Agent Skills instaladas en ~/.claude/skills/** (OBLIGATORIO)
 - [ ] **Git hooks instalados** (OBLIGATORIO)
 - [ ] **CodeRabbit configurado en GitHub** (OBLIGATORIO)
 - [ ] **Repositorio pusheado a GitHub** (OBLIGATORIO)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specleap-framework",
-  "version": "2.1.14",
+  "version": "2.2.1",
   "description": "Spec-Driven Development Framework — Transform VSCode, Cursor, JetBrains into spec-first development machines",
   "keywords": [
     "spec-driven-development",

package/scripts/README.md

@@ -43,7 +43,7 @@ git commit --no-verify -m "mensaje"
 
 ### `install-skills.sh`
 
-**Propósito:** Instalar los 34 Agent Skills del framework en `~/.skills/`.
+**Propósito:** Instalar los 34 Agent Skills del framework en `~/.claude/skills/` (path canónico que Claude Code auto-descubre). Si existe `~/.skills/` de instalaciones previas (versiones ≤ 2.2.0), se crea un symlink desde el path canónico para mantener compatibilidad.
 
 **Uso:**
 ```bash

package/scripts/create-asana-tasks.sh

@@ -8,6 +8,15 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ASANA_UTILS="$SCRIPT_DIR/lib/asana-utils.sh"
 
+# Auto-cargar .env desde el root del proyecto SpecLeap.
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+if [[ -f "$PROJECT_ROOT/.env" ]]; then
+    set -a
+    # shellcheck disable=SC1090
+    source "$PROJECT_ROOT/.env"
+    set +a
+fi
+
 source "$ASANA_UTILS"
 
 # Colores

package/scripts/generate-asana-structure.sh

@@ -4,6 +4,17 @@
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/../.specleap/i18n.sh"
 
+# Auto-cargar .env desde el root del proyecto SpecLeap.
+# setup.sh guarda ASANA_ACCESS_TOKEN/ASANA_WORKSPACE_GID en .env, pero las
+# shells nuevas (ej: las que arranca Claude Code) no lo cargan automáticamente.
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+if [[ -f "$PROJECT_ROOT/.env" ]]; then
+    set -a
+    # shellcheck disable=SC1090
+    source "$PROJECT_ROOT/.env"
+    set +a
+fi
+
 # SpecLeap — Generador de estructura Asana
 # Convierte CONTRATO.md → proyecto Asana con secciones y tareas
 

package/scripts/install-skills.sh

@@ -1,6 +1,10 @@
 #!/bin/bash
-# SpecLeap — Instalador de Agent Skills TIER 1 + TIER 2
-# Versión 2.1.1 — 34 skills profesionales
+# SpecLeap — Instalador de Agent Skills TIER 1 + TIER 2 (34 skills profesionales)
+#
+# Path: instala en $HOME/.claude/skills/ (path canónico que Claude Code
+# auto-descubre). Si existe $HOME/.skills/ (path legacy de versiones previas
+# de SpecLeap), se crea un symlink desde el path canónico para mantener
+# compatibilidad sin mover archivos.
 
 set -e
 
@@ -85,9 +89,22 @@ INSTALLED=0
 FAILED=0
 SKIPPED=0
 
-SKILLS_DIR="$HOME/.skills"
+SKILLS_DIR="$HOME/.claude/skills"
+LEGACY_SKILLS_DIR="$HOME/.skills"
 TMP_DIR="/tmp/specleap-skills-$$"
 
+# Compatibilidad con instalaciones legacy:
+# Si el path antiguo ($HOME/.skills/) tiene skills y el path canónico
+# no existe todavía, crear symlink. Así Claude Code los ve sin tener
+# que mover archivos ni reinstalar nada.
+if [ -d "$LEGACY_SKILLS_DIR" ] && [ ! -e "$SKILLS_DIR" ]; then
+    mkdir -p "$HOME/.claude"
+    ln -s "$LEGACY_SKILLS_DIR" "$SKILLS_DIR"
+    echo -e "${YELLOW}⚠️  Detected legacy skills path $LEGACY_SKILLS_DIR${NC}"
+    echo -e "${YELLOW}   Created symlink at $SKILLS_DIR for Claude Code auto-discovery.${NC}"
+    echo ""
+fi
+
 mkdir -p "$SKILLS_DIR"
 mkdir -p "$TMP_DIR"
 

package/scripts/lib/critical_fields.json

@@ -0,0 +1,39 @@
+{
+  "metadata": {
+    "version": "1.0",
+    "description": "Campos mínimos que el modo 'creativo' verifica tras extraer información del párrafo del usuario. Si falta alguno, la AI pregunta sólo ese (no las 58/93 completas). Las claves apuntan a IDs de questions.{es,en}.json."
+  },
+  "mvp_critical": [
+    "project.name",
+    "project.display_name",
+    "project.responsible",
+    "identity.objective",
+    "identity.target_audience",
+    "stack.backend.framework",
+    "stack.frontend.framework",
+    "stack.database.engine",
+    "features.core",
+    "features.auth.enabled",
+    "design.responsive",
+    "design.primary_color",
+    "deployment.hosting",
+    "deployment.ssl",
+    "security.level",
+    "security.gdpr_compliant",
+    "testing.coverage_target",
+    "constraints.time_limit"
+  ],
+  "serio_critical_extra": [
+    "governance.product_owner",
+    "governance.release_approver",
+    "departments.list",
+    "compliance.frameworks",
+    "sla.uptime_target",
+    "sla.rto",
+    "roadmap.phases",
+    "release.deploy_strategy",
+    "observability.apm_logs_metrics",
+    "multi.tenant",
+    "multi.regions"
+  ]
+}