Yunta: El Harness para Spec-Driven Development (SDD)

English | Español

Harness de agente de código para terminal, agnóstico al proveedor del modelo.

Yunta: pareja de bueyes unidos para trabajar juntos — tú y el agente, sin importar qué modelo tire del otro lado.

🎯 Yunta: El Harness para Spec-Driven Development (SDD)

En la metodología Spec-Driven Development (SDD), el código no se genera por intuición o prompts ad-hoc, sino a partir de especificaciones formales y contratos verificables. Yunta actúa como el harness de ejecución y verificación:

• 📋 Consumo Estricto de Especificaciones: Lee AGENTS.md y especificaciones del proyecto en cada ciclo como única fuente de verdad.
• 🔬 Edición Quirúrgica (str_replace): Previene la degradación del código mediante reemplazos exactos con validación estricta de unicidad.
• 🛡️ Aprobaciones Humanas en Tiempo Real: Visualización interactiva de git diff antes de autorizar cualquier escritura o comando.
• ⚡ Prompt Caching Agnóstico: Permite iterar continuamente contra especificaciones y arquitecturas extensas con hasta un 90% de ahorro en costos y latencia.
• 🔄 Bucle Cerrado de Verificación: El agente valida autónomamente sus cambios contra la suite de pruebas (pytest) antes de dar por cerrada la tarea.

👉 Ver la Guía y Metodología SDD en Detalle (docs/sdd.md)

---

✨ Características y Capacidades Principales

• 🔌 Agnóstico al Proveedor: Conecta OpenAI (gpt-4o), Anthropic Claude (claude-3-7-sonnet), Google Gemini (gemini-2.5-flash), DeepSeek, Groq, o modelos locales vía Ollama/vLLM sin tocar una sola línea de código.
• 🔍 Indexación Semántica AST (find_symbol, get_ast_outline): Búsqueda instantánea de firmas de clases y funciones y generación de mapas de estructura sintáctica sin saturar la ventana de contexto.
• ⚡ Concurrencia y Paralelización (delegate_batch): Ejecución en paralelo de múltiples subtareas de investigación con ThreadPoolExecutor.
• 🖼️ Inspección Multimodal UI (read_image): Lectura de capturas de pantalla, mockups y diagramas (PNG, JPEG, WebP hasta 5MB) para modelos con capacidad de visión.
• 🛡️ Gobernanza y Auditoría SDD (yunta check & yunta hooks): Auditoría local determinista ($0 en API) y hooks pre-commit automatizados para impedir commits con pruebas rotas o contratos violados.
• 🔬 Edición Quirúrgica de Código (str_replace): Edita fragmentos exactos de archivos validando unicidad de contexto al estilo de Anthropic Claude Code y SWE-bench.
• 🔄 Resiliencia & Tolerancia a Fallos: Escritura atómica anti-corrupción (.tmp), auto-guardado de estado (.yunta/session_state.json), conmutación automática entre modelos ante 429/503 (LLM_MODELS), y recuperación con yunta --resume.
• 💸 Control de Presupuesto, ROI y Undo: Compactación por etapas (70%/85%/99%), dashboard de ahorro en USD (/roi), telemetría de tokens (/metrics, /tokens) y time-travel undo (/undo).
• 🌐 Soporte Nativo de MCP & JSON-RPC: Servidor MCP stdio RPC (yunta serve-mcp), streaming NDJSON (yunta serve-json) y extensión gráfica nativa oficial para VS Code & Cursor (yunta-vscode-extension).

---

Guía Rápida Paso a Paso

👉 ¿Primera vez usando Yunta? Sigue la Guía Paso a Paso Completa (docs/quickstart.md) para aprender desde la configuración del modelo hasta el flujo de edición con diffs y comandos del REPL.

---

Instalación

Requiere Python 3.11 o superior.

Desde PyPI (Recomendado):

pip install yunta-harness

💡 Nota sobre el nombre: En PyPI el paquete se instala como yunta-harness, pero el comando ejecutable en tu terminal es simplemente yunta (por ejemplo: yunta, yunta init . o yunta "tu instrucción"). No necesitas instalarlo dentro de tu aplicación existente: funciona como herramienta global (igual que Git).

Desde el repositorio fuente (Desarrollo):

