blueprint:validate

What this skill does

# Validate Blueprint Compliance

Check codebase against documented specs, patterns, anti-patterns, architectural decisions, DESIGN.md, and UX decisions using parallel sub-agents.

**Invoked by:** `/blueprint:validate`

## Principles

1. **Discover first, scan second**: Build a structural map before diving into details.
2. **Parallel sub-agents**: Launch one Task agent per validation domain — they run concurrently in the background.
3. **Severity-based**: Rank findings by impact (Critical > High > Medium > Low).
4. **Non-destructive**: Report only, never auto-fix without explicit request.

**TOOL USAGE: You MUST invoke the `AskUserQuestion` tool for scope selection if not specified.**
When you see JSON examples in this skill, they are parameters for the AskUserQuestion tool — invoke it, don't output the JSON as text.

## Process

**FIRST ACTION: Enter plan mode by calling the `EnterPlanMode` tool.**

### Step 1: Discovery

Gather repo structure and blueprint inventory in parallel. Use Glob and Read directly (not sub-agents) — this should be fast.

**1a. Blueprint inventory** (parallel Glob calls — code tree, design tree, and important adjacent design context):

Code / architecture tree:
- `docs/specs/*.md` and `docs/specs/**/*.md` — specs (tech-stack, product, boundaries, features, NFRs)
- `docs/adrs/*.md` — architecture decision records
- `patterns/bad/**/*.md` and `patterns/good/**/*.md` — documented code patterns

Important adjacent design context:
- `DESIGN.md` — top-level design context, if present; important, but not part of the Blueprint structure

Design / UX tree:
- `design/ux-decisions/*.md` — UX decisions

If no Blueprint files exist in either tree and no `DESIGN.md` exists: "No Blueprint structure found. Run `/blueprint:onboard` first." and stop. If only `DESIGN.md` exists, run a limited design-context validation and suggest `/blueprint:onboard` or `/blueprint:onboard-design` for full Blueprint coverage.

**1b. Repo structure** (parallel Glob calls):
- `**/*.md` — all markdown files (for documentation drift detection)
- `.github/workflows/*.yml` or `.gitlab-ci.yml` or `Jenkinsfile` or `bitbucket-pipelines.yml` — CI/CD
- `infra/**/*` or `terraform/**/*` or `cdk/**/*` or `pulumi/**/*` or `sst.config.*` or `Dockerfile*` or `docker-compose*` — infrastructure
- `package.json` or `requirements.txt` or `go.mod` or `Cargo.toml` or `pyproject.toml` — dependency manifests
- Top-level source directories (e.g., `src/`, `lib/`, `app/`, `functions/`, `common/`)

**1c. Read validation context**: Read all discovered spec, ADR, boundary, pattern, `DESIGN.md`, and UX decision files. `DESIGN.md` is an important adjacent repo artifact, not a Blueprint-structure file. Patterns are tree-agnostic (one `patterns/` tree for all subjects). Extract key validation rules into a structured context block:

```
=== BLUEPRINT CONTEXT ===

TECH STACK (from docs/specs/tech-stack.md):
- Runtime: [X]
- Framework: [X]
- Database: [X]
- Commands: install=[X], dev=[X], test=[X], lint=[X]

BOUNDARIES (from docs/specs/boundaries.md):
- Always: [rule1], [rule2], ...
- Never: [rule1], [rule2], ...
- Ask First: [rule1], [rule2], ...

ADR DECISIONS:
- ADR-001 [title]: Chose [X], rejected [Y, Z]
- ADR-002 [title]: Chose [X], rejected [Y, Z]
- ...

CODE PATTERNS:
- Anti-patterns: [name1: description], ...
- Good patterns: [name1: key elements], ...

FEATURES (from docs/specs/features/):
- [name] (status, maturity, module, ADRs)
- ...

UX DECISIONS (from design/ux-decisions/):
- UX-001 [title]: Chose [X], rejected [Y, Z]
- ...

DESIGN CONTEXT (from DESIGN.md, if present):
- Cross-cutting rules/prohibitions: [rule1], [rule2], ...
- Voice/tone: [rules]

=== END CONTEXT ===
```

