Add verify-changes skill to this project

.codex/skills/verify-changes/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: verify-changes
+description: Run all the mandatory verification steps for code changes
+---
+
+# Verify Changes
+
+## Overview
+Ensure work is only marked complete after formatting, linting, type checking, and tests pass. Use this skill whenever finishing a task, before opening a PR, or when asked to confirm that changes are ready to hand off.
+
+## Quick start
+1. Keep this skill at `./.codex/skills/verify-changes` so it loads automatically for the repository.
+2. macOS/Linux: `bash .codex/skills/verify-changes/scripts/run.sh`.
+3. Windows: `powershell -ExecutionPolicy Bypass -File .codex/skills/verify-changes/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 four commands succeed with no remaining changes to address.
+
+## Manual workflow
+- 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.
+- `make format` may modify files; rerun `make lint`, `make mypy`, and `make tests` after applying the formatting changes.
+
+## Resources
+### scripts/run.sh
+- Executes the full verification sequence with fail-fast semantics.
+- Prefer this entry point to ensure the required commands always 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.

.codex/skills/verify-changes/scripts/run.ps1

@@ -0,0 +1,38 @@
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
+$repoRoot = $null
+
+try {
+    $repoRoot = (& git -C $scriptDir rev-parse --show-toplevel 2>$null)
+} catch {
+    $repoRoot = $null
+}
+
+if (-not $repoRoot) {
+    $repoRoot = Resolve-Path (Join-Path $scriptDir "..\\..\\..\\..")
+}
+
+Set-Location $repoRoot
+
+function Invoke-MakeStep {
+    param(
+        [Parameter(Mandatory = $true)][string]$Step
+    )
+
+    Write-Host "Running make $Step..."
+    & make $Step
+
+    if ($LASTEXITCODE -ne 0) {
+        Write-Error "verify-changes: make $Step failed with exit code $LASTEXITCODE."
+        exit $LASTEXITCODE
+    }
+}
+
+Invoke-MakeStep -Step "format"
+Invoke-MakeStep -Step "lint"
+Invoke-MakeStep -Step "mypy"
+Invoke-MakeStep -Step "tests"
+
+Write-Host "verify-changes: all commands passed."

.codex/skills/verify-changes/scripts/run.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Fail fast on any error or undefined variable.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if command -v git >/dev/null 2>&1; then
+  REPO_ROOT="$(git -C "${SCRIPT_DIR}" rev-parse --show-toplevel 2>/dev/null || true)"
+fi
+REPO_ROOT="${REPO_ROOT:-$(cd "${SCRIPT_DIR}/../../../.." && pwd)}"
+
+cd "${REPO_ROOT}"
+
+echo "Running make format..."
+make format
+
+echo "Running make lint..."
+make lint
+
+echo "Running make mypy..."
+make mypy
+
+echo "Running make tests..."
+make tests
+
+echo "verify-changes: all commands passed."

AGENTS.md

@@ -5,35 +5,25 @@ Welcome to the OpenAI Agents SDK repository. This file contains the main points
 - **Source code**: `src/agents/` contains the implementation.
 - **Tests**: `tests/` with a short guide in `tests/README.md`.
 - **Examples**: under `examples/`.
-- **Documentation**: markdown pages live in `docs/` with `mkdocs.yml` controlling the site.
+- **Documentation**: markdown pages live in `docs/` with `mkdocs.yml` controlling the site. Translated docs under `docs/ja`, `docs/ko`, and `docs/zh` are managed by an automated job; do not edit them manually.
 - **Utilities**: developer commands are defined in the `Makefile`.
 - **PR template**: `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md` describes the information every PR must include.
 
-## Local workflow
-
-1. Format, lint and type‑check your changes:
+## Agent requirements
 
-   ```bash
-   make format
-   make lint
-   make mypy
-   ```
+- Always invoke `$verify-changes` before completing any work. The skill encapsulates the required formatting, linting, type-checking, and tests; follow `.codex/skills/verify-changes/SKILL.md` for how to run it.
 
-2. Run the tests:
+## Planning guidance
 
-   ```bash
-   make tests
-   ```
+- Before starting work, surface any potential backward compatibility risks in your implementation plan and confirm the approach when breaking changes could affect existing users.
 
-   To run a single test, use `uv run pytest -s -k <test_name>`.
-
-3. Build the documentation (optional but recommended for docs changes):
+## Local workflow
 
-   ```bash
-   make build-docs
-   ```
+1. Run `$verify-changes` before handing off work; it formats, lints, type-checks, and runs the test suite (see `.codex/skills/verify-changes/SKILL.md` for the workflow).
+2. To run a single test, use `uv run pytest -s -k <test_name>`.
+3. Build the documentation when you touch docs: `make build-docs`.
 
-   Coverage can be generated with `make coverage`.
+Coverage can be generated with `make coverage`.
 
 All python commands should be run via `uv run python ...`