chatgpt-team is a small public experiment in organizing the software-engineering capabilities currently available through ChatGPT and Codex into a repeatable, human-supervised workflow.
It is not an agent framework and it does not call the OpenAI API. The repository contains Codex custom-agent definitions, Agent Skills, review rules, validation procedures, and a few bootstrap helpers for exploring what the subscription products can do as they exist today.
The premise is deliberately modest: coding agents can be useful for planning, implementation, testing, browser validation, and review, but ordinary engineering controls still matter. Git history, isolated worktrees, deterministic tests, independent review, and human judgement remain part of the process.
Status: experimental capability research. ChatGPT and Codex change quickly, so product claims are kept in a dated capability ledger and should be re-verified against current OpenAI documentation.
This project is intentionally opinionated toward a web/systems stack rather than trying to cover every ecosystem:
- Elixir and Phoenix
- Phoenix LiveView
- Rust
- Svelte
- optional Next.js
Stack guidance is reusable. Project-specific architecture, commands, dependencies, and invariants stay in each project's own AGENTS.md.
human / product intent
|
v
Lead
|
+--> Planner ----------------------+
| |
+--> Engineer(s) ------------------+--> Reviewer
+--> UI Engineer ------------------+--> UI Validator
+--> Docs Writer ------------------+--> Reviewer
+--> QA ---------------------------+
| |
+--> Security Reviewer (when needed)
|
v
Integrator
|
final validation
|
pull request
|
human/repo policy
The roles are deliberately few. There is no separate "Rust agent" or "Elixir agent"; language and framework knowledge is supplied through skills. A normal implementation agent can therefore combine its role with stack-rust, stack-elixir, stack-phoenix-liveview, or another applicable skill.
See Agent roles.
- Human supervised. Agents do useful engineering work; humans retain product intent and consequential decisions.
- Evidence over claims. A change is not validated unless the relevant commands and user journeys were actually exercised.
- One writer, one worktree. Parallel writers do not share a checkout or branch.
- Independent review. Non-trivial production changes are reviewed independently from their author.
- Rendered UI matters. User-facing work is run and inspected rather than approved from source alone.
- Least privilege. Read-oriented roles stay read-oriented; writers are bounded to their worktrees.
- Project facts stay with the project. Shared process belongs here; local architecture and commands do not.
- Public by construction. This repository must remain safe to read in full by anyone.
AGENTS.md maintenance instructions for this repository
.codex/agents/ Codex custom-agent roles
.agents/skills/ workflow and stack Agent Skills
policies/ engineering, Git, review, security, permissions
scripts/ safe user-level bootstrap and diagnostics
templates/ project AGENTS, task, handoff, and PR templates
docs/ operating model and capability notes
tests/ instruction checks and generic evaluation fixtures
Clone the repository somewhere stable and inspect the bootstrap plan:
git clone https://github.com/refpath/chatgpt-team.git
cd chatgpt-team
./scripts/bootstrap.shThe first command is a dry run. If the proposed links look right:
./scripts/bootstrap.sh --apply
./scripts/doctor.shThe bootstrap helper links shared agents into ~/.codex/agents/, skills into ~/.agents/skills/, and creates a global ~/.codex/AGENTS.md only if one does not already exist. It deliberately does not touch authentication, ~/.codex/config.toml, MCP credentials, Git credentials, sandbox/approval settings, or an existing global instruction file.
Then give each actual project a small repository-local AGENTS.md containing its real architecture and commands. The template is intentionally incomplete so those facts must be filled in from the project itself.
More detail: Installation and consumption.
The central concurrency rule is:
one writer = one worktree = one branch
Writers hand off exact commit SHAs. Reviewers inspect committed state. QA gets a separate worktree when it needs to author tests. The Integrator assembles reviewed SHAs in a clean integration worktree rather than allowing several agents to mutate one checkout.
See Worktrees and concurrency and Git policy.
For user-facing work, the intended loop is:
code
-> build
-> start application
-> readiness check
-> open rendered UI
-> exercise the affected journey
-> inspect visual states and browser failures
-> run project-native browser/E2E tests
-> fix defects
-> repeat on the new SHA
-> report exact evidence
The built-in ChatGPT/Codex Browser is used where the current product surface supports it. Existing deterministic browser tooling such as Playwright can complement that. This repository does not require a project to adopt Node.js or Playwright merely to follow the workflow.
See UI and browser validation and the ui-validation skill.
Docs Writer handles substantial documentation with technical-writing, elixir-docs when applicable, and unslop. The workflow checks source contracts, examples, and rendered documentation while preserving a natural writing style and the public/internal API boundary. Small prose edits remain with their author. See Documentation workflow.
Engineer and QA share systematic-debugging; assigned structural changes use safe-refactor; Integrator uses package-readiness for library candidates. Existing planning and review skills trace changed contracts through callers, generated output, docs, and consumers. Elixir references cover OTP, ExUnit, and conditional dependency concerns without prescribing an architecture.
Maintainers can run instruction validation to check role and skill files and exercise generic scenarios. Structural checks and observed behavior are reported separately.
Use isolated live trials to exercise handoffs and recovery on synthetic projects. Completed research, audit reports, and run logs stay outside version control.
Two computers are treated as independent execution pools rather than a fixed frontend/backend split. A useful default is interactive implementation on one machine and independent QA/review/full builds on the other, with either machine available for extra implementation capacity.
Separate ChatGPT/Codex subscriptions remain separate accounts with their own sessions, limits, permissions, and remote connections. They coordinate through Git/GitHub and explicit handoffs; this project does not pretend they form one OpenAI-managed scheduler.
See Two-computer topology, Operating model, and Mobile supervision.
- replace developers or code review;
- turn every task into a multi-agent exercise;
- provide a universal stack or prompt collection;
- hide several repositories behind an artificial mega-workspace;
- add infrastructure solely for agent convenience;
- use OpenAI API keys or pay-per-token inference;
- bypass account, usage, approval, or sandbox limits.
Small changes should remain small. Parallel agents are useful when work is genuinely separable or when independent validation improves confidence.
Private repositories may be inspected to discover a general capability need, but material contributed here must be independently written and generalized so its source cannot be reconstructed.
Do not add credentials, tokens, cookies, authenticated browser state, private URLs, organization/repository inventories, proprietary architecture, business rules, schemas, internal prompts, or copied private source material.
See Public repository boundary and Security policy.
Current product assumptions are tracked in docs/capabilities.md. Primary references include official OpenAI documentation for:
- Codex custom agents and subagents
- Agent Skills
AGENTS.md- local/worktree/cloud environments
- Browser and Computer Use
- Codex Remote
- permissions and sandboxing
- GitHub and MCP integrations
The verification date matters. If the product documentation changes, the repository should change with it rather than preserving an old claim for compatibility with this README.
This repository is not the first attempt to make AI-assisted engineering workflows explicit and version-controlled. A few public projects informed the shape of the experiment, particularly OpenAI's own Codex/Skills material and GitHub's Spec Kit. The useful idea borrowed is the boring one: keep instructions, reusable capabilities, workflow artifacts, and validation expectations visible in Git instead of hiding them in one person's chat history.
Contributions are welcome when they keep the project small, verifiable, public-safe, and grounded in currently supported product behavior. Please read CONTRIBUTING.md first.
For security-sensitive reports, see SECURITY.md.
MIT. See LICENSE.
This is an independent open-source experiment and is not an official OpenAI project.