vgxness 0.1.0

package/docs/funcionamiento-del-sistema.md

@@ -0,0 +1,868 @@
+# Funcionamiento del sistema vgxness
+
+`vgxness` es un harness local-first para desarrollo agentico. Su objetivo es darle estructura, memoria, seguridad y trazabilidad al trabajo hecho con herramientas de IA como OpenCode, Claude Code u otros proveedores futuros.
+
+La idea central del sistema es simple: los agentes pueden ejecutar trabajo, pero `vgxness` mantiene el estado verificable de lo que pasa. Ese estado incluye memoria persistente, fases SDD, artefactos, agentes registrados, skills, permisos, ejecuciones, checkpoints y evidencia.
+
+## Resumen rapido
+
+`vgxness` ataca tres problemas principales:
+
+1. La perdida de contexto entre sesiones de trabajo con IA.
+2. La falta de un flujo disciplinado para cambios grandes.
+3. La dependencia excesiva en prompts sin estado verificable.
+
+Para resolverlos, el sistema se construye sobre estos bloques:
+
+| Bloque | Funcion |
+|---|---|
+| Memoria local/global | Guarda observaciones, artefactos, sesiones y trazas en SQLite. Por defecto usa una base global de usuario; para dogfood o tests se puede forzar una base por proyecto con `--db`. |
+| SDD workflow | Ordena cambios en fases verificables: explore, proposal, spec, design, tasks, apply-progress, verify y archive. |
+| Orquestador de lenguaje natural | Clasifica pedidos del usuario en direct, plan, sdd o diagnose sin ejecutar acciones. |
+| Registro de agentes | Define agentes y subagentes con capacidades, permisos, workflows y compatibilidad por proveedor. |
+| Registro de skills | Administra skills reutilizables, versiones, adjuntos, uso y propuestas de mejora. |
+| Runtime de runs | Registra ejecuciones agenticas con estado, eventos, checkpoints, aprobaciones y resultado final. |
+| Politica de permisos | Decide si una operacion se permite, se bloquea o requiere aprobacion humana. |
+| MCP server | Expone herramientas para que agentes consulten y actualicen el control plane. |
+| CLI | Permite operar el sistema desde comandos reproducibles. |
+| Dashboard/TUI | Muestra estado local, setup, runs y progreso SDD para humanos. |
+
+## Que problema resuelve
+
+Cuando se trabaja con IA en proyectos reales aparecen problemas repetidos:
+
+1. El agente no recuerda decisiones anteriores.
+2. Cada herramienta de IA tiene su propia configuracion y sus propios limites.
+3. Los cambios grandes se vuelven improvisados: se empieza a implementar antes de entender, especificar o verificar.
+4. La seguridad queda distribuida en prompts, permisos del proveedor o disciplina manual.
+5. Despues de una interrupcion no siempre queda claro que se hizo, que falta y que evidencia existe.
+
+`vgxness` busca resolver eso agregando una capa local entre el humano, los agentes y las herramientas proveedoras.
+
+Esa capa no reemplaza a OpenCode, Claude Code o futuros adapters. Los coordina. El sistema guarda estado, valida prerrequisitos, registra actividad y ofrece APIs para que los agentes no tengan que adivinar donde estan parados.
+
+## Como esta construido
+
+El proyecto esta escrito en TypeScript y corre sobre Node.js 22 o superior.
+
+Dependencias principales:
+
+| Dependencia | Uso |
+|---|---|
+| `better-sqlite3` | Persistencia local en SQLite. |
+| `@modelcontextprotocol/sdk` | Servidor MCP por stdio. |
+| `zod` | Validacion de schemas de entrada. |
+| `tsx` | Ejecucion TypeScript en desarrollo. |
+| `typescript` | Build y typecheck. |
+
+Scripts principales:
+
+| Script | Funcion |
+|---|---|
+| `npm run cli -- ...` | Ejecuta la CLI local desde `src/cli/index.ts`. |
+| `npm run build` | Compila TypeScript y copia migraciones. |
+| `npm run test` | Ejecuta tests con el runner nativo de Node. |
+| `npm run typecheck` | Valida tipos sin emitir archivos. |
+| `npm run package:dry-run` | Simula el empaquetado npm. |
+| `npm run package:smoke:install` | Prueba instalacion local del tarball. |
+
+## Vista de alto nivel
+
+```text
+Humano / operador
+      |
+      | usa
+      v
+CLI / Dashboard / TUI
+      |
+      | llama servicios locales
+      v
+Core de vgxness
+      |
+      | persiste y consulta
+      v
+SQLite local/global
+
+Agente IA / herramienta MCP
+      |
+      | invoca tools MCP
+      v
+MCP control plane
+      |
+      | llama los mismos servicios
+      v
+Core de vgxness
+```
+
+La regla importante es que CLI, MCP y dashboard no deberian tener reglas de negocio duplicadas. Todos deben pasar por los mismos servicios de dominio.
+
+## Capas del sistema
+
+### 1. Interfaces de entrada
+
+El sistema tiene varias superficies de uso.
+
+| Superficie | Usuario principal | Archivo clave | Funcion |
+|---|---|---|---|
+| CLI | Humano, scripts, smoke tests | `src/cli/dispatcher.ts` | Parsear comandos y llamar servicios. |
+| MCP stdio | Agentes y herramientas IA | `src/mcp/stdio-server.ts` | Exponer herramientas MCP locales. |
+| MCP control plane | Capa interna MCP | `src/mcp/control-plane.ts` | Validar tool calls y despacharlas a servicios. |
+| Dashboard/TUI | Humano local | `src/cli/interactive-dashboard.ts` | Mostrar estado operativo y permitir navegacion local. |
+
+La CLI es intencionalmente fina. Abre la base local, instancia servicios y devuelve JSON o texto. No deberia contener la logica profunda del producto.
+
+### 2. Servicios de dominio
+
+Los servicios encapsulan la logica del sistema.
+
+| Servicio | Archivo | Responsabilidad |
+|---|---|---|
+| `MemoryService` | `src/memory/memory-service.ts` | Guardar, buscar, actualizar memoria, sesiones, artefactos y trazas. |
+| `SddWorkflowService` | `src/sdd/sdd-workflow-service.ts` | Calcular estado, readiness, siguiente fase y guardar artefactos SDD. |
+| `NaturalLanguagePlanner` | `src/orchestrator/natural-language-planner.ts` | Clasificar intenciones del usuario y producir un plan preview-only. |
+| `AgentRegistryService` | `src/agents/agent-registry-service.ts` | Registrar, listar, obtener y resolver agentes/subagentes. |
+| `SkillRegistryService` | `src/skills/skill-registry-service.ts` | Registrar skills, versiones, adjuntos, propuestas y payloads. |
+| `RunService` | `src/runs/run-service.ts` | Crear runs, eventos, checkpoints, aprobaciones, preflight y finalizacion. |
+| `SetupLifecycleService` | `src/setup/setup-lifecycle-service.ts` | Reportar si el proyecto esta listo para operar. |
+| `OpenCodeManagerPayloadService` | `src/providers/opencode/manager-payload.ts` | Construir payloads para integracion con OpenCode. |
+
+### 3. Repositorios y almacenamiento
+
+La persistencia esta basada en SQLite local.
+
+Archivo clave:
+
+```text
+src/memory/sqlite/database.ts
+```
+
+Al abrir la base, el sistema:
+
+1. Crea una conexion con `better-sqlite3`.
+2. Activa `foreign_keys`.
+3. Configura `busy_timeout`.
+4. Aplica migraciones SQL si la base no esta en modo readonly.
+5. Devuelve una instancia `MemoryDatabase` usada por los repositorios.
+
+Ruta por defecto de usuario:
+
+```text
+macOS: ~/Library/Application Support/vgxness/memory.sqlite
+Linux: ${XDG_DATA_HOME:-~/.local/share}/vgxness/memory.sqlite
+Windows: %APPDATA%\vgxness\memory.sqlite
+```
+
+La ruta `.vgx/memory.sqlite` se sigue usando para dogfood local o pruebas cuando se pasa explicitamente con `--db`.
+
+Los repositorios viven debajo de carpetas como:
+
+```text
+src/memory/repositories/
+src/agents/repositories/
+src/skills/repositories/
+src/runs/repositories/
+```
+
+## Flujo principal del sistema
+
+### Paso 1: El usuario o agente inicia una accion
+
+Una accion puede entrar por CLI o por MCP.
+
+Ejemplos CLI:
+
+```bash
+npm run cli -- sdd status --project vgxness --change my-change
+npm run cli -- orchestrator preview --project vgxness --intent "Build a new checkout workflow" --change checkout-flow
+npm run cli -- agents resolve --project vgxness --workflow sdd --phase apply-progress
+npm run cli -- runs list --project vgxness
+```
+
+Ejemplo MCP:
+
+```text
+vgxness_sdd_status
+vgxness_agent_resolve
+vgxness_run_start
+vgxness_run_checkpoint
+```
+
+### Paso 2: La interfaz valida y normaliza la entrada
+
+En CLI, `dispatchCli` y `dispatchCliAsync` parsean argumentos, validan area/comando y abren la base local.
+
+En MCP, `callVgxTool` valida la tool call contra schemas antes de ejecutar la operacion.
+
+Esto evita que cada comando implemente su propio contrato de entrada de manera inconsistente.
+
+### Paso 3: Se instancia el servicio correspondiente
+
+Por ejemplo:
+
+| Accion | Servicio usado |
+|---|---|
+| Consultar estado SDD | `SddWorkflowService` |
+| Clasificar un pedido natural | `createNaturalLanguagePlan` |
+| Guardar memoria | `MemoryService` |
+| Resolver agente | `AgentRegistryService` |
+| Resolver skill payload | `SkillRegistryService` |
+| Crear run | `RunService` |
+| Evaluar permisos | `evaluatePermission` |
+
+### Paso 4: El servicio aplica reglas de negocio
+
+Ejemplos:
+
+1. SDD valida que la fase exista.
+2. El orquestador clasifica si el pedido es directo, planificable, diagnostico o requiere SDD.
+3. SDD calcula si faltan artefactos prerrequisito.
+4. Runs evalua permisos antes de operaciones riesgosas.
+5. Memory registra trazas cuando una operacion de memoria ocurre.
+6. Skills solo construye payloads con versiones activas/resueltas.
+
+### Paso 5: Se persiste o consulta estado local
+
+Si la accion cambia estado, se guarda en SQLite.
+
+Ejemplos de estado persistido:
+
+| Estado | Ejemplo |
+|---|---|
+| Observaciones | Decisiones, aprendizajes, preferencias. |
+| Artefactos SDD | `sdd/my-change/proposal`, `sdd/my-change/spec`. |
+| Sesiones | Actividad agrupada por sesion. |
+| Trazas | Registro de operaciones de memoria. |
+| Agentes | Definiciones y metadata. |
+| Skills | Versiones, adjuntos, uso y propuestas. |
+| Runs | Estado, eventos, checkpoints, aprobaciones y resultado. |
+
+### Paso 6: La respuesta vuelve como JSON o texto estructurado
+
+La CLI devuelve resultados para humanos o scripts. MCP devuelve un envelope JSON con `ok`, nombre de tool y resultado o error.
+
+## Funcionamiento del orquestador de lenguaje natural
+
+El orquestador de lenguaje natural es el nuevo punto de entrada para transformar texto humano en una decision operativa segura.
+
+Archivo principal:
+
+```text
+src/orchestrator/natural-language-planner.ts
+```
+
+Schema principal:
+
+```text
+src/orchestrator/schema.ts
+```
+
+La funcion central es `createNaturalLanguagePlan`. Recibe `project`, `intent`, un `change` opcional y contexto SDD opcional. Devuelve un plan deterministico de version 1.
+
+El plan puede elegir uno de cuatro flujos:
+
+| Flow | Cuando aparece | Que significa |
+|---|---|---|
+| `direct` | Pedido de explicacion o cambio chico de bajo riesgo. | Se puede responder o tratar sin entrar a SDD. |
+| `plan` | Pedido de plan, preview, review o dry-run sin riesgo fuerte. | Se puede preparar un plan manual sin ejecutar nada. |
+| `sdd` | Nueva capacidad, arquitectura, workflow, persistencia, seguridad, cambio amplio o pedido de ejecucion. | Conviene pasar por el flujo SDD antes de implementar. |
+| `diagnose` | Pedido de diagnostico, estado, health, logs, setup o doctor. | Se mantiene en modo lectura/diagnostico. |
+
+La decision se basa en signals extraidas del texto. Algunos ejemplos:
+
+| Signal | Detecta |
+|---|---|
+| `answer-only` | Preguntas como explain, what, how o why. |
+| `planning-request` | plan, preview, review o dry-run. |
+| `diagnostic-request` | diagnose, failure, status, health, logs, setup o doctor. |
+| `new-capability` | build, add, create, new, feature o capability. |
+| `architecture-change` | architecture, refactor o boundaries. |
+| `workflow-change` | workflow, orchestration, orchestrator, SDD o phase. |
+| `persistence-change` | persistent, storage, SQLite, database, memory o migration. |
+| `security-sensitive` | security, auth, token, secret o permission. |
+| `execution-request` | run, execute, apply, start, install o push. |
+| `destructive` | delete, remove, destroy, drop o reset. |
+
+Si el pedido es ambiguo, por ejemplo `Fix it`, el planner baja la confianza, marca `needsClarification` y devuelve una pregunta aclaratoria antes de sugerir acciones de escritura.
+
+### Contrato de seguridad
+
+El orquestador actual es preview-only. Esto es CLAVE.
+
+El plan siempre devuelve safety con estas garantias:
+
+| Campo | Valor actual |
+|---|---|
+| `executed` | `false` |
+| `callsProvider` | `false` |
+| `editsFiles` | `false` |
+| `writesProviderConfig` | `false` |
+| `recordsRuns` | `false` |
+
+Eso significa que `orchestrator preview` no llama providers, no edita archivos, no escribe configuracion, no crea runs, no instala memoria global y no crea `openspec/`.
+
+Este seam es importante porque separa la decision de ruteo de la ejecucion real. Primero se clasifica y se revisa. Despues, si corresponde, otro flujo aprobado puede ejecutar.
+
+### CLI del orquestador
+
+La CLI expone el planner con:
+
+```bash
+npm run cli -- orchestrator preview --project vgxness --intent "Build a new persistent checkout workflow" --change checkout-flow --db .vgx/memory.sqlite
+```
+
+Parametros:
+
+| Parametro | Requerido | Funcion |
+|---|---|---|
+| `--project` | Si | Proyecto donde se interpreta la intencion. |
+| `--intent` | Si | Texto natural del usuario. |
+| `--change` | No | Change SDD a consultar o reutilizar. |
+| `--db` | No | Base SQLite local a usar. |
+
+Cuando se pasa `--change`, la CLI consulta `SddWorkflowService.getStatus` y `SddWorkflowService.getNext` contra la base local seleccionada. Ese contexto se incluye en la respuesta para que el preview pueda sugerir el siguiente paso SDD sin mutar estado.
+
+Ejemplo de decision esperada:
+
+```text
+Intent: Build a new persistent checkout workflow capability
+Flow: sdd
+Suggested change id: checkout-flow
+Preview action: npm run cli -- sdd next --project vgxness --change checkout-flow
+Safety: no ejecuto nada
+```
+
+### Como encaja en el flujo general
+
+Antes, un humano o agente podia ir directo a `sdd status`, `agents resolve` o `runs start`. Ahora existe una puerta previa:
+
+```text
+Texto del usuario
+      |
+      v
+orchestrator preview
+      |
+      v
+Clasificacion: direct | plan | sdd | diagnose
+      |
+      v
+Accion sugerida, no ejecutada
+```
+
+Esto apunta a la vision del producto: que el usuario pueda interactuar en lenguaje natural, pero que el sistema no confunda entender una intencion con tener permiso para ejecutar.
+
+## Funcionamiento del flujo SDD
+
+SDD significa Spec-Driven Development. En `vgxness`, SDD no es solo una recomendacion en un prompt: es un workflow con fases, topic keys y prerrequisitos.
+
+Fases canonicas:
+
+```text
+explore -> proposal -> spec -> design -> tasks -> apply-progress -> verify -> archive
+```
+
+Cada fase se guarda como artefacto bajo una topic key canonica:
+
+```text
+sdd/{change}/{phase}
+```
+
+Ejemplo:
+
+```text
+sdd/add-auth/proposal
+sdd/add-auth/spec
+sdd/add-auth/design
+```
+
+Prerrequisitos actuales:
+
+| Fase | Requiere |
+|---|---|
+| `explore` | Nada. |
+| `proposal` | `explore`. |
+| `spec` | `proposal`. |
+| `design` | `proposal`, `spec`. |
+| `tasks` | `proposal`, `spec`, `design`. |
+| `apply-progress` | `tasks`. |
+| `verify` | `apply-progress`. |
+| `archive` | `verify`. |
+
+El servicio SDD puede responder tres preguntas centrales:
+
+| Pregunta | Metodo | Resultado |
+|---|---|---|
+| Que fases existen y cuales estan presentes | `getStatus` | Estado por fase y proxima fase lista. |
+| Una fase esta lista para correr | `getReady` | `ready`, prerrequisitos satisfechos y faltantes. |
+| Cual es el siguiente paso | `getNext` | `runnable`, `blocked` o `complete`. |
+
+Este flujo obliga a que los cambios grandes avancen con estructura. No impide que alguien escriba codigo manualmente, pero le da al agente y al humano una fuente de verdad para saber si el cambio esta preparado.
+
+## Funcionamiento de la memoria
+
+La memoria es local y persistente. No depende de una cuenta cloud.
+
+Por defecto, la CLI instalada usa una base global de usuario. Esto permite instalar `vgxness` y empezar a guardar memoria sin pasar `--db` en cada comando.
+
+| Plataforma | Ruta global por defecto |
+|---|---|
+| macOS | `~/Library/Application Support/vgxness/memory.sqlite` |
+| Linux | `${XDG_DATA_HOME:-~/.local/share}/vgxness/memory.sqlite` |
+| Windows | `%APPDATA%\vgxness\memory.sqlite` |
+
+La precedencia de seleccion de base es:
+
+```text
+--db <path> > VGXNESS_DB_PATH > base global de usuario
+```
+
+La ruta historica `.vgx/memory.sqlite` sigue siendo compatible, pero ahora es explicita:
+
+```bash
+npm run cli -- memory search --project vgxness --db .vgx/memory.sqlite
+```
+
+Este detalle es importante: `vgxness` puede funcionar como herramienta instalada globalmente sin acoplar la memoria al workdir actual, pero tambien permite aislar estado cuando se necesita reproducibilidad en tests o dogfood local.
+
+`MemoryService` trabaja con cuatro conceptos principales:
+
+| Concepto | Funcion |
+|---|---|
+| Observations | Guardan conocimiento durable: decisiones, descubrimientos, preferencias o contenido general. |
+| Sessions | Agrupan actividad por sesion de trabajo. |
+| Artifacts | Guardan documentos estructurados, especialmente artefactos SDD. |
+| Traces | Registran operaciones realizadas sobre memoria. |
+
+Cuando se guarda un artefacto SDD, internamente tambien se guarda una observation con tipo `sdd-artifact`. Eso permite que el contenido sea recuperable por topic key y tambien trazable como memoria.
+
+El flujo simplificado es:
+
+```text
+Servicio solicita guardar memoria
+      |
+      v
+ObservationRepository / ArtifactRepository
+      |
+      v
+SQLite
+      |
+      v
+TraceRepository registra la operacion
+```
+
+## Funcionamiento de agentes y subagentes
+
+El registro de agentes permite definir quien puede ejecutar trabajo y bajo que contexto.
+
+Un agente puede incluir:
+
+1. Nombre y descripcion.
+2. Instrucciones.
+3. Capacidades.
+4. Workflows y fases compatibles.
+5. Skills asociadas.
+6. Permisos.
+7. Compatibilidad con adapters como OpenCode o Claude.
+
+El sistema puede resolver candidatos para una tarea con `agents resolve`. Esa resolucion es metadata-driven: usa capacidades, workflow, fase, provider, modo y texto de tarea. No llama a un modelo para rankear en la version actual.
+
+Esto es importante porque mantiene la seleccion de agente explicable y reproducible.
+
+## Funcionamiento de skills
+
+Las skills son conocimiento operativo reutilizable.
+
+El sistema no las trata como archivos sueltos, sino como entidades versionadas con ciclo de vida.
+
+Puede manejar:
+
+1. Registro de skills.
+2. Versiones activas o historicas.
+3. Adjuntos a agentes, fases, workflows o adapters.
+4. Registro de uso.
+5. Escenarios de evaluacion.
+6. Propuestas de mejora.
+7. Aprobacion antes de activar una mejora.
+
+El flujo ideal es:
+
+```text
+Se registra una skill
+      |
+      v
+Se agrega una version
+      |
+      v
+Se adjunta a un agente o fase
+      |
+      v
+Durante un run se resuelve e inyecta el payload
+      |
+      v
+Se registra si ayudo o fallo
+      |
+      v
+Si hace falta mejorarla, se crea una propuesta revisable
+```
+
+## Funcionamiento de runs
+
+Un run representa una operacion agentica significativa.
+
+Sirve para responder preguntas como:
+
+1. Quien ejecuto esto.
+2. Para que proyecto y fase fue.
+3. Que modelo o provider se uso.
+4. Que eventos ocurrieron.
+5. Que aprobaciones hicieron falta.
+6. Que checkpoints existen para retomar.
+7. Como termino la operacion.
+
+`RunService` permite:
+
+| Accion | Funcion |
+|---|---|
+| `createRun` | Crear un registro auditable. |
+| `appendEvent` | Agregar eventos al historial. |
+| `appendCheckpoint` | Guardar estado resumible. |
+| `preflightOperation` | Evaluar seguridad antes de ejecutar. |
+| `updateFinalStatus` | Cerrar el run con estado y outcome. |
+| `getRunInsights` | Construir resumen operativo del run. |
+
+Este runtime separa memoria de ejecucion. Una decision durable puede vivir en memoria, pero una ejecucion concreta vive como run con eventos, approvals y checkpoints.
+
+## Politica de permisos
+
+La politica de permisos define si una operacion se permite, pide aprobacion o se deniega.
+
+Categorias actuales:
+
+```text
+read, edit, shell, network, git, memory, external-directory, provider-tool, secrets
+```
+
+Politica base:
+
+| Categoria | Decision default |
+|---|---|
+| `read` | `allow` |
+| `edit` | `ask` |
+| `shell` | `ask` |
+| `network` | `ask` |
+| `git` | `ask` |
+| `memory` | `ask` |
+| `external-directory` | `deny` |
+| `provider-tool` | `ask` |
+| `secrets` | `deny` |
+
+Reglas importantes:
+
+1. Acceso a secretos se deniega por defecto.
+2. Acceso a directorios externos se deniega por defecto.
+3. Operaciones destructivas, externas, privilegiadas o ambiguas requieren aprobacion humana.
+4. Operaciones de filesystem deben estar dentro del workspace.
+
+Esto evita que la seguridad dependa solamente de que el agente “se acuerde” de portarse bien.
+
+## Funcionamiento del MCP
+
+El MCP server es la puerta para que herramientas de IA interactuen con `vgxness`.
+
+Archivo principal:
+
+```text
+src/mcp/stdio-server.ts
+```
+
+El servidor:
+
+1. Crea un `McpServer` llamado `vgxness`.
+2. Crea el control plane local.
+3. Registra todas las tools soportadas.
+4. Conecta por `StdioServerTransport`.
+5. Devuelve respuestas JSON como texto MCP.
+
+El control plane crea servicios sobre la misma base SQLite:
+
+```text
+MemoryService
+SddWorkflowService
+AgentRegistryService
+SkillRegistryService
+RunService
+AgentActivationService
+OpenCodeManagerPayloadService
+```
+
+Tools representativas (no exhaustivas; la fuente actual de nombres soportados es `SUPPORTED_VGX_MCP_TOOL_NAMES`):
+
+| Tool | Funcion |
+|---|---|
+| `vgxness_sdd_status` | Consultar estado de un change SDD. |
+| `vgxness_sdd_ready` | Saber si una fase esta lista. |
+| `vgxness_sdd_next` | Decidir siguiente fase runnable, blocked o complete. |
+| `vgxness_sdd_save_artifact` | Guardar un artefacto SDD. |
+| `vgxness_sdd_get_artifact` / `vgxness_sdd_list_artifacts` | Recuperar artefactos SDD previos como fuente de verdad. |
+| `vgxness_memory_save` | Guardar memoria. |
+| `vgxness_memory_search` | Buscar memoria. |
+| `vgxness_agent_resolve` | Resolver agente para una tarea. |
+| `vgxness_skill_payload` | Construir payload de skills para un contexto. |
+| `vgxness_opencode_manager_payload` | Construir preview read-only para integracion del manager OpenCode. |
+| `vgxness_run_start` | Crear un run. |
+| `vgxness_run_preflight` | Evaluar permisos y plan de seguridad antes de operaciones riesgosas. |
+| `vgxness_run_checkpoint` | Guardar checkpoint. |
+| `vgxness_run_finalize` | Finalizar run. |
+
+## Funcionamiento de la CLI
+
+La CLI se ejecuta localmente con:
+
+```bash
+npm run cli -- <area> <command> [flags]
+```
+
+Areas principales vistas en el dispatcher:
+
+| Area | Funcion |
+|---|---|
+| `setup` / `init` | Estado de setup local. |
+| `agents` | Registro, listado, resolucion y render de agentes. |
+| `subagents` | Operaciones sobre subagentes. |
+| `memory` | Operaciones de memoria. |
+| `runs` | Runs, checkpoints, approvals y estado. |
+| `permissions` | Evaluacion de permisos. |
+| `skills` | Registro, resolucion, propuestas y evaluacion de skills. |
+| `sdd` | Estado, readiness y guardado de artefactos SDD. |
+| `orchestrator` | Preview de ruteo desde lenguaje natural hacia direct, plan, sdd o diagnose. |
+| `opencode` | Previews/integracion OpenCode. |
+| `dashboard` | Estado visual o interactivo. |
+| `mcp` | Setup, doctor e instalacion MCP. |
+
+La base se selecciona con la misma regla que el resto del sistema:
+
+```text
+--db <path> > VGXNESS_DB_PATH > base global de usuario
+```
+
+Sin `--db`, la CLI usa la base global de usuario. Si se quiere la base del repo para pruebas locales, se debe pedir explicitamente:
+
+```bash
+npm run cli -- sdd status --project vgxness --change my-change --db .vgx/memory.sqlite
+```
+
+## Setup local
+
+El setup busca contestar si el proyecto esta listo para usar `vgxness`.
+
+`SetupLifecycleService` revisa:
+
+| Check | Que verifica |
+|---|---|
+| Store | Que la base local este disponible. |
+| MCP | Que OpenCode MCP este visible o tenga acciones sugeridas. |
+| Default context | Que exista el agente default `vgxness-manager`. |
+
+La respuesta incluye `nextAction`, por ejemplo sembrar agentes, revisar MCP o listar runs.
+
+## Integracion con OpenCode
+
+OpenCode aparece como primer adapter concreto.
+
+El sistema puede:
+
+1. Generar previews de configuracion.
+2. Diagnosticar visibilidad MCP desde el worktree.
+3. Planificar instalacion sin escribir archivos.
+4. Aplicar instalacion solo con confirmacion explicita.
+5. Preservar configuracion existente y crear backups cuando corresponde.
+
+Un limite importante: las operaciones de preview no escriben `.opencode/`, `.claude/` ni configuracion global. Esa separacion es intencional para mantener seguridad y revisabilidad.
+
+El manager OpenCode versionado (`vgxness-manager`) es MCP-first: al iniciar, reanudar o recuperar contexto llama `vgxness_session_restore` con proyecto y directorio del workspace antes de inferir desde el chat; consulta estado SDD con `sdd_status`/`sdd_next`/`sdd_ready`, recupera prerequisitos con `sdd_get_artifact` o `sdd_list_artifacts`, resuelve el subagente exacto con `agent_resolve`, delega la fase, guarda el artefacto aceptado con `sdd_save_artifact` y usa `run_preflight`/`run_checkpoint`/`run_finalize` cuando el trabajo es significativo. Antes de terminar, pausar, handoff o compactar llama `vgxness_session_close` con el session id actual, actor `manager` y un resumen accionable; si no hay session id, no lo inventa y preserva el resumen en la respuesta final. Preguntas simples o respuestas read-only no necesitan crear runs por defecto.
+
+La integracion mantiene `permission.task` deny-by-default: el manager solo puede delegar a subagentes SDD canonicos por nombre exacto. Las instrucciones del seed incluido son autosuficientes y no requieren archivos externos `~/.config/opencode/skills/sdd-*`; esas skills pueden registrarse como mejora opcional, pero no son requisito. `vgxness_opencode_manager_payload` es solo preview/read-only: no instala, no ejecuta OpenCode, no carga seeds y no escribe configuracion global.
+
+## Que esta implementado hoy y que es objetivo
+
+El proyecto ya contiene implementaciones concretas de:
+
+1. Memoria SQLite con migraciones.
+2. SDD workflow con estado, readiness, next y guardado de artefactos.
+3. Orquestador de lenguaje natural preview-only con clasificacion `direct`, `plan`, `sdd` y `diagnose`.
+4. Registro y resolucion de agentes.
+5. Registro, versionado, resolucion y propuestas de skills.
+6. Runs con eventos, checkpoints, approvals, preflight y finalizacion.
+7. Politica de permisos base.
+8. MCP stdio server y control plane.
+9. CLI para operar los servicios.
+10. Setup status y dashboard local.
+11. Integracion inicial con OpenCode.
+12. CLI instalable con memoria global por defecto y compatibilidad explicita con `--db`.
+
+La arquitectura objetivo documentada en `docs/architecture.md` amplia esa base hacia:
+
+1. TUI mas completa.
+2. Configurador de assets mas amplio.
+3. Multiples providers como Claude Code y futuros adapters.
+4. Perfiles/model routing mas avanzados.
+5. Auditoria y trazabilidad mas profundas.
+6. Flujos de instalacion guiados mas completos.
+
+Esta distincion importa. `vgxness` ya tiene un nucleo funcional, pero tambien es una plataforma en evolucion.
+
+## Recorrido completo de ejemplo
+
+Supongamos que se quiere trabajar en un cambio llamado `add-agent-profiles`.
+
+### 1. Revisar setup
+
+```bash
+npm run cli -- setup status --project vgxness
+```
+
+El sistema revisa store, MCP y agente default.
+
+### 2. Clasificar el pedido natural
+
+```bash
+npm run cli -- orchestrator preview --project vgxness --intent "Build a new agent profile workflow" --change add-agent-profiles
+```
+
+El sistema devuelve un preview no ejecutable. Si detecta nueva capacidad, arquitectura, workflow, persistencia, seguridad o riesgo de ejecucion, recomienda `sdd` y puede incluir el proximo comando manual de SDD.
+
+### 3. Consultar estado SDD
+
+```bash
+npm run cli -- sdd status --project vgxness --change add-agent-profiles
+```
+
+Si no hay artefactos, la primera fase lista deberia ser `explore`.
+
+### 4. Guardar el artefacto de exploracion
+
+```bash
+npm run cli -- sdd save-artifact --project vgxness --change add-agent-profiles --phase explore --content "# Explore"
+```
+
+El sistema guarda el contenido en memoria como artefacto con topic key:
+
+```text
+sdd/add-agent-profiles/explore
+```
+
+### 5. Preguntar la siguiente fase
+
+```bash
+npm run cli -- sdd next --project vgxness --change add-agent-profiles
+```
+
+Si `explore` esta presente, la siguiente fase runnable sera `proposal`.
+
+### 6. Resolver un agente para implementar
+
+```bash
+npm run cli -- agents resolve --project vgxness --workflow sdd --phase apply-progress --provider opencode --task "Implement agent profile routing"
+```
+
+El sistema devuelve candidatos con score y razones.
+
+### 7. Crear un run
+
+El agente o la CLI crean un run para registrar la operacion.
+
+Desde MCP seria una llamada a:
+
+```text
+vgxness_run_start
+```
+
+### 8. Evaluar permisos antes de operar
+
+Antes de acciones riesgosas, el run puede hacer preflight.
+
+```text
+vgxness_run_preflight
+```
+
+Si la operacion es destructiva, externa, privilegiada o ambigua, el sistema pide aprobacion o bloquea.
+
+### 9. Guardar checkpoints
+
+Durante el trabajo, el agente puede persistir progreso.
+
+```text
+vgxness_run_checkpoint
+```
+
+Eso permite retomar si la sesion se corta.
+
+### 10. Verificar y archivar
+
+Cuando el cambio avanza, SDD exige pasar por `verify` y luego `archive`, cada uno con su artefacto correspondiente.
+
+## Principio de diseno mas importante
+
+El principio clave es separar comportamiento de agente y estado de producto.
+
+| Capa | Que hace |
+|---|---|
+| Comportamiento de agente | Prompts, skills, instrucciones, modelos y adapters ayudan a ejecutar bien. |
+| Estado de producto | SQLite, SDD, runs, permisos y trazas dicen que paso y que se puede hacer ahora. |
+
+Si todo vive solo en prompts, el sistema depende de disciplina del LLM. Si todo vive solo en estado pero los agentes no reciben buen contexto, el sistema es burocratico. `vgxness` necesita ambas partes.
+
+## Estructura de carpetas relevante
+
+```text
+src/
+  agents/        Registro, resolucion, activacion y renderers de agentes.
+  cli/           Dispatcher, dashboard y renderers de salida CLI.
+  export/        Redaccion/export de snapshots.
+  harness/       Handlers reutilizables para tools internas.
+  mcp/           Servidor stdio, schemas, validacion, doctor e instalacion MCP.
+  memory/        Servicio de memoria, repositorios, busqueda y SQLite.
+  orchestrator/  Planner preview-only para clasificar lenguaje natural.
+  permissions/   Politica y schema de permisos.
+  providers/     Integraciones por proveedor, hoy principalmente OpenCode.
+  runs/          Runtime de ejecuciones, eventos, checkpoints y approvals.
+  sdd/           Workflow SDD, schemas y portabilidad de artefactos.
+  setup/         Estado de setup local.
+  skills/        Registro, resolucion, payloads y propuestas de skills.
+
+docs/
+  architecture.md                Arquitectura objetivo y decisiones principales.
+  prd.md                         Vision de producto y alcance MVP.
+  cli.md                         Uso de CLI y flujos operativos.
+  funcionamiento-del-sistema.md  Este documento.
+```
+
+## Como pensar el sistema
+
+Una buena forma de entender `vgxness` es verlo como una torre de control local.
+
+Los agentes son los aviones: ejecutan, se mueven rapido y hacen trabajo complejo. Pero la torre de control mantiene rutas, permisos, estado, historial y reglas de seguridad. Sin torre, cada avion decide por su cuenta. Sin aviones, la torre no produce valor. El sistema funciona cuando ambas partes colaboran.
+
+En terminos practicos:
+
+1. El humano define intencion y revisa decisiones importantes.
+2. Los agentes ejecutan trabajo especializado.
+3. `vgxness` guarda estado, valida readiness y registra evidencia.
+4. Las herramientas proveedoras son adaptadores, no la fuente unica de verdad.
+
+## Checklist para entender si el sistema esta funcionando
+
+Un proyecto `vgxness` sano deberia poder responder estas preguntas:
+
+1. Donde esta mi base local y esta disponible?
+2. Que flow recomienda el orquestador para este pedido natural?
+3. Que agentes tengo registrados?
+4. Que skills estan activas y para que contexto aplican?
+5. En que fase SDD esta mi cambio?
+6. Que artefactos faltan para avanzar?
+7. Que runs se ejecutaron y como terminaron?
+8. Que operaciones pidieron aprobacion?
+9. Que checkpoints permiten retomar trabajo?
+10. Que evidencia existe de verificacion?
+11. Que configuracion de proveedor fue preview, planificada o aplicada?
+
+Si esas respuestas existen en estado local y no solo en memoria conversacional del agente, el sistema esta cumpliendo su objetivo.