​

Goals

​

The Hierarchy

Mission  →  Project  →  Goal  →  Task

​

Why It Matters

1. Routines inject goal context. A routine with goal_id: mrr-80k in config/routines.yaml tells the agent: “this is the outcome you’re working toward.” Reports, analyses, and recommendations become sharper because the agent knows what “good” looks like.
2. Heartbeats inject goal context. Same mechanism — a heartbeat with a goal_id gives the proactive agent an anchor.
3. Progress is visible. The dashboard shows every goal with current_value / target_value, due date, and status. Stale or overdue goals surface automatically.

​

Creating a Goal

​

Via the create-goal skill (recommended)

“Create a goal to reach 80k MRR by June 30.”

1. Pick (or create) a mission
2. Pick (or create) a project under it
3. Define the goal — title, metric type, target, due date
4. (Optional) attach starter tasks
5. (Optional) link an existing routine

​

Via the dashboard

​

Via the API

# 1. Create the project (if needed)
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. Create the goal
curl -X POST http://localhost:8080/api/goals \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "mrr-80k",
    "project_id": 7,
    "title": "Reach 80k MRR",
    "metric_type": "currency",
    "target_value": 80000,
    "current_value": 62000,
    "due_date": "2026-06-30"
  }'

​

Metric Types

​

Progress Tracking

​

Automatic (via tasks)

1. Create tasks with goal_id: {numeric_id}
2. When a task’s status flips to done, the backend recomputes current_value from the SQL view goal_progress_v
3. When current_value >= target_value, the goal’s status flips to achieved

​

Manual (direct PATCH)

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

​

Drift correction

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

​

Linking a Routine

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

​

Linking a Heartbeat

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

​

Linking a Ticket

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

​

Viewing Progress

​

Dashboard

​

API

# All active goals
curl "http://localhost:8080/api/goals?status=active"

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

# Goals under a project, with tasks
curl "http://localhost:8080/api/goals?project_id=7&include_tasks=true"

​

Anti-patterns

• Goals without metrics. “Make the product better” isn’t a goal — it’s a wish. Every goal needs metric_type, target_value, and due_date.
• Goals that never change state. If current_value doesn’t move for weeks, the goal is either stale (archive it) or not wired to a signal (add a routine that updates it).
• Overloading missions. A mission should span a quarter or longer. If you’re creating a mission per week, flatten them into projects.
• Linking a routine to a non-existent goal slug. The API returns 404. Confirm the slug with GET /api/goals first.

​

CLI Skills

​

Related

• docs/heartbeats.md — wake agents on intervals with goal context
• docs/tickets.md — persistent work units linkable to goals
• Source: dashboard/backend/routes/goals.py, dashboard/backend/goal_context.py