Reusable Codex roles, skills, and engineering workflows for working with ChatGPT and Codex under human supervision.
This repository puts planning, implementation, documentation, testing, and review into a shared set of instructions. Each project supplies its own architecture and commands; the shared workflow defines who owns the work, how it is checked, and when it is ready to hand off.
The setup is intended for subscription-authenticated Codex sessions and ordinary development tools. It contains configuration, documentation, and local helpers, with no OpenAI API inference runtime.
Status: experimental. Product assumptions, official sources, verification dates, and known limits are recorded in the capability ledger.
You need Git, Bash, a local Codex installation signed in through ChatGPT, and the tools your project already uses. Keep the clone somewhere stable: installation creates links back to it.
git clone https://github.com/refpath/chatgpt-team.git
cd chatgpt-team
./scripts/bootstrap.shRunning bootstrap.sh without arguments is a dry run. Review the proposed changes, then apply them:
./scripts/bootstrap.sh --apply
./scripts/doctor.shWith default paths, bootstrap links roles into ~/.codex/agents/ and skills into ~/.agents/skills/. It skips existing destinations and copies the global instruction template to ~/.codex/AGENTS.md when that file is absent. Authentication, ~/.codex/config.toml, and existing global instructions stay untouched.
doctor.sh checks for Git and Codex, reports optional stack tools, and lists instruction locations. It does not prove that a session loaded a particular role or skill.
In your own project, adapt the repository instruction template into an AGENTS.md with its actual setup, build, test, and start commands. Begin with a small task and inspect the result. For example:
Read this project's AGENTS.md and check the README setup instructions against
the actual configuration and scripts. Update any stale steps. Use
technical-writing and unslop, and report which commands you verified.
See installation for configuration paths, existing installations, and delegation settings. Bootstrap does not install this repository's .codex/config.toml into your projects or user configuration.
Small changes stay with one author. Larger work uses only the roles needed for the task:
- Define the outcome. The human sets the intent and constraints. Lead coordinates the work; Planner helps with acceptance criteria and interfaces when needed.
- Assign ownership. Each parallel writer gets a separate worktree and branch. Tasks that edit the same files are sequenced.
- Implement and check. Writers run the project's relevant checks and hand off the complete change with exact base and head commit SHAs, results, and unresolved risks.
- Review the candidate. Independent review covers non-trivial code and consequential documentation or instruction changes. UI and security work get the additional checks required by their scope.
- Integrate and validate. Integrator assembles the reviewed changes and checks the combined result. Later edits require renewed review and affected checks. Merge and deployment follow the project's policy.
The operating model, Git policy, and handoff template cover the details, including patch handoffs when a sandbox permits source edits but denies Git writes.
The repository provides ten roles with distinct responsibilities:
| Role | Responsibility |
|---|---|
| Lead | Own the plan, assignments, limits, and completion criteria |
| Planner | Define requirements, interfaces, risks, and task dependencies |
| Engineer | Implement a bounded change and run relevant checks |
| UI Engineer | Build user-facing changes and check the running interface |
| Docs Writer | Write documentation from verified source behavior and inspect rendered output |
| QA | Design regressions and test behavior independently |
| UI Validator | Exercise real user journeys and inspect the rendered application independently |
| Reviewer | Check correctness, compatibility, and maintainability |
| Security Reviewer | Review changes that affect a security boundary |
| Integrator | Assemble reviewed commits and validate the combined result |
Roles define responsibilities. The eighteen skills supply reusable methods for planning, debugging, refactoring, review, package checks, documentation, and parallel delivery. Stack guidance covers Elixir, Phoenix/LiveView, Rust, Svelte, and optional Next.js. Each project keeps its own architecture and toolchain.
Docs Writer combines technical-writing for structure and evidence, elixir-docs for Elixir API documentation and ExDoc, and unslop for the final prose edit. The documentation workflow checks examples, typespec agreement, public API boundaries, and generated pages. For UI work, browser validation requires running the application and exercising affected journeys with the tools available in that environment.
See the role guide for permissions and review requirements.
One coordinator owns the plan. Delegated tasks cannot start their own agents or nested model CLI sessions. The local coordination rules require:
- At most two active children, counting separate model CLI sessions too.
- A finite dispatch allowance set before work begins: four by default, sized to include required review and integration.
- At most two correction rounds, with run and task deadlines.
- Results tied to the exact task attempt and commit; stale or incomplete reviews cannot approve a replacement.
- Verified worker and process termination before replacement, and cleanup when the work finishes.
The project and Lead configuration cap open spawned threads at two, excluding the primary thread. Other roles disable delegation by default. These settings depend on the active client's configuration and runtime precedence; verify that the intended role and settings were loaded. See the official subagent documentation.
The wider allowances and cleanup rules require supervision. They do not provide a hard token ceiling, a limit across accounts, or automatic cleanup after a disconnected session. Follow the coordination rules and keep completed run records outside Git. Stop when acceptance criteria and required checks pass, or when the agreed limits are reached.
Maintainers use Python 3.11+ and PyYAML for structural checks:
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python scripts/validate-instructions.py
.venv/bin/python -m unittest discover -s tests -p 'test_*.py'These checks validate maintained role and skill contracts, coordination defaults, and local Markdown link targets. They do not establish live permissions or agent reliability. Consuming projects do not need these Python dependencies.
Use the instruction scenarios and isolated trial procedure to evaluate behavior on synthetic projects. Keep research, audit reports, logs, screenshots, and completed evaluations outside version control, even when sanitized.
| Task | Guide |
|---|---|
| Understand product support and limits | Capability ledger |
| Coordinate parallel writers | Worktrees |
| Work across repositories | Multi-repository changes |
| Use another computer or supervise remotely | Two computers · Mobile supervision |
| Consider an optional review service | External review |
| Change roles, skills, or validation | Instruction validation |
| Explore the project's influences | Related public work |
Read CONTRIBUTING.md before proposing a change. Keep instructions concise, verify product claims against current official OpenAI documentation, and use independently written examples. Credentials, private repository identities, copied private material, and run-specific research do not belong here. See the public repository boundary.
For security reports, follow SECURITY.md.
ChatGPT Team is an independent open-source project under the MIT license. It is not an official OpenAI project.