validate-plan-file

star 2

Validate that orchestrator plan files conform to expected JSON schema. Use before workers read plan files or after orchestrators create them to ensure proper structure and required fields.

maslennikov-ig By maslennikov-ig schedule Updated 2/3/2026
play_arrow Run Skill in Manus View GitHub

name: validate-plan-file description: Validate that orchestrator plan files conform to expected JSON schema. Use before workers read plan files or after orchestrators create them to ensure proper structure and required fields. allowed-tools: Read

Validate Plan File

Validate orchestrator plan files to ensure they conform to the expected schema before workers process them.

When to Use

  • Before workers read plan files
  • After orchestrators create plan files
  • When debugging plan file issues
  • In quality gates validation

Instructions

Step 1: Read Plan File

Use Read tool to load the plan file.

Expected Input:

  • file_path: Path to plan file (e.g., .bug-detection-plan.json, .security-scan-plan.json)

Tools Used: Read

Step 2: Determine Schema

Map file name pattern to appropriate JSON schema.

Schema Mapping:

  • .bug-*-plan.json → .claude/schemas/bug-plan.schema.json
  • .security-*-plan.json → .claude/schemas/security-plan.schema.json
  • .dead-code-*-plan.json → .claude/schemas/dead-code-plan.schema.json
  • .dependency-*-plan.json → .claude/schemas/dependency-plan.schema.json
  • .version-*-plan.json → base schema (version update workflow)

New Naming Convention (standardized):

  • Bug workflow: .bug-detection-plan.json, .bug-fixing-plan.json, .bug-verification-plan.json
  • Security workflow: .security-scan-plan.json, .security-remediation-plan.json, .security-verification-plan.json
  • Dead code workflow: .dead-code-detection-plan.json, .dead-code-cleanup-plan.json, .dead-code-verification-plan.json
  • Dependency workflow: .dependency-audit-plan.json, .dependency-update-plan.json, .dependency-verification-plan.json

Step 3: Load and Parse JSON Schema

Use Read tool to load the appropriate schema file from .claude/schemas/.

Tools Used: Read

Step 4: Validate JSON Against Schema

Validate the plan file content against the loaded JSON schema.

Base Schema Validation (all plan files):

  • workflow: String (required, e.g., "bug-management", "security-audit")
  • phase: String (required, e.g., "detection", "fixing", "verification")
  • phaseNumber: Integer (optional, for sequencing)
  • config: Object (required, domain-specific configuration)
  • validation: Object (required, with required array of validation criteria)
  • nextAgent: String (optional, agent to invoke next)
  • timestamp: String (optional, ISO-8601 format)
  • metadata: Object (optional, with createdBy, iteration, maxIterations)

Domain-Specific Validation:

Bug Plans:

  • config.priority: "critical"|"high"|"medium"|"low"|"all" (required)
  • config.categories: Array of bug types (optional)
  • config.maxBugsPerRun: Integer (optional, default 50)
  • config.verifyOnly: Boolean (optional, default false)

Security Plans:

  • config.severity: "critical"|"high"|"medium"|"low"|"all" (required)
  • config.categories: Array of vulnerability types (optional)
  • config.maxVulnsPerRun: Integer (optional, default 25)
  • config.skipSupabaseRLS: Boolean (optional, default false)

Dead Code Plans:

  • config.type: "critical"|"high"|"medium"|"low"|"all" (required)
  • config.categories: Array of dead code types (optional)
  • config.maxItemsPerRun: Integer (optional, default 100)
  • config.safeMode: Boolean (optional, default true)

Dependency Plans:

  • config.category: "security"|"unused"|"outdated"|"all" (required)
  • config.severity: "critical"|"high"|"medium"|"low"|"all" (optional)
  • config.maxUpdatesPerRun: Integer (optional, default 10)
  • config.updateStrategy: "one-at-a-time"|"batch-compatible"|"all" (optional)

Step 5: Return Validation Result

Return detailed validation result with errors/warnings.

Expected Output:

{
  "valid": true,
  "file": ".bug-detection-plan.json",
  "errors": [],
  "warnings": [],
  "schema": "bug-plan",
  "schemaPath": ".claude/schemas/bug-plan.schema.json"
}

Error Handling

  • File Not Found: Return error with file path
  • Invalid JSON: Return parsing error with line number if possible
  • Schema File Not Found: Return error if schema file missing
  • Missing Required Fields: List all missing fields from JSON schema validation
  • Invalid Field Types: Describe type mismatches (e.g., expected string, got number)
  • Invalid Enum Values: Report when value not in allowed enum list
  • Schema Mismatch: Warn if file doesn't match expected schema pattern
  • Validation Array Errors: Report missing or invalid validation criteria

Examples

Example 1: Valid Bug Detection Plan

Input:

file_path: .bug-detection-plan.json

Content:

{
  "workflow": "bug-management",
  "phase": "detection",
  "phaseNumber": 1,
  "config": {
    "priority": "all",
    "categories": ["type-errors", "runtime-errors"],
    "maxBugsPerRun": 50
  },
  "validation": {
    "required": ["report-exists", "type-check"],
    "optional": ["tests"]
  },
  "nextAgent": "bug-hunter",
  "timestamp": "2025-10-18T14:00:00Z",
  "metadata": {
    "createdBy": "bug-orchestrator",
    "iteration": 1,
    "maxIterations": 3
  }
}

Output:

{
  "valid": true,
  "file": ".bug-detection-plan.json",
  "errors": [],
  "warnings": [],
  "schema": "bug-plan",
  "schemaPath": ".claude/schemas/bug-plan.schema.json"
}

Example 2: Missing Required Field

Input:

file_path: .security-scan-plan.json

Content:

{
  "workflow": "security-audit",
  "phase": "scan",
  "config": {
    "categories": ["sql-injection"]
  },
  "validation": {
    "required": ["report-exists"]
  }
}

Output:

{
  "valid": false,
  "file": ".security-scan-plan.json",
  "errors": [
    "Missing required property: config.severity",
    "Schema validation failed at /config/severity: required property missing"
  ],
  "warnings": [],
  "schema": "security-plan",
  "schemaPath": ".claude/schemas/security-plan.schema.json"
}

Example 3: Invalid Enum Value

Input:

file_path: .dependency-audit-plan.json

Content:

{
  "workflow": "dependency-management",
  "phase": "audit",
  "config": {
    "category": "deprecated",
    "severity": "critical"
  },
  "validation": {
    "required": ["report-exists", "lockfile-valid"]
  },
  "nextAgent": "dependency-auditor"
}

Output:

{
  "valid": false,
  "file": ".dependency-audit-plan.json",
  "errors": [
    "Invalid enum value at /config/category: 'deprecated' not in allowed values ['security', 'unused', 'outdated', 'all']"
  ],
  "warnings": [],
  "schema": "dependency-plan",
  "schemaPath": ".claude/schemas/dependency-plan.schema.json"
}

Example 4: Workflow/Phase Mismatch

Input:

file_path: .bug-fixing-plan.json

Content:

{
  "workflow": "security-audit",
  "phase": "fixing",
  "config": {
    "priority": "critical"
  },
  "validation": {
    "required": ["type-check"]
  }
}

Output:

{
  "valid": false,
  "file": ".bug-fixing-plan.json",
  "errors": [
    "Schema mismatch: file pattern suggests 'bug-plan' schema but workflow field is 'security-audit'",
    "Invalid enum value at /phase: 'fixing' not in allowed values ['detection', 'fixing', 'verification'] for bug-plan"
  ],
  "warnings": ["Consider renaming file to match workflow: .security-remediation-plan.json"],
  "schema": "bug-plan",
  "schemaPath": ".claude/schemas/bug-plan.schema.json"
}

Validation

  • Validates all required fields present
  • Checks field types correctly (string, number, boolean, array, object)
  • Validates enum values against allowed lists
  • Identifies schema based on file name pattern
  • Returns clear error messages with JSON paths
  • Handles malformed JSON gracefully
  • Validates domain-specific fields (priority, severity, category)
  • Checks workflow/phase consistency
  • Validates validation criteria arrays (required/optional)
  • Handles schema file loading errors

Supporting Files

Located in .claude/schemas/:

  • base-plan.schema.json: Base schema for all plan files
  • bug-plan.schema.json: Bug management workflow schema
  • security-plan.schema.json: Security audit workflow schema
  • dead-code-plan.schema.json: Dead code cleanup workflow schema
  • dependency-plan.schema.json: Dependency management workflow schema

Integration with Orchestrators

All orchestrators should use this Skill after creating plan files:

## Step 3: Create Plan File

1. Write plan to `.{domain}-{phase}-plan.json`
2. Use validate-plan-file Skill to verify:
   - Input: file_path = ".{domain}-{phase}-plan.json"
   - Check result.valid === true
   - If errors exist, fix plan file and retry
3. Only signal readiness after validation passes

Notes

JSON Schema Validation: This Skill performs full JSON Schema Draft-07 validation including:

  • Type checking (string, number, boolean, array, object)
  • Required properties
  • Enum constraints
  • Pattern matching
  • Nested object validation (allOf, $ref)
  • Array item validation

File Naming Convention: Plan files must follow pattern .{domain}-{phase}-plan.json where:

  • {domain}: bug|security|dead-code|dependency
  • {phase}: detection|fixing|verification (bugs), scan|remediation|verification (security), etc.

Schema References: Uses JSON Schema $ref for base schema inheritance. All domain schemas extend base-plan.schema.json.

Install via CLI
npx skills add https://github.com/maslennikov-ig/BuhBot --skill validate-plan-file
Repository Details
star Stars 2
call_split Forks 0
navigation Branch main
article Path SKILL.md
More from Creator
maslennikov-ig
maslennikov-ig Explore all skills →