@johpaz/hive-sdk 0.1.4 → 0.1.6

package/packages/core/src/skills/bundled/agents/task_orchestrator/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: task_orchestrator
+description: "Orchestrate tasks across multiple workers with delegation, status tracking, and bus communication"
+version: 1.2.0
+author: Hive Team
+icon: "🎻"
+category: agents
+permissions:
+  - agent_manage
+  - agent_bus
+dependencies: []
+tools: [get_available_models, task_delegate, task_list, task_status, agent_find, agent_create, bus_publish, bus_read]
+
+# Structured skill fields
+triggers:
+  - "delegá esta tarea"
+  - "delegate task"
+  - "orquestá los workers"
+  - "orchestrate workers"
+  - "coordiná el equipo"
+  - "coordinate team"
+  - "estado de las tareas"
+  - "task status"
+  - "comunicá los workers"
+  - "communicate workers"
+  - "mensaje al bus"
+  - "bus message"
+  - "tarea en paralelo"
+  - "parallel tasks"
+
+preferred_agents: []
+---
+# Task Orchestrator — referencia operativa
+
+La doctrina de orquestación (descomponer → delegar en paralelo → terminar el turno → sintetizar en el fan-in) está en tu system prompt. Esta skill es la referencia de las herramientas.
+
+## Herramientas
+
+| Tool | Qué hace | Cuándo |
+|------|----------|--------|
+| `task_delegate` | Persiste y asigna una tarea a un worker | Delegar. Preferí `mode="async"` |
+| `agent_find` | Descubre workers del catálogo y propios | Antes de delegar. Nunca para comprobar ejecución |
+| `task_list` | Lista ejecuciones reales persistidas | El usuario pregunta y no conocés IDs |
+| `task_status` | Estado de tareas por ID | El usuario pide estado antes del fan-in |
+| `get_available_models` | Providers y modelos activos | Antes de crear un worker |
+| `agent_create` | Crea un worker nuevo | Último recurso: nada del catálogo sirve |
+| `bus_publish` / `bus_read` | Mensajes entre workers | Dependencias entre workers en vuelo |
+
+## Fan-out
+
+```javascript
+// Tres partes independientes → tres llamadas en la MISMA respuesta
+task_delegate({ worker_id: "web_researcher",            task_description: "...", mode: "async" })
+task_delegate({ worker_id: "office_document_agent",     task_description: "...", mode: "async" })
+task_delegate({ worker_id: "schedule_automation_agent", task_description: "...", mode: "async" })
+```
+
+Cada llamada devuelve `task_id`, `job_id` y `run_id`: prueba de que la tarea quedó persistida.
+
+## Fan-in
+
+Hive te reinvoca con:
+
+```
+[Sistema] Todas las tareas delegadas de este turno alcanzaron estado terminal.
+[{ task_id, worker_id, task, ok, result, error }, ...]
+```
+
+Sintetizá una sola respuesta. Las entradas con `ok: false` se reportan con su motivo real.
+
+## Crear un worker (último recurso)
+
+```javascript
+get_available_models({ capabilities: "analysis" })
+// → [{ providerId: "anthropic", modelId: "claude-sonnet-4-6", ... }]
+
+agent_create({
+  name: "data_analyst",
+  description: "Experto en análisis de datos",
+  system_prompt: "Sos analista de datos experto...",
+  tools_json: ["web_search", "web_fetch", "save_note"],
+  providerId: "anthropic",   // OBLIGATORIO
+  modelId: "claude-sonnet-4-6", // OBLIGATORIO
+})
+```
+
+Para una integración MCP sin especialista, pedí autorización primero. Si el usuario acepta, creá un worker con `mcp_server_id`; si participan varios servidores, creá o reutilizá uno por servidor. Nunca pases servidores MCP dinámicos a `task_delegate`.
+
+## Errores a evitar
+
+- ❌ Serializar tareas independientes en vez de fan-out paralelo
+- ❌ Polling con `task_status` esperando el resultado — el fan-in llega solo
+- ❌ Declarar éxito antes de recibir el `[Sistema]`, o presentar `ok=false` como éxito
+- ❌ Reportar éxito sin revisar `acceptance`/`checks` de la entrega, o ignorar un `checks.status="failed"`
+- ❌ Corregir a mano lo que `task_revise` puede reencolar en el mismo worker
+- ❌ Crear un worker que el catálogo ya cubre
+- ❌ Delegar saludos, preguntas simples o la conversación
+- ❌ Usar `delegate_task`, `find_agent`, `create_agent`, `get_task_status`, `publish_to_bus`, `get_bus_messages` — **no existen**

