Plan

A directed acyclic graph (DAG) of nodes with dependencies that describes how to achieve a goal.

Overview

Plans are the core resource in PlanSpec. They define a graph of nodes that can be executed to achieve a goal. The graph supports multiple node kinds: Tasks (work to be done), Gates (approval checkpoints), Groups (logical groupings), and External (references to external plans). Each node can have dependencies on other nodes, forming a DAG that determines execution order. Tasks can include machine-verifiable acceptance criteria that allow automated validation of completion.

Schema

yaml

apiVersion: planspec.io/v1alpha1
kind: Plan
metadata:
  name: string          # Required, unique identifier
  namespace: string     # Required, resource namespace
  labels: object        # Optional, key-value pairs
  annotations: object   # Optional, metadata
spec:
  description: string   # Required, what this plan accomplishes
  goalRef:              # Optional, reference to a Goal
    name: string        # Name of the goal this plan achieves
  series: string        # Optional, plan series identifier (requires version)
  version: string       # Optional, plan version (requires series)
  supersedes:           # Optional, references to plans this supersedes
    - name: string
  graphDigest: string   # Optional, hash of the graph for integrity
  context: object[]     # Optional, contextual attachments
  graph:
    nodes:              # Required, list of nodes (minItems: 1)
      - id: string      # Required, unique node identifier
        kind: string    # Required: Task | Gate | Group | External
        # ... kind-specific fields
    edges:              # Optional, explicit dependency edges
      - from: string
        to: string
        type: string    # hard | soft
status:
  phase: string         # Ready | Invalid
  nodeCount: number     # Total number of nodes in the graph
  conditions: object[]  # Status conditions
  observedGeneration: number  # Last observed generation

Fields

Spec Fields

Field	Type	Required	Description
`description`	string	Yes	What this plan accomplishes
`goalRef`	object	No	Reference to the goal this plan achieves
`goalRef.name`	string	Yes*	Name of the referenced goal (*if goalRef provided)
`series`	string	No	Plan series identifier (requires version)
`version`	string	No	Version within the series (requires series)
`supersedes`	object[]	No	References to plans this plan supersedes
`graphDigest`	string	No	Hash of the graph for integrity verification
`context`	object[]	No	Contextual attachments
`graph`	object	Yes	The node graph
`graph.nodes`	Node[]	Yes	List of nodes (minimum 1)
`graph.edges`	Edge[]	No	Explicit dependency edges

Node Kinds

Kind	Description
`Task`	Work to be performed by an agent or tool
`Gate`	Approval checkpoint referencing a Gate resource
`Group`	Logical grouping of other nodes
`External`	Reference to an external system or process

Task Node Fields

Field	Type	Required	Description
`id`	string	Yes	Unique identifier within the plan
`kind`	string	Yes	Must be "Task"
`name`	string	No	Human-readable name
`description`	string	No	What this task accomplishes
`dependsOn`	string[]	No	IDs of nodes that must complete first
`capabilityRefs`	object[]	No	Required capabilities to execute this task
`inputs`	object	No	Input parameters for the task
`outputs`	string[]	No	Expected output names
`timeout`	string	No	Maximum time allowed for task execution
`retries`	number	No	Number of retry attempts on failure (0-10)
`when`	string	No	Conditional expression for task execution
`estimatedEffort`	string	No	Effort level: `small`, `medium`, `large`, `xlarge`
`acceptanceCriteria`	object[]	No	Machine-verifiable success criteria

Gate Node Fields

Field	Type	Required	Description
`id`	string	Yes	Unique identifier within the plan
`kind`	string	Yes	Must be "Gate"
`name`	string	No	Human-readable name
`description`	string	No	What this gate approves
`dependsOn`	string[]	No	IDs of nodes that must complete first
`gateRef`	object	Yes	Reference to the Gate resource
`gateRef.name`	string	Yes	Name of the Gate resource

Acceptance Criteria Types

Type	Required Fields	Description
`artifact_exists`	`name`, `path`	Verify a file or directory exists
`test_passes`	`name`, `command`	Run a test command and check exit code
`endpoint_responds`	`name`, `url`	Check HTTP endpoint responds correctly
`command_succeeds`	`name`, `command`	Run a shell command and verify success
`custom`	`name`, `webhookUrl`, `expectedResponse`	Custom webhook validation

