@saulwade/swl-ses 2.5.3 → 2.6.0

package/comandos/swl/mcp-status.md

@@ -1,175 +1,175 @@
----
-name: swl:mcp-status
-description: >
-  Health check de servidores MCP, descubrimiento dinamico de herramientas y
-  gestion de conexiones MCP configuradas en swl-ses.
-version: 1.0.0
-tipo: comando
----
-
-# /swl:mcp-status — Estado y descubrimiento MCP
-
-Reporta el estado de todos los servidores MCP configurados en `.claude/settings.json`,
-lista sus herramientas disponibles y guarda un snapshot para referencia futura.
-
-## Subcomandos disponibles
-
-### Status (health check)
-
-Muestra si cada servidor responde correctamente y cuantas herramientas expone:
-
-```bash
-python scripts/mcp-orchestrator.py status
-```
-
-Salida esperada:
-```
-Estado de servidores MCP:
---------------------------------------------------------------------
-  code-review-graph            OK    5 tools   1203ms  [stdio]
-
-  Total: 1 servidores, 1 activos, 5 herramientas disponibles
-```
-
-Con traza registrada en `.planning/traces/`:
-```bash
-python scripts/mcp-orchestrator.py status --trace
-```
-
-### Discover (inventario completo)
-
-Lista todas las herramientas de todos los servidores con sus descripciones:
-
-```bash
-python scripts/mcp-orchestrator.py discover
-```
-
-Para un servidor especifico (via pool-manager):
-```bash
-python scripts/mcp-pool-manager.py list-tools code-review-graph
-```
-
-### Find-tool (busqueda de herramientas)
-
-Busca herramientas por nombre o descripcion en todos los servidores activos:
-
-```bash
-python scripts/mcp-orchestrator.py find-tool "review"
-python scripts/mcp-orchestrator.py find-tool "blast radius"
-```
-
-### Summary (ultimo snapshot sin reconectar)
-
-Muestra el ultimo estado guardado sin iniciar conexiones nuevas:
-
-```bash
-python scripts/mcp-orchestrator.py summary
-```
-
-Util en contextos donde no se quiere esperar la reconexion.
-
-### Ping
-
-Verifica conectividad y tiempo de respuesta de un servidor especifico:
-
-```bash
-python scripts/mcp-pool-manager.py ping
-python scripts/mcp-pool-manager.py ping code-review-graph
-```
-
-### Call-tool (llamada directa a herramienta)
-
-Llama una herramienta MCP directamente desde CLI para pruebas:
-
-```bash
-python scripts/mcp-pool-manager.py call-tool code-review-graph <herramienta> '{"arg": "valor"}'
-```
-
-## Salida JSON
-
-Todos los subcomandos aceptan `--json` para salida estructurada:
-
-```bash
-python scripts/mcp-orchestrator.py status --json
-python scripts/mcp-orchestrator.py discover --json | python -m json.tool
-python scripts/mcp-pool-manager.py list-tools --json
-```
-
-## Trazabilidad
-
-Las llamadas MCP pueden instrumentarse con `mcp-telemetry.py`:
-
-```bash
-# Ver trazas de hoy
-python scripts/mcp-telemetry.py report
-
-# Estadisticas de los ultimos 7 dias por servidor/herramienta
-python scripts/mcp-telemetry.py stats --days 7
-
-# Salida JSON para procesamiento
-python scripts/mcp-telemetry.py stats --json
-```
-
-Las trazas se guardan en formato OTLP-lite en `.planning/traces/mcp-YYYY-MM-DD.jsonl`,
-compatible con el sistema de trazabilidad de `telemetria-agentes.js`.
-
-## Uso desde otro script (importacion)
-
-`mcp-telemetry.py` expone `MCPTelemetrySession` para instrumentar sesiones MCP
-desde otros scripts de swl-ses:
-
-```python
-import sys
-sys.path.insert(0, 'scripts')
-from mcp_telemetry import MCPTelemetrySession
-from pathlib import Path
-
-cwd = Path('.')
-server_cfg = {'command': 'python', 'args': ['-m', 'mi_server']}
-
-async def ejemplo():
-    async with MCPTelemetrySession(cwd, 'mi-server', server_cfg) as sess:
-        tools = await sess.list_tools()
-        result = await sess.call_tool('mi_herramienta', {'arg': 'valor'})
-        # La traza se registra automaticamente en .planning/traces/
-```
-
-## Archivos del modulo mcp-swl
-
-| Archivo | Proposito |
-|---------|-----------|
-| `scripts/mcp-pool-manager.py` | Gestor de conexiones — CLI para list-servers, list-tools, ping, call-tool |
-| `scripts/mcp-telemetry.py` | Trazabilidad OTLP-lite — registra y reporta llamadas MCP |
-| `scripts/mcp-orchestrator.py` | Orquestador multi-servidor — status, discover, find-tool, summary |
-| `comandos/swl/mcp-status.md` | Esta documentacion |
-
-## Configuracion de servidores MCP
-
-Los servidores se leen de la clave `mcpServers` en:
-1. `.claude/settings.local.json` (maxima prioridad, no versionado)
-2. `.claude/settings.json` (proyecto, versionado)
-3. `mcp-servers.json` (alternativa independiente)
-
-Formato de configuracion:
-```json
-{
-  "mcpServers": {
-    "mi-server": {
-      "command": "npx",
-      "args": ["-y", "@mcp/mi-server"],
-      "env": { "MI_VAR": "valor" }
-    },
-    "server-http": {
-      "url": "http://localhost:8931/sse"
-    }
-  }
-}
-```
-
-## Cuando usar este comando
-
-- Al iniciar una sesion de trabajo: verificar que los servers MCP esten activos
-- Antes de `/swl:revisar-impacto`: validar que `code-review-graph` responde
-- Al agregar un nuevo MCP server: descubrir sus herramientas con `discover`
-- En debugging: llamar herramientas directamente con `call-tool`
-- En reporting: generar snapshots para documentacion o metricas
+---
+name: swl:mcp-status
+description: >
+  Health check de servidores MCP, descubrimiento dinamico de herramientas y
+  gestion de conexiones MCP configuradas en swl-ses.
+version: 1.0.0
+tipo: comando
+---
+
+# /swl:mcp-status — Estado y descubrimiento MCP
+
+Reporta el estado de todos los servidores MCP configurados en `.claude/settings.json`,
+lista sus herramientas disponibles y guarda un snapshot para referencia futura.
+
+## Subcomandos disponibles
+
+### Status (health check)
+
+Muestra si cada servidor responde correctamente y cuantas herramientas expone:
+
+```bash
+python scripts/mcp-orchestrator.py status
+```
+
+Salida esperada:
+```
+Estado de servidores MCP:
+--------------------------------------------------------------------
+  code-review-graph            OK    5 tools   1203ms  [stdio]
+
+  Total: 1 servidores, 1 activos, 5 herramientas disponibles
+```
+
+Con traza registrada en `.planning/traces/`:
+```bash
+python scripts/mcp-orchestrator.py status --trace
+```
+
+### Discover (inventario completo)
+
+Lista todas las herramientas de todos los servidores con sus descripciones:
+
+```bash
+python scripts/mcp-orchestrator.py discover
+```
+
+Para un servidor especifico (via pool-manager):
+```bash
+python scripts/mcp-pool-manager.py list-tools code-review-graph
+```
+
+### Find-tool (busqueda de herramientas)
+
+Busca herramientas por nombre o descripcion en todos los servidores activos:
+
+```bash
+python scripts/mcp-orchestrator.py find-tool "review"
+python scripts/mcp-orchestrator.py find-tool "blast radius"
+```
+
+### Summary (ultimo snapshot sin reconectar)
+
+Muestra el ultimo estado guardado sin iniciar conexiones nuevas:
+
+```bash
+python scripts/mcp-orchestrator.py summary
+```
+
+Util en contextos donde no se quiere esperar la reconexion.
+
+### Ping
+
+Verifica conectividad y tiempo de respuesta de un servidor especifico:
+
+```bash
+python scripts/mcp-pool-manager.py ping
+python scripts/mcp-pool-manager.py ping code-review-graph
+```
+
+### Call-tool (llamada directa a herramienta)
+
+Llama una herramienta MCP directamente desde CLI para pruebas:
+
+```bash
+python scripts/mcp-pool-manager.py call-tool code-review-graph <herramienta> '{"arg": "valor"}'
+```
+
+## Salida JSON
+
+Todos los subcomandos aceptan `--json` para salida estructurada:
+
+```bash
+python scripts/mcp-orchestrator.py status --json
+python scripts/mcp-orchestrator.py discover --json | python -m json.tool
+python scripts/mcp-pool-manager.py list-tools --json
+```
+
+## Trazabilidad
+
+Las llamadas MCP pueden instrumentarse con `mcp-telemetry.py`:
+
+```bash
+# Ver trazas de hoy
+python scripts/mcp-telemetry.py report
+
+# Estadisticas de los ultimos 7 dias por servidor/herramienta
+python scripts/mcp-telemetry.py stats --days 7
+
+# Salida JSON para procesamiento
+python scripts/mcp-telemetry.py stats --json
+```
+
+Las trazas se guardan en formato OTLP-lite en `.planning/traces/mcp-YYYY-MM-DD.jsonl`,
+compatible con el sistema de trazabilidad de `telemetria-agentes.js`.
+
+## Uso desde otro script (importacion)
+
+`mcp-telemetry.py` expone `MCPTelemetrySession` para instrumentar sesiones MCP
+desde otros scripts de swl-ses:
+
+```python
+import sys
+sys.path.insert(0, 'scripts')
+from mcp_telemetry import MCPTelemetrySession
+from pathlib import Path
+
+cwd = Path('.')
+server_cfg = {'command': 'python', 'args': ['-m', 'mi_server']}
+
+async def ejemplo():
+    async with MCPTelemetrySession(cwd, 'mi-server', server_cfg) as sess:
+        tools = await sess.list_tools()
+        result = await sess.call_tool('mi_herramienta', {'arg': 'valor'})
+        # La traza se registra automaticamente en .planning/traces/
+```
+
+## Archivos del modulo mcp-swl
+
+| Archivo | Proposito |
+|---------|-----------|
+| `scripts/mcp-pool-manager.py` | Gestor de conexiones — CLI para list-servers, list-tools, ping, call-tool |
+| `scripts/mcp-telemetry.py` | Trazabilidad OTLP-lite — registra y reporta llamadas MCP |
+| `scripts/mcp-orchestrator.py` | Orquestador multi-servidor — status, discover, find-tool, summary |
+| `comandos/swl/mcp-status.md` | Esta documentacion |
+
+## Configuracion de servidores MCP
+
+Los servidores se leen de la clave `mcpServers` en:
+1. `.claude/settings.local.json` (maxima prioridad, no versionado)
+2. `.claude/settings.json` (proyecto, versionado)
+3. `mcp-servers.json` (alternativa independiente)
+
+Formato de configuracion:
+```json
+{
+  "mcpServers": {
+    "mi-server": {
+      "command": "npx",
+      "args": ["-y", "@mcp/mi-server"],
+      "env": { "MI_VAR": "valor" }
+    },
+    "server-http": {
+      "url": "http://localhost:8931/sse"
+    }
+  }
+}
+```
+
+## Cuando usar este comando
+
+- Al iniciar una sesion de trabajo: verificar que los servers MCP esten activos
+- Antes de `/swl:revisar-impacto`: validar que `code-review-graph` responde
+- Al agregar un nuevo MCP server: descubrir sus herramientas con `discover`
+- En debugging: llamar herramientas directamente con `call-tool`
+- En reporting: generar snapshots para documentacion o metricas

