Skip to main content
skill CX Codex

validation · josstei — Claude Code skill: project checks and installation

The validation skill runs build, lint, and test checks, then classifies the results. Use it to validate orchestration phases or review a focused set of changes.

Apache-2.0 ★ 489 updated 2026-10-26

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add josstei/maestro-orchestrate --skill validation -a claude-code
Open on GitHub

What validation does

The skill identifies project types from files such as package.json, Cargo.toml, and pyproject.toml, then selects matching build, style, and test commands. Checks run in sequence; a blocking failure stops the pipeline. It also looks for integration tests and prepares a manual checklist when a change cannot be verified automatically.

Set MAESTRO_VALIDATION_STRICTNESS to strict, normal, or lenient to control how results affect phase progression. The default is normal: warnings are recorded, while blocking failures stop progress. In strict mode warnings also block; lenient records results and continues. This setting changes whether a warning can prevent a phase from completing.

The skill can narrow its checks based on the files changed. New files receive targeted lint and type checks, existing-file changes trigger the test suite, and configuration changes run the full pipeline. Documentation-only work and read-only analysis are skipped under the stated conditions, with a rationale recorded.

What it helps with

  • check whether a project builds after code changes
  • run project-specific lint and formatting commands
  • catch regressions with unit and integration tests
  • choose validation scope from the files changed
  • create a manual checklist for UI or external-service changes

Example prompts for the agent

  • Validate the project changes and stop at the first blocking failure.
  • Run checks for the changed files and explain any warnings.
  • Prepare a manual verification checklist for the UI changes.

How to install validation

1Skills CLI (Vercel)

npx skills add josstei/maestro-orchestrate --skill validation -a claude-code

2Manually: put the files in place

~/.claude/skills/validation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/validation/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about validation

How do I install validation in Claude Code?

Run npx skills add josstei/maestro-orchestrate --skill validation -a claude-code. The skill file is installed at ~/.claude/skills/validation/SKILL.md.

What does the validation skill do?

It detects project types, runs relevant build, style, and test checks, then classifies their results. For changes that need human review, it prepares a checklist.

How does validation strictness affect phase progression?

MAESTRO_VALIDATION_STRICTNESS supports strict, normal, and lenient. Strict mode blocks on warnings, normal mode blocks only on errors, and lenient mode records results while continuing.

Source text

SKILL.md · Apache-2.0
---
name: validation
description: Cross-cutting validation methodology for verifying phase outputs and project integrity
---

# Validation Skill

Activate this skill when validating phase outputs during orchestration execution or when running standalone validation checks. This skill provides the pipeline, heuristics, and interpretation rules for verifying that changes meet quality standards.

## Validation Pipeline

Execute validation steps in this order. Stop on the first blocking failure unless the user explicitly requests continuing.

### Step 1: Build / Compile
Verify the project compiles without errors.

| Project Type | Command |
|-------------|---------|
| Node.js (TypeScript) | `npx tsc --noEmit` |
| Node.js (JavaScript) | N/A (skip) |
| Rust | `cargo build` |
| Go | `go build ./...` |
| Python | `python -m py_compile [files]` |
| Java (Maven) | `mvn compile` |
| Java (Gradle) | `./gradlew compileJava` |

### Step 2: Lint / Format
Verify code meets style and quality standards.

| Project Type | Command |
|-------------|---------|
| Node.js | `npx eslint . && npx prettier --check .` |
| Rust | `cargo clippy && cargo fmt --check` |
| Go | `go vet ./... && gofmt -l .` |
| Python | `ruff check . && ruff format --check .` |
| Java | `mvn checkstyle:check` or `./gradlew checkstyleMain` |

### Step 3: Unit Tests
Run unit tests to verify behavior preservation.

| Project Type | Command |
|-------------|---------|
| Node.js (Jest) | `npx jest` |
| Node.js (Vitest) | `npx vitest run` |
| Rust | `cargo test` |
| Go | `go test ./...` |
| Python (pytest) | `python -m pytest tests/` |
| Java (Maven) | `mvn test` |
| Java (Gradle) | `./gradlew test` |

### Step 4: Integration Tests
Run integration tests if available and applicable.

Detect integration test presence by looking for:
- `tests/integration/`, `test/integration/`, or `**/integration_test*` directories/files
- Test files with `integration` in the name
- Test scripts in package.json (e.g., `test:integration`)

### Step 5: Manual Verification
For changes that cannot be automatically validated, present a checklist to the user.

## Project Type Detection

Detect the project type by checking for the presence of these files in the project root:

