Workers e Intelligence Layer

Arc OS utiliza un sistema de workers para distribuir tareas entre agentes de IA especializados, y el Intelligence Layer garantiza la calidad de sus respuestas mediante cuatro módulos: Binary Evals, Context Router, Learnings y Karpathy Loop.

Sistema de workers

Cada worker es un agente de IA independiente con un rol, modelo y conjunto de herramientas definidos. Los workers operan dentro de un proyecto y están disponibles a través del Workspace UI o comandos de Telegram (/c, /d, /w:worker_id).

Biblioteca canónica de presets (12)

Todos los presets viven en config/workers_registry.json y están disponibles vía GET /api/crm/workers/presets. Cada uno es una plantilla genérica para cualquier proyecto: sin referencias de marca, sin nombres de personajes, sin alusiones a nuestra infraestructura.

Engineering / Core (6):

Operaciones de startup (6, añadidos en Phase 66):

Crear un worker en un proyecto

Desde la UI (default): clic en + Add en la pill bar del WorkerSelector → se abre el WorkerCreationWizard con 3 pasos:

1. Identity — elegir una tarjeta de preset O "From scratch"
2. Capabilities — modelo + tools + advertencias inteligentes (p. ej. "rol read-only + tool Write = misconfig")
3. Instructions — system prompt + selector de skills + vista previa en vivo

El wizard auto-inyecta el baseline SYSTEM_PROTOCOL (ver más abajo) — el preset se centra solo en la pericia específica del rol.

Desde CLI / API: POST /api/crm/projects/:name/workers con el body completo (formulario legacy, enlace "Show advanced form →" en el wizard).

Tipos de workers

• chat — conversación por turnos con historial de contexto completo. El worker recibe toda la conversación anterior y responde como interlocutor.
• terminal — ejecución en streaming con tool events. El worker opera como una sesión de terminal, ejecutando herramientas en secuencia y transmitiendo el progreso en tiempo real.

Crear un worker personalizado

Los workers personalizados se describen en el archivo config/workers_registry.json. Cada entrada define el comportamiento del agente:

{
  "id": "my-worker",
  "label": "My Worker",
  "icon": "🔧",
  "type": "chat",
  "model": "claude-sonnet-4-5",
  "max_turns": 10,
  "tools": ["Read", "Glob", "Grep"],
  "system_prompt": "You are...",
  "focus_dirs": ["src/"],
  "builtin": false
}

Campos de configuración

SYSTEM_PROTOCOL — Baseline para todos los workers

Mientras que worker.system_prompt define la pericia específica del rol (el analyst hace TAM/SAM/SOM, el sentinel hace auditorías de SQL injection), hay 15 reglas transversales que todo worker debe cumplir — del developer al pitch-coach. En lugar de duplicarlas en cada preset, viven en una sola constante (shared/cli-routes.ts:SYSTEM_PROTOCOL) y se auto-inyectan en cada spawn de worker a través de child-bot/claude-runner.ts.

5 reglas de Mandatory Workflow

1. Every new task MUST be registered via arc issue create
2. Any plan change MUST update ROADMAP.md via arc roadmap sync
3. Before starting work, read ROADMAP.md + open issues (arc issues)
4. After significant changes, sync knowledge via arc memory refresh
5. Log meaningful progress on issues via arc issue log <id> "<text>"

