PlanSpec

Open source infrastructure for declarative work orchestration

Overview

PlanSpec provides a Kubernetes-inspired control plane for expressing goals, plans, and executions. It defines the core resource contracts for orchestrating work across humans and AI agents.

PlanSpec is intentionally minimal and implementation-agnostic. It defines the contracts; implementations may build richer features (knowledge graphs, retrieval, learning) on top.

Core Primitives

Key Principles

• Declarative over imperative: Describe what you want, not how to get there
• Plan is the durable artifact: Nodes are embedded in Plan.spec.graph, not separate resources
• Late binding: Capabilities resolved at execution time via Bindings
• Immutable intent: Execution.spec is immutable; Execution.status tracks runs
• Reconciliation-driven: Controllers continuously drive toward desired state

Quick Start

Installation

# Build from source
cd cli
cargo build --release

# Or install directly
cargo install --path cli

Validate a Specification

planspec validate -f goal.yaml

Apply Resources

planspec apply -f goal.yaml

Watch Executions

planspec watch executions

Visualize a Plan

planspec graph sso-implementation-v2

Example

Goal

apiVersion: planspec.io/v1alpha1
kind: Goal
metadata:
  name: enable-google-sso
  namespace: team-platform
spec:
  description: "Enable Google SSO for the application"
  constraints:
    frontend: react
    idp: google
  acceptanceCriteria:
    - description: "Users can sign in with Google"
    - description: "Existing sessions remain valid"
  planSelector:
    matchLabels:
      planspec.io/goal: enable-google-sso
  timeout: "7d"
  priority: 10

Plan

apiVersion: planspec.io/v1alpha1
kind: Plan
metadata:
  name: sso-implementation-v2
  namespace: team-platform
  labels:
    planspec.io/goal: enable-google-sso
    planspec.io/series: sso
    planspec.io/version: "2"
spec:
  goalRef:
    name: enable-google-sso
  series: sso
  version: "2"
  description: "Implementation plan for Google SSO"
  graph:
    nodes:
      - id: research
        kind: Task
        description: "Research OAuth2/OIDC requirements"
        capabilityRefs:
          - name: code-analysis
      - id: implement
        kind: Task
        description: "Implement SSO flow"
        capabilityRefs:
          - name: code-generation
        inputs:
          framework: react
        timeout: "4h"
        retries: 2
      - id: review
        kind: Gate
        description: "Security review checkpoint"
        gateRef:
          name: sso-security-review
    edges:
      - from: research
        to: implement
      - from: implement
        to: review

Execution

apiVersion: planspec.io/v1alpha1
kind: Execution
metadata:
  name: sso-exec-001
  namespace: team-platform
spec:
  goalRef:
    name: enable-google-sso
  planRef:
    name: sso-implementation-v2
  bindingRef:
    name: platform-bindings
  parameters:
    dryRun: false
    priority: high

Documentation

• SPECIFICATION.md - Formal definitions of all primitives
• ARCHITECTURE.md - System design and reconciliation model
• CONTRIBUTING.md - Development setup and contribution guidelines
• Examples - Sample specifications for common scenarios

Project Structure

planspec/
├── api/openapi/          # OpenAPI specification
├── cli/                  # Rust CLI tool
├── docs/examples/        # Example specifications
└── schemas/              # JSON Schema definitions
    ├── common/           # Shared schemas (metadata, status, graph)
    └── v1alpha1/         # Version-specific resource schemas

API Version

PlanSpec follows Kubernetes API versioning conventions:

• v1alpha1 - Current version, breaking changes expected
• v1beta1 - (Future) More stable, deprecation policy applies
• v1 - (Future) Stable, backwards-compatible changes only

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

© 2026 Exponential Build, Inc.