package/comandos/swl/modelo.md

@@ -1,100 +1,100 @@
----
-name: swl:modelo
-description: Sugiere o consulta el modelo óptimo (haiku/sonnet/opus) para la tarea actual según complejidad detectada. Muestra costo relativo y justificación. Útil antes de delegar a un subagente o antes de iniciar una tarea larga.
-allowed_tools: ["Read", "Bash"]
----
-
-# /swl:modelo — Sugerencia de modelo por complejidad de tarea
-
-Analiza la descripción de una tarea y sugiere el modelo Claude óptimo según
-su complejidad. No fuerza el modelo — Claude Code lo decide — pero proporciona
-una recomendación fundamentada con costo relativo para que el usuario elija
-conscientemente.
-
-## Cuándo usar
-
-- Antes de iniciar una tarea larga o costosa para optimizar el uso de tokens
-- Antes de delegar a un subagente y querer indicar qué modelo usar
-- Cuando se tiene duda entre sonnet y opus para una tarea ambigua
-- Como parte del flujo del orquestador al asignar trabajo a agentes especializados
-
-## Uso
-
-```
-/swl:modelo               — Muestra modelo sugerido para el contexto actual
-/swl:modelo "descripción" — Sugiere modelo para la tarea descrita
-```
-
-## Paso 1 — Obtener descripción
-
-Si el usuario invocó el comando sin argumentos, inferir la tarea del contexto
-de la conversación activa: último mensaje del usuario, archivos abiertos, o
-el plan activo en `.planning/ESTADO.md`.
-
-Si el usuario pasó una descripción entre comillas, usar esa descripción directamente.
-
-## Paso 2 — Evaluar complejidad
-
-Evaluar la complejidad con el subcomando del CLI (resuelve cross-scope: repo
-madre / `swl-ses` en PATH / `npx`; ver `docs/invocacion-cli-cross-scope.md`):
-
-```bash
-swl-ses sugerir-modelo "DESCRIPCIÓN_DE_LA_TAREA"
-# fallback si swl-ses no está en PATH:
-#   npx -y @saulwade/swl-ses@latest sugerir-modelo "DESCRIPCIÓN_DE_LA_TAREA"
-```
-
-Si el subcomando falla (CLI no disponible), aplicar la tabla de routing
-manualmente (ver Paso 3).
-
-## Paso 3 — Tabla de routing manual (fallback)
-
-Aplicar este criterio si el script no está disponible:
-
-| Condición | Modelo | Complejidad |
-|-----------|--------|-------------|
-| > 20 archivos afectados o > 2 lenguajes | opus | compleja |
-| Descripción contiene: arquitectura, migración, seguridad, performance, diseñar, planificar, debugging profundo, sistema completo | opus | compleja |
-| Descripción contiene: formateo, typo, renombrar, import, lint fix, comment — Y <= 3 archivos | haiku | trivial |
-| Cualquier otro caso | sonnet | estándar |
-
-## Paso 4 — Presentar resultado
-
-Presentar la sugerencia con este formato exacto:
-
-```
-Modelo sugerido: [MODELO] ([costo relativo])
-
-Complejidad detectada: [trivial | estándar | compleja]
-Razón: [justificación de una oración]
-
-Tabla de routing:
-  Trivial  → haiku  ($)    Formateo, typos, lint fixes, imports
-  Estándar → sonnet ($$)   Implementación, tests, reviews, refactors
-  Compleja → opus   ($$$)  Arquitectura, migraciones, seguridad, sistemas
-
-Nota: Esta es una sugerencia. Claude Code usa el modelo configurado en la sesión.
-Para tareas complejas, considera iniciar una sesión nueva con opus activo.
-```
-
-## Tabla de routing completa
-
-| Complejidad | Modelo | Costo | Indicadores de detección |
-|-------------|--------|-------|--------------------------|
-| Trivial | haiku | $ | formateo, typo, renombrar, import, lint fix, comment |
-| Estándar | sonnet | $$ | implementar, test, review, refactor, endpoint, componente, fix bug |
-| Compleja | opus | $$$ | arquitectura, migración, seguridad, performance, diseñar, planificar, debugging profundo, sistema completo |
-
-**Escalado automático por contexto**:
-- > 20 archivos afectados → opus independiente de los indicadores de texto
-- > 2 lenguajes involucrados → opus independiente de los indicadores de texto
-
-## Reglas de comportamiento
-
-- NUNCA modificar archivos como parte de este comando — es de solo lectura.
-- Si no hay descripción ni contexto inferable, pedir al usuario una descripción
-  de 1 oración antes de evaluar.
-- La sugerencia es informativa. No bloquear ni generar error si el usuario elige
-  un modelo distinto al sugerido.
-- Si el usuario pide explicación de la fórmula, explicar pass@k no aplica aquí —
-  ese concepto está en `evaluacion-agentes`. Este comando usa heurísticas de texto.
+---
+name: swl:modelo
+description: Sugiere o consulta el modelo óptimo (haiku/sonnet/opus) para la tarea actual según complejidad detectada. Muestra costo relativo y justificación. Útil antes de delegar a un subagente o antes de iniciar una tarea larga.
+allowed_tools: ["Read", "Bash"]
+---
+
+# /swl:modelo — Sugerencia de modelo por complejidad de tarea
+
+Analiza la descripción de una tarea y sugiere el modelo Claude óptimo según
+su complejidad. No fuerza el modelo — Claude Code lo decide — pero proporciona
+una recomendación fundamentada con costo relativo para que el usuario elija
+conscientemente.
+
+## Cuándo usar
+
+- Antes de iniciar una tarea larga o costosa para optimizar el uso de tokens
+- Antes de delegar a un subagente y querer indicar qué modelo usar
+- Cuando se tiene duda entre sonnet y opus para una tarea ambigua
+- Como parte del flujo del orquestador al asignar trabajo a agentes especializados
+
+## Uso
+
+```
+/swl:modelo               — Muestra modelo sugerido para el contexto actual
+/swl:modelo "descripción" — Sugiere modelo para la tarea descrita
+```
+
+## Paso 1 — Obtener descripción
+
+Si el usuario invocó el comando sin argumentos, inferir la tarea del contexto
+de la conversación activa: último mensaje del usuario, archivos abiertos, o
+el plan activo en `.planning/ESTADO.md`.
+
+Si el usuario pasó una descripción entre comillas, usar esa descripción directamente.
+
+## Paso 2 — Evaluar complejidad
+
+Evaluar la complejidad con el subcomando del CLI (resuelve cross-scope: repo
+madre / `swl-ses` en PATH / `npx`; ver `docs/invocacion-cli-cross-scope.md`):
+
+```bash
+swl-ses sugerir-modelo "DESCRIPCIÓN_DE_LA_TAREA"
+# fallback si swl-ses no está en PATH:
+#   npx -y @saulwade/swl-ses@latest sugerir-modelo "DESCRIPCIÓN_DE_LA_TAREA"
+```
+
+Si el subcomando falla (CLI no disponible), aplicar la tabla de routing
+manualmente (ver Paso 3).
+
+## Paso 3 — Tabla de routing manual (fallback)
+
+Aplicar este criterio si el script no está disponible:
+
+| Condición | Modelo | Complejidad |
+|-----------|--------|-------------|
+| > 20 archivos afectados o > 2 lenguajes | opus | compleja |
+| Descripción contiene: arquitectura, migración, seguridad, performance, diseñar, planificar, debugging profundo, sistema completo | opus | compleja |
+| Descripción contiene: formateo, typo, renombrar, import, lint fix, comment — Y <= 3 archivos | haiku | trivial |
+| Cualquier otro caso | sonnet | estándar |
+
+## Paso 4 — Presentar resultado
+
+Presentar la sugerencia con este formato exacto:
+
+```
+Modelo sugerido: [MODELO] ([costo relativo])
+
+Complejidad detectada: [trivial | estándar | compleja]
+Razón: [justificación de una oración]
+
+Tabla de routing:
+  Trivial  → haiku  ($)    Formateo, typos, lint fixes, imports
+  Estándar → sonnet ($$)   Implementación, tests, reviews, refactors
+  Compleja → opus   ($$$)  Arquitectura, migraciones, seguridad, sistemas
+
+Nota: Esta es una sugerencia. Claude Code usa el modelo configurado en la sesión.
+Para tareas complejas, considera iniciar una sesión nueva con opus activo.
+```
+
+## Tabla de routing completa
+
+| Complejidad | Modelo | Costo | Indicadores de detección |
+|-------------|--------|-------|--------------------------|
+| Trivial | haiku | $ | formateo, typo, renombrar, import, lint fix, comment |
+| Estándar | sonnet | $$ | implementar, test, review, refactor, endpoint, componente, fix bug |
+| Compleja | opus | $$$ | arquitectura, migración, seguridad, performance, diseñar, planificar, debugging profundo, sistema completo |
+
+**Escalado automático por contexto**:
+- > 20 archivos afectados → opus independiente de los indicadores de texto
+- > 2 lenguajes involucrados → opus independiente de los indicadores de texto
+
+## Reglas de comportamiento
+
+- NUNCA modificar archivos como parte de este comando — es de solo lectura.
+- Si no hay descripción ni contexto inferable, pedir al usuario una descripción
+  de 1 oración antes de evaluar.
+- La sugerencia es informativa. No bloquear ni generar error si el usuario elige
+  un modelo distinto al sugerido.
+- Si el usuario pide explicación de la fórmula, explicar pass@k no aplica aquí —
+  ese concepto está en `evaluacion-agentes`. Este comando usa heurísticas de texto.