package/packages/core/src/skills/bundled/api/api_client/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: api_client
+description: "Make HTTP requests to REST APIs using curl-like methods (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)"
+version: 1.0.0
+author: Hive Team
+icon: "🌐"
+category: api
+permissions:
+  - internet_access
+dependencies: []
+tools: [api_request]
+
+# Structured skill fields
+triggers:
+  - "llama a la api"
+  - "llama al api"
+  - "consume la api"
+  - "haz una petición"
+  - "haz un request"
+  - "envía un post"
+  - "envía un put"
+  - "envía un delete"
+  - "curl"
+  - "api request"
+  - "rest api"
+  - "endpoint"
+  - "webhook"
+  - "integrar con api"
+  - "conectar con api"
+  - "obtener datos de api"
+  - "enviar datos a api"
+
+preferred_agents: []
+
+steps:
+  - step: 1
+    action: api_request
+    instruction: "Call the API endpoint with the correct HTTP method, headers, and body. Always include Content-Type and Authorization if required by the API."
+    params:
+      method: "GET | POST | PUT | DELETE | PATCH"
+      url: "https://api.example.com/endpoint"
+      headers:
+        Content-Type: "application/json"
+        Authorization: "Bearer TOKEN_IF_NEEDED"
+      body: '{"key":"value"}'
+    output: api_response
+
+  - step: 2
+    action: validate
+    instruction: "Check the response status. If 2xx, extract and present the data. If 4xx/5xx, analyze the error and suggest fixes (missing auth, wrong payload, rate limit)."
+    output: validated_result
+
+rules:
+  - "Always use api_request instead of web_fetch when you need custom headers, body, or non-GET methods"
+  - "Never expose API keys or tokens in the final response to the user — mention they are handled securely"
+  - "If the API returns JSON, parse and present it in a readable format (tables, lists, markdown)"
+  - "For paginated APIs, indicate if more pages exist and offer to fetch them"
+  - "Respect rate limits — if a 429 is returned, wait and retry or inform the user"
+  - "Always include the Content-Type header when sending a body (usually application/json)"
+  - "Use query_params object instead of manually appending to the URL"
+  - "If the user provides a curl command, translate it into api_request parameters"
+
+output_format:
+  structure: markdown
+  sections:
+    - "summary"
+    - "request_details"
+    - "response_data"
+    - "next_steps"
+  max_length: "800 words unless user requests full raw response"
+
+examples:
+  - user_input: "haz un get a https://api.github.com/users/octocat"
+    expected_behavior: "api_request({ method: 'GET', url: 'https://api.github.com/users/octocat' }) → parse JSON → show key fields"
+
+  - user_input: "envía un post a https://httpbin.org/post con {nombre: 'Juan'}"
+    expected_behavior: "api_request({ method: 'POST', url: 'https://httpbin.org/post', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({nombre:'Juan'}) }) → show response"
+
+  - user_input: "actualiza el recurso 123 en la API con {status: 'active'}"
+    expected_behavior: "api_request({ method: 'PUT', url: '.../123', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ...' }, body: JSON.stringify({status:'active'}) }) → confirm update"
+
+  - user_input: "curl -X DELETE https://api.example.com/items/456 -H 'Authorization: Bearer token123'"
+    expected_behavior: "Translate curl to api_request({ method: 'DELETE', url: 'https://api.example.com/items/456', headers: { 'Authorization': 'Bearer token123' } }) → confirm deletion"
+---
+
+# API Client Skill
+
+## Cuándo se Activa
+
+Esta skill se activa cuando el usuario necesita interactuar con una API REST: consultar datos, crear recursos, actualizar, eliminar, o cualquier operación HTTP.
+
+## Herramientas Disponibles
+
+| Tool | Qué hace | Cuándo usarla |
+|------|----------|---------------|
+| `api_request` | Realiza peticiones HTTP completas (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS) con headers, body, query params y timeout | Siempre que necesites llamar un endpoint REST, webhook, o servicio externo |
+
+## Parámetros de api_request
+
+- `method` (requerido): GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
+- `url` (requerido): URL completa del endpoint
+- `headers` (opcional): objeto con headers HTTP. Ej: `{ "Authorization": "Bearer TOKEN", "Content-Type": "application/json" }`
+- `body` (opcional): cuerpo de la petición como string. Para JSON, enviar JSON.stringify(objeto)
+- `query_params` (opcional): parámetros de query que se codificarán automáticamente en la URL
+- `timeout_ms` (opcional): timeout en ms. Default: 30000. Máx: 120000
+
+## Diferencia con web_fetch
+
+- `web_fetch`: solo GET, sin headers custom, ideal para scraping de páginas web
+- `api_request`: cualquier método HTTP, headers custom, body, query params — ideal para APIs REST
+
+## Workflow
+
+1. **Identificar endpoint y método** → Determinar URL, método, headers necesarios
+2. **Construir request** → `api_request({ method, url, headers, body })`
+3. **Validar respuesta** → Si 2xx: extraer datos. Si error: analizar y sugerir fix
+4. **Presentar resultados** → JSON parseado en formato legible, no crudo a menos que se pida
+
+## Mejores Prácticas
+
+- Siempre enviar `Content-Type: application/json` cuando el body es JSON
+- Usar `query_params` en lugar de append manual a la URL
+- No exponer tokens/secrets en la respuesta final al usuario
+- Si la API requiere auth, pedirla al usuario o usar variables de entorno
+- Para errores 4xx, revisar: auth, formato del body, campos requeridos, rate limits
+
+## Errores a Evitar
+
+- ❌ Usar web_fetch para POST/PUT/DELETE con headers
+- ❌ Enviar objetos directamente en body (debe ser string)
+- ❌ Olvidar Content-Type al enviar JSON
+- ❌ Exponer API keys en la respuesta visible

