---
title: PM Goals
---

# PM Goals

Hierarchical goal tracking for Mission Control workspaces: set objectives,
link them to boards, and track progress automatically or manually.

## What it is

Goals are workspace-scoped objectives that sit above individual boards. Each
goal has a title, description (up to 5000 characters), optional owner,
target date, and a status that reflects health: on track, at risk, off
track, or achieved.

Goals support hierarchy via `parent_goal_id`, letting you nest sub-goals
under a parent. Progress tracking uses two modes: **auto** (derived from
linked boards) and **manual** (explicit 0-100 percent set by the user).

You can link any number of PM boards to a goal. Linking gives the goal
concrete backlog items to track against. An activity feed records every
change (status, progress, board links, parent changes) with field-level
detail.

## Where to find it

Goals live in the Mission Control PM system, inside a workspace. The goals
list is the entry point — every goal in the workspace, with its health status
and progress — and selecting a goal opens its detail view, carrying the
description, owner, target date, linked boards, comments and the activity
feed. Goal comments are their own thread, separate from that activity feed.

The same surface is reachable without the UI: the CLI control server exposes
`/pm/goals`, so a session or an external script can create, read and update
goals programmatically.

## How it behaves

1. **Create** -- sets progress to 0 and status to `on_track` by default; uses request deduplication
2. **Update** -- field-level activity logging via `logGoalFieldChange` (only logs fields actually included in the patch)
3. **Link / Unlink boards** -- connects goals to PM boards for context and (in auto mode) progress derivation
4. **Nest** -- `parent_goal_id` enables hierarchical goal trees; `listChildGoals` returns sub-goals
5. **Comment** -- separate comment system (add, list, delete) alongside the activity feed
6. **Delete** -- soft delete

## For agents

### Key files

- `src/shared/types/pm.ts` (lines 309-357) -- `PmGoal`, `PmGoalBoard`, `PmGoalActivity` types; status and progress-mode enums
- `src/shared/ipc-schemas/pm-goals.ts` -- Zod validation schemas for all goal IPC inputs
- `src/main/db/queries-pm-goals.ts` -- SQLite CRUD against `pm_goals`, `pm_goal_boards`, `pm_goal_activity` tables
- `src/main/ipc/pm-goals-handlers.ts` -- IPC handler registrations (auto-discovered)
- `src/main/services/pm/pm-goal-comment-queries.ts` -- goal comment queries
- `src/main/services/cli/pm/pm-goal-routes.ts` -- CLI routes (`/pm/goals`)
- `src/plugins/mission-control/web/lib/session-bridge-goals.ts` -- frontend session-bridge wrappers
- `src/plugins/mission-control/web/features/goals/GoalPage.tsx` -- single goal detail view
- `src/plugins/mission-control/web/features/goals/GoalsListPage.tsx` -- goals list view

### Implementation notes

- 15 IPC channels prefixed `pm:goal:` and `pm:goal-*`: list, get, create, update, delete, board link/unlink, activity list, children list, comments (list/add/delete/changed), goals changed
- CLI routes mirror the IPC surface as REST endpoints gated by `pmCliEnabled`: `GET /pm/goals`, `GET /pm/goals/:id`, `POST /pm/goals`, `PATCH /pm/goals/:id`, plus board-link and activity endpoints
- Activity logging via `logGoalFieldChange` records old/new values per field

## Related

Goals are one part of the Mission Control PM system, so [mission-control.md](mission-control.md)
is the parent page to read next. If what you want is a rollup of the *boards* a goal points at,
[pm-portfolios.md](pm-portfolios.md) covers grouping several boards into a named portfolio with
a unified status summary — portfolios aggregate boards, goals sit above them as objectives. The
full list of library pages is in [INDEX.md](INDEX.md).