# Plan Pipeline 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.

- Skill: `gabrielmoreira/plan-pipeline-validate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/plan-pipeline-validate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/plan-pipeline-validate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/plan-pipeline-validate

---


# /plan-pipeline:validate: 2-Layer Validation

Independently validate the plan produced by `/plan-pipeline:start`. No code is written. Run `/clear` after this command before running `/plan-pipeline: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-pipeline: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 `Read` on `.claude/tasks/<id>/output.log` (TaskOutput is deprecated since v2.1.83). 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`:

```json
{
  "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"
}
```

---

## Auto-Transition

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

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

---

## Usage

```
/plan-pipeline:validate
```

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

```
/plan-pipeline: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-pipeline:execute
```

## When to Use

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

## Pipeline Position

```
/plan-pipeline:ceo-review    → product direction locked
/plan-pipeline:eng-review    → architecture locked
/plan-pipeline:start         → produce implementation plan
/plan-pipeline:validate      → validate before execution     ← you are here
/plan-pipeline:execute       → execute to merged PR
```