Workers e Intelligence Layer

Arc OS utiliza um sistema de workers para distribuir tarefas entre agentes de IA especializados, e o Intelligence Layer garante a qualidade das respostas por meio de quatro módulos: Binary Evals, Context Router, Learnings e Karpathy Loop.

Sistema de workers

Cada worker é um agente de IA independente com papel, modelo e conjunto de ferramentas definidos. Os workers operam dentro de um projeto e estão disponíveis via Workspace UI ou comandos do Telegram (/c, /d, /w:worker_id).

Biblioteca canônica de presets (12)

Todos os presets vivem em config/workers_registry.json e estão disponíveis via GET /api/crm/workers/presets. Cada um é um template genérico para qualquer projeto: sem referências de marca, sem nomes de personagens, sem menções à nossa infraestrutura.

Engineering / Core (6):

Operações de startup (6, adicionados na Phase 66):

Criação de worker em um projeto

Via UI (default): clique em + Add na pill bar do WorkerSelector → abre o WorkerCreationWizard com 3 etapas:

1. Identity — escolha um card de preset OU "From scratch"
2. Capabilities — modelo + tools + avisos inteligentes (p.ex. "role read-only + tool Write = misconfig")
3. Instructions — system prompt + seletor de skills + preview ao vivo

O wizard injeta automaticamente o baseline SYSTEM_PROTOCOL (veja abaixo) — o preset foca apenas na expertise específica do role.

Via CLI / API: POST /api/crm/projects/:name/workers com o body completo (formulário legado, link "Show advanced form →" no wizard).

Tipos de workers

• chat — conversa turn-based com histórico completo de contexto. O worker recebe toda a conversa anterior e responde como interlocutor.
• terminal — execução em streaming com tool events. O worker funciona como uma sessão de terminal, executando ferramentas sequencialmente e transmitindo o progresso em tempo real.

Criando um worker personalizado

Workers personalizados são descritos no arquivo config/workers_registry.json. Cada entrada define o comportamento do 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 configuração

SYSTEM_PROTOCOL — Baseline para todos os workers

Enquanto worker.system_prompt define a expertise específica do role (o analyst faz TAM/SAM/SOM, o sentinel faz auditoria de SQL injection), existem 15 regras transversais que qualquer worker deve seguir — do developer ao pitch-coach. Em vez de duplicá-las em cada preset, elas vivem em uma única constante (shared/cli-routes.ts:SYSTEM_PROTOCOL) e são injetadas automaticamente em cada spawn de worker via child-bot/claude-runner.ts.

5 regras 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 regras 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

Efeito

Graças a essa injeção automática, os presets ficaram 50-70% mais curtos. Exemplo: o product-owner caiu de 733 para 404 chars — sobrou apenas o "User-first lens" (frame específico); o resto (priorities/roadmap/issues/DoD/trade-offs) agora é baseline.

Admins podem estender o baseline em shared/cli-routes.ts — a mudança se aplica automaticamente a todos os workers no próximo spawn.

Binary Evals — Validação de respostas

O que é isso?

Regras declarativas para verificar a qualidade das respostas dos workers. Cada regra é determinística (sem IA), executa instantaneamente e não bloqueia a resposta. Os resultados têm severity warning ou info — eles informam, não interrompem.

6 tipos de regras

Formato do arquivo de evals

O arquivo fica junto à 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 regra tem um id único, um name legível por humanos, um dos 6 tipos, value para comparação e severity (warning ou info).

Context Router — Seleção automática de skills

Como funciona?

A cada mensagem, o Context Router pontua todas as skills de skills/_registry.json e seleciona automaticamente as mais relevantes:

1. Trigger match (+2 pontos) — ocorrência direta de uma palavra-gatilho da mensagem
2. Keyword match (+1 ponto) — proximidade semântica por palavras-chave
3. Top-5 pela soma de pontos, injetadas como SKILLS_HINT no prompt do worker

Exemplo

Mensagem: "review the git commit for security"

• code-review: trigger "review" encontrado → +2 pontos
• git-manager: keyword "commit" encontrado → +1 ponto
• Resultado: code-review (2), git-manager (1) injetados no prompt

Formato do registro de skills

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

• triggers — palavras que indicam claramente a skill (alta prioridade)
• keywords — termos adicionais para associação semântica
• agents — quais workers podem usar essa skill
• category — classificação (simple, complex, critical)

Learnings — Memória de correções

Como são criados?

Learnings são regras acumuladas que surgem do feedback:

1. Thumbs-down (👎) — um learning é criado automaticamente com source "negative" a partir da resposta problemática
2. Fix It — reexecutar uma tarefa gera um learning com source "fixit"
3. Manuais — decisões de arquitetura e regras com source "manual" ou "architecture"

Formato do arquivo

Arquivo learnings.md na raiz do projeto:

# 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...

Como são usados?

• Carregados no início de cada sessão do worker
• Injetados no GSD prompt do Developer (orçamento de 2000 caracteres)
• As regras mais recentes ficam primeiro (prioridade por data)
• Funcionam como memória imune — erros cometidos uma vez não se repetem nas sessões seguintes

Karpathy Loop — Autoaperfeiçoamento noturno

Ciclo automático de melhoria de skills, inspirado nas ideias de Andrej Karpathy sobre iterative self-improvement.

Como funciona?

Todo dia às 3h UTC, um pipeline automático é executado:

1. Coleta de métricas — lê quality-metrics.json de cada projeto
2. Busca de skills problemáticas — filtra skills com success rate < 80% ou com mais feedback negativo do que positivo
3. Análise pelo Sage — Haiku gera uma versão melhorada da skill com base nos erros coletados
4. Blind A/B test — 3 cenários, ordem randomizada, dual scoring:
   • Eval rules (60% do peso) + LLM judge (40% do peso)
5. Criação de PR — se a nova versão vencer (new_wins > old_wins), um pull request é criado
6. Relatório ao CEO — os resultados são enviados pelo Telegram para a decisão final

Métricas de qualidade

Cada projeto acumula estatísticas em 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
    }
  ]
}

Essas métricas permitem que o sistema identifique objetivamente quais skills precisam de melhoria e acompanhe o progresso após as atualizações.