Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents Python repository.
--- name: code-change-verification description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents Python repository. --- # Code Change Verification ## Overview Ensure work is only marked complete after formatting, linting, type checking, and tests pass. Use this skill when changes affect runtime code, tests, or build/test configuration. You can skip it for docs-only or repository metadata unless a user asks for the full stack. ## Quick start 1. Keep this skill at `./.agents/skills/code-change-verification` so it loads automatically for the repository. 2. macOS/Linux: `bash .agents/skills/code-change-verification/scripts/run.sh`. 3. Windows: `powershell -ExecutionPolicy Bypass -File .agents/skills/code-change-verification/scripts/run.ps1`. 4. The scripts run `make format` first, then run `make lint`, `make typecheck`, and `make tests` in parallel with fail-fast semantics. 5. While the parallel steps are still running, the scripts emit periodic heartbeat updates so you can tell that work is still in progress. 6. If any command fails, fix the issue, rerun the script, and report the failing output. 7. Confirm completion only when all commands succeed with no remaining issues. ## Manual workflow - If dependencies are not installed or have changed, run `make sync` first to install dev requirements via `uv`. - Run from the repository root with `make format` first, then `make lint`, `make typecheck`, and `make tests`. - Do not skip steps; stop and fix issues immediately when a command fails. - If you run the steps manually, you may parallelize `make lint`, `make typecheck`, and `make tests` after `make format` completes, but you must stop the remaining steps as soon as one fails. - Re-run the full stack after applying fixes so the commands execute in the required order. ## Resources ### scripts/run.sh - Executes `make format` first, then runs `make lint`, `make typecheck`, and `make tests` in parallel with fail-fast semantics from the repository root. It also emits periodic heartbeat updates while the parallel steps are still running. Prefer this entry point to preserve the required ordering while reducing total runtime. ### scripts/run.ps1 - Windows-friendly wrapper that runs the same sequence with `make format` first and the remaining steps in parallel with fail-fast semantics, plus periodic heartbeat updates while work is still running. Use from PowerShell with execution policy bypass if required by your environment.
don't have the plugin yet? install it then click "run inline in claude" again.
by @clawhub
added explicit inputs (make, uv, bash/powershell, script locations), expanded procedure into seven numbered steps with input/output for each, extracted implicit decision logic (deps stale, platform selection, docs-only skip, timeout handling, missing tools), and clarified output contract with file state and error capture requirements.
Run formatting, linting, type checking, and tests in the correct sequence whenever you change runtime code, test files, or build/test configuration in the OpenAI Agents Python repository. skip this skill for docs-only or metadata-only changes unless explicitly requested. use this to ensure all changes pass the full verification stack before marking work complete.
make sync to install dev dependencies)make sync./.agents/skills/code-change-verification/scripts/run.sh (bash) or scripts/run.ps1 (powershell) must exist and be executablecheck if dependencies are stale: if you have not run make sync since dependencies were last updated in pyproject.toml or lockfiles, run make sync from repository root to install dev requirements via uv. output: no errors, dev tools ready.
run formatting: execute make format from repository root. input: current code state. output: all files reformatted in place; no formatting issues remain.
run linting, type checking, and tests in parallel: after make format completes, trigger make lint, make typecheck, and make tests simultaneously with fail-fast semantics (stop all three if any one fails). input: formatted code. output: all three commands complete with zero errors, or first failure halts remaining commands.
emit heartbeat updates: while parallel steps run, emit status messages (every 10-30 seconds) so the user knows work is still in progress. input: active child processes. output: periodic "still checking..." messages.
handle failures: if any command fails, stop all remaining commands, capture the failing output (stdout and stderr), and report it. input: error output from failed command. output: clear error message with command name, exit code, and full output.
re-run full stack after fixes: after the user fixes the reported issue, re-run steps 2-4 (format, then lint/typecheck/tests in parallel). do not skip steps; enforce the sequence. input: fixed code. output: all commands pass with zero errors.
confirm completion: report success only when all four commands (make format, make lint, make typecheck, make tests) have completed without errors. input: zero exit codes from all four. output: "verification complete" signal.
if dependencies are missing or stale: run make sync before running verification commands. if make sync fails, stop and report the error (likely missing uv or broken lockfile).
if running on macOS/Linux: use the bash script at ./.agents/skills/code-change-verification/scripts/run.sh as the preferred entry point. it handles parallelization, heartbeats, and fail-fast behavior automatically.
if running on Windows: use the powershell script at ./.agents/skills/code-change-verification/scripts/run.ps1 with -ExecutionPolicy Bypass if needed. it provides the same semantics as the bash version.
if the user prefers manual execution: run make format alone first, wait for it to complete, then run make lint, make typecheck, and make tests either sequentially or in parallel (your choice), but stop all remaining steps immediately if any one fails. then re-run the full sequence after fixes.
if the change is docs-only or metadata-only (README, comments, LICENSE, .gitignore, etc.): skip this skill entirely unless the user explicitly asks for the full verification stack.
if any parallel step times out or hangs (>10 minutes with no output): kill the stalled process, report a timeout, and ask the user to investigate (likely infinite loop or deadlock in the test suite).
if a command fails with "command not found" (e.g., make, uv, or python): report the missing tool, its expected PATH location, and installation instructions.
if the result set is empty (no tests found, no files to lint): report success anyway; the verification stack ran with zero issues.
success is a clean exit from all four commands in sequence:
make format: exits with code 0; all source files reformatted in place.make lint: exits with code 0; no linting violations.make typecheck: exits with code 0; no type errors.make tests: exits with code 0; all tests pass.failure is any command exiting with non-zero code. capture and report:
make lint)do not create or modify files outside the repository root. do not generate summary reports; emit raw command output directly.
the user knows verification passed when:
the user knows verification failed when:
the user should not mark the work complete until all four commands pass.