Pulso

Pulso convierte una solicitud de ingeniería en un cambio implementado, validado y trazable. Es un framework local de orquestación adaptativa para OpenCode y VS Code Agents que coordina especialistas, protege el alcance y exige evidencia antes de declarar una entrega completa.

Su principio es sencillo: usar el menor proceso que permita entregar con confianza. Una corrección acotada va directamente a Executor; planificación, exploración, verificación y auditorías aparecen solo cuando aportan valor real.

Capacidades

Capacidad	Qué aporta
Orquestación adaptativa	Selecciona rutas rápidas, normales, planificadas o sensibles a partir de señales concretas de riesgo.
Entrega de extremo a extremo	Coordina descubrimiento, implementación, pruebas, revisión e integración Git sin abandonar el objetivo original.
Contratos de trabajo	Limita cada tarea por rutas permitidas, exclusiones, criterios de aceptación, validación y autoridad explícita.
Especialistas bajo demanda	Incorpora Planner, Explorer, Verifier, Challenger y auditores únicamente cuando la tarea los necesita.
Autointegración de agentes	`/pulso-autointegrate` descubre, entrevista y registra agentes personalizados en una agenda global para delegarlos mediante tareas nativas de OpenCode.
Seguridad operativa	Usa leases, control de alcance, circuit breaker, protección de cambios ajenos y restricciones sobre Git y operaciones remotas.
Verificación basada en evidencia	Diferencia implementación, verificación e integración; una narración del agente nunca basta para declarar éxito.
Memoria técnica selectiva	Conserva únicamente lecciones verificadas y reutilizables, sin guardar conversaciones, payloads ni datos sensibles.
Preferencias controladas	Propone preferencias a partir del uso, pero requiere aprobación humana antes de convertirlas en comportamiento estable.
Observabilidad local	Dashboard y métricas muestran objetivos, agentes, duración, validaciones, reparaciones e intervenciones humanas.
Diagnóstico y recuperación	Doctor, leases recuperables y reparación de experiencia permiten detectar y resolver estado inconsistente sin borrar trabajo útil.
Configuración de modelos	`/pulso-configure` descubre el catálogo real de OpenCode y guía presets rápidos o asignaciones por agente, globales o por proyecto.
OpenCode y VS Code Agents	Comparte protocolo y plano de control mediante adaptadores específicos, sin contaminar sesiones donde Pulso no está activo.
Contexto BBVA	Distribuye skills de Pulso para BBVA, CELLS, APX y testing; se activan solo cuando el repositorio proporciona evidencia suficiente.

Por qué Pulso

No crea un enjambre por defecto. La ruta habitual es Pulso → Executor.
No entrega autonomía sin límites. Los permisos técnicos se refuerzan con contratos, leases y guards de runtime.
No confunde actividad con progreso. Detiene ciclos repetitivos y mantiene disponibles el diagnóstico y la evidencia.
No hace crecer su prompt con cada extensión. Los agentes personalizados viven en una agenda consultada bajo demanda.
No convierte todo en memoria. Solo cura resultados verificados con valor reutilizable.
No obliga a cambiar de herramientas. Funciona sobre los flujos nativos de OpenCode y VS Code Agents.

Arquitectura y flujo de entrega

Pulso se organiza como un plano de control local sobre OpenCode. El orquestador recibe el objetivo, inspecciona el estado mínimo necesario y selecciona una ruta determinista mediante señales de riesgo.

Solicitud del usuario
        │
        ▼
Pulso (objetivo, decisiones y enrutamiento)
        │
        ├── Ruta rápida: Executor
        ├── Ruta normal: Executor + Verifier
        ├── Ruta planificada: Planner → Executor
        └── Ruta sensible: Executor + auditor específico
        │
        ▼
Evidencia de implementación y validación
        │
        ▼
Experiencia, métricas y cierre del objetivo

Las rutas se escogen por señales explícitas, como ambigüedad, dependencias, cambios entre capas, autenticación, persistencia, datos sensibles, operaciones remotas, cambios destructivos o evidencia de validación contradictoria. No se añaden especialistas por orden ceremonial: se incorporan solo si ayudan a resolver un hecho, una decisión o un riesgo material.

Antes de permitir una edición, el plugin asigna al Executor un lease de 30 minutos y lo renueva en cada operación. Los cambios que se solapan se serializan; únicamente pueden paralelizarse trabajos independientes. La integración Git es deliberadamente restrictiva: requiere una petición explícita del usuario y una referencia Jira válida.