git clone https://github.com/j0sp0nc3/yunta-harness.git
cd yunta-harness
pip install -e .

---

Configuración de Modelos

Yunta no tiene modelos por defecto: tú eliges quién tira del carro configurando tu entorno. Consulta la Matriz de Proveedores Verificados para ver la lista de modelos probados con el script de prueba universal (scripts/prueba_proveedor.py).

Google Gemini

export LLM_MODEL=gemini/gemini-3.5-flash
export GEMINI_API_KEY=tu-api-key

Anthropic Claude

export LLM_MODEL=anthropic/claude-3-7-sonnet
export ANTHROPIC_API_KEY=sk-ant-...

OpenAI

export LLM_MODEL=openai/gpt-4o
export OPENAI_API_KEY=sk-...

DeepSeek / OpenRouter

export LLM_MODEL=openrouter/deepseek/deepseek-chat
export LLM_API_KEY=tu-openrouter-key

Modelos Locales (Ollama)

export LLM_MODEL=ollama/llama3.3

Endpoints Compatibles con OpenAI (vLLM, LocalAI, etc.)

export LLM_MODEL=openai/tu-modelo-local
export LLM_API_BASE=http://localhost:8000/v1
export LLM_API_KEY=dummy

---

Uso y Comandos

Modos de Invocación desde el CLI (yunta)

• Sesión interactiva (REPL):

  yunta
  

• Ejecución directa single-shot:

  yunta "Explica la estructura de este repositorio y ejecuta los tests"
  

• Inicializar proyecto SDD (SPEC.md, PLAN.md, AGENTS.md):

  yunta init [idea_o_nombre]
  

• Auditoría de gobernanza local ($0 en tokens):

  yunta check [ruta] [--json] [--tests]
  

• Scaffolding para VS Code (.vscode/mcp.json y tasks.json):

  yunta ide-init
  

• Reanudar última sesión guardada:

  yunta --resume  # o yunta -r
  

• Servidor MCP stdio (para Claude Desktop, Cursor, Windsurf):

  yunta serve-mcp  # o yunta mcp
  

• Diagnóstico y Ayuda:

  yunta --version  # o yunta -v
  yunta --help     # o yunta -h
  

Comandos Interactivos del REPL (dentro de Yunta)

• /init [idea]: Inicializa o andamia un proyecto SDD generando SPEC.md, PLAN.md y AGENTS.md.
• /sandbox [merge|discard]: Crea o gestiona un entorno aislado en Git Worktree para operaciones destructivas o experimentales.
• /context: Muestra la cantidad de mensajes, tokens estimados en contexto y porcentaje consumido del presupuesto (YUNTA_MAX_TOKENS).
• /undo: Deshace la última edición de archivos y restaura el estado inmediatamente anterior ("Time-Travel Undo").
• /permissions [clear]: Muestra los permisos persistentes otorgados con 'siempre' en la sesión o los revoca (/permissions clear).
• /roi: Despliega el dashboard de retorno de inversión, acierto de caché y ahorro estimado en USD.
• /metrics: Despliega la telemetría detallada de herramientas ejecutadas, startup tax, errores y turnos.
• /tokens: Muestra el consumo acumulado de tokens y tasa de acierto de caché.
• /help: Muestra la lista de comandos interactivos disponibles.
• /clear: Limpia el historial de mensajes de la conversación actual.
• /exit: Guarda lecciones aprendidas en .yunta/learnings.md y finaliza la sesión.
• Ctrl+C: Interrumpe el turno en curso de forma limpia y regresa al prompt > sin tumbar la sesión ni dejar tool_use huérfano.

Variables de Entorno Principales

