Goals, Tasks & Gates

PlanSpec organizes work into three main concepts: Goals, Tasks, and Gates.

Goals

A Goal represents the desired end state or outcome. Goals are stable—they describe what you want to achieve without prescribing how.

yaml

apiVersion: planspec.io/v1alpha1
kind: Goal
metadata:
  name: user-authentication
  namespace: default
spec:
  description: Secure user authentication system
  acceptanceCriteria:
    - description: Users can create accounts
    - description: Users can log in securely
    - description: Sessions expire after inactivity

Goal Properties

Property	Description
`name`	Unique identifier for the goal
`description`	Human-readable summary
`acceptanceCriteria`	Conditions that define success

Tasks

A Task is a discrete unit of work within a plan. Tasks have:

Clear descriptions
Dependencies on other tasks
Their own acceptance criteria

yaml

# Tasks are defined within a Plan's graph.nodes array
graph:
  nodes:
    - id: setup-database
      kind: Task
      description: Create user table in database
      acceptanceCriteria:
        - type: command_succeeds
          name: Table exists
          command: psql
          args: ["-c", "\\d users"]

    - id: implement-signup
      kind: Task
      description: Create signup endpoint
      dependsOn:
        - setup-database
      acceptanceCriteria:
        - type: endpoint_responds
          name: Signup endpoint works
          url: http://localhost:3000/signup
          method: POST
          expectedStatus: 201

Task Dependencies

Tasks can depend on other tasks. A task won't start until all dependencies are complete.

yaml

# Tasks use dependsOn to declare dependencies
graph:
  nodes:
    - id: task-a
      kind: Task
      description: First task

    - id: task-b
      kind: Task
      dependsOn: [task-a]
      description: Depends on task-a

    - id: task-c
      kind: Task
      dependsOn: [task-a, task-b]
      description: Depends on both

Gates

A Gate is a checkpoint that must be passed before work can continue. Gates are useful for:

Code reviews
Security audits
Stakeholder approval

yaml

apiVersion: planspec.io/v1alpha1
kind: Gate
metadata:
  name: security-review
  namespace: default
spec:
  gateType: review
  targetRef:
    kind: Execution
    name: my-execution
  description: Security team must approve before deployment
  reviewers:
    - team:security

How They Work Together

Goal defines the destination
Plan references the goal and contains tasks
Tasks break down the work
Gates ensure quality checkpoints

Next Steps

Acceptance Criteria — Writing effective criteria
CLI Commands — Working with plans