Code Change Verification

intent

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.

inputs

• repository: openai agents python repo, checked out locally at repository root
• make: gnu make installed and available on PATH
• uv: uv package manager installed (used by make sync to install dev dependencies)
• dev dependencies: python packages listed in project pyproject.toml or requirements files, installed via make sync
• bash or powershell: bash 3.2+ (macOS/Linux) or powershell 5.0+ (Windows) to run automation scripts
• script location: ./.agents/skills/code-change-verification/scripts/run.sh (bash) or scripts/run.ps1 (powershell) must exist and be executable

procedure

1. check 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.

2. run formatting: execute make format from repository root. input: current code state. output: all files reformatted in place; no formatting issues remain.

3. 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.

4. 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.

5. 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.

6. 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.

7. 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.

decision points

• 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.

output contract

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:

• command name (e.g., make lint)
• exit code
• full stdout and stderr output
• file paths and line numbers of violations (if applicable)

do not create or modify files outside the repository root. do not generate summary reports; emit raw command output directly.

outcome signal

the user knows verification passed when:

• all four commands complete without errors and the final message states "all checks passed" or equivalent.
• the shell prompt returns with exit code 0.
• no remaining issues are reported.

the user knows verification failed when:

• one or more commands exit with non-zero code.
• the script stops and reports the failing command name, exit code, and output.
• the shell prompt returns with a non-zero exit code.

the user should not mark the work complete until all four commands pass.