• LLM_MODEL: Proveedor/modelo a utilizar (ej. openai/gpt-4o, anthropic/claude-3-7-sonnet, gemini/gemini-3.7-flash, ollama/llama3.3).
• LLM_MODELS: Lista priorizada por comas para conmutación automática ante 429/503/cuota agotada.
• LLM_API_BASE: Endpoint custom compatible con OpenAI (ej. http://localhost:8000/v1).
• LLM_API_KEY: API Key o Bearer Token.
• YUNTA_SYSTEM_PROMPT: Sobrescribe el System Prompt base del harness.
• YUNTA_MAX_TOKENS: Presupuesto máximo de tokens para la compactación por etapas (default: 128000).
• YUNTA_MAX_MESSAGES: Tamaño máximo de ventana deslizante de historial (default: 40).
• YUNTA_YES: Activa el modo de auto-aprobación autónoma para todas las herramientas (equivalente a -y / --yes).
• YUNTA_BLOCKLIST_EXTRA: Ruta a archivo con patrones regex adicionales para bloquear comandos en bash.
• YUNTA_ALLOW_FORCE: Permite ejecutar git push --force en bash si se establece en 1.

---

Uso como Librería en Python (API v1.0)

A partir de la versión 1.0.0, puedes importar y embeber a Yunta directamente en tus scripts o aplicaciones:

from yunta import Agent, LiteLLMProvider, FeedbackStore

# Inicializa el proveedor usando la variable de entorno LLM_MODEL
provider = LiteLLMProvider(system="Eres un asistente técnico conciso.")

# Instancia el agente con aprobaciones automáticas o personalizadas
agent = Agent(provider=provider, system=provider.system, confirm=lambda name, detail: True)

# Envía un mensaje y recibe la respuesta estructurada
respuesta = agent.send("Lista los archivos en el directorio actual")
print(respuesta)

---

Detalles de Implementación para el Usuario

1. Contexto de Proyecto (AGENTS.md)

Si creas un archivo AGENTS.md en la raíz de tu proyecto, Yunta lo leerá e inyectará automáticamente en su system prompt. Úsalo para definir reglas inviolables, comandos de test o convenciones de tu equipo.

2. Edición de Archivos y Aprobaciones

Cuando Yunta decida modificar o escribir un archivo:

• str_replace: Reemplaza fragmentos específicos. Si la cadena a reemplazar es ambigua (aparece más de una vez), fallará pidiendo más contexto.
• Previsualización de Diffs: Si la herramienta requiere aprobación, verás un diff unificado estilo Git en la consola antes de pulsar y (confirmar) o n (rechazar).

3. Memoria Persistente entre Sesiones

El agente cuenta con las herramientas remember y recall para almacenar notas, decisiones de arquitectura o preferencias en .yunta/memory.json.

4. Servidores MCP (Model Context Protocol)

Puedes conectar herramientas de servidores MCP locales (stdio) creando el archivo .yunta/mcp.json:

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["servidores/weather_server.py"]
    }
  }
}

Las herramientas descubiertas se registrarán como mcp__weather__<nombre_tool>.

5. Creación de Herramientas Propias

Para agregar herramientas al agente, crea un archivo en yunta/tools/ y usa el decorador @registry.register:

from . import _parse, registry

@registry.register(
    "mi_tool",
    "Descripción clara de la herramienta para el modelo.",
    {
        "type": "object",
        "properties": {
            "parametro": {"type": "string", "description": "Texto de entrada"}
        },
        "required": ["parametro"]
    },
    requires_approval=False,
)
def mi_tool(raw: str) -> str:
    args = _parse(raw)
    return f"Resultado procesado: {args['parametro']}"

---

Arquitectura

Yunta está organizado de forma modular, limpia y compacta:

main.py            -> Punto de entrada y REPL de consola
yunta/
  api.py           -> Tipos canónicos neutrales (Message, Block, ToolDef, Response)
  provider.py      -> Capa de conexión LiteLLM (streaming, reintentos 429/503)
  agent.py         -> Bucle iterativo de turnos, approvals de diffs y Ctrl+C
  compact.py       -> Compactación de contexto (SlidingWindow)
  feedback.py      -> Auto-feedback de lecciones (.yunta/learnings.md)
  mcp.py           -> Cliente nativo JSON-RPC 2.0 stdio MCP
  tools/           -> Registro y herramientas nativas
    files.py       -> read_file, write_file, str_replace (SWE-bench style)
    bash.py        -> Ejecución de comandos en subprocess con timeout
    search.py      -> glob y grep dentro del repositorio
    memory.py      -> remember y recall (.yunta/memory.json)
    delegate.py    -> delegate_research con subagente secundario

Para una explicación técnica detallada del diseño, consulta la Documentación de Arquitectura Completa.

---

Licencia

Este proyecto está bajo la Licencia MIT - Copyright (c) 2026 j0sp0nc3 beroiza79@gmail.com.