| Indicator File | Project Type |
|---------------|-------------|
| `package.json` | Node.js (check for `typescript` dep for TS) |
| `Cargo.toml` | Rust |
| `go.mod` | Go |
| `pyproject.toml` or `setup.py` | Python |
| `pom.xml` | Java (Maven) |
| `build.gradle` or `build.gradle.kts` | Java (Gradle) |
| `Gemfile` | Ruby |
| `*.csproj` or `*.sln` | .NET |

When multiple indicators are present, validate each project type independently.

## Validation Result Interpretation

### Pass
All executed validation steps completed with exit code 0. No errors or warnings that indicate broken functionality.

### Fail (Blocking)
Any of the following constitute a blocking failure:
- Build/compile errors
- Lint errors (not warnings, unless the project treats warnings as errors)
- Test failures
- Type errors

### Warn (Non-Blocking)
The following are recorded but do not block progression:
- Lint warnings (when not configured as errors)
- Deprecation notices
- Coverage decreases (unless coverage threshold is configured)
- Format-only issues (can be auto-fixed)

## Validation Modes

The validation strictness is controlled by `MAESTRO_VALIDATION_STRICTNESS` (default: `normal`).

| Mode | Behavior |
|------|----------|
| `strict` | Warnings are treated as blocking failures. All lint warnings, deprecation notices, and coverage decreases block phase progression. |
| `normal` | Only errors block. Warnings are recorded but do not prevent phase completion. This is the default behavior described in the Pass/Fail/Warn sections above. |
| `lenient` | Nothing blocks automatically. All failures and warnings are recorded in session state and reported to the user, but phase progression continues. The user reviews the accumulated report at completion. |

### Strictness Application

When evaluating each validation step:
1. Run the validation command and capture the exit code and output
2. Classify the result as Pass, Fail (Blocking), or Warn (Non-Blocking) using the standard criteria above
3. Apply the strictness mode:
   - `strict`: Fail (Blocking) AND Warn (Non-Blocking) both stop progression
   - `normal`: Only Fail (Blocking) stops progression
   - `lenient`: Record everything, stop nothing — append all results to session state and continue
4. If strictness causes a result to be downgraded from blocking to non-blocking, note this in the validation output: "Warning recorded but not blocking (lenient mode)"

## Post-Phase Validation

### When to Validate
Run validation after:
- Every phase that creates or modifies source code
- Every parallel batch completion (validate the combined result)
- Before marking any phase as `completed`

### When to Skip Validation
Skip validation when:
- The phase only modified documentation files
- The phase only produced read-only analysis (`architect`, `code-reviewer` reports)
- The user explicitly requests skipping validation

Record `skipped` with rationale in the phase validation result.

## Manual Verification Checklist

For changes that cannot be automatically validated, present this checklist template:

```
### Manual Verification Required

The following changes require manual verification:

- [ ] [Description of what to verify]
- [ ] [Visual/UI changes look correct]
- [ ] [Integration with external service works]
- [ ] [Environment-specific behavior confirmed]

Please confirm these items are verified before I mark this phase as complete.
```

Use manual verification for:
- UI/visual changes
- External service integrations
- Environment-specific configurations
- Performance improvements (require load testing)
- Security remediations (require penetration testing)

## Incremental Validation Mode

When full pipeline validation is unnecessary, use targeted validation based on the type of changes in the completed phase:

### Validation Scope by Change Type
- **Phase created new files only** (no existing files modified): Run lint + type check on the new files only. This provides fast feedback without running the full test suite against unchanged code.
- **Phase modified existing files**: Run the full test suite. Existing tests serve as behavior-preservation checks — any failure indicates a potential regression.
- **Phase touched configuration files** (build config, CI config, environment config, dependency manifests): Run the full pipeline (build + lint + type check + all tests). Configuration changes can have cascading effects across the entire project.
- **Phase only produced documentation or analysis**: Skip validation (record as `skipped` with rationale).

### Scope Detection
Determine the change type automatically from the completing agent's Task Report:
1. Parse Files Created and Files Modified lists
2. Classify each file: source code, test code, configuration, documentation
3. Apply the most comprehensive validation scope that matches any changed file type (e.g., if one config file and three source files changed, run the full pipeline because config was touched)

## Validation Failure Diagnosis

When validation fails, provide a structured diagnosis to help the orchestrator decide next steps.

