plan-validate

name	plan-validate
description	Validate plan document structure and frontmatter. Use when checking plans for compliance, ensuring proper formatting, or verifying metadata before commits.
allowed-tools	Read, Bash(bash *)
context	fork
agent	design-doc-agent

Plan Validation

Validates plan documentation files for structure, frontmatter, and quality compliance.

Overview

This skill validates plan documents by:

1. Reading the plan configuration from design.config.json
2. Finding plan files for validation
3. Validating YAML frontmatter structure and values
4. Checking required fields and data types
5. Validating status-progress alignment
6. Validating dates and field relationships
7. Reporting issues with actionable recommendations

Quick Start

Validate specific plan:

/design-docs:plan-validate plan-design-linking-phase-1

Validate all plans:

/design-docs:plan-validate --all

Validate with strict mode:

/design-docs:plan-validate plan-design-linking-phase-1 --strict

How It Works

1. Parse Parameters

• plan-name: Plan name/ID to validate (or --all for all plans) [REQUIRED]
• --strict: Enable strict mode with additional quality checks
• --fix: Auto-fix issues when possible

2. Load Configuration

Read .claude/design/design.config.json to get:

• Plan paths and directories
• Quality standards for plans
• Required frontmatter fields
• Valid status values
• Progress range limits

The canonical JSON schema for plan frontmatter is published at https://raw.githubusercontent.com/spencerbeggs/design-docs-plugin/main/plan-frontmatter.schema.json — fetch it when a machine-checkable definition of the frontmatter contract is needed.

3. Locate Plan File

Use the plan name to find the file:

• Check .claude/plans/{plan-name}.md
• If not found, check .claude/plans/_archive/{plan-name}.md
• Report error if file doesn't exist

4. Validate Plan Document

Execute scripts/validate-plan.sh (co-located with this skill) which checks:

Required Fields:

• name (kebab-case format)
• title (non-empty string)
• created (YYYY-MM-DD format)
• status (valid enum value)
• progress (0-100 integer)

Status Values:

• ready
• in-progress
• blocked
• completed
• abandoned

Status-Progress Alignment:

• ready: progress must be 0%
• in-progress/blocked: progress 1-99%
• completed: progress must be 100%

Date Validation:

• All dates in YYYY-MM-DD format
• created ≤ updated
• started ≤ completed (if both present)

Completion Requirements:

• Status completed: requires completed date and outcome
• Status abandoned: requires completed date and archival-reason

Optional Field Validation:

• modules: must exist in design.config.json
• implements: paths must point to existing design docs
• phases: each phase has required fields (name, status, progress)

5. Generate Report

Output validation results:

Success:

✓ Plan validation passed: plan-design-linking-phase-1
  ✓ All required fields present
  ✓ Status-progress aligned (ready, 0%)
  ✓ Dates valid and in order
  ✓ No issues found

Failure:

✗ Plan validation failed: plan-design-linking-phase-1

Errors (3):
  ✗ Missing required field: status
  ✗ progress: 150 (must be integer 0-100)
  ✗ Status 'completed' requires 'outcome' field

Warnings (1):
  ⚠ Status 'ready' should have progress 0%, found 25%

Usage Patterns

Validate Before Commit

# Check plan before committing
/design-docs:plan-validate my-feature-plan

Validate All Plans

# Check entire plan directory
/design-docs:plan-validate --all

Fix Common Issues

# Auto-fix when possible (updates dates, formats fields)
/design-docs:plan-validate my-feature-plan --fix

Strict Validation

# Additional quality checks
/design-docs:plan-validate my-feature-plan --strict

Strict mode adds:

• Check for stale plans (no updates >30 days)
• Verify bidirectional links to design docs
• Check for orphaned plans (no implements field)
• Validate estimated vs actual effort alignment

Implementation Steps

1. Parse arguments from user input (plan name, flags)
2. Read config from .claude/design/design.config.json
3. Locate plan file in .claude/plans/ or _archive/
4. Execute validation script scripts/validate-plan.sh
5. Parse script output to extract errors/warnings
6. Check additional rules if strict mode enabled
7. Generate report with colored output and recommendations
8. Return exit code (0 = pass, 1 = fail)

Error Messages

Missing Required Fields

✗ Missing required field: {field}

Fix: Add '{field}: value' to the plan frontmatter

Invalid Status Value

✗ status: '{value}' (must be one of: ready, in-progress, blocked,
  completed, abandoned)

Fix: Change status to a valid value

Status-Progress Mismatch

⚠ Status 'ready' should have progress 0%, found {value}%

Fix: Either set progress to 0 or change status to 'in-progress'

Invalid Date Format

✗ {field}: {value} (must be YYYY-MM-DD)

Fix: Use format YYYY-MM-DD (e.g., 2026-01-18)

Missing Completion Fields

✗ Status 'completed' requires 'outcome' field

Fix: Add 'outcome: success|partial|failed' to frontmatter

Examples

See examples.md for detailed usage examples.

Related Skills

• design-docs:plan-create - Create new plans
• design-docs:plan-complete - Complete a plan and persist knowledge to design docs
• design-docs:plan-list - List all plans
• design-docs:design-validate - Validate design docs