package/packages/core/src/skills/bundled/cli/cli_pipeline/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: cli_pipeline
+description: "Execute shell commands and pipe output to files for logging and further processing"
+version: 1.0.0
+author: Hive Team
+icon: "🔗"
+category: cli
+permissions:
+  - shell_exec
+  - filesystem_write
+dependencies: []
+tools: [cli_exec, fs_write]
+
+# Structured skill fields
+triggers:
+  - "guardá el output"
+  - "save output"
+  - "pipeline"
+  - "pipe to file"
+  - "redireccioná el output"
+  - "redirect output"
+  - "log del comando"
+  - "command log"
+  - "ejecutá y guardá"
+  - "run and save"
+  - "resultado en archivo"
+  - "result to file"
+
+preferred_agents: []
+
+steps:
+  - step: 1
+    action: validate_command
+    instruction: "Validate command is safe and appropriate for pipeline execution"
+    output: validated_command
+
+  - step: 2
+    action: cli_exec
+    instruction: "Execute command and capture full output (stdout + stderr)"
+    params:
+      command: "validated command"
+      timeout: "appropriate timeout"
+    output: command_output
+
+  - step: 3
+    action: format_output
+    instruction: "Format output for file storage: add timestamp, command, execution time"
+    output: formatted_output
+
+  - step: 4
+    action: fs_write
+    instruction: "Write output to specified file path"
+    params:
+      path: "logs/command_YYYY-MM-DD_HH-MM-SS.log"
+      content: "formatted output"
+    output: file_written
+
+rules:
+  - "Capture both stdout and stderr for complete logging"
+  - "Add metadata: timestamp, command, execution time, exitCode"
+  - "Use descriptive filenames with timestamps for logs"
+  - "For large outputs, write incrementally or split files"
+  - "Confirm file path before writing"
+
+output_format:
+  structure: markdown
+  sections:
+    - "command"
+    - "timestamp"
+    - "exit_code"
+    - "execution_time"
+    - "output_file"
+  max_length: "Full logged output"
+
+examples:
+  - user_input: "ejecutá npm install y guardá el output en logs/install.log"
+    expected_behavior: "cli_exec({ command: 'npm install' }) → format with metadata → fs_write({ path: 'logs/install.log' })"
+
+  - user_input: "corré los tests y guardá el resultado"
+    expected_behavior: "cli_exec({ command: 'npm test' }) → capture full output → write to timestamped log file"
+
+  - user_input: "hacé un pipeline de git log a archivo"
+    expected_behavior: "cli_exec({ command: 'git log --oneline' }) → write to 'logs/git_log_YYYY-MM-DD.md'"
+---
+
+# CLI Pipeline Skill
+
+## Cuándo se Activa
+
+Para ejecutar comandos y guardar el output en archivos para logging o procesamiento posterior.
+
+## Herramientas Disponibles
+
+| Tool | Qué hace | Cuándo usarla |
+|------|----------|---------------|
+| `cli_exec` | Ejecuta un comando con timeout y captura su salida | Comandos autorizados |
+| `fs_write` | Escribe un archivo dentro del workspace | Guardar output |
+
+## Workflow
+
+1. **Validar comando** → Seguro para ejecución
+2. **Ejecutar** → Capturar stdout + stderr
+3. **Formatear** → Agregar timestamp, comando, metadata
+4. **Escribir** → `fs_write({ path, content })`
+
+## Formato de Log
+
+```markdown
+# Command Log
+
+**Command**: npm install
+**Timestamp**: 2025-03-09 14:30:00
+**Exit Code**: 0
+**Execution Time**: 45.2s
+
+---
+
+## Output
+
+[stdout content...]
+[stderr if any...]
+```
+
+## Mejores Prácticas
+
+- Filenames con timestamp para tracking
+- Incluir metadata completa (exitCode, tiempo)
+- Capturar stdout y stderr
+- Para outputs grandes, escribir incrementalmente
+
+## Errores a Evitar
+
+- ❌ No incluir metadata en log
+- ❌ Filenames genéricos sin timestamp
+- ❌ No capturar stderr

