---
title: Goals — Reference
---

# Goals — Reference

The Goals page shows strategic intent at two levels — **domain** and **repository** — and how they relate. It provides context for why workstreams exist and what they collectively deliver.

---

## The two goal levels

### Domain Goal

A domain goal captures the **high-level strategic intent** for an entire domain (e.g., railiance, markitect). It answers the question: *"What are we ultimately trying to achieve here?"*

Key properties:
- Only **one domain goal can be active** per domain at any time.
- When a new goal is activated, the previous one is automatically marked **superseded** — it is retained as history, not deleted.
- Goals can also be manually set to **archived** to park them permanently.

### Repository Goal

A repository goal refines a domain goal into **actionable scope** for a specific repository. It answers: *"What does this repo need to deliver to advance the domain goal?"*

Key properties:
- A repo can have **multiple active goals** with different **priorities**.
- Priority is an integer — lower number means higher priority (e.g., `10` takes precedence over `100`).
- Each repo goal should be linked to its parent domain goal via `domain_goal_id`, though unlinked goals are also supported.
- Goals can shift between `active`, `paused`, `completed`, and `archived` as work evolves.

---

## Status lifecycle

### Domain goals

```
active  ──→  superseded   (auto, when a newer goal is activated)
active  ──→  archived     (manual, via PATCH /domain-goals/{id})
```

Only one goal per domain can hold `active` status. Activating a goal via `POST /domain-goals/{id}/activate` supersedes whatever was active before.

### Repository goals

```
active  ──→  paused      (work deprioritised, not abandoned)
active  ──→  completed   (the goal was achieved)
active  ──→  archived    (scope dropped or obsolete)
paused  ──→  active      (work resumed)
```

Completed and archived goals are preserved as history. They appear in the secondary accordion on the Goals page under the domain goal they were linked to.

---

## Page layout

The Goals page groups everything by domain:

```
┌─ railiance ──────────────────────────────────────────────────────┐
│  ┌─ Domain Goal ──────────────────────────── [active] ─────────┐ │
│  │  Three-Phoenix Secure Kubernetes Infrastructure              │ │
│  │  Improve the railiance repositories so that I can …         │ │
│  │  ─────────────────────────────────────────────────────────  │ │
│  │  Repository Goals                                            │ │
│  │  ┌─ #10  railiance-bootstrap ─────────── [active] ────────┐ │ │
│  │  │  Secure Single-Server Bootstrap at HostEurope           │ │ │
│  │  │  Bootstrap a new server securely at hosteurope …        │ │ │
│  │  └────────────────────────────────────────────────────────┘ │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                    │
│  ▶ 0 secondary goals                                              │
└────────────────────────────────────────────────────────────────────┘
```

- The **active domain goal** is the primary card with a green left border.
- **Repository goals** are nested inside it, sorted by priority (lowest number first).
- **Secondary goals** (superseded and archived domain goals, with their repo goals) are collapsed into an accordion below the active goal. Click to expand.
- Domains that have no active goal are shown at the bottom and highlighted amber in the KPI box.
- **Unlinked repository goals** — active repo goals not associated with any domain goal — appear in a separate section at the bottom of the page.

---

## KPI sidebar

| Metric | Meaning |
|---|---|
| **domains with active goal** | How many of your active domains have a current strategic intent set |
| **active repo goals** | Total active repo goals across all repos |
| **no active goal** | Domains missing a goal — shown in amber when non-zero |

---

## MCP tools

| Tool | Description |
|---|---|
| `create_domain_goal(domain_slug, title, description)` | Create a new active goal for a domain (supersedes previous active) |
| `get_domain_goals(domain_slug, status?)` | List domain goals, optionally filtered by status |
| `activate_domain_goal(goal_id)` | Make an existing goal active, superseding the current one |
| `create_repo_goal(repo_slug, title, description, domain_goal_id?, priority?)` | Create a repo goal, optionally linked to a domain goal |
| `get_repo_goals(repo_slug, status?)` | List repo goals for a repository |
| `update_repo_goal(goal_id, ...)` | Update title, description, priority, status, or domain link |

---

## REST endpoints

| Method | Path | Effect |
|---|---|---|
| `GET` | `/domain-goals/` | List domain goals (filter: `domain_slug`, `status`) |
| `POST` | `/domain-goals/` | Create a domain goal |
| `GET` | `/domain-goals/{id}` | Get a single domain goal |
| `PATCH` | `/domain-goals/{id}` | Update title, description, or status |
| `POST` | `/domain-goals/{id}/activate` | Activate a goal (supersedes current active) |
| `GET` | `/repo-goals/` | List repo goals (filter: `repo_slug`, `domain_goal_id`, `status`) |
| `POST` | `/repo-goals/` | Create a repo goal |
| `GET` | `/repo-goals/{id}` | Get a single repo goal |
| `PATCH` | `/repo-goals/{id}` | Update any field |

---

## Linking workstreams to repo goals

Workstreams carry an optional `repo_goal_id` field. Setting it traces *why* a workstream exists — which specific repo goal it contributes to. This connection is currently recorded in the DB but is not yet visualised in the Workstreams page.

To set the link when creating a workstream via `create_workstream`, pass `repo_goal_id`. To update an existing one, use `PATCH /workstreams/{id}/` with `{"repo_goal_id": "<uuid>"}`.

---

## Design rationale

Goals are intentionally separate from workstreams. A workstream is a unit of *deliverable work*; a goal is a statement of *strategic intent*. Goals are stable and long-lived; workstreams are created, completed, and replaced as work advances. The goal hierarchy (domain → repo → workstream) provides the context needed to understand why any given piece of work exists.