Acceptance Criteria Common Fields

Field	Type	Required	Description
`id`	string	No	Unique identifier for this criterion
`name`	string	Yes	Human-readable name
`type`	string	Yes	Criterion type
`required`	boolean	No	Whether this criterion is required (default: true)
`timeout`	string	No	Timeout for verification
`extensions`	object	No	Extension data

Acceptance Criteria Field Details

artifact_exists

Field	Type	Required	Description
`path`	string	Yes	Path to the file or directory
`contentMatch`	string	No	Regex pattern to match file content

test_passes / command_succeeds

Field	Type	Required	Description
`command`	string	Yes	Command to execute
`args`	string[]	No	Command arguments
`expectedExitCode`	number	No	Expected exit code (default: 0)
`outputMatch`	string	No	Regex pattern to match output (command_succeeds only)

endpoint_responds

Field	Type	Required	Description
`url`	string	Yes	URL to check
`method`	string	No	HTTP method (default: GET)
`expectedStatus`	number	No	Expected status code (default: 200)
`bodyMatch`	string	No	Regex pattern to match response body

custom

Field	Type	Required	Description
`webhookUrl`	string	Yes	URL to call for validation
`payload`	object	No	Payload to send with the request
`expectedResponse`	object	Yes	Expected response constraints

Status Fields

Field	Type	Description
`phase`	string	Plan validity phase: `Ready` or `Invalid`
`nodeCount`	number	Total number of nodes in the graph
`conditions`	object[]	Status conditions with details
`observedGeneration`	number	Last observed spec generation

Example

yaml

apiVersion: planspec.io/v1alpha1
kind: Plan
metadata:
  name: user-auth-implementation
  namespace: default
  labels:
    component: auth
spec:
  description: Implementation plan for user authentication system
  series: user-auth
  version: "1.0.0"
  goalRef:
    name: user-authentication
  graph:
    nodes:
      - id: setup-database
        kind: Task
        name: Setup Database
        description: Create users table with required columns
        timeout: 30m
        estimatedEffort: small
        acceptanceCriteria:
          - type: command_succeeds
            name: Users table exists
            command: psql
            args: ["-c", "SELECT 1 FROM users LIMIT 1"]

      - id: implement-signup
        kind: Task
        name: Implement Signup
        description: Create signup endpoint with email validation
        dependsOn: [setup-database]
        estimatedEffort: medium
        capabilityRefs:
          - name: code-generation
        inputs:
          language: typescript
          framework: express
        outputs: [signup_endpoint, validation_logic]
        acceptanceCriteria:
          - type: endpoint_responds
            name: Signup endpoint works
            url: http://localhost:3000/api/signup
            method: POST
            expectedStatus: 201
          - type: test_passes
            name: Signup tests pass
            command: npm
            args: ["test", "--", "--grep", "signup"]

      - id: implement-login
        kind: Task
        name: Implement Login
        description: Create login endpoint with JWT generation
        dependsOn: [setup-database]
        estimatedEffort: medium
        acceptanceCriteria:
          - type: endpoint_responds
            name: Login returns JWT
            url: http://localhost:3000/api/login
            method: POST
            expectedStatus: 200

      - id: security-review
        kind: Gate
        name: Security Review
        description: Security team reviews authentication implementation
        dependsOn: [implement-signup, implement-login]
        gateRef:
          name: auth-security-review

      - id: implement-refresh
        kind: Task
        name: Implement Refresh
        description: Add refresh token endpoint
        dependsOn: [security-review]
        estimatedEffort: small
        acceptanceCriteria:
          - type: endpoint_responds
            name: Refresh endpoint works
            url: http://localhost:3000/api/refresh
            method: POST
            expectedStatus: 200

JSON Schema

The full JSON Schema is available at: Plan Schema

Next Steps

Goal - Define what the plan should achieve
Gate - Add approval checkpoints
Execution - Track plan execution state
Concepts: Acceptance Criteria - Learn about verification