Goal

A high-level objective with acceptance criteria that defines the desired outcome.

Overview

Goals represent what you want to achieve. They define the desired outcome in human-readable terms, along with optional acceptance criteria that specify when the goal is considered complete. Goals are typically referenced by Plans, which describe how to achieve them.

Schema

yaml

apiVersion: planspec.io/v1alpha1
kind: Goal
metadata:
  name: string          # Required, unique identifier
  namespace: string     # Required, resource namespace
  labels: object        # Optional, key-value pairs for organization
  annotations: object   # Optional, arbitrary metadata
spec:
  description: string   # Required, human-readable description of the goal
  acceptanceCriteria:   # Optional, list of criteria objects
    - description: string  # Required, what must be true
      id: string           # Optional, unique identifier for reference
  constraints: object    # Optional, execution constraints
  planSelector: object   # Optional, criteria for selecting plans
  timeout: string        # Optional, time limit for achieving the goal
  priority: number       # Optional, goal priority level
  context: object[]      # Optional, contextual attachments
status:
  phase: string          # Goal lifecycle phase
  activePlanRef: object  # Reference to the currently active plan
  conditions: object[]   # Status conditions
  observedGeneration: number  # Last observed generation

Fields

Spec Fields

Field	Type	Required	Description
`description`	string	Yes	Human-readable description of the desired outcome
`acceptanceCriteria`	object[]	No	Array of criteria that define success
`acceptanceCriteria[].description`	string	Yes	What must be true for this criterion
`acceptanceCriteria[].id`	string	No	Unique identifier for referencing this criterion
`constraints`	object	No	Execution constraints for the goal
`planSelector`	object	No	Criteria for selecting plans to achieve this goal
`timeout`	string	No	Time limit for achieving the goal (e.g., "2h", "30m")
`priority`	number	No	Goal priority level (higher = more important)
`context`	object[]	No	Contextual attachments for plan generation

Metadata Fields

Field	Type	Required	Description
`name`	string	Yes	Unique identifier for the goal
`namespace`	string	Yes	Resource namespace
`labels`	object	No	Key-value pairs for filtering and organization
`annotations`	object	No	Arbitrary metadata

Status Fields

Field	Type	Description
`phase`	string	Current goal lifecycle phase
`activePlanRef`	object	Reference to the plan currently being executed
`conditions`	object[]	Status conditions with type, status, reason, message
`observedGeneration`	number	Last observed spec generation

Goal Phases

Phase	Description
`Pending`	Goal created but no plan assigned
`Planning`	Plan is being generated for this goal
`Ready`	Plan assigned and ready for execution
`Executing`	Plan is currently being executed
`Succeeded`	Goal achieved, acceptance criteria met
`Failed`	Goal could not be achieved
`Cancelled`	Goal was cancelled before completion

Example

yaml

apiVersion: planspec.io/v1alpha1
kind: Goal
metadata:
  name: user-authentication
  namespace: default
  labels:
    component: auth
    priority: high
  annotations:
    planspec.io/created-by: "alice@example.com"
spec:
  description: Implement secure user authentication for the web application
  priority: 100
  timeout: "8h"
  acceptanceCriteria:
    - id: signup
      description: Users can sign up with email and password
    - id: password-security
      description: Passwords are hashed using bcrypt with cost factor 12
    - id: jwt-expiry
      description: JWT tokens expire after 24 hours
    - id: refresh-tokens
      description: Refresh tokens allow session extension without re-authentication

JSON Schema

The full JSON Schema is available at: Goal Schema

Next Steps

Plan - Create a plan to achieve this goal
Concepts: Goals, Tasks & Gates - Learn more about goals