package/packages/core/src/skills/bundled/cli/cli_safe_exec/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: cli_safe_exec
+description: "Execute shell commands safely with error handling, timeouts, and output validation"
+version: 1.0.0
+author: Hive Team
+icon: "💻"
+category: cli
+permissions:
+  - shell_exec
+dependencies: []
+tools: [cli_exec]
+
+# Structured skill fields
+triggers:
+  - "ejecutá este comando"
+  - "run this command"
+  - "corré el comando"
+  - "execute command"
+  - "terminal"
+  - "bash"
+  - "shell"
+  - "npm"
+  - "yarn"
+  - "bun"
+  - "git"
+  - "docker"
+  - "comando de sistema"
+  - "system command"
+
+preferred_agents: []
+
+steps:
+  - step: 1
+    action: validate_command
+    instruction: "Validate command is safe. Check for destructive operations (rm, DROP, DELETE)"
+    output: validated_command
+
+  - step: 2
+    action: exec or terminal
+    instruction: "Execute with appropriate timeout. Use exec for simple, terminal for complex"
+    params:
+      command: "validated command"
+      timeout: 30-300 seconds
+    output: command_result
+
+  - step: 3
+    action: parse_result
+    instruction: "Parse stdout and stderr. Check exitCode (0=success)"
+    output: parsed_output
+
+  - step: 4
+    action: handle_error
+    instruction: "If failed, analyze error and suggest fixes or retry options"
+    output: error_handling
+
+rules:
+  - "NEVER use for scheduled tasks — use cron.create instead"
+  - "Prefer read-only commands when possible"
+  - "Confirm before destructive operations (rm, DROP, DELETE, --force)"
+  - "Set appropriate timeout: 30s simple, 120s builds, 300s heavy"
+  - "Always check exitCode — non-zero means failure"
+  - "Use absolute paths for reliability"
+
+output_format:
+  structure: markdown
+  sections:
+    - "command"
+    - "exit_code"
+    - "stdout"
+    - "stderr"
+    - "execution_time"
+  max_length: "Full output with analysis"
+
+examples:
+  - user_input: "ejecutá npm install"
+    expected_behavior: "exec({ command: 'npm install', timeout: 120 }) → check exitCode → return installation summary"
+
+  - user_input: "corré los tests"
+    expected_behavior: "exec({ command: 'npm test', timeout: 180 }) → parse results → report pass/fail count"
+
+  - user_input: "hacé git status"
+    expected_behavior: "exec({ command: 'git status' }) → return current branch and changes"
+---
+
+# CLI Safe Exec Skill
+
+## Cuándo se Activa
+
+Para ejecutar comandos de shell de forma segura con manejo de errores y timeouts.
+
+## Herramientas Disponibles
+
+| Tool | Qué hace | Cuándo usarla |
+|------|----------|---------------|
+| `exec` | Ejecuta con validación y timeout | Comandos simples (<30s) |
+| `terminal` | Ejecuta con entorno completo | Comandos complejos, Git, npm |
+
+## ⚠️ ADVERTENCIA CRÍTICA
+
+**NUNCA usar para tareas programadas** — usar `cron.create` en su lugar.
+
+## Workflow
+
+1. **Validar** → Comando es seguro, no destructivo
+2. **Ejecutar** → `exec` o `terminal` con timeout apropiado
+3. **Parsear** → Check exitCode, stdout, stderr
+4. **Manejar error** → Si falló, analizar y sugerir fixes
+
+## Timeouts Apropiados
+
+| Tipo | Timeout |
+|------|---------|
+| Listar archivos | 10s |
+| Git operations | 30s |
+| npm install | 120s |
+| npm run build | 120s |
+| npm test | 180s |
+| Docker builds | 300s |
+
+## Errores a Evitar
+
+- ❌ Usar para cron (usar cron.create)
+- ❌ Sin timeout apropiado
+- ❌ Ignorar exitCode
+- ❌ Comandos destructivos sin confirmar

package/packages/core/src/skills/bundled/cli/software_engineering/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: software_engineering
+description: "Implement, debug, and verify scoped software changes in an existing repository"
+version: 1.0.0
+author: Hive Team
+icon: "🛠️"
+category: cli
+permissions: [filesystem_read, filesystem_write, shell_exec]
+dependencies: []
+tools: [fs_read, fs_write, fs_edit, fs_list, fs_glob, fs_exists, cli_exec]
+triggers: [implementar código, corregir bug, ejecutar tests, implement code, fix bug]
+preferred_agents: [software_engineer]
+---
+
+# Ingeniería de software
+
+1. Inspecciona estructura, convenciones y cambios existentes.
+2. Determina la causa o el cambio mínimo antes de editar.
+3. Conserva cambios ajenos y limita el diff al objetivo.
+4. Ejecuta tests, typecheck o build proporcionales al riesgo.
+5. Entrega archivos cambiados, comandos ejecutados, resultados y riesgos.
+
+No publiques, no delegues y no uses comandos destructivos sin autorización explícita.