### Diagnosis Protocol
1. **Categorize the failure**: type error, lint error, test failure, build error, runtime error
2. **Identify involved files**: Which files from the current phase appear in the error output?
3. **Determine causality**: Is the failure caused by the current phase's changes, or is it a pre-existing issue?
   - Check: Does the failure reference files modified in this phase?
   - Check: Run validation against a clean snapshot while always restoring local state:
     - `git stash push --include-untracked -m "maestro-causality-check"`
     - `[validation command]` (capture exit code as `validation_exit`)
     - `git stash pop` (run regardless of `validation_exit`)
   - If `validation_exit` is non-zero in the clean snapshot, classify the failure as pre-existing.
   - If `git stash pop` fails, mark the diagnosis as inconclusive until restoration conflicts are resolved.
4. **Classify resolution path**:
   - **Fixable by same agent**: The error is in files the agent owns, the fix is straightforward (missing import, type mismatch, lint violation). Re-delegate to the same agent with the error context.
   - **Requires different agent**: The error is caused by an interface mismatch between phases. Identify which phase introduced the incompatibility.
   - **Requires human input**: The error reveals an ambiguity in the design or plan that cannot be resolved without user guidance. Escalate with full context.

### Diagnosis Output Format
```
### Validation Diagnosis
- **Failure Type**: [type error | lint error | test failure | build error]
- **Failing Files**: [list of files from current phase involved in the failure]
- **Root Cause**: [brief description of why validation failed]
- **Pre-existing**: [yes | no — was this failure present before this phase's changes?]
- **Resolution Path**: [re-delegate to same agent | escalate to user | requires cross-phase fix]
- **Recommended Action**: [specific next step with context to include in re-delegation or escalation]
```

© josstei · Apache-2.0 · josstei/maestro-orchestrate

Similar skills

All skills for Testing and QA →

validation by other authors comes first.

validation official OpenAI The validation skill for Codex assesses candidate security findings and confirms them with project evidence. Use it during a security scan's validation phase or upon request, not for full repository scans. CX Codex GP ChatGPT +1 29installs validation honeydew-ai validation validates Honeydew metrics, attributes, entities, and domains right after creation or modification. CX Codex +1 ★ 44repo stars quality-validation qodex-ai quality-validation blocks AI agents from claiming a task is finished without running fresh verification commands and checking exit codes. CX Codex +1 142installs multi-agent-e2e-validation terrylica The multi-agent-e2e-validation skill for Claude Code and other AI editors spawns multiple validation agents in parallel to test database refactors comprehensively. CX Codex +1 128installs defense-in-depth-validation secondsky defense-in-depth-validation — a skill that pushes your agent to validate data at every layer it passes through, so the bug becomes structurally impossible. Useful when bad data fails deep in execution. CX Codex +1 437installs md-validation haowjy md-validation is a Claude Code skill that checks Markdown links and Mermaid diagrams. It activates on requests to validate links or diagrams before delivery. CX Codex +1 441installs zod-validation-utilities giuseppe-trisciuoglio zod-validation-utilities — a skill for building reusable Zod v4 schemas to validate API payloads, forms, and configuration input with full TypeScript type inference. CX Codex +1 4,100installs 403-frameworks-quarkus-validation Juan Antonio Breña Moral 403-frameworks-quarkus-validation guides Quarkus validation work, from DTO constraints and REST boundaries to configuration checks and API error mapping. CX Codex +1 296installs

From the same set40

The whole set →
refactor Subagent for codebase refactoring without altering existing behavior. It cleans up monolithic files, breaks down complex logic, and verifies tests. CX Codex ★ 489repo stars devops-engineer devops-engineer automates work on CI/CD, containers, and infrastructure. Use it to configure a build pipeline, write a Docker setup, or prepare deployment scripts. CX Codex ★ 489repo stars security-engineer security-engineer — a subagent for checking code against OWASP Top 10 vulnerabilities, auditing authentication, and scanning dependencies. Builds threat models and delivers prioritized remediation reports. CX Codex ★ 489repo stars tester tester generates unit and integration test suites, checks edge cases, and verifies execution without touching application source code. CX Codex ★ 489repo stars product-manager product-manager turns a rough feature idea into a PRD, a prioritised backlog and testable user stories that other agents can pick up and build. CX Codex ★ 489repo stars ux-designer ux-designer designs user journeys, interaction patterns, and wireframe specs without generating frontend code. CX Codex ★ 489repo stars accessibility-specialist accessibility-specialist audits interfaces against WCAG criteria and reviews keyboard access, semantic HTML, and ARIA. Use it to find barriers in a web app. CX Codex ★ 489repo stars analytics-engineer analytics-engineer — a subagent for event taxonomy design, tracking implementation, and experiment planning. Instruments features with analytics, builds conversion funnels, and designs A/B tests with proper statistical foundations. CX Codex ★ 489repo stars

Project sponsors

Companies that keep this analytics open