What is a Plan?

A plan in PlanSpec is a declarative specification that describes work to be done, who or what should do it, and how to verify it's complete.

The Problem PlanSpec Solves

Modern software development increasingly involves coordination between:

  • Human developers
  • AI agents (like Claude)
  • Automated systems and CI/CD pipelines

Without a shared format, this coordination happens through:

  • Informal chat messages
  • Scattered documentation
  • Implicit assumptions

PlanSpec provides a single source of truth for planned work.

Core Principles

Declarative, Not Imperative

Plans describe what should be achieved, not how to achieve it. This allows flexibility in execution while maintaining clarity of intent.

yaml
# Good: Declarative
description: User authentication system
acceptanceCriteria:
  - Users can sign up with email
  - Passwords are hashed securely

# Avoid: Imperative
description: Run npm install, then create auth.js...

Inspectable

Every aspect of a plan can be examined:

  • Current status of tasks
  • Dependencies between work items
  • Acceptance criteria for completion

Composable

Plans can reference other plans, allowing complex projects to be broken into manageable pieces.

Plan vs Goal

PlanSpec distinguishes between:

  • Goal: The desired outcome or end state
  • Plan: The specific approach to achieve a goal

One goal can have multiple plans. Plans can be revised while the goal remains stable.

Next Steps