The Goals page shows strategic intent at two levels — **domain** and **repository** — and how they relate. It provides context for why workplans exist and what they collectively deliver.
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.
- 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 |
Workplans carry an optional `repo_goal_id` field. Setting it traces *why* a workplan exists — which specific repo goal it contributes to. This connection is currently recorded in the DB but is not yet visualised in the Workplans page.
To set the link when creating a workplan through the preferred API, pass `repo_goal_id`. To update an existing one, use `PATCH /workplans/{id}/` with `{"repo_goal_id": "<uuid>"}`. Legacy `create_workstream` and `/workstreams/{id}/` callers remain compatibility-supported while they are metered.
Goals are intentionally separate from workplans. A workplan is a unit of *deliverable work*; a goal is a statement of *strategic intent*. Goals are stable and long-lived; workplans are created, completed, and replaced as work advances. The goal hierarchy (domain → repo → workplan) provides the context needed to understand why any given piece of work exists.
