From jaan-to
Validates OpenAPI contracts using Spectral linting, oasdiff diffing, Prism mocking, and Schemathesis fuzzing. Use when verifying API spec compliance.
npx claudepluginhub parhumm/jaan-to --plugin jaan-toThis skill is limited to using the following tools:
> Validate API contracts through a multi-tool pipeline -- lint, diff, mock, and fuzz.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Validate API contracts through a multi-tool pipeline -- lint, diff, mock, and fuzz.
$JAAN_CONTEXT_DIR/tech.md - Tech stack context$JAAN_LEARN_DIR/jaan-to-qa-contract-validate.learn.md - Past lessons (loaded in Pre-Execution)$JAAN_TEMPLATES_DIR/jaan-to-qa-contract-validate.template.md - Output template${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocolContract Source: $ARGUMENTS
Input modes:
Scope: OpenAPI/Swagger specs only (v1). GraphQL schema validation and gRPC proto linting are out of scope.
MANDATORY -- Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md
Skill name: qa-contract-validate
Execute: Step 0 (Init Guard) -> A (Load Lessons) -> B (Resolve Template) -> C (Offer Template Seeding)
Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md
Override field for this skill: language_qa-contract-validate
ultrathink
Use extended reasoning for:
openapi: or swagger: version fieldCheck each tool using only commands permitted by allowed-tools. Use npx --no-install for npm tools to prevent silent auto-installation. Never use bare npx or which.
| Tool | Check Command | Type |
|---|---|---|
| Spectral | npx --no-install @stoplight/spectral-cli --version | npm |
| oasdiff | oasdiff --version | Go binary (NOT npm) |
| Prism | npx --no-install @stoplight/prism-cli --version | npm |
| Schemathesis | schemathesis --version | Python pip |
Report availability:
TOOL AVAILABILITY
-------------------------------------------------------------
Spectral: {available/unavailable}
oasdiff: {available/unavailable} (requires --baseline)
Prism: {available/unavailable} (requires --url)
Schemathesis: {available/unavailable} (requires --url)
Pipeline: {count}/4 tools available
Hard rule: If 0 out of 4 tools are available, report status as INCONCLUSIVE (not PASS). Output must state: "No validation tools installed -- contract compliance unknown. Install at least one tool to validate."
Based on available tools and provided inputs:
| Tool | Condition | Stage |
|---|---|---|
| Spectral | Always (if available) | Lint spec |
| oasdiff | If --baseline provided AND tool available | Breaking changes |
| Prism | If --url provided AND tool available | Conformance check |
| Schemathesis | If --url provided AND tool available | Fuzz testing |
CONTRACT VALIDATION PLAN
-------------------------------------------------------------
Spec: {spec_path} ({endpoint_count} endpoints, {schema_count} schemas)
Baseline: {baseline_path or "none"}
API URL: {url or "none"}
Pipeline Stages:
1. Spectral Lint: {will run / skipped (unavailable)}
2. oasdiff Diff: {will run / skipped (no baseline or unavailable)}
3. Prism Conformance: {will run / skipped (no URL or unavailable)}
4. Schemathesis Fuzz: {will run / skipped (no URL or unavailable)}
Output Folder: $JAAN_OUTPUTS_DIR/qa/contract-validate/{id}-{slug}/
Use AskUserQuestion:
Do NOT proceed to Phase 2 without explicit approval.
Parallel Tool Execution: Spectral, oasdiff, Prism, and Schemathesis are independent with no data dependencies between them. When multiple tools are available, execute them concurrently (e.g., parallel Bash calls or Task-based sub-agents) and aggregate results after all complete.
Incremental Validation: When --baseline is provided, use oasdiff to identify changed endpoints first. Then scope Schemathesis fuzzing to only those endpoints using --endpoint filter, avoiding full-spec fuzzing on unchanged paths.
Schemathesis Speed Tuning: For large specs, constrain fuzzing with --workers=4 --max-examples=50 --stateful=links to bound execution time while maintaining coverage quality.
Reference: See
${CLAUDE_PLUGIN_ROOT}/docs/extending/qa-contract-validate-reference.mdsection "Performance Optimization" for parallel execution patterns and Schemathesis tuning options.
npx @stoplight/spectral-cli lint {spec_path} --format json --ruleset .spectral.yaml
If .spectral.yaml not found, use built-in rulesets. Parse JSON output:
oasdiff breaking --fail-on ERR {baseline_path} {spec_path} --format json
oasdiff is a Go binary, NOT npm. Install: go install github.com/tufin/oasdiff@latest or brew install oasdiff.
CI: use oasdiff/oasdiff-action@{pinned-sha} GitHub Action (pin to immutable commit SHA, never @latest).
Parse output: list breaking changes with severity and path.
npx @stoplight/prism-cli proxy {spec_path} --host 0.0.0.0 --port 4010
Or validate against running API in proxy mode. Parse conformance violations.
schemathesis run --url {api_url} {spec_path} --stateful=links --format json
schemathesis is a Python pip package, NOT npm. Parse: test count, failure count, defect details.
Combine all tool outputs into aggregate status:
| Stage | Status | Findings |
|---|---|---|
| Spectral | PASS/WARN/FAIL | {error_count} errors, {warn_count} warnings |
| oasdiff | PASS/FAIL/SKIPPED | {breaking_count} breaking changes |
| Prism | PASS/FAIL/SKIPPED | {violation_count} conformance violations |
| Schemathesis | PASS/FAIL/SKIPPED | {defect_count} defects found |
Aggregate: PASS (all ran pass), WARN (warnings only), FAIL (any errors/breaking/defects), INCONCLUSIVE (0 tools ran).
source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/id-generator.sh"
SUBDOMAIN_DIR="$JAAN_OUTPUTS_DIR/qa/contract-validate"
mkdir -p "$SUBDOMAIN_DIR"
NEXT_ID=$(generate_next_id "$SUBDOMAIN_DIR")
Template:
API contract validation for {spec_title} v{spec_version} ({endpoint_count} endpoints).
Pipeline: {tools_ran}/{tools_total} tools executed. Aggregate status: {PASS/WARN/FAIL/INCONCLUSIVE}.
Spectral: {status}. oasdiff: {status}. Prism: {status}. Schemathesis: {status}.
Path: $JAAN_OUTPUTS_DIR/qa/contract-validate/${NEXT_ID}-${slug}/
Files:
{id}-{slug}.md -- Main validation reportspectral-results.json -- Raw Spectral output (if ran)oasdiff-results.json -- Raw oasdiff output (if ran)schemathesis-results.json -- Raw Schemathesis output (if ran)source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/index-updater.sh"
add_to_index \
"$SUBDOMAIN_DIR/README.md" \
"$NEXT_ID" \
"${NEXT_ID}-${slug}" \
"{Spec Title} Contract Validation" \
"{Executive Summary}"
Use AskUserQuestion:
If "Learn from this": Run /jaan-to:learn-add qa-contract-validate "{feedback}"
$JAAN_OUTPUTS_DIR path