10 reglas de Quality Baseline (#229)

6. Priorities: P0 > P1 > P2 > P3 — always know what's next and why
7. Session report: close meaningful work with arc report --summary
8. Definition of Done includes documentation, not just commit
9. Trade-offs explicit: scope vs deadline vs quality — recommend one path + 1-2 alternatives
10. Format: concise, tables/numbers where possible, actionable beats descriptive
11. Cite sources for any fact/number; "I don't know" beats fabrication
12. No silent failures: state blockers explicitly, don't continue down wrong path
13. Honest progress: report what actually shipped (done vs attempted vs failed)
14. Convention over invention: follow existing patterns, explain deviations
15. Learnings feedback loop: append to learnings.md when corrected on recurring mistake

Efecto

Gracias a esta inyección automática, los presets quedaron un 50-70 % más cortos. Ejemplo: product-owner bajó de 733 a 404 caracteres — solo quedó el "User-first lens" (el enfoque específico); el resto (priorities/roadmap/issues/DoD/trade-offs) ahora es baseline.

Los administradores pueden ampliar el baseline en shared/cli-routes.ts — el cambio se aplica automáticamente a todos los workers en el siguiente spawn.

Binary Evals — Validación de respuestas

¿Qué son?

Reglas declarativas para verificar la calidad de las respuestas de los workers. Cada regla es determinista (sin IA), se ejecuta al instante y no bloquea la respuesta. Los resultados tienen severity warning o info — informan, no detienen.

6 tipos de reglas

Formato del archivo evals

El archivo se coloca junto a la skill: skills/{skill_name}/{skill_name}.evals.json

{
  "version": 1,
  "skill": "code-review",
  "rules": [
    {
      "id": "cr-001",
      "name": "Must return JSON verdict",
      "type": "string_contains",
      "value": "\"verdict\"",
      "severity": "warning"
    }
  ]
}

Cada regla tiene un id único, un name legible por humanos, uno de los 6 tipos, un value para la comparación y un severity (warning o info).

Context Router — Selección automática de skills

¿Cómo funciona?

Con cada mensaje, el Context Router puntúa todas las skills de skills/_registry.json y selecciona automáticamente las más relevantes:

1. Trigger match (+2 puntos) — coincidencia directa de una palabra trigger del mensaje
2. Keyword match (+1 punto) — proximidad semántica por palabras clave
3. Top-5 por puntaje total, inyectadas como SKILLS_HINT en el prompt del worker

Ejemplo

Mensaje: "review the git commit for security"

• code-review: trigger "review" encontrado → +2 puntos
• git-manager: keyword "commit" encontrado → +1 punto
• Resultado: code-review (2), git-manager (1) inyectadas en el prompt

Formato del registro de skills

{
  "name": "code-review",
  "triggers": ["review", "audit", "security"],
  "keywords": ["vulnerability", "OWASP", "XSS"],
  "agents": ["summer"],
  "category": ["complex"]
}

• triggers — palabras que apuntan directamente a la skill (alta prioridad)
• keywords — términos adicionales para la asociación semántica
• agents — qué workers pueden usar esta skill
• category — clasificación (simple, complex, critical)

Learnings — Memoria de correcciones

¿Cómo se crean?

Los Learnings son reglas acumuladas que surgen del feedback:

1. Thumbs-down (👎) — se crea automáticamente un learning con source "negative" a partir de una respuesta problemática
2. Fix It — volver a ejecutar una tarea genera un learning con source "fixit"
3. Manuales — decisiones de arquitectura y reglas, source "manual" o "architecture"

Formato del archivo

El archivo learnings.md en la raíz del proyecto:

# Learnings
> Auto-generated. Injected into GSD prompt at session start.

## Rules
- [2026-04-03T20:00:00Z] [architecture] Rule text here...
- [2026-04-04T10:00:00Z] [security] Another rule...

¿Cómo se usan?

• Se cargan al inicio de cada sesión del worker
• Se inyectan en el GSD-prompt del Developer (presupuesto: 2000 caracteres)
• Las reglas más recientes van primero (prioridad por tiempo)
• Actúan como memoria inmune — los errores cometidos una vez no se repiten en sesiones posteriores

Karpathy Loop — Automejora nocturna

Ciclo automático de mejora de skills, inspirado en las ideas de Andrej Karpathy sobre la automejora iterativa.

¿Cómo funciona?

Cada noche a las 3:00 UTC se ejecuta un pipeline automático:

1. Recopilación de métricas — lee quality-metrics.json de cada proyecto
2. Detección de skills problemáticas — filtra skills con success rate < 80% o con más feedback negativo que positivo
3. Análisis con Sage — Haiku genera una versión mejorada de la skill a partir de los errores recopilados
4. Test A/B ciego — 3 escenarios, orden aleatorizado, puntuación dual:
   • Eval rules (60% del peso) + LLM judge (40% del peso)
5. Creación de PR — si la nueva versión gana (new_wins > old_wins), se crea un pull request
6. Reporte al CEO — los resultados se envían por Telegram para la decisión final

Métricas de calidad

Cada proyecto acumula estadísticas en quality-metrics.json:

{
  "total_invocations": 42,
  "total_successes": 40,
  "total_feedback_positive": 35,
  "total_feedback_negative": 2,
  "avg_duration_ms": 15000,
  "skills": [
    {
      "name": "code-review",
      "applied_count": 5,
      "success_count": 4
    }
  ]
}

Estas métricas permiten al sistema identificar objetivamente qué skills necesitan mejoras y hacer seguimiento del progreso tras las actualizaciones.