plan-validate

name	plan-validate
description	Deterministic plan.json validation via Python script, replacing most plan-validator agent calls. Performs JSON parsing, schema validation, task checkbox regex, required section checks, sync validation, and data extraction. Only semantic consistency checks (storage/query alignment) require the LLM agent. Triggers on: plan validation, checking plan format, extracting plan data. Returns PLAN_VALID with extracted data or PLAN_FORMAT_ISSUES with issues list.
context	fork
allowed-tools	Bash

Plan Validate

Deterministic plan.json validation that replaces the plan-validator Sonnet agent for all structural checks. The semantic consistency check (storage/query alignment, task/architecture contradictions) still requires the LLM agent and should be run separately when needed.

When to Use

Activate this skill instead of launching @code:plan-validator at every plan validation site. The orchestrator should only launch the full plan-validator agent for semantic-only checks after plan creation or modification phases.

Usage

Run the validation script:

python3 ${CLAUDE_SKILL_DIR}/scripts/validate_plan.py <WORKDIR> --auto-sync

The --auto-sync flag detects questions answered in the markdown content that are still in the openQuestions JSON array, extracts the answer text, and moves them to answeredQuestions before validation — writing the updated plan.json back to disk.

Three answer formats are supported:

1. Inline with prefix — **Answer: text**, *Answer: text*, or plain Answer: text on the question line.
2. A-### keyed answer — a separate A-001: answer text line corresponding to Q-001.
3. Inline comment — extra text appended after the known question text on the question line, without any Answer: prefix. Metadata markers like (BLOCKING T-X.Y) and [Recommended: ...] are stripped.

The question checkbox does not need to be checked for any format. When a question is migrated from an unchecked [ ] line, the script checks it automatically.

If none of these yield answer text, falls back to the recommendedAnswer field from the JSON entry. Questions with no extractable answer are left in openQuestions.

Always pass --auto-sync so that users can answer questions by editing the markdown directly.

Interpreting Output

The script prints JSON to stdout matching the exact plan-validator output format.

Plan Valid (PLAN_VALID)

{
  "status": "VALID",
  "issues": [],
  "has_unanswered_questions": false,
  "unanswered_questions": [],
  "has_answered_questions": false,
  "answered_questions": [],
  "has_addressed_gaps": false,
  "addressed_gaps": [],
  "pending_tasks": [{"id": "T-1.1", "description": "...", "acceptanceCriteria": ["AC-001"]}],
  "completed_tasks": [],
  "manual_tasks": [],
  "decision_table_path": ".closedloop-ai/decision-tables/pln-001.md",
  "decision_table_status": "pending"
}

Action: Parse the extracted data fields. Use pending_tasks, completed_tasks, etc. as if the plan-validator agent returned them. The decision_table_path and decision_table_status keys are always present — they are empty strings ("") when the plan does not yet reference a decision-table artifact.

Plan Format Issues (PLAN_FORMAT_ISSUES)

{
  "status": "FORMAT_ISSUES",
  "issues": ["Missing required field: openQuestions", "Task missing checkbox in content: '- **T-1.2**: ...'"],
  ...
}

Action: Handle the same way as plan-validator FORMAT_ISSUES — launch fix subagents as appropriate.

Other Statuses

• EMPTY_FILE: plan.json doesn't exist or is empty
• INVALID_JSON: plan.json contains malformed JSON

What This Script Validates

1. JSON parsing — file exists, is valid JSON, root is an object
2. Schema fields — required top-level fields present with correct types, ID pattern validation
3. Task checkboxes — every **T-X.Y** line has - [ ] or - [x] prefix
4. Required sections — all 10 required ## headers present in content
5. Sync validation — pendingTasks/completedTasks/manualTasks/openQuestions/answeredQuestions arrays match markdown content lines

What Still Requires the LLM Agent

Semantic consistency validation (Step 6 in plan-validator):

• Cross-referencing storage definitions with query operations
• Verifying tasks don't contradict Architecture Decisions table
• Checking data flow consistency

Only run the plan-validator agent with semantic-only focus after phases that modify the plan content (Phase 1 creation, Phase 2.6 critic merge, Phase 2.7 finalization).