​

Goals

​

A Hierarquia

Mission  →  Project  →  Goal  →  Task

​

Por que importa

1. Rotinas injetam contexto do goal. Uma rotina com goal_id: mrr-80k em config/routines.yaml informa ao agente: “este é o resultado que você está perseguindo.” Relatórios, análises e recomendações ficam mais afiados porque o agente sabe como é o “bom”.
2. Heartbeats injetam contexto do goal. Mesmo mecanismo — um heartbeat com goal_id dá ao agente proativo uma âncora.
3. Progresso fica visível. O dashboard mostra cada goal com current_value / target_value, prazo e status. Goals parados ou atrasados aparecem automaticamente.

​

Criando um Goal

​

Via skill create-goal (recomendado)

“Crie um goal para atingir 80k MRR até 30 de junho.”

1. Escolher (ou criar) uma mission
2. Escolher (ou criar) um project sob ela
3. Definir o goal — título, tipo de métrica, target, due date
4. (Opcional) anexar tasks iniciais
5. (Opcional) ligar uma rotina existente

​

Via dashboard

​

Via API

# 1. Criar o project (se necessário)
curl -X POST http://localhost:8080/api/projects \
  -H "Content-Type: application/json" \
  -d '{"slug": "sales-q2-2026", "title": "Sales — Q2 2026", "mission_id": 1}'

# 2. Criar o goal
curl -X POST http://localhost:8080/api/goals \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "mrr-80k",
    "project_id": 7,
    "title": "Atingir 80k MRR",
    "metric_type": "currency",
    "target_value": 80000,
    "current_value": 62000,
    "due_date": "2026-06-30"
  }'

​

Tipos de Métrica

​

Acompanhamento de Progresso

​

Automático (via tasks)

1. Crie tasks com goal_id: {numeric_id}
2. Quando o status da task vira done, o backend recalcula current_value a partir da view SQL goal_progress_v
3. Quando current_value >= target_value, o status do goal vira achieved

​

Manual (PATCH direto)

curl -X PATCH http://localhost:8080/api/goals/{id} \
  -H "Content-Type: application/json" \
  -d '{"current_value": 67500}'

​

Correção de drift

curl -X POST http://localhost:8080/api/goals/{id}/recalculate

​

Ligando uma Rotina

curl -X POST http://localhost:8080/api/goals/link-routine \
  -H "Content-Type: application/json" \
  -d '{"routine_name": "financial-pulse", "goal_id": "mrr-80k"}'

​

Ligando um Heartbeat

- id: flux-6h
  agent: flux-finance
  goal_id: mrr-80k
  # ... resto

​

Ligando um Ticket

curl -X POST http://localhost:8080/api/tickets \
  -d '{"title": "...", "goal_id": 12}'

​

Visualizando Progresso

​

Dashboard

​

API

# Todos os goals ativos
curl "http://localhost:8080/api/goals?status=active"

# Goals atrasados
curl "http://localhost:8080/api/goals?due_date=overdue"

# Goals de um project, com tasks
curl "http://localhost:8080/api/goals?project_id=7&include_tasks=true"

​

Anti-padrões

• Goals sem métrica. “Melhorar o produto” não é um goal — é um desejo. Todo goal precisa de metric_type, target_value e due_date.
• Goals que nunca mudam de estado. Se current_value não se move por semanas, o goal está parado (arquive-o) ou não está conectado a um sinal (adicione uma rotina que atualize).
• Sobrecarregar missions. Uma mission deve cobrir um trimestre ou mais. Se você está criando uma mission por semana, achate-as em projects.
• Ligar uma rotina a um goal slug inexistente. A API retorna 404. Confirme o slug com GET /api/goals antes.

​

Skills do CLI

​

Relacionados

• docs/heartbeats.md — acordar agentes em intervalos com contexto de goal
• docs/tickets.md — unidades de trabalho persistentes que podem ser ligadas a goals
• Código: dashboard/backend/routes/goals.py, dashboard/backend/goal_context.py