القائمة
Validate API contracts with Spectral, oasdiff, and Schemathesis pipeline. Use when verifying API spec compliance.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Root installer anchor for the jaan.to Codex skill pack. Use when installing jaan.to skills in Codex.
Audit AI history and existing workflow, then plan a reliable, evaluated, safe AI system. Use when maturing AI workflows.
Report bugs, feature requests, or skill issues to the jaan-to GitHub repo or save locally. Use when reporting plugin issues.
Detect repeated workflow patterns from AI sessions and suggest skills to automate them. Use when optimizing workflows.
Assemble role-based AI teammates to ship ideas from concept to production via agent teams. Use when orchestrating multi-role delivery.
Orchestrate RED/GREEN/REFACTOR TDD cycle with context-isolated agents. Use when implementing features test-first.
| name | qa-contract-validate |
| description | Validate API contracts with Spectral, oasdiff, and Schemathesis pipeline. Use when verifying API spec compliance. |
| allowed-tools | Read, Glob, Grep, Bash(npx @stoplight/spectral-cli:*), Bash(oasdiff:*), Bash(npx @stoplight/prism-cli:*), Bash(schemathesis:*), Write($JAAN_OUTPUTS_DIR/qa/contract-validate/**), Task, AskUserQuestion, Edit(jaan-to/config/settings.yaml) |
| argument-hint | [openapi-spec-path] [--baseline baseline-spec] [--url api-url] |
| license | PROPRIETARY |
| context | fork |
| disable-model-invocation | true |
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