/codex-team Lifecycle · charter-as-truth และ proven recipe

สายเลือดของสูตร · The knowledge-transfer chain

สูตรนี้ไม่ได้เกิดวันเดียว — มันวิวัฒน์มาเป็นขั้น แต่ละขั้นเพิ่มบทเรียน. ขั้นสุดท้าย (arra) คือที่ scale ขึ้นไป 7 coders แล้วเจอ trap ครบทุกข้อในงานจริง 115 PRs.

The recipe did not appear in a day — it evolved in stages, each adding a lesson. The final stage (arra) scaled to 7 coders and hit every trap in a real 115-PR session.

Charter YAML ≠ Config JSON · บทเรียนที่เจ็บที่สุด

กฎแกนกลางทั้งเล่ม: charter คือความจริงหนึ่งเดียว. ไฟล์ที่คุม spawn คือ ψ/teams/*.yaml — ไม่ใช่ ~/.claude/teams/*.json ซึ่งเป็นแค่ registry/skeleton. Session เคยพลาดตรงนี้: ไปหา ~/.claude/teams/ แล้วสร้างทีมใหม่ทับของจริง.

The book's core rule: the charter is the single source of truth. The file that controls spawning is ψ/teams/*.yaml — not ~/.claude/teams/*.json, which is only a registry/skeleton. The painful miss: going to ~/.claude/teams/ and creating a new team that overwrote the real one.

5 actions ของ /codex-team SKILL.md · the executable lifecycle

/codex-team เป็น executable version ของหนังสือ — charter auto-discovery บวกห้าคำสั่ง lifecycle. จำคู่ที่สลับกันบ่อย: preflight ใช้ PATH, up/down ใช้ NAME — สลับกันคือ trap.

/codex-team is the executable version of the book — charter auto-discovery plus five lifecycle actions. Remember the pair people swap: preflight takes a PATH, up/down take a NAME — swapping them is a trap.

7 traps ที่จ่ายค่าเรียนไปแล้ว · the seven traps

ทุก trap ในรายการนี้มีเวลาที่เสียไปจริงในงาน arra — ไม่ใช่ทฤษฎี. กันไว้ก่อนดีกว่าไล่ debug ทีหลัง.

Every trap below cost real time in the arra session — not theory. Cheaper to guard against than to debug after.

1. charter-before-verification — เขียน task ก่อนตรวจ codebase · writing the task before checking the codebase.
2. omx-resume ขาด --yolo --direct · the resume command missing its flags.
3. dead-state replay งานเก่า · a dead tile replaying old work on wake.
4. bun test เจอ ghost files จาก worktree — scope bun test tests/http/<cluster>/ · ghost files from sibling worktrees; scope the test path.
5. symlink กลายเป็นไฟล์จริง · a symlink silently becoming a real file.
6. no-force-push บน diverged branch — ใช้ --force-with-lease · push --force-with-lease, never raw force.
7. silent omx launch failures — omx รับงานทาง maw hey เท่านั้น, team send = silent no-op.

Bonus (staging hygiene): git checkout -b ขณะ staging dirty → abort + staging เปื้อน. แก้: git status ก่อน git checkout -b ทุกครั้ง · run git status before every git checkout -b.

กฎการ scale · add a lead, not a coder

Scaling insight ที่สำคัญที่สุด: sweet spot = 3–4 coders ต่อ 1 lead. 7 coders ทำได้ แต่ lead ใช้เวลาเกือบทั้งหมดไปกับ dispatch + review จน throughput ไม่โต. ต้องการมากกว่านั้น → เพิ่ม lead ไม่ใช่เพิ่ม coder.

The key scaling insight: the sweet spot is 3–4 coders per lead. Seven coders works, but the lead spends almost all its time dispatching and reviewing, so throughput stops growing. Need more → add a lead, not another coder.

ทำไมมันถึงเวิร์ก + การ generalize · why it works

สรุปของทั้งเล่ม — pattern นี้ทำงานได้เพราะสามสิ่ง: charter = single source of truth, skip-live = zero interrupt (ปลุกเฉพาะตัวที่ต้องการด้วย --only), และ maw hey = reliable delivery ที่ไม่มี silent failure.

The book's closing: the pattern works because of three things — charter = single source of truth, skip-live = zero interrupt (wake only the tile you need via --only), and maw hey = reliable delivery with no silent failure.

ข้อควรระวังตอน adopt: SKILL.md ตอนนี้ยัง hard-wire กับ arra-oracle-v3 (session, repo, base, loop codex-1..7). จะใช้ข้ามทุก repo ต้อง parametrize 3 ค่าจาก charter เอง: name: → team/session, project: → repo+base, member list → แทน loop 1..7 ตายตัว.

Adoption caveat: the SKILL.md is still hard-wired to arra-oracle-v3 (session, repo, base, a fixed codex-1..7 loop). To make it portable it must read three values from the charter: name: → team/session, project: → repo+base, and the member list instead of a fixed 1..7 loop.

Checklist

1. Edit the ψ/teams/*.yaml charter — never ~/.claude/teams/*.json; the charter is what actually spawns.
2. Pass a PATH to preflight and a NAME to up/down — swapping them is the most common trap.
3. Run git status before any git checkout -b; a dirty staging area aborts the branch and leaves the index dirty.
4. Scope tests to the cluster (bun test tests/http/<cluster>/) so sibling-worktree ghost files do not run.
5. Deliver work to a coder only via maw hey; team send is a silent no-op for omx tiles.
6. Push diverged branches with --force-with-lease, never raw --force.
7. Keep 3–4 coders per lead; to go bigger, add a lead, not another coder.