Claude Integration

PlanSpec integrates with Claude Code via the /planspec skill, enabling AI-assisted plan creation and execution.

Overview

The /planspec skill provides commands for:

  • Creating plans from natural language task descriptions
  • Converting markdown plans to PlanSpec resources
  • Executing plans with automatic progress tracking
  • Validating plan files
  • Visualizing plan dependencies

Setup

1. Install the Skill

Copy the planspec skill to your project:

bash
cp -r ~/.claude/skills/planspec .claude/skills/

Or to your global skills directory:

bash
mkdir -p ~/.claude/skills
cp -r /path/to/planspec ~/.claude/skills/

2. Start the Server

Most commands require the PlanSpec server to be running:

bash
planspec serve

3. Configure Environment (Optional)

Set environment variables to customize behavior:

bash
# Server URL (default: http://localhost:8080)
export PLANSPEC_SERVER=http://localhost:8080

# Default namespace (default: default)
export PLANSPEC_NAMESPACE=default

Available Commands

CommandDescriptionServer Required
/planspec setupInstall CLI, create directories, set environmentNo
/planspec validate [file]Validate plan resources offlineNo
/planspec server [start|stop|status]Manage the planspec serverN/A
/planspec plan <task>Create a Goal + Plan for a task descriptionYes
/planspec convert [file]Convert markdown plan to PlanSpec formatNo (create), Yes (apply)
/planspec implement <plan>Execute a plan with progress trackingYes
/planspec status [plan]Show execution statusYes
/planspec graph <plan>Visualize plan as a dependency graphYes

Workflow Example

1. Create a Plan

Start by describing what you want to accomplish:

/planspec plan "Add user authentication with JWT tokens"

This creates a Goal resource describing the objective and a Plan resource with tasks.

2. Review and Refine

Claude will show you the generated plan. You can refine it before applying:

/planspec validate auth-plan-v1

3. Execute the Plan

Begin implementation with automatic progress tracking:

/planspec implement auth-plan-v1

Claude works through tasks in dependency order, updating status as work completes.

4. Check Progress

Monitor execution status at any time:

/planspec status auth-plan-v1

Best Practices

Clear Acceptance Criteria

Help Claude verify task completion:

yaml
acceptanceCriteria:
  - File `src/auth.ts` exports `login` function
  - Function accepts email and password parameters
  - Returns a Promise<User>

Appropriate Task Granularity

Tasks should be:

  • Small enough to complete in one session
  • Large enough to be meaningful
  • Clear about what "done" means

Use Gates for Review Points

yaml
kind: Gate
metadata:
  name: code-review
spec:
  description: Human review required
  criteria:
    - Code reviewed by team member

Claude will pause at gates and request human review before continuing.

Troubleshooting

Server Not Responding

Ensure the server is running on the correct port:

bash
curl http://localhost:8080/health

If using a custom port, verify your PLANSPEC_SERVER environment variable.

Validation Errors

Validate your plan file with the correct syntax:

bash
planspec validate -f plan.yaml

Skill Not Found

Ensure the skill is installed in either:

  • Project: .claude/skills/planspec/
  • Global: ~/.claude/skills/planspec/

Next Steps