### Step 2: Scope Selection

**Branch Detection:**
1. Run `git branch --show-current`
2. If NOT `main`/`master`, run `git diff --name-only main...HEAD 2>/dev/null || git diff --name-only master...HEAD 2>/dev/null`

**If on a feature branch with changes, use AskUserQuestion:**
```json
{
  "questions": [{
    "question": "You're on branch '[branch-name]' with [N] changed files vs main. What should I validate?",
    "header": "Scope",
    "options": [
      {"label": "Branch changes (Recommended)", "description": "Only validate files changed on this branch vs main/master"},
      {"label": "All source", "description": "Validate entire codebase excluding node_modules, dist, build"},
      {"label": "Specific directory", "description": "I'll specify a path to validate"}
    ],
    "multiSelect": false
  }]
}
```

**If on main/master or no branch changes:**
```json
{
  "questions": [{
    "question": "What should I validate?",
    "header": "Scope",
    "options": [
      {"label": "All source (Recommended)", "description": "Validate entire codebase excluding node_modules, dist, build"},
      {"label": "Recent changes", "description": "Only files modified in last commit or uncommitted"},
      {"label": "Specific directory", "description": "I'll specify a path to validate"}
    ],
    "multiSelect": false
  }]
}
```

### Step 3: Launch Parallel Sub-Agents

Based on discovery results, launch **one Task agent per validation domain** — all in a **single message** so they run concurrently. Use `subagent_type: "Explore"` and `run_in_background: true` for each.

Every agent prompt MUST include:
1. The full **Blueprint Context** block from Step 1c
2. The **scope** (file list or directory) from Step 2
3. Domain-specific scan instructions (below)
4. Instruction to return findings as a structured list with severity, location, description, and blueprint source

#### Agent: Source Code

**Launch when:** Source directories exist.

Prompt must instruct the agent to:
1. **Tech stack compliance**: Read dependency manifests, compare against declared tech stack. Flag undeclared dependencies, missing declared tech, version mismatches.
2. **Boundary violations**: For each "Never Do" rule, Grep source files for violations. For "Always Do" rules, verify compliance. For "Ask First" items, warn if detected.
3. **Anti-pattern scan**: For each documented anti-pattern, Grep source files for matching code.
4. **ADR compliance**: For each ADR's chosen approach, verify source follows it. For rejected alternatives, Grep for their usage.
5. **Undocumented patterns**: Note consistent code patterns (repeated 3+ times) not captured in `patterns/good/`.

#### Agent: Features

**Launch when:** `docs/specs/features/*.md` exist.

Prompt must instruct the agent to:
1. For each feature spec, verify declared module path exists.
2. Check for test files in each feature's module.
3. Verify status matches reality (Active features should have code, Deprecated should not be actively developed).
4. Verify maturity matches reality:
   - `Exploring` with substantial code and tests → suggest advancing to Building/Hardening
   - `Stable` with many open TODOs or missing tests → flag as inconsistent
   - Missing `maturity` field → flag as needing update
5. Check Implementation State section:
   - Missing entirely → flag (Medium severity)
   - Has stale "Current focus" that doesn't match recent git activity → flag (Low severity)
   - Has open questions that appear resolved in code → flag (Low severity)
6. Flag orphaned modules — source directories with no corresponding feature spec.
7. Verify related ADRs referenced by features are still Active.

#### Agent: Documentation Drift & Content Classification

**Launch when:** Markdown files exist outside `docs/specs/`, `docs/adrs/`, `patterns/`, `design/` **OR** any Blueprint files or `DESIGN.md` exist.

Prompt must instruct the agent to:
1. Find all `.md` files outside the Blueprint structure (CLAUDE.md, README.md, guides, `.claude/*.md`, etc.). Treat `DESIGN.md` as an important adjacent design-context file, not as stray documentation.
2. Cross-reference against tech stack: Grep for superseded/banned alternatives (e.g., `npm install` when ADR chose Bun).
3. Cross-reference against ADR decisions: Grep for rejected alternatives b