--- name: design-with-multiple-agents description: Multi-agent design collaboration — Claude Code (reviewer) and Codex (designer) iterate on a design doc via file-based chat. Gathers requirements from user, then runs a review loop until design is satisfactory. Args: --- # Design With Multiple Agents Create a design document through iterative collaboration between you (Claude Code, the reviewer) and Codex (the designer). You gather requirements, Codex drafts/revises, you review, repeat until the design is solid. ## Args `/design-with-multiple-agents ` - `` — short description of what needs designing. If missing, ask the user. ## Roles - **You (Claude Code)** — requirements gatherer, reviewer, quality gate. - **Codex** — designer, author of the design document. ## File Locations All files live in `.tmp/design-chat/`: - `brief.md` — requirements brief (you write this, seed for Codex) - `design.md` — the design document (Codex writes/revises this) - `review-N.md` — your review for round N (N = 1, 2, 3, ...) Create `.tmp/design-chat/` at the start. Clean up old contents if present. ## Step 1: Gather Requirements Ask the user targeted questions to understand: - **Goal** — what problem does this solve? - **Scope** — what is in/out of scope? - **Constraints** — performance, compatibility, dependencies, existing code patterns? - **Deliverables** — what artifacts result? (code, config, API, schema, etc.) - **Context** — relevant files, packages, or systems in the codebase? Keep questions focused. 3-5 questions max per round. Stop when you have enough to write a brief. ## Step 2: Write Brief Write `.tmp/design-chat/brief.md` containing: - Goal (1-2 sentences) - Scope (in/out) - Constraints - Deliverables - Relevant codebase context (file paths, package names, patterns observed) This file is the seed for Codex. ## Step 3: Codex Drafts Design Run Codex to create the initial design: ``` codex exec --sandbox workspace-write "Read .tmp/design-chat/brief.md. Based on the brief, \ create a detailed design document at .tmp/design-chat/design.md. \ Include: overview, proposed approach, data flow, key interfaces/types, \ file structure, edge cases, and open questions. \ For every major decision, state WHY — what alternatives were considered and why they were rejected. \ The reviewer will challenge any decision without a clear rationale. \ Read relevant source files referenced in the brief to ground the design in existing code." ``` Read `.tmp/design-chat/design.md` after Codex completes. ## Step 4: Review Read the design. Be adversarial — your job is to stress-test the reasoning, not rubber-stamp it. Challenge WHY before evaluating HOW. A well-implemented bad idea is worse than a rough sketch of the right idea. Write `.tmp/design-chat/review-N.md` (N = current round) with: - **Verdict**: `approved` or `revise` - **Why-challenges**: question the rationale behind key decisions: - Why this approach over alternatives? Were alternatives considered? - Why is this problem worth solving this way? Is the complexity justified? - Why these abstractions/boundaries? What would break if they were different? - Flag any decision that lacks stated rationale as `must-fix`. - **Strengths**: what the design gets right (be specific) - **Issues**: problems, gaps, contradictions, or missed requirements — each with: - severity: `must-fix` or `suggestion` - description of the issue - what the fix should address (not how — let Codex decide the how) - **Questions**: anything unclear or underspecified Criteria for `approved`: - Every major decision has a stated rationale (why, not just what) - Alternatives were considered and rejection reasons are clear - All requirements from the brief are addressed - No `must-fix` issues remain - Approach is feasible given constraints - Key interfaces/types are well-defined - Edge cases are handled or explicitly deferred with rationale ## Step 5: Codex Revises (if verdict = revise) Run Codex to revise: ``` codex exec --sandbox workspace-write "Read .tmp/design-chat/design.md (current design) \ and .tmp/design-chat/review-N.md (review feedback). \ Revise the design in-place at .tmp/design-chat/design.md to address all must-fix issues. \ Pay special attention to why-challenges — if the reviewer questioned your rationale, \ strengthen it with concrete reasoning or change the approach if you cannot justify it. \ Do not hand-wave — if you chose X over Y, explain what makes X better for THIS problem. \ Consider suggestions but use your judgment on those. \ Add a changelog section at the bottom noting what changed in this revision." ``` Read the revised design after Codex completes. ## Step 6: Loop or Finish - If verdict was `revise` → go back to Step 4 (increment N). - If verdict is `approved` → proceed to Report. Cap at **5 review rounds**. If still not `approved` after 5 rounds: - Report to user with current state - List remaining issues - Let user decide whether to continue, adjust requirements, or accept as-is ## Report Present to user: - **Design file**: `.tmp/design-chat/design.md` - **Review rounds**: count + final verdict - **Summary**: 3-5 sentence overview of the design - **Remaining concerns**: any `suggestion`-level items not addressed, or open questions Ask the user if they want to move the design to a permanent location (e.g., `docs/`). ## Rules - NEVER edit `design.md` yourself — only Codex writes/revises it. - NEVER skip the review step — always read and evaluate before approving. - NEVER approve a design with `must-fix` issues remaining. - ALWAYS ground reviews in the original brief — don't introduce new requirements mid-loop. - ALWAYS let Codex read relevant source files — don't paste large code blocks in prompts. - If Codex fails or times out, retry once. If still fails, report to user. - Keep Codex prompts focused. Reference file paths, don't inline content.