Multi-agent autonomous workflow: Claude Code + Codex coordination pattern

[broszkowski]

Draft: gstack GitHub Issue

Repo: https://github.com/garrytan/gstack
Type: Feature / Pattern Documentation

---

Title

Multi-agent autonomous workflow: Claude Code + Codex coordination pattern

Body

Hey @garrytan — love what you've built with gstack. We've been running it on a production veterinary SaaS (two repos, Node.js backend + React frontend) and developed a coordination pattern for running two agents together that might be useful to the community.

The problem

gstack skills (/review, /ship, /design-review) are write-capable — they auto-fix code, commit, push. This is great for single-agent use, but breaks when you have Codex implementing on codex/* branches and Claude Code reviewing on claude/* branches. Running /review on Codex's branch means Claude is writing on another agent's branch — violating ownership rules and creating merge confusion.

What we built

A branch transfer model that cleanly separates the two agents:

1. Codex implements on codex/* branch, pushes
2. Claude Code reviews via git diff (READ-ONLY — never checkouts codex branch)
3. If issues → writes REVIEW.md → Codex fixes → repeat (max 3x)
4. If approved → Claude Code creates claude/ship-wave-NN from base
5. Merges codex work into claude/* branch
6. NOW runs /review, /design-review (write-capable, safe on own branch)
7. /ship from claude/* branch → PR

Key insight: gstack's write-capable skills only run AFTER merge to the reviewing agent's own branch. The iteration loop (steps 2-3) is pure read-only diff analysis. This preserves full branch ownership while using gstack's auto-fix capabilities.

Other patterns that might be useful

1. Gate vocabulary mapping

gstack skills output DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT. Our autonomous workflow maps these to domain gates:

gstack output	Workflow gate
DONE (0 critical findings)	APPROVED
DONE_WITH_CONCERNS or findings > 0	NEEDS_WORK
BLOCKED	Escalate to human
NEEDS_CONTEXT	Provide context, re-run

This could be documented in gstack for teams building their own orchestration on top of skills.

2. Wave-based task specs

Each unit of work is a structured markdown file with YAML frontmatter:

wave: 01
title: booking-sms-retry
repo: backend
branch: codex/booking-sms-retry
critical: false          # triggers /codex challenge
behavior_change: true    # triggers spec-first workflow
paired_wave: null        # cross-repo linkage

Plus required sections: specs to read, acceptance criteria, verification commands (pre_commit + review_gate), contract impacts. This gives Codex everything it needs to implement without asking questions.

3. Review checklist template

We created domain-specific .claude/skills/review/checklist.md files structured as:

• Critical (ASK, never AUTO-FIX) — security, data integrity, spec compliance
• Informational (lean toward AUTO-FIX) — missing types, unused imports
• DO NOT flag — formatting, style preferences

This makes /review much more effective for specialized projects.

What we're NOT proposing

• Changes to gstack core code
• New skills that need to be maintained
• Anything VetOS-specific

This is purely a pattern documentation contribution — a reference for teams using gstack with multiple agents.

Questions for you

1. Would this fit as a doc in the gstack repo (e.g., docs/MULTI_AGENT_WORKFLOW.md)?
2. Or better as a standalone blog post / example repo that links to gstack?
3. Is anyone else in the community running multi-agent setups with gstack?

Happy to write a PR if there's interest. We've battle-tested this through 3 rounds of adversarial review (Claude Code wrote it, Codex challenged it, repeat until both agreed).

---

Built with gstack + Claude Code (Opus 4.6) + Codex (GPT-5.4)

[jordan-romeroporter]

why not just share it, and see if it sticks? what's the point in asking for permission.

Btw i think this sounds great, but this seems rhetorical in this age when people are building at light speed.