Codex Setting

Open Source Codex Setup | 오픈소스 Codex 세팅

[Contributing](./CONTRIBUTING.md) | [Changelog](./CHANGELOG.md) | [License](./LICENSE)

Overview | 개요

한국어
Codex Setting은 PRD 중심 실행, 계획 우선 구현, 검증 및 리뷰 게이트를 바탕으로 Codex 작업 흐름을 구성하고 싶은 팀과 개인을 위한 오픈소스 템플릿입니다.
바로 가져와서 프로젝트에 맞게 조정할 수 있도록 공개되어 있으며, 누구나 자유롭게 사용, 수정, 복제, 재배포할 수 있습니다.

English
Codex Setting is an open-source template for teams and individuals who want a Codex workflow built around PRD-driven execution, plan-first implementation, and an orchestrator-plus-worktree delivery model.
It is published to be cloned and adapted to real projects, and anyone is free to use, modify, copy, and redistribute it.

What Is Included | 포함 내용

• README.md: project overview and setup guide
• AGENTS.md: repository operating contract
• .agents/skills/: reusable Codex skills for PRD intake, planning, review, and release checks
• .codex/agents/: core agent definitions for orchestration, exploration, builders, and reviewers
• .codex/config.toml: Codex project configuration
• WORKTREES/README.md: worktree layout and cleanup conventions
• TEAM/: lightweight multi-worktree coordination guidance and state examples
• PRD/: PRD template files
• PLANS/: plan template and planning guidance
• NOTICE.md: short bilingual open-source usage notice
• LICENSE: MIT license text

Who This Is For | 이런 경우에 잘 맞습니다

한국어
다음과 같은 흐름을 원하는 경우에 특히 잘 맞습니다.

• PRD를 기준으로 구현 범위를 정리하고 싶은 경우
• 구현 전에 계획과 검증 단계를 명확히 두고 싶은 경우
• 오케스트레이터는 메인 체크아웃에서 유지하고 구현은 작업별 워크트리로 분리하고 싶은 경우
• QA 및 보안 리뷰를 Codex 작업 절차에 포함하고 싶은 경우
• 저장소별 운영 규칙을 문서로 남기고 싶은 경우

English
This template is especially useful if you want to:

• anchor implementation to a PRD
• require planning and validation before coding moves too far
• keep orchestration in the primary checkout and implementation in per-task worktrees
• include QA and security review in the Codex workflow
• keep repository-specific operating rules documented in one place

Default Operating Model | 기본 작업 방식

한국어

• 메인 체크아웃에서는 PRD 확인, 계획 수립, 에이전트 라우팅을 진행합니다.
• 실제 구현은 승인된 계획마다 별도 git worktree에서 수행합니다.
• 하나의 구현 워크트리는 하나의 빌더 에이전트가 전담합니다.
• 병렬 구현이 필요하면 구현 lane, 검증 lane, 리뷰 lane을 분리합니다.
• tmux 같은 별도 런타임 없이도 .coord/ 상태 파일로 handoff와 진행 상태를 기록할 수 있습니다.
• 리뷰와 검증은 변경이 들어간 워크트리 기준으로 실행합니다.

English

• Use the primary checkout for PRD intake, planning, and orchestration.
• Do implementation in a dedicated git worktree for each approved task.
• Keep one builder agent responsible for one worktree.
• Split implementation, evidence, and review lanes when parallel execution is justified.
• Use lightweight .coord/ state files when the team needs resumable coordination without a heavy runtime.
• Run validation and review against the worktree that contains the change.

Borrowed Ideas | 차용한 아이디어

한국어

이 템플릿은 oh-my-codex 같은 더 무거운 팀 런타임에서 유용한 요소만 골라 경량화해서 반영합니다.

• lane마다 전용 worktree를 둡니다.
• 리더 워크스페이스가 더럽다면 새 worktree fanout을 시작하지 않습니다.
• 팀 실행 상태는 .coord/team/<team-name>/ 아래의 단순 JSON과 JSONL 파일로 남깁니다.
• 구현 lane 외에 검증 lane을 별도로 두는 것을 권장합니다.
• 각 lane은 종료 전에 handoff 메모와 검증 결과를 남깁니다.

English

This template selectively borrows useful ideas from heavier orchestration systems such as oh-my-codex and keeps them lightweight.

• Give each lane its own dedicated worktree.
• Do not fan out new worktrees from a dirty leader workspace.
• Persist team state in simple JSON and JSONL files under .coord/team/<team-name>/.
• Prefer a separate evidence lane when parallel execution is justified.
• Require each lane to leave behind a handoff note and validation evidence.

Quick Start | 빠른 시작

한국어

1. 이 저장소를 클론하거나 복제합니다.
2. AGENTS.md를 팀의 운영 규칙에 맞게 수정합니다.
3. .codex/config.toml과 WORKTREES/README.md를 읽고 워크트리 운영 규칙을 정합니다.
4. 필요하면 훅, 검증 규칙, 리뷰 절차를 추가합니다.
5. 실제 프로젝트에서 템플릿으로 사용합니다.

English

1. Clone or copy this repository.
2. Adjust AGENTS.md to match your team’s working rules.
3. Update .codex/config.toml and WORKTREES/README.md for your project environment.
4. Add hooks, validation rules, or review steps only if your team needs them.
5. Use the result as a starting point in your real project.

Customization | 커스터마이징

한국어
이 템플릿은 시작점을 제공하는 용도이며, 그대로 고정해서 쓰기보다 각 팀의 제품 특성과 배포 방식에 맞게 조정하는 것을 권장합니다.
예를 들어 다음과 같은 항목을 변경할 수 있습니다.

• 리뷰 게이트의 적용 기준과 순서
• 워크트리 경로와 브랜치 명명 규칙
• .coord/ 상태 파일 유지 범위와 청소 규칙
• 검증 명령과 승인 절차
• 저장소별 문서 규칙
• 훅과 자동화 수준

English
This template is meant to be a starting point, not a rigid standard.
You are encouraged to adapt it to your team’s product constraints and delivery model.
Typical customization points include:

• review thresholds and gate ordering
• worktree path and branch naming rules
• .coord/ state retention and cleanup rules
• validation commands and approval steps
• repository documentation rules
• hook behavior and automation level

Contributing | 기여 안내

한국어
기여를 원하면 먼저 CONTRIBUTING.md를 확인해주세요.
문서 개선, 설정 정리, 스킬 추가, 에이전트 개선 모두 환영합니다.

English
If you want to contribute, start with CONTRIBUTING.md.
Documentation improvements, setup refinements, new skills, and agent improvements are all welcome.

License | 라이선스

한국어
이 저장소는 MIT License로 배포됩니다.
즉, 출처 고지 조건 아래 자유롭게 사용, 수정, 복제, 재배포할 수 있습니다.

English
This repository is distributed under the MIT License.
That means it can be used, modified, copied, and redistributed as long as the license terms are preserved.

Notes | 참고

한국어
현재 기본 템플릿은 특정 언어 런타임에 의존하지 않도록 훅 없이 구성되어 있습니다.
필요하다면 각 팀의 정책에 맞춰 훅, 검증 규칙, 승인 절차를 추가해 사용할 수 있습니다.

English
The default template does not depend on a specific runtime for hooks.
If needed, teams can add hooks, validation rules, or approval steps to match their own policy.