Componentes y capas del sistema

Capa	Componentes	Responsabilidad
Orquestación	`agents/pulso.md`, `pulso_delivery`, `pulso-control-core.js`	Activa entregas solo tras detectar intención sustantiva, proyecta su contrato y selecciona la ruta mínima.
Contactos de agentes	`/pulso-autointegrate`, `pulso_agent_contacts`	Descubre especialistas externos, conserva fichas aprobadas globalmente y los recupera bajo demanda sin ampliar el prompt permanente.
Ejecución y revisión	`pulso-executor`, Planner, Challenger, Explorer, Verifier y auditores	Implementan o aportan evidencia dentro de límites de autoridad y alcance definidos.
Protocolo y estado	`skills/pulso-protocol/`, `.pulso/`	Establece contratos internos; los plugins proyectan estado, evidencia y leases sin parches del agente.
Resiliencia	`plugins/pulso-circuit-breaker.mjs`, `lib/pulso-circuit-breaker-core.js`	Limita reparaciones repetitivas y bloquea mutaciones cuando una tarea entra en un estado de riesgo.
Experiencia y observabilidad	`plugins/pulso-experience-engine.mjs`, dashboard y reporter	Conserva métricas y memorias verificadas en SQLite, y presenta el estado operativo de forma local.
Operación e instalación	`scripts/`, `bin/`, `tools/`, `pulso.manifest.json`	Sincroniza la distribución, instala el runtime y ofrece diagnóstico y operación local.

