chore: refine repo skills

.agents/skills/docs-sync/SKILL.md

@@ -15,7 +15,7 @@ Identify doc coverage gaps and inaccuracies by comparing main branch features an
    - Identify the current branch and default branch (usually `main`).
    - Prefer analyzing the current branch to keep work aligned with in-flight changes.
    - If the current branch is not `main`, analyze only the diff vs `main` to scope doc updates.
-   - Avoid switching branches if it would disrupt local changes; use `git show main:<path>` or `git worktree add` when needed.
+   - Avoid switching branches if it would disrupt local changes. Prefer read-only inspection such as `git show main:<path>`. If a separate checkout is genuinely required, stop and obtain the explicit approval required by `AGENTS.md` before creating or switching a worktree.
 
 2. Build a feature inventory from the selected scope
    - If on `main`: inventory the full surface area and review docs comprehensively.

.agents/skills/implementation-final-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: implementation-final-review
-description: Perform a risk-tiered zero-base final review loop before an implementation is declared complete. Use only when the user explicitly invokes $implementation-final-review or repository instructions authorize automatic invocation after implementation. Audit the complete merge-base diff for requirement fit, contract-surface coverage, await-boundary and lifecycle gaps, released compatibility, security, protocol, and persistence boundaries, unnecessary complexity, package and generated public surfaces, and adversarial test coverage; use compact self-contained reviewer packets and two concurrent no-history independent reviewers per round, defer broad final repository verification until review is clean and observable host capacity is available, preserve clean evidence for unchanged semantic components, close repeated root-cause groups instead of accumulating local patches, and enforce bounded review cycles in one task-global ledger.
+description: Perform the repository's risk-tiered independent final review before implementation completion. Use only when explicitly invoked or when repository instructions require it after behavior-impacting implementation work; audit the complete task diff, supported contracts, lifecycle and security boundaries, complexity, and tests before final verification.
 ---
 
 # Implementation Final Review
@@ -178,6 +178,9 @@ Choose dimensions based on the changed boundary; do not mechanically invent find
 ### Tests and generated public surfaces
 
 - Prefer public-boundary or caller-visible adversarial tests.
+- Exercise the highest stable caller boundary that reproduces the required behavior. A helper-only test is insufficient when a caller transforms the input, owns the lifecycle, or determines the observable result before or after invoking that helper.
+- Require expected values and failure signals to come from the contract, a worked example, a baseline, or another independent oracle. Do not accept an assertion that recomputes the expected result with the same logic as the implementation.
+- Use a narrower internal boundary when a lifecycle, concurrency, provider-wire, or malformed-stream scenario cannot be controlled reliably through a public entry point, and record why that boundary is necessary.
 - Add controlled interleavings for concurrency instead of relying only on sequential tests.
 - Test the required behavior, the nearest supported alternative, and one representative input per unsupported category.
 - Do not accept passing existing tests as proof when they encode the same assumptions as the implementation.

.agents/skills/implementation-kickoff/SKILL.md

