Goals

Goals are persistent objectives that sit above individual issues. Each goal groups a set of related issues, and the orchestrator uses that grouping to build an ordered execution plan — and optionally run it automatically with Autopilot. Goals are stored locally in .agenties/goals.json.

Goal structure

interface GoalRecord {
  id: string;               // "goal-<6chars>-<4chars>"
  title: string;            // Short objective statement
  description?: string;     // Optional markdown context
  status: GoalStatus;       // "active" | "paused" | "done"
  priority: "high" | "medium" | "low";
  createdAt: string;        // ISO timestamp
  updatedAt: string;
}

Issues link back to a goal via the goalId field on each issue. The goal record itself holds no issue IDs — the link is on the issue side.

Statuses

Creating goals

From the Goals panel

Open the Goals section in the sidebar. Click New goal, enter a title, optional description, and priority. The goal is saved immediately and becomes the target for linking new issues.

From chat

Describe a multi-issue objective in chat and the orchestrator will create a goal automatically, then break it down into linked issues. You can also ask explicitly: "Create a goal to improve the authentication flow, then split it into issues."

Via MCP tool

create_goal({
  title: "Harden MCP server lifecycle",
  description: "Ensure the sidecar restarts cleanly on crash and exposes health checks.",
  priority: "high"
})
// Returns: GoalRecord with status="active"

Linking issues to a goal

Set the goalId field when creating or updating an issue:

create_issue({
  title: "Add process health-check endpoint",
  priority: "medium",
  goalId: "goal-abc123-xyz9"   // links this issue to the goal
})

update_issue({
  id: "issue-existing-id",
  goalId: "goal-abc123-xyz9"   // attach an existing issue to a goal
})

Issues can only belong to one goal. Removing goalId or setting it to an empty string unlinks the issue. The goal itself is not updated — re-reading the execution plan reflects the change immediately.

Execution plan

Call get_execution_plan to get an ordered view of all non-done issues for a goal:

get_execution_plan({ goalId: "goal-abc123-xyz9" })

// Returns:
{
  goalId: "goal-abc123-xyz9",
  goalTitle: "Harden MCP server lifecycle",
  goalStatus: "active",
  totalItems: 3,
  items: [
    {
      issue: { id: "issue-...", seq: 1, title: "Add health-check", status: "open", ... },
      suggestedMember: { id: "member-xyz", name: "Jordan", role: "builder" },
      routingReason: "team match: backend/MCP match",
      estimatedCost: null,     // not implemented — always null
      reviewCheckpoint: true   // always true
    },
    // ...
  ]
}

Team routing

Each plan item includes a suggestedMember— a heuristic match based on the issue title/description against each team member's name, role, and instructions. The routing uses keyword overlap and domain experience signals from.agenties/experience.json. If no confident match is found (score < 3), the field is null and the orchestrator chooses the member itself.

Running a goal with Autopilot

The Goals panel has a Run button that starts the Autopilot loop for the goal. Autopilot iterates the execution plan — one issue at a time — spawning agents, waiting for evidence, and persisting a journal entry before moving to the next issue.

Updating and closing goals

// Pause a goal (Autopilot will not start new runs)
update_goal({ id: "goal-abc123-xyz9", status: "paused" })

// Mark a goal done
update_goal({ id: "goal-abc123-xyz9", status: "done" })

// Change priority
update_goal({ id: "goal-abc123-xyz9", priority: "high" })

Marking a goal done does not automatically close its linked issues — the orchestrator closes issues individually as agents complete them. Always verify linked issues are done before marking the goal itself as done.

What persists in .agenties/

What Goals do not do