claude-code-ultimate-guide/examples/commands/plan-validate.md

name	description
plan-validate	2-layer plan validation: instant structural checks + trigger-based specialist agents. Auto-fixes issues using ADRs and first principles. Every issue must be resolved before execution.

Plan Validate — 2-Layer Validation

Independently validate the plan produced by /plan-start. No code is written. Run /clear after this command before running /plan-execute.

Validation is separate from planning by design: validators that didn't write the plan are not anchored to its assumptions.

---

Prerequisite

A committed plan file must exist at docs/plans/plan-{name}.md. If multiple plans exist, list them and ask the user which to validate.

---

Layer 1: Structural Validation

Run immediately, no agents required. Check the plan document for:

Format & Completeness

• All required sections present (Summary, Decisions, Architecture, Tasks, Test Plan, Out of Scope)
• Each task has: description, files affected, acceptance criteria, layer assignment

Dependency Chain

• No circular dependencies between tasks
• Tasks in higher layers only depend on tasks in lower layers
• All stated dependencies exist in the plan

File Existence

• Every file listed for modification actually exists in the codebase (use Glob)
• New files are in appropriate directories per project conventions

ADR Consistency

• Plan decisions align with ADRs created during /plan-start
• No contradiction with existing ADRs in docs/adr/

CLAUDE.md Compliance

• Plan respects all hard rules in CLAUDE.md
• No first principles violations (no workarounds, no backward-compat shims)

Test Coverage

• Every new function/component has a corresponding test task
• TDD-marked tasks have failing test written before implementation task

Record all Layer 1 issues with severity (BLOCKER / WARNING / INFO) before proceeding to Layer 2.

---

Layer 2: Specialist Review

Select agents by applying trigger rules to the plan content. No user input needed — triggers are objective.

Validation agent pool:

Agent	Trigger	Model
security-reviewer	Auth, payments, PII, RBAC, new public APIs	Opus
db-migration-reviewer	New tables, columns, indexes, or migration files	Opus
performance-reviewer	New queries, resolvers, routes, or added dependencies	Sonnet
design-system-reviewer	New UI components or visual styling changes	Sonnet
ux-reviewer	New pages, forms, modals, or interaction patterns	Sonnet
cross-platform-reviewer	Changes touching both web and mobile, or shared packages	Sonnet
native-app-reviewer	Mobile screens, native UI package changes	Sonnet
integration-reviewer	New external services, libraries, or OTEL config	Opus

Spawn triggered agents in parallel (Task tool, run_in_background: true). Each agent receives: the plan file, relevant ADRs, and targeted questions based on its domain.

Monitor via TaskOutput polling loop. Report progress to user.

Each agent must return structured findings:

FINDING: [BLOCKER|WARNING|INFO]
Location: [plan section or file reference]
Issue: [concrete description]
Risk: [what breaks if this isn't addressed]
Suggestion: [specific fix or alternative]

---

Auto-Fix Phase

Merge Layer 1 structural issues + Layer 2 specialist findings into a single issue list. Every issue must be resolved. No skipping.

Triage each issue:

Bucket A — Auto-resolve:

• Issue matches an existing ADR decision → cite ADR, mark resolved
• Issue matches a confirmed pattern in PATTERNS.md → cite pattern, mark resolved
• Issue resolvable from first principles in CLAUDE.md → apply rule, mark resolved

Bucket B — Needs human input:

• Novel architectural question not covered by existing decisions
• Conflicting ADRs with no clear precedent
• Blocker with no obvious resolution

For Bucket B items: present the issue, explain why it can't be auto-resolved, propose options, wait for decision. Record the decision in the plan's ## Decisions section and create a new ADR if it's architecturally significant.

Apply all fixes in one batch once all issues are triaged. Update the plan file. Commit the updated plan.

---

Issue Persistence

Record every issue in docs/plans/metrics/{name}.json under validation.issues:

{
  "id": "S-001",
  "layer": 1,
  "severity": "WARNING",
  "category": "test-coverage",
  "description": "No test task for the new webhook handler",
  "reporting_agent": "structural",
  "triage": "A",
  "resolution_source": "first-principles",
  "resolution": "Added test task in Layer 2 of the plan"
}

This data feeds /plan-metrics for pattern analysis over time.

---

Auto-Transition

If all issues are auto-resolved (Bucket A only): auto-start /plan-execute without asking.

If any human input was required (Bucket B): ask "All issues resolved. Ready to execute?" before proceeding.

---

Usage

/plan-validate

Picks up the most recent uncommitted plan automatically. Or specify:

/plan-validate plan-user-authentication

Output

Layer 1: Structural validation...
  ✓ Format complete
  ✓ Dependencies valid
  ⚠ WARNING S-001: Missing test task for webhook handler
  ✓ CLAUDE.md compliant

Layer 2: Triggering specialist agents...
  → security-reviewer (auth changes detected) [Opus]
  → db-migration-reviewer (new users table) [Opus]
  → performance-reviewer (new query in /api/users) [Sonnet]
  Monitoring... 1/3 complete... 2/3 complete... done.

  BLOCKER B-001 [security-reviewer]: JWT expiry not validated on refresh endpoint
  WARNING B-002 [db-migration-reviewer]: Migration lacks rollback strategy

Auto-fix phase:
  S-001 → auto-resolved (first principles: test coverage rule)
  B-001 → NEEDS INPUT (no existing ADR for JWT refresh strategy)
  B-002 → auto-resolved (ADR-0003: migration rollback pattern)

[User input requested for B-001]
Decision recorded. ADR-0011 created.

All 3 issues resolved. Plan updated.
→ Auto-starting /plan-execute

When to Use

Always — before any /plan-execute call. The cost of validation ($0.20-3.00) is negligible against the cost of discovering issues mid-execution.

See Also

• Plan-Validate-Execute Pipeline
• Integration Reviewer Agent
• Plan Challenger Agent