specleap-framework 2.1.11 → 2.1.13

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.13] - 2026-05-01
+
+### Fixed
+
+- **Confusion between the two install flows.** Reported by Styng during testing: with `git clone … && bash setup.sh`, the installer was not asking the carpeta-base / folder-name prompts that `bin/specleap` (the npx entry point) does ask. That looked like a regression but it's by design — the prompts live in `bin/specleap` (Node), not in `setup.sh` (bash). When the user clones with git they already chose where the code lives, and the second positional argument of `git clone` is the canonical way to set a custom folder name. The fix is making the difference obvious in docs and in runtime.
+
+#### Changes
+
+- `setup.sh` now prints a bilingual heads-up at the very start (before the language step) when the current folder is named `specleap-framework` (the `git clone` default) AND the script was invoked without `bin/specleap` having set `SPECLEAP_INSTALL_PATH`. The user gets a one-second pause, an explanation of how to clone with a custom name (`git clone <url> mi-proyecto`), and a [S/n] confirmation before continuing. If they cancel, the script exits 0 cleanly.
+- `README.md`: rewrote the "Instalación Rápida" section as two clearly-labeled options (Opción A: vía npx — interactive prompts; Opción B: vía git clone — direct, name controlled by `git clone <url> <nombre>`) plus a comparison table so the reader picks intentionally.
+- `SETUP.md`: replicated the same comparison upfront in the Quick Start section, with full examples for each path.
+
+### Notes
+
+- No code-path change in the actual installation logic. `bin/specleap` keeps its prompts; `setup.sh` runs the same setup it always ran. Only documentation and a single pre-check in `setup.sh` change.
+- The pre-check in `setup.sh` is opt-out (Enter or `S` to continue), so users who really want a folder named `specleap-framework` aren't forced to do anything extra.
+
+## [2.1.12] - 2026-04-30
+
+### Added
+
+- **`scripts/convert-docs.sh`** — wrapper sobre [Microsoft markitdown](https://github.com/microsoft/markitdown) para convertir PDF, Word, PowerPoint, Excel, HTML, CSV, JSON, XML, EPub, imágenes (OCR) y audio (transcripción) a Markdown que el framework pueda usar como contexto. markitdown es una **dependencia opcional** (no se incluye en el tarball npm, no se instala automáticamente): si no está presente, el script muestra el mensaje de instalación (`pip install markitdown` o `uv tool install markitdown`) y termina con exit 1 sin tocar ningún archivo. Bilingüe ES/EN según `SPECLEAP_LANG`.
+- Acepta tanto un archivo individual (`brief.pdf` → `brief.md`) como una carpeta entera (recursivo, max 3 niveles, filtra por extensiones soportadas).
+- Documentación en `README.md` (sección "Convertir documentos a Markdown") y `SETUP.md` (sección "Herramientas Opcionales") con caso de uso típico (briefs de cliente, user stories exportadas, reference docs).
+
+### Notes
+
+- Decisión de diseño: markitdown se queda como opcional para no imponer Python 3.10+ a usuarios que no lo necesiten. SpecLeap solo requiere bash + node + git + curl + jq como antes.
+- Caso de uso típico: cliente entrega brief en PDF → `bash scripts/convert-docs.sh brief.pdf` → `brief.md` → se referencia desde el cuestionario inicial. El AI gana contexto rico desde el primer comando.
+
 ## [2.1.11] - 2026-04-30
 
 ### Fixed

package/README.md

@@ -20,7 +20,7 @@
 
 SpecLeap convierte cualquier IDE con asistente de IA en un entorno de desarrollo spec-first. Combina un contrato de proyecto inmutable, agentes conversacionales especializados, 34 Agent Skills profesionales y un pipeline de validación en tres capas para entregar código consistente y probado sin improvisación.
 
-**Versión actual:** 2.1.11 · **Licencia:** MIT · **Autor:** Styng Arias ([ConceptualCreative](https://conceptualcreative.com))
+**Versión actual:** 2.1.13 · **Licencia:** MIT · **Autor:** Styng Arias ([ConceptualCreative](https://conceptualcreative.com))
 
 ---
 
@@ -44,23 +44,57 @@ SpecLeap convierte cualquier IDE con asistente de IA en un entorno de desarrollo
 
 ## Instalación Rápida
 
-### Vía npm (recomendado)
+Hay dos formas de instalar SpecLeap. Elige según tu preferencia:
+
+### Opción A: Vía npm (instalación interactiva, recomendado)
 
 ```bash
 npx specleap-framework@latest
 ```
 
-### Desde GitHub
+El instalador te **pregunta dónde quieres la carpeta y con qué nombre** antes de copiar nada. Ideal si quieres un setup guiado paso a paso.
+
+Ejemplo de lo que verás:
+
+```
+📁 ¿En qué carpeta base instalar SpecLeap?
+   Default: /Users/tu-usuario/Desktop
+Carpeta base: ~/Downloads
+
+📝 ¿Qué nombre quieres para la carpeta?
+   Default: specleap-framework
+Nombre: mi-app-tienda
+
+→ Resultado: /Users/tu-usuario/Downloads/mi-app-tienda/
+```
+
+### Opción B: Vía git clone (control directo, sin prompts)
 
 ```bash
-git clone https://github.com/ConceptualCreative/specleap-framework.git
-cd specleap-framework
+git clone https://github.com/ConceptualCreative/specleap-framework.git mi-proyecto
+cd mi-proyecto
 bash setup.sh
 ```
 
-El instalador interactivo 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.
+Aquí **tú decides el nombre** pasándolo como segundo argumento de `git clone`. El setup arranca directo, sin preguntar carpeta/nombre porque ya estás dentro del repo donde quieres.
 
-**Requisitos previos:** Node.js ≥ 18, Git, Bash.
+Si haces `git clone <url>` sin segundo argumento, la carpeta se llamará `specleap-framework` (default de git). El setup te avisará por si querías otro nombre.
+
+### Diferencias rápidas
+
+| | Vía npm | Vía git clone |
+|---|---|---|
+| **Pregunta carpeta y nombre** | ✅ Sí, interactivo | ❌ No, lo decides con `cd` y `git clone <url> <nombre>` |
+| **Requiere Node.js** | ✅ Sí (≥ 18) | ⛔ No, solo Git + Bash |
+| **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.
+
+**Requisitos previos:**
+
+- Vía npm → Node.js ≥ 18, Git, Bash.
+- Vía git clone → Git, Bash.
 
 ---
 
@@ -245,6 +279,41 @@ Ambos modos coexisten. Lo habitual es trabajar conversacionalmente en el día a
 
 ---
 
+## Convertir documentos a Markdown (opcional)
+
+Si tienes el brief de un cliente en PDF, user stories en Word, o specs antiguas en Excel, SpecLeap incluye un wrapper sobre [Microsoft markitdown](https://github.com/microsoft/markitdown) para convertirlos a Markdown que el framework pueda usar como contexto.
+
+**Instalación de markitdown** (dependencia opcional):
+
+```bash
+pip install markitdown
+# o, si usas uv:
+uv tool install markitdown
+```
+
+Requiere Python 3.10+. No es obligatorio: SpecLeap funciona perfectamente sin él. Solo lo necesitas si vas a alimentar archivos no-Markdown.
+
+**Uso:**
+
+```bash
+# Un archivo individual
+bash scripts/convert-docs.sh brief.pdf
+# → genera brief.md
+
+# Una carpeta entera (recursivo, max 3 niveles)
+bash scripts/convert-docs.sh ./briefings/
+# → convierte todos los pdf/docx/xlsx/pptx/html/csv/json/xml/epub que encuentre
+
+# Ayuda
+bash scripts/convert-docs.sh --help
+```
+
+Formatos soportados: **PDF, Word, PowerPoint, Excel, HTML, CSV, JSON, XML, EPub, imágenes (con OCR), audio (con transcripción)**.
+
+Si markitdown no está instalado, el script muestra un mensaje claro con las instrucciones de instalación y termina sin tocar nada.
+
+---
+
 ## Preguntas Frecuentes (FAQ)
 
 Las preguntas habituales están respondidas en archivos dedicados:

package/SETUP.md

@@ -2,23 +2,70 @@
 
 ## ⚡ Quick Start (5 minutos)
 
-### Paso 1: Clonar el repositorio
+Hay **dos formas de instalar SpecLeap**. Elige la que prefieras según cómo te resulte más cómodo trabajar.
+
+### Comparativa rápida
+
+| | Opción A: vía npx | Opción B: vía git clone |
+|---|---|---|
+| **Pregunta carpeta y nombre** | ✅ Sí, prompt interactivo | ❌ No (lo decides con `cd` y `git clone <url> <nombre>`) |
+| **Requiere** | Node.js ≥ 18, Git, Bash | Git, Bash |
+| **Cuándo usar** | Quieres setup guiado | Manejas git fluidamente |
+
+---
+
+### Opción A: vía npx (recomendado para empezar)
 
 ```bash
-git clone https://github.com/ConceptualCreative/specleap-framework.git
-cd specleap-framework
+cd ~/Downloads      # o donde quieras que vaya el proyecto
+npx specleap-framework@latest
+```
+
+El instalador te pregunta:
+1. **Carpeta base** (default = donde estás).
+2. **Nombre de la carpeta** (default = `specleap-framework`).
+
+Después continúa con el setup normal (idioma, GitHub token, Asana token, skills, CodeRabbit).
+
+**Ejemplo:**
+
 ```
+📁 ¿En qué carpeta base instalar SpecLeap?
+   Default: /Users/tu-usuario/Downloads
+Carpeta base: (Enter para usar default)
 
-### Paso 2: Ejecutar instalador
+📝 ¿Qué nombre quieres para la carpeta?
+   Default: specleap-framework
+Nombre: mi-app-tienda
+
+→ Resultado final: /Users/tu-usuario/Downloads/mi-app-tienda/
+```
+
+---
+
+### Opción B: vía git clone
 
 ```bash
-bash install.sh
+# Clona el repo con el nombre que tú quieras (segundo argumento de git clone)
+git clone https://github.com/ConceptualCreative/specleap-framework.git mi-proyecto
+cd mi-proyecto
+bash setup.sh
 ```
 
-**Qué hace:**
+Aquí **no hay prompts de carpeta o nombre** — ya estás dentro de `mi-proyecto/` que tú nombraste con git. El `setup.sh` arranca directo con la selección de idioma.
+
+Si haces `git clone <url>` **sin segundo argumento**, la carpeta se llamará `specleap-framework` por defecto. El setup te avisará por si esperabas otro nombre y te ofrecerá cancelar.
+
+---
+
+### Después del setup (ambas opciones)
+
+**Qué hace `setup.sh`:**
 - Selecciona idioma (Español/English)
-- Crea estructura de carpetas
-- Genera archivos base
+- Pide tokens GitHub y Asana
+- Instala los 34 Agent Skills en `~/.skills/`
+- Configura CodeRabbit
+- Crea estructura base + archivos de configuración
 
 ### Paso 3: Responder cuestionario
 
@@ -254,6 +301,50 @@ El commit es rechazado. Corrige y vuelve a intentar.
 
 ---
 
+## 🔄 Herramientas Opcionales
+
+### markitdown — Convertir PDF/Word/Excel a Markdown
+
+Útil cuando un cliente te entrega el brief en PDF, las user stories en Word, o cualquier doc de referencia que quieras alimentar a SpecLeap como contexto. **No es obligatorio**: SpecLeap funciona sin él, sólo lo necesitas si trabajas con archivos no-Markdown.
+
+**Requisito previo:** Python 3.10 o superior.
+
+**Instalación:**
+
+```bash
+pip install markitdown
+# o, si prefieres uv:
+uv tool install markitdown
+```
+
+**Uso (vía wrapper de SpecLeap):**
+
+```bash
+# Un archivo
+bash scripts/convert-docs.sh ./brief-cliente.pdf
+
+# Una carpeta entera (max 3 niveles de profundidad)
+bash scripts/convert-docs.sh ./referencias/
+
+# Ayuda
+bash scripts/convert-docs.sh --help
+```
+
+**Formatos soportados:** PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx), HTML, CSV, JSON, XML, EPub, imágenes (con OCR), audio (con transcripción).
+
+Si markitdown no está instalado, el script muestra el mensaje de instalación y termina con exit 1. No toca ningún archivo. Es seguro ejecutarlo aunque no lo tengas.
+
+**Caso típico de uso en SpecLeap:**
+
+1. Recibes el brief de un cliente en PDF.
+2. `bash scripts/convert-docs.sh ./brief.pdf` → genera `brief.md`.
+3. Lo pegas o referencias en el cuestionario al responder "¿Qué hace este proyecto?" / "¿Qué problema resuelve?".
+4. El AI tiene contexto rico desde el primer comando.
+
+Más info sobre markitdown: https://github.com/microsoft/markitdown
+
+---
+
 ## 📚 Documentación Completa
 
 ### Guías Detalladas

package/package.json

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

package/scripts/convert-docs.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# SpecLeap — Wrapper para convertir documentos a Markdown.
+#
+# Usa Microsoft markitdown (https://github.com/microsoft/markitdown) por
+# debajo. markitdown es una dependencia OPCIONAL: si no está instalada,
+# este script muestra cómo instalarla y termina sin tocar nada.
+#
+# Formatos soportados (por markitdown): PDF, Word (.docx), PowerPoint
+# (.pptx), Excel (.xlsx), HTML, imágenes (con OCR), audio (con
+# transcripción), CSV, JSON, XML, ZIP, EPub, YouTube URLs.
+#
+# Uso:
+#   bash scripts/convert-docs.sh <archivo-o-carpeta>
+#
+# Ejemplos:
+#   bash scripts/convert-docs.sh brief.pdf
+#   bash scripts/convert-docs.sh ./docs/
+#   bash scripts/convert-docs.sh user-stories.docx
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ─── Detectar idioma ──────────────────────────────────────────────────────
+SPECLEAP_LANG="${SPECLEAP_LANG:-}"
+
+if [ -z "$SPECLEAP_LANG" ] && [ -f "$SCRIPT_DIR/../.specleap/config.json" ]; then
+    SPECLEAP_LANG=$(grep -o '"language": "[^"]*"' "$SCRIPT_DIR/../.specleap/config.json" 2>/dev/null | cut -d'"' -f4 || true)
+fi
+SPECLEAP_LANG="${SPECLEAP_LANG:-es}"
+
+# ─── Mensajes bilingües ───────────────────────────────────────────────────
+if [ "$SPECLEAP_LANG" = "en" ]; then
+    MSG_USAGE="Usage: bash scripts/convert-docs.sh <file-or-directory>"
+    MSG_NOT_INSTALLED="markitdown is not installed."
+    MSG_INSTALL_TIP="Install with: pip install markitdown   (or: uv tool install markitdown)"
+    MSG_PYTHON_REQ="Requires Python 3.10 or higher."
+    MSG_DOCS="Docs: https://github.com/microsoft/markitdown"
+    MSG_CONVERTING="Converting"
+    MSG_DONE="Done"
+    MSG_NOT_FOUND="File or directory not found"
+    MSG_CONVERTED_TO="→"
+    MSG_NO_FILES="No convertible files found in"
+    MSG_SUMMARY="Summary"
+    MSG_FAIL="FAIL"
+    MSG_PROCESSING_DIR="Processing directory"
+    MSG_HELP_INTRO="Convert documents (PDF, Word, Excel, HTML, etc.) to Markdown using markitdown."
+    MSG_HELP_FORMATS="Supported formats: PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, XML, EPub, images, audio."
+    MSG_HELP_EXAMPLES="Examples:"
+else
+    MSG_USAGE="Uso: bash scripts/convert-docs.sh <archivo-o-carpeta>"
+    MSG_NOT_INSTALLED="markitdown no está instalado."
+    MSG_INSTALL_TIP="Instala con: pip install markitdown   (o: uv tool install markitdown)"
+    MSG_PYTHON_REQ="Requiere Python 3.10 o superior."
+    MSG_DOCS="Docs: https://github.com/microsoft/markitdown"
+    MSG_CONVERTING="Convirtiendo"
+    MSG_DONE="Listo"
+    MSG_NOT_FOUND="Archivo o carpeta no encontrado"
+    MSG_CONVERTED_TO="→"
+    MSG_NO_FILES="No se encontraron archivos convertibles en"
+    MSG_SUMMARY="Resumen"
+    MSG_FAIL="FALLO"
+    MSG_PROCESSING_DIR="Procesando carpeta"
+    MSG_HELP_INTRO="Convierte documentos (PDF, Word, Excel, HTML, etc.) a Markdown usando markitdown."
+    MSG_HELP_FORMATS="Formatos soportados: PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, XML, EPub, imágenes, audio."
+    MSG_HELP_EXAMPLES="Ejemplos:"
+fi
+
+# ─── Colores ──────────────────────────────────────────────────────────────
+if [[ -t 1 ]]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[1;33m'
+    CYAN='\033[0;36m'
+    BOLD='\033[1m'
+    NC='\033[0m'
+else
+    RED=''; GREEN=''; YELLOW=''; CYAN=''; BOLD=''; NC=''
+fi
+
+# ─── Help ─────────────────────────────────────────────────────────────────
+show_help() {
+    echo "$MSG_HELP_INTRO"
+    echo ""
+    echo "$MSG_USAGE"
+    echo ""
+    echo "$MSG_HELP_FORMATS"
+    echo ""
+    echo "$MSG_HELP_EXAMPLES"
+    echo "  bash scripts/convert-docs.sh brief.pdf"
+    echo "  bash scripts/convert-docs.sh ./docs/"
+    echo "  bash scripts/convert-docs.sh user-stories.docx"
+    echo ""
+    echo "$MSG_DOCS"
+}
+
+if [ $# -lt 1 ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
+    show_help
+    exit 0
+fi
+
+# ─── Verificar markitdown instalado ───────────────────────────────────────
+if ! command -v markitdown >/dev/null 2>&1; then
+    echo -e "${RED}❌ $MSG_NOT_INSTALLED${NC}"
+    echo ""
+    echo -e "${YELLOW}💡 $MSG_INSTALL_TIP${NC}"
+    echo -e "   $MSG_PYTHON_REQ"
+    echo ""
+    echo -e "${CYAN}📖 $MSG_DOCS${NC}"
+    exit 1
+fi
+
+INPUT="$1"
+if [ ! -e "$INPUT" ]; then
+    echo -e "${RED}❌ $MSG_NOT_FOUND: $INPUT${NC}"
+    exit 1
+fi
+
+# ─── Conversión ────────────────────────────────────────────────────────────
+CONVERTED_OK=0
+CONVERTED_FAIL=0
+
+convert_one() {
+    local file="$1"
+    local base="${file%.*}"
+    local out="${base}.md"
+
+    echo -ne "  ${CYAN}→${NC} $MSG_CONVERTING $(basename "$file") ... "
+    if markitdown "$file" > "$out" 2>/dev/null; then
+        echo -e "${GREEN}✅${NC} $MSG_CONVERTED_TO $(basename "$out")"
+        CONVERTED_OK=$((CONVERTED_OK + 1))
+    else
+        echo -e "${RED}❌ $MSG_FAIL${NC}"
+        # No dejar archivo .md basura si falló
+        rm -f "$out"
+        CONVERTED_FAIL=$((CONVERTED_FAIL + 1))
+    fi
+}
+
+if [ -f "$INPUT" ]; then
+    convert_one "$INPUT"
+elif [ -d "$INPUT" ]; then
+    echo -e "${BOLD}📁 $MSG_PROCESSING_DIR: $INPUT${NC}"
+    echo ""
+
+    # Extensiones que markitdown soporta
+    EXTENSIONS=(pdf docx xlsx pptx html htm csv json xml epub rtf odt ods odp txt)
+    FOUND_ANY=0
+
+    for ext in "${EXTENSIONS[@]}"; do
+        while IFS= read -r -d '' file; do
+            convert_one "$file"
+            FOUND_ANY=1
+        done < <(find "$INPUT" -maxdepth 3 -type f -iname "*.${ext}" -print0 2>/dev/null)
+    done
+
+    if [ $FOUND_ANY -eq 0 ]; then
+        echo -e "${YELLOW}⚠️  $MSG_NO_FILES $INPUT${NC}"
+        echo "   (pdf, docx, xlsx, pptx, html, csv, json, xml, epub, ...)"
+        exit 0
+    fi
+fi
+
+echo ""
+echo -e "${GREEN}✅ $MSG_DONE${NC} — $MSG_SUMMARY: ${BOLD}$CONVERTED_OK${NC} OK, ${BOLD}$CONVERTED_FAIL${NC} $MSG_FAIL"

package/setup.sh

@@ -48,6 +48,38 @@ echo -e "${YELLOW}  v2.0.0 — Instalador Profesional${NC}"
 echo -e "${CYAN}${LINE}${NC}"
 echo ""
 
+# ============================================
+# PRE-CHECK: Aviso si la carpeta se llama "specleap-framework"
+# ============================================
+# Si el usuario clonó con `git clone <url>` (sin segundo argumento), la
+# carpeta se llamará "specleap-framework" por defecto. Le avisamos por si
+# quería otro nombre, antes de empezar el setup interactivo.
+# Solo aplica cuando setup.sh se ejecuta directamente (no via bin/specleap,
+# que ya pregunta nombre interactivamente). Detectamos este caso por
+# ausencia de la variable SPECLEAP_INSTALL_PATH (que solo la pone bin/specleap).
+
+CURRENT_FOLDER_NAME="$(basename "$(pwd)")"
+
+if [ -z "${SPECLEAP_INSTALL_PATH:-}" ] && [ "$CURRENT_FOLDER_NAME" = "specleap-framework" ]; then
+    echo "ℹ️  Esta carpeta se llama 'specleap-framework' (nombre por defecto de git clone)."
+    echo "   This folder is named 'specleap-framework' (git clone default)."
+    echo ""
+    echo "   Si querías otro nombre / If you wanted a different name:"
+    echo "     1) Cancela con Ctrl+C / Cancel with Ctrl+C"
+    echo "     2) Vuelve a ejecutar / Run again with:"
+    echo "        git clone https://github.com/ConceptualCreative/specleap-framework.git mi-proyecto"
+    echo "        cd mi-proyecto"
+    echo "        bash setup.sh"
+    echo ""
+    read -p "¿Continuar con el nombre 'specleap-framework'? / Continue with 'specleap-framework'? [S/n]: " CONTINUE_DEFAULT
+    if [[ "$CONTINUE_DEFAULT" =~ ^[Nn]$ ]]; then
+        echo ""
+        echo "Cancelado por el usuario / Cancelled by user."
+        exit 0
+    fi
+    echo ""
+fi
+
 # ============================================
 # PASO 1: Selección de Idioma
 # ============================================