@@ -35,6 +35,8 @@ Do not create the final branch yet. A detached worktree makes the eventual `$pr-
 
 Keep the task diff uncommitted through implementation, focused tests, formatting, and review fixes. Track new files explicitly because ordinary diff statistics omit untracked files. Maintain one canonical shipped-path manifest separately from operational artifacts and require a concrete deliverable reason for every path in it. Use the applicable repository skills and references, including `$implementation-strategy` before user-facing or runtime changes.
 
+When the task can be decomposed without temporarily breaking a supported contract, implement one narrow end-to-end behavior slice at a time and run its focused test before adding the next slice. Do not force cross-cutting migrations or atomic compatibility changes into artificial slices that cannot remain valid independently.
+
 Do not create checkpoint commits. If an external interruption requires extra protection, leave the dedicated worktree intact or use a clearly named temporary stash; restore the changes before continuing and do not treat the stash as a deliverable.
 
 ### Taking over an existing pull request

.agents/skills/implementation-strategy/SKILL.md

@@ -61,6 +61,9 @@ Example: if successive findings require traversing a direct wrapper, partial, ne
 - Unreleased persisted schema versions may be renumbered or squashed when intermediate snapshots are intentionally unsupported; update the support set and tests together.
 - Do not equate a broad Python or third-party protocol with support for every representable shape.
 - Prefer the nearest existing pipeline and one source of truth for schema, documentation, validation, identity, and invocation.
+- Treat an interface as everything a caller must know to use the behavior correctly, including ordering, errors, lifecycle, configuration, and performance constraints when relevant; do not judge its size from the signature alone.
+- Apply the deletion test before retaining a new abstraction: keep it when removing it would distribute required complexity across callers, but remove it when the complexity itself would disappear.
+- Add a replaceable boundary only for demonstrated variation, ownership, or testability. One hypothetical adapter or a test-only indirection is not enough when the existing pipeline already provides a stable boundary.
 - Add abstractions, state, classifications, branches, configuration, dependencies, or parallel paths only for a stated requirement, supported contract, or verified risk.
 - Prefer deletion or direct replacement for unreleased code. Treat branch-local implementation and tests as disposable.
 - Prefer an actionable construction- or validation-time error plus an existing alternative over partial protocol emulation.
@@ -117,7 +120,9 @@ Before declaring the design complete, answer all of these with concrete evidence
 - Can the required behavior be described without naming internal helper types or reflection mechanics?
 - Does the implementation reuse the nearest existing pipeline rather than maintain a parallel interpretation?
 - Does every new abstraction and branch map to the scope contract or a verified risk?
+- Would deleting each new abstraction merely push required complexity into multiple callers, and does each new boundary correspond to demonstrated variation, ownership, or testability?
 - Are unsupported neighboring cases rejected before side effects with an existing alternative identified?
+- Do tests exercise the highest stable caller boundary that reproduces the required behavior, with expected values independent of the implementation logic?
 - Do the complete diff and tests cover the contract without making every constructible permutation supported?
 - Does the latest review revision shrink or preserve the behavior space rather than widen it without evidence?
 - When a complexity reset occurred, does every retained abstraction, branch, and test map to the frozen reset spec, with later findings classified against it?

.agents/skills/maintainer-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: maintainer-review
-description: Review a GitHub issue or pull request URL as an openai-agents-python maintainer, with a staged assessment of whether the claim is real, practically important, already solvable with supported functionality, correctly scoped, better served by another design, and worth maintainer and contributor effort. Use when assessing issue validity or severity, deciding whether an issue should be prioritized or closed, determining whether a requested feature represents an unmet need rather than a discoverability or usage gap, judging whether a PR is worth bringing to mergeable quality, comparing open PRs or alternative designs, separating code quality from repository readiness, or drafting a concise maintainer assessment. When closure, additional evidence, or code changes should be requested, also produce a polite, concise, complete, copy-paste-ready maintainer comment.
+description: Assess an openai-agents-python GitHub issue or pull request as a maintainer. Use to verify the claimed need and practical impact, compare supported alternatives or competing approaches, separate code quality from repository readiness, recommend the maintainer action, and draft a copy-ready comment when evidence, changes, or closure should be requested.
 ---
 
 # Maintainer Review

.agents/skills/maintainer-review/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Maintainer Review"
   short_description: "Gate PR value on demonstrated user need"
-  default_prompt: "Use $maintainer-review with this GitHub issue or PR URL. Before evaluating implementation quality, verify that linked evidence matches the exact runtime variant and assign Need evidence as Demonstrated, Plausible but unproven, Already covered, or Unsupported. Require either observed practical impact or a complete realistic trigger-to-material-consequence trace; reject harmless speculative logic-only improvements even when the patch is small and correct. Then compare existing and alternative approaches and complete the desk review and required lifecycle ownership checks without executing tests, imports, examples, reproductions, benchmarks, service calls, or another runtime-probe skill. If decision-relevant runtime evidence remains, stop with a Preliminary assessment and suggest a separate runtime investigation by stating the unresolved question, decision impact, evidence needed, and control. Do not plan a command, request probe approval, execute code, or invoke another skill from this review. Compare credible competing PRs, recommend the best maintainer action, and include an English comment draft when closure or changes are needed."
+  default_prompt: "Use $maintainer-review to verify the demonstrated need and practical impact for this issue or PR, keep the assessment desk-review-only, recommend the maintainer action, and provide a copy-ready English comment when changes, evidence, or closure are needed."

.agents/skills/runtime-behavior-probe/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: runtime-behavior-probe
-description: Plan and execute runtime-behavior investigations with temporary probe scripts, validation matrices, state controls, and findings-first reports. Use only when the user explicitly invokes this skill to verify actual runtime behavior beyond normal code-level checks, especially to uncover edge cases, undocumented behavior, or common failure modes in local or live integrations. A baseline smoke check is fine as an entry point, but do not stop at happy-path confirmation.
+description: Plan and, after explicit approval, execute runtime-behavior probes for local or live integrations. Use only when explicitly invoked to verify behavior that code review and normal tests cannot settle; define a controlled validation matrix and report observed evidence.
 ---
 
 # Runtime Behavior Probe
@@ -40,8 +40,9 @@ Use this skill to investigate real runtime behavior, not to restate code or docu
 
 1. Restate the investigation target in operational terms. Name the runtime surface, the key uncertainty, and the highest-risk behaviors to test.
 2. Do a short preflight. Check the relevant code or docs first, decide whether the question needs local or live validation, and note any repo, baseline, or release boundary that matters.
-3. Create a validation matrix before executing probes. Cover both baseline behavior and the most relevant failure or drift cases. The matrix can live in a scratch note, a temporary file, or a structured header inside the probe script.
-4. For each case, choose an execution mode up front:
+3. Define the decision signal before building the matrix. For a suspected defect, name the exact user-visible symptom, the command or probe that can distinguish it from correct behavior, the expected failing observation, and a known-good control. Confirm that the signal exercises the real producer and caller path rather than only an adjacent helper. Prefer a fast, deterministic local loop when one can answer the question. If no credible signal can be built, state the missing access or artifact and do not substitute a nearby behavior as proof.
+4. Create a validation matrix before executing probes. Cover both baseline behavior and the most relevant failure or drift cases. The matrix can live in a scratch note, a temporary file, or a structured header inside the probe script.
+5. For each case, choose an execution mode up front:
    - `single-shot` for deterministic one-run checks.
    - `repeat-N` for cache, retry, streaming, interruption, rate-limit, concurrency, or other run-to-run-sensitive behavior.
    - `warm-up + repeat-N` when first-run cold-start effects could distort the result.
@@ -50,23 +51,23 @@ Use this skill to investigate real runtime behavior, not to restate code or docu
    - Decision-grade latency or release recommendation: `warm-up + repeat-10`.
    - Costly live cases: start at `repeat-3`, then expand only if the answer remains unclear.
    If it is genuinely unclear whether extra runs are worth the time or cost, ask the user before expanding the probe.
-5. When the question is benchmark-like or comparative, run in phases. Start with a high-signal pilot matrix against a control, then expand only the surviving candidates or unresolved cases.
-6. If the question is about a suspected regression or behavior change, add at least one known-good control case such as `origin/main`, the latest release, or the same request without the suspected option.
-7. For comparative probes, define parity before execution. Record prompt or input shape, tool-choice setup, model-settings parity, state reuse rules, and any response-shape constraint that keeps the comparison fair. If materially different output length could bias the result, record usage or token notes too.
-8. If the question asks whether one option has the same intelligence or quality as another, decide whether the matrix supports only example-pattern parity or a broader quality claim. For broader claims, add at least one harder or more open-ended case. Otherwise say explicitly that the result is limited to the covered patterns.
-9. Plan state controls before execution when hidden state could affect the result. Record whether each case uses fresh or reused state, how cache reuse or cache busting is handled, what unique IDs isolate repeated runs, and how cleanup is verified.
-10. If any live case will read environment variables, list the exact variable names and purpose for each case, then ask the user for approval before execution. Prefer `request_user_input` for this gate when it is available, with no auto-resolution and choices that grant or deny only this specific probe. Keep the approval ask short and include destination, read-only versus mutating or costly risk, exact variable names, and cleanup or rollback if relevant.
-11. Build task-specific probe scripts in a temporary location. Keep the script small, observable, and easy to discard.
-12. In `openai-agents-python`, make the runtime context explicit:
+6. When the question is benchmark-like or comparative, run in phases. Start with a high-signal pilot matrix against a control, then expand only the surviving candidates or unresolved cases.
+7. If the question is about a suspected regression or behavior change, add at least one known-good control case such as `origin/main`, the latest release, or the same request without the suspected option.
+8. For comparative probes, define parity before execution. Record prompt or input shape, tool-choice setup, model-settings parity, state reuse rules, and any response-shape constraint that keeps the comparison fair. If materially different output length could bias the result, record usage or token notes too.
+9. If the question asks whether one option has the same intelligence or quality as another, decide whether the matrix supports only example-pattern parity or a broader quality claim. For broader claims, add at least one harder or more open-ended case. Otherwise say explicitly that the result is limited to the covered patterns.
+10. Plan state controls before execution when hidden state could affect the result. Record whether each case uses fresh or reused state, how cache reuse or cache busting is handled, what unique IDs isolate repeated runs, and how cleanup is verified.
+11. If any live case will read environment variables, list the exact variable names and purpose for each case, then ask the user for approval before execution. Prefer `request_user_input` for this gate when it is available, with no auto-resolution and choices that grant or deny only this specific probe. Keep the approval ask short and include destination, read-only versus mutating or costly risk, exact variable names, and cleanup or rollback if relevant.
+12. Build task-specific probe scripts in a temporary location. Keep the script small, observable, and easy to discard.
+13. In `openai-agents-python`, make the runtime context explicit:
    - Run Python probes from the repository root with `uv run python` when practical.
    - Record the current commit, working directory, Python executable, and Python version.
    - Avoid accidental imports from a different checkout or site-packages location. If you must deviate from `uv run python`, say exactly why and what interpreter or environment was used instead.
-13. Present the complete probe proposal with the disclosures required above, including the exact command for each case or approved matrix, then ask the user for explicit approval and wait.
-14. Execute only the approved matrix and capture evidence. Record request shape, setup, observation summary, unexpected or negative result, error details, timing, runtime context, approved environment-variable names, repeat counts, warm-up handling, variance when relevant, cleanup behavior, and for comparisons note what was held constant plus any response-shape or usage notes that affect interpretation.
-15. Update the matrix with actual outcomes, not guesses.
-16. Keep temporary artifacts until the final response is drafted. Then delete them unless the user asked to keep them or they are needed for follow-up. Benchmark and repeat-heavy probes often need follow-up, so keeping artifacts is normal when the result may be revisited. If deleted, retain and report a short run summary.
-17. Report findings first, with unexpected or negative findings first. Then summarize how the validation was performed and which cases were covered.
-18. If the probe isolates one clear defect, you may include a short implementation hypothesis or minimal repro direction. Do not expand into a larger next-step plan unless the user asked for it.
+14. Present the complete probe proposal with the disclosures required above, including the exact command for each case or approved matrix, then ask the user for explicit approval and wait.
+15. Execute only the approved matrix and capture evidence. Record request shape, setup, observation summary, unexpected or negative result, error details, timing, runtime context, approved environment-variable names, repeat counts, warm-up handling, variance when relevant, cleanup behavior, and for comparisons note what was held constant plus any response-shape or usage notes that affect interpretation.
+16. Update the matrix with actual outcomes, not guesses.
+17. Keep temporary artifacts until the final response is drafted. Then delete them unless the user asked to keep them or they are needed for follow-up. Benchmark and repeat-heavy probes often need follow-up, so keeping artifacts is normal when the result may be revisited. If deleted, retain and report a short run summary.
+18. Report findings first, with unexpected or negative findings first. Then summarize how the validation was performed and which cases were covered.
+19. If the probe isolates one clear defect, you may include a short implementation hypothesis or minimal repro direction. Do not expand into a larger next-step plan unless the user asked for it.
 
 ## Validation Matrix
 

.agents/skills/runtime-behavior-probe/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Runtime Behavior Probe"
   short_description: "Plan and run runtime behavior probes"
-  default_prompt: "Use $runtime-behavior-probe to plan an investigation of actual runtime behavior with a validation matrix and explicit state controls. Before executing every probe, disclose the source identity, exact command, transitively executed material, available filesystem, environment, network, and host-service capabilities, side effects, and control, then wait for explicit user approval of that exact probe or matrix. Invoking this skill is not execution approval. After approval, run only the approved scope and produce a findings-first report."
+  default_prompt: "Use $runtime-behavior-probe to plan this runtime investigation; invocation authorizes planning only, so disclose the exact probe and capabilities and obtain explicit approval before execution, then report only observed evidence from the approved scope."
 policy:
   allow_implicit_invocation: false

.agents/skills/test-coverage-improver/SKILL.md

@@ -39,4 +39,4 @@ Use this skill whenever coverage needs assessment or improvement (coverage regre
 
 - Keep any added comments or code in English.
 - Do not create `scripts/`, `references/`, or `assets/` unless needed later.
-- If coverage artifacts are missing or stale, rerun `pnpm test:coverage` instead of guessing.
+- If coverage artifacts are missing or stale, rerun `make coverage` instead of guessing.