playbooks

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

code-change-verification skill

/.codex/skills/code-change-verification

This skill ensures runtime code changes pass installation, build, lint, type checks, and tests before marking work complete.

npx playbooks add skill openai/openai-agents-js --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.7 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 JS monorepo.
---

# Code Change Verification

## Overview

Ensure work is only marked complete after installing dependencies, building, linting, type checking (including generated declarations), and tests pass. Use this skill when changes affect runtime code, tests, or build/test configuration.

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

- Run from the repository root in this order: `pnpm i`, `pnpm build`, `pnpm -r build-check`, `pnpm -r -F "@openai/*" dist:check`, `pnpm lint`, `pnpm test`.
- 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 (including declaration checks) with fail-fast semantics.
- Prefer this entry point to ensure the commands always run in the correct order from the repo root.

### 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 whenever changes touch runtime code, tests, or build/test configuration. It ensures dependencies install correctly, the project builds, linting and type checks (including generated declarations) succeed, and all tests pass before work is marked complete. Follow the provided scripted entry points from the project root to run the full sequence with fail-fast behavior.

How this skill works

The skill executes a strict sequence of commands that install packages, build packages, run build-checks across the monorepo, validate generated distributions, run linting, and execute tests. It provides shell and PowerShell wrappers that enforce the correct order and stop immediately on failure so you can fix issues as they arise. Re-running the full stack after fixes confirms issues are resolved.

When to use it

  • When code changes affect runtime modules or shared libraries
  • When tests were added, modified, or are flaky
  • When build configuration, type generation, or bundling behavior changed
  • Before marking work complete or opening a final review/merge request

Best practices

  • Run the verification from the project root so cross-package checks execute correctly
  • Use the provided run scripts to preserve order and fail-fast semantics
  • Fix the first failing command, then re-run the full stack rather than skipping steps
  • Ensure generated declaration outputs are included in type checks before approving changes
  • Run on the same OS/Node version used by CI to reproduce environment-specific failures

Example use cases

  • A TypeScript runtime refactor touches multiple packages — run full verification to catch type or build regressions
  • Adding or changing tests — validate that test suites pass and type declarations remain correct
  • Updating build or bundler config — confirm dist checks and build-check tasks still succeed
  • Modifying shared types or generated code — ensure declaration files are generated and pass type checks

FAQ

Which entrypoint should I use to run the verification?

Use the provided shell script from a Unix-like terminal or the PowerShell script on Windows; both run the same ordered steps and stop on failure.

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

Match the CI environment: verify Node and package manager versions, OS differences, and rebuild from a clean state. If failures persist, capture and report the failing output for investigation.

Can I skip steps if I know they won’t be affected?

No. The sequence is designed to catch cross-package and generated-output issues; always run the full stack and address failures before confirming completion.