playbooks

home / skills / openai / openai-agents-python / code-change-verification

code-change-verification skill

/.codex/skills/code-change-verification

This skill runs the full code-change verification stack to ensure formatting, linting, typing, and tests pass after code changes.

npx playbooks add skill openai/openai-agents-python --skill code-change-verification

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.8 KB
---
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 `./.codex/skills/code-change-verification` so it loads automatically for the repository.
2. macOS/Linux: `bash .codex/skills/code-change-verification/scripts/run.sh`.
3. Windows: `powershell -ExecutionPolicy Bypass -File .codex/skills/code-change-verification/scripts/run.ps1`.
4. If any command fails, fix the issue, rerun the script, and report the failing output.
5. 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 in this order: `make format`, `make lint`, `make mypy`, `make tests`.
- Do not skip steps; stop and fix issues immediately when a command fails.
- Re-run the full stack after applying fixes so the commands execute in the required order.

## Resources

### scripts/run.sh

- Executes the full verification sequence with fail-fast semantics from the repository root. Prefer this entry point to ensure the required commands run in the correct order.

### scripts/run.ps1

- Windows-friendly wrapper that runs the same verification sequence with fail-fast semantics. Use from PowerShell with execution policy bypass if required by your environment.

Overview

This skill runs the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the repository. It ensures formatting, linting, type checking, and tests all pass before work is marked complete. Use the provided cross-platform scripts or the manual Makefile sequence from the repository root.

How this skill works

The skill executes a fail-fast sequence of commands that enforce code quality and correctness: format, lint, static type checks, and unit tests. It provides cross-platform entry points: a shell script for macOS/Linux and a PowerShell script for Windows, both invoking the required steps in order. If any step fails, stop, fix the issue, and re-run the full stack until all checks succeed.

When to use it

  • When changes touch runtime code or business logic
  • When tests are added, changed, or failing
  • When build or test configuration files are modified
  • Before marking a change as complete or merging to main
  • Skip only for docs-only or metadata-only changes unless full verification is requested

Best practices

  • Run from the repository root to ensure Make targets resolve correctly
  • Use the provided scripts (scripts/run.sh or scripts/run.ps1) to enforce correct ordering and fail-fast behavior
  • If dependencies changed, run make sync first to install developer requirements
  • Do not ignore failures: fix the root cause, then re-run the full stack in order
  • Report and include failing output when asking for help to speed diagnosis

Example use cases

  • Developer changes a core agent runtime file — run the full stack to confirm no regressions
  • A contributor updates unit tests — verify formatting, lint, mypy, and tests pass before merge
  • CI pipeline mirrors this skill to gate pull requests that touch code or tests
  • A maintainer modifies test configuration — run verification to ensure CI will succeed

FAQ

Can I skip verification for small changes?

Only skip for docs-only or repository metadata changes. For any change touching runtime, tests, or build/test config, run the full verification stack.

What if a command fails on my machine but passes in CI?

First run make sync to align dependencies, then re-run the scripts from repo root. If discrepancies persist, capture and share the failing output for investigation.