Quick Start

Get started with PlanSpec using Claude Code.

Prerequisites

1. Install PlanSpec CLI

Download the latest release for your platform from GitHub Releases.

bash
curl -fsSL https://github.com/exponential-build/planspec/releases/download/v0.1.0/planspec-darwin-aarch64.tar.gz | tar xz
sudo mv planspec /usr/local/bin/

Verify the installation:

bash
planspec --version

2. Install the Claude Code Skill

Download and install the /planspec skill from GitHub Releases:

Install globally to use in all projects:

bash
curl -fsSL https://github.com/exponential-build/planspec/releases/download/v0.1.0/planspec-claude-code-skill-0.1.0.tar.gz | tar xz
mkdir -p ~/.claude/skills
mv planspec ~/.claude/skills/

3. Create a Plan with Claude

Now you can use the /planspec skill in Claude Code. Start by describing what you want to accomplish:

/planspec plan "Build a REST API with user authentication"

Claude will generate a Goal and Plan with tasks, dependencies, and acceptance criteria.

Review the Plan

Claude shows you the generated plan. You can ask for changes or validate it:

/planspec validate

Execute the Plan

Once you're happy with the plan, execute it:

/planspec implement

Claude works through tasks in dependency order, checking acceptance criteria as it goes.

Example Plan

Here's what a simple plan looks like:

yaml
apiVersion: planspec.io/v1alpha1
kind: Goal
metadata:
  name: hello-world
  namespace: default
spec:
  description: Build a simple hello world application
  acceptanceCriteria:
    - description: Application prints "Hello, World!" when run
---
apiVersion: planspec.io/v1alpha1
kind: Plan
metadata:
  name: hello-world-plan
  namespace: default
spec:
  description: Implementation plan for hello world
  goalRef:
    name: hello-world
  graph:
    nodes:
      - id: create-app
        kind: Task
        description: Create the main application file
        acceptanceCriteria:
          - type: artifact_exists
            name: Main file exists
            path: src/main.py
      - id: add-docs
        kind: Task
        description: Add documentation
        dependsOn: [create-app]
        acceptanceCriteria:
          - type: artifact_exists
            name: README exists
            path: README.md

Validate Manually

You can also validate plans directly with the CLI:

bash
planspec validate --file plan.yaml

Try the Playground to experiment with PlanSpec schemas interactively.

Next Steps