La configuración local vive en PULSO.md: guarda una sola vez si .pulso/** se versiona y ofrece una sección Project Rules para instrucciones definidas por el usuario. Cuando se elige untracked, Pulso usa exclusivamente el exclude local de Git y no modifica .gitignore; cuando se elige tracked, elimina su propia exclusión local. .pulso/** es una proyección interna escrita atómicamente por plugins; los agentes no la leen, editan ni muestran durante el trabajo normal. El motor de experiencia utiliza un almacén SQLite externo; la memoria técnica se cura únicamente tras cierres verified o integrated.

Los mensajes informativos, dudas puntuales y revisiones sin cambios no crean objetivos. Una entrega se activa mediante la fachada compacta pulso_delivery cuando existen resultado y alcance concretos; esa misma fachada cierra la entrega. Enrutamiento, restricciones de habilidades, memoria, preferencias, métricas y artefactos permanecen en el plano de control.

El dashboard web es opt-in. Solo se inicia y abre cuando el usuario pide explícitamente ver el dashboard o ejecuta /pulso-dashboard; consultar métricas, memorias, preferencias o configuración no abre el navegador.

Integración con el ecosistema BBVA

Pulso no presupone un stack BBVA para todos los repositorios. Detecta el perfil del proyecto a partir de evidencia y carga las habilidades aplicables solo cuando corresponden:

Contexto confirmado	Habilidades aplicables
Proyecto BBVA	`bbva-engineering`
Aplicación CELLS	`bbva-engineering`, `bbva-cells`
Comportamiento o pruebas CELLS	Las anteriores y `bbva-cells-testing`
Unidad de despliegue APX	`bbva-engineering`, `bbva-apx`
Comportamiento o pruebas APX	Las anteriores y `bbva-apx-testing`
Integración CELLS con APX	Todas las habilidades CELLS y APX pertinentes

Esta integración es condicional y basada en evidencia: si el contexto no está confirmado, el perfil permanece como unknown. Así se evitan reglas de plataforma ajenas al repositorio y se conserva el cumplimiento de las convenciones BBVA cuando sí aplican.

Ecosistema de agentes y autoridades

Cada actor tiene una responsabilidad limitada para evitar conflictos de estado y autoaprobación:

Agente o componente	Autoridad principal
`pulso`	Objetivo, prioridades, decisiones, bloqueos, asignación y ciclo de vida de tareas.
`pulso-planner`	Produce propuestas de plan de solo lectura; no modifica artefactos.
`pulso-executor`	Implementa y valida el cambio dentro del alcance; el plugin registra evidencia y propiedad.
`pulso-verifier` y auditores	Proporcionan revisión independiente y de solo lectura.
`pulso-challenger`	Revisa riesgos irreversibles, dependencias nuevas o decisiones materiales sin modificar el estado.
`pulso-experience-curator` y `pulso-delivery-reporter`	Generan propuestas de memoria y comunicación operativa; no cambian el resultado técnico.
Plugins y herramientas Pulso	Son propietarios exclusivos del circuit breaker, el almacén de experiencia, el enrutamiento, los leases y el diagnóstico.

Los especialistas entregan evidencia estructurada y no pueden modificar la intención del usuario, las prioridades ni el alcance sin una delegación explícita. Pulso no declara éxito por narración: requiere pruebas, auditoría, verificación o confirmación humana pertinente.

Concurrencia y resiliencia con circuit breaker

La concurrencia se protege mediante leases por tarea. El plugin adquiere el lease al iniciar Executor, lo renueva antes de cada herramienta y lo libera ante eventos idle, error, cierre o eliminación. Antes de una nueva delegación consulta los estados de sesión de OpenCode: conserva el bloqueo si el propietario sigue busy o retry, pero libera automáticamente propietarios ausentes o inactivos y transfiere la tarea al reemplazo. Si la consulta no está disponible, un heartbeat sin actividad puede recuperarse tras una gracia acotada. La CLI pulso-lease permanece como respaldo del operador, no como paso normal.

El circuit breaker observa validaciones y ciclos de reparación para evitar insistir sobre el mismo error. Por defecto abre el circuito ante dos errores de validación repetidos o tres ciclos de reparación sin progreso. Cuando está abierto, bloquea las herramientas mutantes, pero conserva la investigación de solo lectura y la validación diagnóstica. El reinicio del circuito requiere intervención humana mediante pulso-breaker.

Los fallos de infraestructura —por ejemplo, dependencias ausentes, puertos ocupados o navegadores de prueba no disponibles— se registran por separado y no abren el circuito. El consumo de tokens también es observacional: permite medir la operación sin impedir por sí mismo la entrega.

Requisitos

Node.js 22.5 o superior; el motor de experiencia utiliza node:sqlite.
OpenCode con un proveedor de modelos configurado o VS Code Agent Host.
npm para instalar dependencias y ejecutar los comandos del proyecto.

Límites de VS Code Agent Host

La distribución de VS Code instala agentes, el MCP de control, hooks y /pulso-doctor en las rutas nativas de Agent Host bajo ~/.copilot. No instala ni anuncia capacidades que Agent Host no ofrece con un contrato estable:

/pulso-configure y pulso-config-manager: la asignación de modelos por agente es exclusiva de OpenCode.
Los agentes built-in de Agent Host no se descubren ni registran como contactos. /pulso-autointegrate sí gestiona agentes externos definidos por el usuario o el workspace en ~/.copilot/agents o .github/agents.
/pulso-dashboard y métricas: los eventos de ejecución y tokens de Agent Host no permiten datos consistentes.

Estas capacidades siguen disponibles sin cambios en OpenCode. En VS Code, pulso_capabilities devuelve explícitamente la lista soportada.

CodeGraph externo opcional

Pulso nunca instala, actualiza ni desinstala CodeGraph. Al inicializar una sesión Pulso, OpenCode y VS Code descubren codegraph en PATH; solo aceptan una versión 1.x. El ciclo de vida solo actúa en una raíz de workspace que tenga un PULSO.md regular con frontmatter canónico válido (schema_version: 1 y artifacts: tracked|untracked); no usa .pulso ni sidecars de CodeGraph como señal de inicialización. Si falta o es inválido, informa not_initialized_with_pulso, no crea índice ni configuración MCP y usa las herramientas locales. Para una raíz Git real (o el cwd real fuera de Git) ya inicializada, si es segura y no tiene índice, el único flujo de ciclo de vida ejecuta sin shell codegraph init <raíz-absoluta> --agents=none. Nunca instala activos de agentes y rechaza /, el home y ancestros del home. Las capacidades, estado y doctor solo inspeccionan: no inicializan ni escriben.

El índice externo queda en <workspace>/.codegraph. La configuración MCP es local al workspace y preserva JSONC, comentarios y entradas del usuario: VS Code usa <workspace>/.vscode/mcp.json; OpenCode usa <workspace>/.opencode/opencode.jsonc. Pulso solo administra su entrada pulso-codegraph y solo la retira si una sidecar de propiedad enlaza el runtime, workspace y payload exacto. El servidor es codegraph serve --mcp, con CODEGRAPH_MCP_TOOLS limitado al perfil fijado de ocho consultas de solo lectura. Se inspeccionó la implementación de allowlist del tarball suministrado @bbva-genai/codegraph 1.0.0 en un directorio temporal aislado; las pruebas del repositorio validan el perfil con un hijo MCP simulado porque el paquete externo no es dependencia del proyecto.

La ausencia, incompatibilidad, índice vacío o fallo no bloquean Pulso: los especialistas autorizados vuelven inmediatamente a read, búsqueda, glob, LSP y terminal locales. En OpenCode, el primer mensaje del agente primario pulso inicializa y registra dinámicamente el MCP para esa sesión, sin recarga; también persiste la configuración local para sesiones posteriores. VS Code Agent Host puede requerir recarga/reinicio para descubrir una configuración creada durante una sesión. Ambos mantienen sus instalaciones y desinstalaciones normales porque esta integración no modifica configuración global.

Desarrollo

Instale dependencias y ejecute la suite de pruebas:

npm install
npm test

Edite Pulso en este repositorio. La instalación de OpenCode aplica el preset recomendado a los agentes Pulso que aún no tengan model: github-copilot/gpt-5.6-terra para razonamiento y github-copilot/gpt-5.6-luna para los demás agentes, incluida la ejecución. Conserva cualquier asignación existente, incluso configuraciones parciales, y la desinstalación nunca elimina modelos.

npm run install:local

En ejecución no interactiva se conserva OpenCode como destino predeterminado por compatibilidad. También puede elegirlo explícitamente:

npm run install:opencode
npm run install:vscode

Configuración interactiva de modelos en OpenCode

Los modelos de OpenCode se configuran sin reinstalar mediante /pulso-configure o pidiéndole a Pulso que configure sus agentes. pulso_models es la única autoridad de Pulso que modifica esas asignaciones.

El wizard consulta primero opencode models, por lo que solo ofrece proveedores y modelos realmente disponibles para ese usuario. Recomienda github-copilot cuando existe, pero permite elegir cualquier otro proveedor detectado.

Rápida / Recomendada: un modelo para razonamiento y ejecución y otro para trabajo estático.
Rápida / Rendimiento: modelos separados para razonamiento, ejecución y trabajo estático.
Rápida / Heredada: elimina modelos fijados para que los agentes usen el modelo de la sesión.
Personalizada: permite escoger un modelo disponible para cada agente, mostrando su rol recomendado.

La configuración puede guardarse globalmente en la instalación de OpenCode o únicamente en el proyecto actual. El gestor solicita confirmación antes de escribir y preserva el resto del archivo JSONC.

Nota sobre el ciclo de vida de OpenCode: OpenCode carga la configuración de modelos al arrancar y no la recarga en caliente. Después de aplicar el wizard es necesario cerrar y reiniciar OpenCode.

El adaptador OpenCode usa ~/.config/opencode de forma predeterminada; OPENCODE_CONFIG_DIR permite elegir otra instalación. El adaptador VS Code registra un plugin local con agentes, skill, hooks y servidor MCP. La instalación deja Pulso disponible, conserva los modelos ya configurados y no lo selecciona como agente predeterminado. Para hacer opt-in al agente predeterminado de OpenCode:

npm run install:opencode -- --set-default

Para instalar sin aplicar el preset de modelos, use npm run install:opencode -- --no-model-preset.

El instalador no sobrescribe archivos administrados que hayan divergido de este repositorio. Revise primero esas diferencias y use el siguiente comando solo cuando el reemplazo sea intencional:

npm run install:local:force

Para retirar únicamente los archivos gestionados por el proyecto que siguen coincidiendo con este repositorio y desregistrar sus plugins:

npm run uninstall:local

Reinicie OpenCode o recargue la ventana de VS Code después de instalar o desinstalar: ambos runtimes descubren agentes, skills, herramientas y plugins al iniciar la sesión, pero Pulso difiere su trabajo de estado hasta una activación explícita.

Adaptadores de runtime

OpenCode sincroniza los archivos listados en pulso.manifest.json y registra circuit breaker y experiencia. Ambos plugins permanecen inertes en sesiones ajenas: SQLite, mantenimiento y migraciones se activan con el primer mensaje de un agente Pulso o con una operación Pulso explícita. --set-default permite configurar pulso como agente predeterminado de forma voluntaria.

VS Code Agents consume este repositorio como un plugin Agent Plugins 1.0. Los agentes en com.github.copilot/agents/ reflejan los contratos de OpenCode y solo pulso es invocable por el usuario. skills/pulso-protocol/ se comparte sin duplicación. El MCP usa ${PLUGIN_ROOT}, no requiere binarios externos y proyecta contratos internos al worker autorizado. Los hooks aplican scope, leases, circuit breaker y Git gate sobre eventos nativos; las sesiones ordinarias no reciben estado de Pulso.

Los runtimes deben descubrir al inicio el catálogo de agentes y skills para poder seleccionarlos. Pulso evita trabajo activo fuera de sus sesiones: OpenCode no abre SQLite ni migra estado, y VS Code no añade instrucciones globales ni inicia pulso-control fuera del plugin.

Flujo recomendado:

npm install
npm test
npm run install:vscode

Tras reiniciar OpenCode, Pulso quedará disponible para selección; solo será el agente predeterminado si se instaló con --set-default. En VS Code se selecciona desde el catálogo de agentes.

Contactos de agentes

OpenCode puede conectar agentes personalizados existentes mediante una experiencia interactiva:

/pulso-autointegrate

Pulso escanea definiciones globales y de proyecto, permite elegir agentes nuevos o modificados, los entrevista mediante una tarea nativa visible y solicita aprobación antes de añadirlos a la agenda global. Las fichas se guardan en el directorio de datos local de OpenCode; no almacenan el prompt completo del agente ni se incorporan a la memoria técnica.

Durante una entrega, Pulso consulta la agenda únicamente cuando necesita un especialista que sus agentes internos no cubren. Solo puede delegar contactos vigentes y aprobados, siempre mediante task y con PULSO_TASK_ID y PULSO_CONTACT_ID. Las entrevistas son de solo lectura; los contactos con capacidad de edición quedan sujetos al scope, lease y circuit breaker de la tarea y nunca pueden modificar .pulso/**.

OpenCode y VS Code Agents comparten el mismo core de control-plane; los adapters no introducen workflows ni persistencia nuevos.

Dashboard y Doctor

Abra el dashboard de métricas y experiencia de la instalación actual de estas formas:

/pulso-dashboard

o, desde este repositorio:

npm run dashboard

El dashboard muestra estado y duración de objetivos, tokens y ejecuciones, actividad por agente, intervenciones humanas, ciclos de reparación, memorias verificadas y preferencias de perfil. OpenCode registra tokens mediante sus eventos de modelo; VS Code Agents no ofrece un contrato estable de esos eventos, por lo que sus objetivos se marcan con seguimiento de tokens no disponible, nunca como consumo cero.

El servidor se enlaza exclusivamente a 127.0.0.1, usa un token temporal de acceso, lee SQLite sin modificarlo y se detiene tras 30 minutos de inactividad o al pulsar Stop server.

Para un diagnóstico de solo lectura de agentes, plugins, herramientas, estado local y almacén de experiencia, ejecute dentro de OpenCode:

/pulso-doctor

Configuración

Combine los campos pertinentes de opencode.example.jsonc con el opencode.jsonc de destino. Las rutas de los plugins son relativas al archivo de configuración de OpenCode.

El archivo de ejemplo configura pulso como default_agent, registra los plugins de circuit breaker y experiencia, y propone modelos para cada agente. Los modelos son ejemplos operativos: pueden sustituirse sin modificar los contratos de comportamiento de Pulso.

Estructura del repositorio

agents/                   Orquestador y especialistas acotados
bin/                      CLI de operación local
com.github.copilot/       Agentes y hooks de Agent Plugins para VS Code
vscode/                   Adaptador MCP y hooks de VS Code Agents
commands/                 Comandos interactivos de OpenCode
lib/                      Implementación del plano de control
plugins/                  Circuit breaker y motor de experiencia
scripts/                  Instalación y sincronización del runtime
skills/pulso-protocol/    Protocolo compartido de coordinación y estado
plugin.json               Manifiesto Agent Plugins 1.0
pulso.manifest.json       Archivos sincronizados por el instalador
opencode.example.jsonc    Configuración de referencia para OpenCode

Bootstrap

El comando de bootstrap importa los archivos del manifiesto de runtime desde una instalación existente de OpenCode:

npm run bootstrap

Las pruebas y demás archivos exclusivos de desarrollo permanecen bajo propiedad del repositorio y no se esperan en el directorio de configuración de OpenCode. Use bootstrap únicamente para inicializar o reconciliar deliberadamente el repositorio. El flujo normal de desarrollo sincroniza desde este proyecto hacia OpenCode, no en sentido inverso.