specleap-framework 2.1.10 → 2.1.12

package/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **`setup.sh` was lying about how many Agent Skills get installed.** The "Paso 4/6" header correctly read "34 skills" but the description right below said "SpecLeap incluye 20 Agent Skills profesionales" with a four-bullet breakdown that summed to exactly 20 — leftover text from before the 14 TIER 2 skills were added in v2.1.0. Reported by Styng during v2.1.10 testing.
+
+#### What the user sees now
+
+- The full count (34) is stated up front.
+- TIER 1 (20) is broken down into its 6 actual categories: Consistency (3), Backend/Dev (7), Design (4), DevOps (3), Testing (2), Frontend (1).
+- TIER 2 (14) is broken down into its 8 actual categories: Design/Frontend advanced (3), Mobile (2), Security audits/GDPR (2), Testing advanced (2), Infrastructure (2), Brainstorming (1), PDF (1), Documentation (1).
+- Both blocks are localised (ES + EN) and visually grouped with bold tier headers so the user can scan them quickly before deciding whether to install.
+
+The numbers now match exactly what `scripts/install-skills.sh` actually downloads from upstream repos (obra/superpowers, jeffallan/claude-skills, anthropics/skills, vercel-labs/agent-*, alirezarezvani/claude-skills).
+
 ## [2.1.10] - 2026-04-30
 
 ### Added

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.10 · **Licencia:** MIT · **Autor:** Styng Arias ([ConceptualCreative](https://conceptualcreative.com))
+**Versión actual:** 2.1.12 · **Licencia:** MIT · **Autor:** Styng Arias ([ConceptualCreative](https://conceptualcreative.com))
 
 ---
 
@@ -245,6 +245,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

@@ -254,6 +254,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.10",
+  "version": "2.1.12",
   "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

@@ -395,20 +395,48 @@ echo -e "${CYAN}${LINE}${NC}"
 echo ""
 
 if [ "$LANG" = "es" ]; then
-    echo "SpecLeap incluye 20 Agent Skills profesionales:"
-    echo "  • 5 Seguridad (OWASP, STRIDE)"
-    echo "  • 3 Consistencia (verification-before-completion)"
-    echo "  • 6 Diseño (Vercel-style, UI/UX)"
-    echo "  • 6 Backend/Dev (Laravel, React, TDD)"
+    echo "SpecLeap incluye 34 Agent Skills profesionales:"
+    echo ""
+    echo "  ${BOLD}TIER 1 (20 skills):${NC}"
+    echo "    • 3 Consistencia (verification-before-completion, code review)"
+    echo "    • 7 Backend/Dev (Laravel, React, Python, API, DB)"
+    echo "    • 4 Diseño (Vercel-style, UI/UX, Canvas)"
+    echo "    • 3 DevOps (Cloud, Architecture)"
+    echo "    • 2 Testing (TDD, Code Review)"
+    echo "    • 1 Frontend (TypeScript)"
+    echo ""
+    echo "  ${BOLD}TIER 2 (14 skills):${NC}"
+    echo "    • 3 Design/Frontend avanzado (Vercel agent-browser)"
+    echo "    • 2 Mobile (React Native, Flutter)"
+    echo "    • 2 Security (audits, GDPR/DSGVO)"
+    echo "    • 2 Testing avanzado (Playwright, Test Master)"
+    echo "    • 2 Infrastructure (Terraform, Monitoring)"
+    echo "    • 1 Brainstorming"
+    echo "    • 1 PDF"
+    echo "    • 1 Documentation"
     echo ""
     echo "⏱️  Tiempo: 2-3 minutos"
     echo ""
 else
-    echo "SpecLeap includes 20 professional Agent Skills:"
-    echo "  • 5 Security (OWASP, STRIDE)"
-    echo "  • 3 Consistency (verification-before-completion)"
-    echo "  • 6 Design (Vercel-style, UI/UX)"
-    echo "  • 6 Backend/Dev (Laravel, React, TDD)"
+    echo "SpecLeap includes 34 professional Agent Skills:"
+    echo ""
+    echo "  ${BOLD}TIER 1 (20 skills):${NC}"
+    echo "    • 3 Consistency (verification-before-completion, code review)"
+    echo "    • 7 Backend/Dev (Laravel, React, Python, API, DB)"
+    echo "    • 4 Design (Vercel-style, UI/UX, Canvas)"
+    echo "    • 3 DevOps (Cloud, Architecture)"
+    echo "    • 2 Testing (TDD, Code Review)"
+    echo "    • 1 Frontend (TypeScript)"
+    echo ""
+    echo "  ${BOLD}TIER 2 (14 skills):${NC}"
+    echo "    • 3 Design/Frontend advanced (Vercel agent-browser)"
+    echo "    • 2 Mobile (React Native, Flutter)"
+    echo "    • 2 Security (audits, GDPR/DSGVO)"
+    echo "    • 2 Testing advanced (Playwright, Test Master)"
+    echo "    • 2 Infrastructure (Terraform, Monitoring)"
+    echo "    • 1 Brainstorming"
+    echo "    • 1 PDF"
+    echo "    • 1 Documentation"
     echo ""
     echo "⏱️  Time: 2-3 minutes"
     echo ""