You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Run `$code-change-verification` before marking work complete when changes affect runtime code, tests, or build/test behavior.
27
20
@@ -33,21 +26,23 @@ Run it when you change:
33
26
34
27
You can skip `$code-change-verification` for docs-only or repo-meta changes (for example, `docs/`, `.codex/`, `README.md`, `AGENTS.md`, `.github/`), unless a user explicitly asks to run the full verification stack.
35
28
36
-
### `$openai-knowledge`
29
+
####`$openai-knowledge`
37
30
38
31
When working on OpenAI API or OpenAI platform integrations in this repo (Responses API, tools, streaming, Realtime API, auth, models, rate limits, MCP, Agents SDK or ChatGPT Apps SDK), use `$openai-knowledge` to pull authoritative docs via the OpenAI Developer Docs MCP server (and guide setup if it is not configured).
39
32
40
-
##Planning & ExecPlans
33
+
###ExecPlans
41
34
42
35
Call out potential backward compatibility or public API risks early in your plan and confirm the approach before implementing changes that could impact users.
43
36
44
37
Use an ExecPlan when work is multi-step, spans several files, involves new features or refactors, or is likely to take more than about an hour. Start with the template and rules in `PLANS.md`, keep milestones and living sections (Progress, Surprises & Discoveries, Decision Log, Outcomes & Retrospective) up to date as you execute, and rewrite the plan if scope shifts. If you intentionally skip an ExecPlan for a complex task, note why in your response so reviewers understand the choice.
45
38
46
-
## Overview
39
+
## Project Structure Guide
40
+
41
+
### Overview
47
42
48
43
The OpenAI Agents Python repository provides the Python Agents SDK, examples, and documentation built with MkDocs. Use `uv run python ...` for Python commands to ensure a consistent environment.
49
44
50
-
## Repo Structure & Important Files
45
+
###Repo Structure & Important Files
51
46
52
47
-`src/agents/`: Core library implementation.
53
48
-`tests/`: Test suite; see `tests/README.md` for snapshot guidance.
@@ -60,13 +55,38 @@ The OpenAI Agents Python repository provides the Python Agents SDK, examples, an
60
55
-`.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`: Pull request template to use when opening PRs.
61
56
-`site/`: Built documentation output.
62
57
63
-
## Testing & Automated Checks
58
+
## Operation Guide
59
+
60
+
### Prerequisites
61
+
62
+
- Python 3.9+.
63
+
-`uv` installed for dependency management (`uv sync`) and `uv run` for Python commands.
64
+
-`make` available to run repository tasks.
65
+
66
+
### Development Workflow
67
+
68
+
1. Sync with `main` and create a feature branch:
69
+
```bash
70
+
git checkout -b feat/<short-description>
71
+
```
72
+
2. If dependencies changed or you are setting up the repo, run `make sync`.
73
+
3. Implement changes and add or update tests alongside code updates.
74
+
4. Highlight backward compatibility or API risks in your plan before implementing breaking or user-facing changes.
75
+
5. Build docs when you touch documentation:
76
+
```bash
77
+
make build-docs
78
+
```
79
+
6. When `$code-change-verification` applies, run it to execute the full verification stack before marking work complete.
80
+
7. Commit with concise, imperative messages; keep commits small and focused, then open a pull request.
81
+
8. When reporting code changes as complete (after substantial code work), invoke `$pr-draft-summary` to generate the required PR summary block with change summary, PR title, and draft description.
82
+
83
+
### Testing & Automated Checks
64
84
65
85
Before submitting changes, ensure relevant checks pass and extend tests when you touch code.
66
86
67
87
When `$code-change-verification` applies, run it to execute the required verification stack from the repository root. Rerun the full stack after applying fixes.
68
88
69
-
### Unit tests and type checking
89
+
####Unit tests and type checking
70
90
71
91
- Run the full test suite:
72
92
```bash
@@ -81,7 +101,7 @@ When `$code-change-verification` applies, run it to execute the required verific
81
101
make mypy
82
102
```
83
103
84
-
### Snapshot tests
104
+
####Snapshot tests
85
105
86
106
Some tests rely on inline snapshots; see `tests/README.md` for details. Re-run `make tests` after updating snapshots.
87
107
@@ -94,14 +114,21 @@ Some tests rely on inline snapshots; see `tests/README.md` for details. Re-run `
94
114
make snapshots-create
95
115
```
96
116
97
-
### Coverage
117
+
####Coverage
98
118
99
119
- Generate coverage (fails if coverage drops below threshold):
100
120
```bash
101
121
make coverage
102
122
```
103
123
104
-
### Mandatory local run order
124
+
#### Formatting, linting, and type checking
125
+
126
+
- Formatting and linting use `ruff`; run `make format` (applies fixes) and `make lint` (checks only).
127
+
- Type hints must pass `make mypy`.
128
+
- Write comments as full sentences ending with a period.
129
+
- Imports are managed by Ruff and should stay sorted.
130
+
131
+
#### Mandatory local run order
105
132
106
133
When `$code-change-verification` applies, run the full sequence in order (or use the skill scripts):
107
134
@@ -112,7 +139,7 @@ make mypy
112
139
make tests
113
140
```
114
141
115
-
##Repo-Specific Utilities
142
+
### Utilities & Tips
116
143
117
144
- Install or refresh development dependencies:
118
145
```bash
@@ -133,57 +160,24 @@ make tests
133
160
make snapshots-fix
134
161
make snapshots-create
135
162
```
163
+
- Use `examples/` to see common SDK usage patterns.
164
+
- Review `Makefile` for common commands and use `uv run` for Python invocations.
165
+
- Explore `docs/` and `docs/scripts/` to understand the documentation pipeline.
166
+
- Consult `tests/README.md` for test and snapshot workflows.
167
+
- Check `mkdocs.yml` to understand how docs are organized.
136
168
137
-
## Style, Linting & Type Checking
138
-
139
-
- Formatting and linting use `ruff`; run `make format` (applies fixes) and `make lint` (checks only).
140
-
- Type hints must pass `make mypy`.
141
-
- Write comments as full sentences ending with a period.
142
-
- Imports are managed by Ruff and should stay sorted.
143
-
144
-
## Development Workflow
145
-
146
-
1. Sync with `main` and create a feature branch:
147
-
```bash
148
-
git checkout -b feat/<short-description>
149
-
```
150
-
2. If dependencies changed or you are setting up the repo, run `make sync`.
151
-
3. Implement changes and add or update tests alongside code updates.
152
-
4. Highlight backward compatibility or API risks in your plan before implementing breaking or user-facing changes.
153
-
5. Build docs when you touch documentation:
154
-
```bash
155
-
make build-docs
156
-
```
157
-
6. When `$code-change-verification` applies, run it to execute the full verification stack before marking work complete.
158
-
7. Commit with concise, imperative messages; keep commits small and focused, then open a pull request.
159
-
8. When reporting code changes as complete (after substantial code work), invoke `$pr-draft-summary` to generate the required PR summary block with change summary, PR title, and draft description.
160
-
161
-
## Pull Request & Commit Guidelines
169
+
### Pull Request & Commit Guidelines
162
170
163
171
- Use the template at `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`; include a summary, test plan, and issue number if applicable.
164
172
- Add tests for new behavior when feasible and update documentation for user-facing changes.
165
173
- Run `make format`, `make lint`, `make mypy`, and `make tests` before marking work ready.
166
174
- Commit messages should be concise and written in the imperative mood. Small, focused commits are preferred.
0 commit comments