affaan-m--everything-claude-code/commands/multi-workflow.md

---
description: Run a full multi-model development workflow with research, planning, execution, optimization, and review.
---

# Workflow - Multi-Model Collaborative Development

Multi-model collaborative development workflow (Research → Ideation → Plan → Execute → Optimize → Review), with intelligent routing: Frontend → Gemini, Backend → Codex.

> **Prerequisite:** Requires the external `ccg-workflow` runtime, which is **not** part of the base ECC install. Initialize it with `npx ccg-workflow` to provision `~/.claude/bin/codeagent-wrapper` and the `~/.claude/.ccg/prompts/*` role files this command depends on. Without that runtime, this command will not run correctly.

Structured development workflow with quality gates, MCP services, and multi-model collaboration.

## Usage

```bash
/workflow <task description>
```

## Context

- Task to develop: $ARGUMENTS
- Structured 6-phase workflow with quality gates
- Multi-model collaboration: Codex (backend) + Gemini (frontend) + Claude (orchestration)
- MCP service integration (ace-tool, optional) for enhanced capabilities

## Your Role

You are the **Orchestrator**, coordinating a multi-model collaborative system (Research → Ideation → Plan → Execute → Optimize → Review). Communicate concisely and professionally for experienced developers.

**Collaborative Models**:
- **ace-tool MCP** (optional) – Code retrieval + Prompt enhancement
- **Codex** – Backend logic, algorithms, debugging (**Backend authority, trustworthy**)
- **Gemini** – Frontend UI/UX, visual design (**Frontend expert, backend opinions for reference only**)
- **Claude (self)** – Orchestration, planning, execution, delivery

---

## Multi-Model Call Specification

**Call syntax** (parallel: `run_in_background: true`, sequential: `false`):

```
# New session call
Bash({
  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
EOF",
  run_in_background: true,
  timeout: 3600000,
  description: "Brief description"
})

# Resume session call
Bash({
  command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}resume <SESSION_ID> - \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
EOF",
  run_in_background: true,
  timeout: 3600000,
  description: "Brief description"
})
```

**Model Parameter Notes**:
- `{{GEMINI_MODEL_FLAG}}`: When using `--backend gemini`, replace with `--gemini-model gemini-3-pro-preview` (note trailing space); use empty string for codex

**Role Prompts**:

| Phase | Codex | Gemini |
|-------|-------|--------|
| Analysis | `~/.claude/.ccg/prompts/codex/analyzer.md` | `~/.claude/.ccg/prompts/gemini/analyzer.md` |
| Planning | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/architect.md` |
| Review | `~/.claude/.ccg/prompts/codex/reviewer.md` | `~/.claude/.ccg/prompts/gemini/reviewer.md` |

**Session Reuse**: Each call returns `SESSION_ID: xxx`, use `resume xxx` subcommand for subsequent phases (note: `resume`, not `--resume`).

**Parallel Calls**: Use `run_in_background: true` to start, wait for results with `TaskOutput`. **Must wait for all models to return before proceeding to next phase**.

**Wait for Background Tasks** (use max timeout 600000ms = 10 minutes):

```
TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
```

**IMPORTANT**:
- Must specify `timeout: 600000`, otherwise default 30 seconds will cause premature timeout.
- If still incomplete after 10 minutes, continue polling with `TaskOutput`, **NEVER kill the process**.
- If waiting is skipped due to timeout, **MUST call `AskUserQuestion` to ask user whether to continue waiting or kill task. Never kill directly.**

---

## Communication Guidelines

1. Start responses with mode label `[Mode: X]`, initial is `[Mode: Research]`.
2. Follow strict sequence: `Research → Ideation → Plan → Execute → Optimize → Review`.
3. Request user confirmation after each phase completion.
4. Force stop when score < 7 or user does not approve.
5. Use `AskUserQuestion` tool for user interaction when needed (e.g., confirmation/selection/approval).

## When to Use External Orchestration

Use external tmux/worktree orchestration when the work must be split across parallel workers that need isolated git state, independent terminals, or separate build/test execution. Use in-process subagents for lightweight analysis, planning, or review where the main session remains the only writer.

```bash
node scripts/orchestrate-worktrees.js .claude/plan/workflow-e2e-test.json --execute
```

---

## Execution Workflow

**Task Description**: $ARGUMENTS

### Phase 1: Research & Analysis

`[Mode: Research]` - Understand requirements and gather context:

1. **Prompt Enhancement** (if ace-tool MCP available): Call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for all subsequent Codex/Gemini calls**. If unavailable, use `$ARGUMENTS` as-is.
2. **Context Retrieval** (if ace-tool MCP available): Call `mcp__ace-tool__search_context`. If unavailable, use built-in tools: `Glob` for file discovery, `Grep` for symbol search, `Read` for context gathering, `Task` (Explore agent) for deeper exploration.
3. **Requirement Completeness Score** (0-10):
   - Goal clarity (0-3), Expected outcome (0-3), Scope boundaries (0-2), Constraints (0-2)
   - ≥7: Continue | <7: Stop, ask clarifying questions

### Phase 2: Solution Ideation

`[Mode: Ideation]` - Multi-model parallel analysis:

**Parallel Calls** (`run_in_background: true`):
- Codex: Use analyzer prompt, output technical feasibility, solutions, risks
- Gemini: Use analyzer prompt, output UI feasibility, solutions, UX evaluation

Wait for results with `TaskOutput`. **Save SESSION_ID** (`CODEX_SESSION` and `GEMINI_SESSION`).

**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**

Synthesize both analyses, output solution comparison (at least 2 options), wait for user selection.

### Phase 3: Detailed Planning

`[Mode: Plan]` - Multi-model collaborative planning:

**Parallel Calls** (resume session with `resume <SESSION_ID>`):
- Codex: Use architect prompt + `resume $CODEX_SESSION`, output backend architecture
- Gemini: Use architect prompt + `resume $GEMINI_SESSION`, output frontend architecture

Wait for results with `TaskOutput`.

**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**

**Claude Synthesis**: Adopt Codex backend plan + Gemini frontend plan, save to `.claude/plan/task-name.md` after user approval.

### Phase 4: Implementation

`[Mode: Execute]` - Code development:

- Strictly follow approved plan
- Follow existing project code standards
- Request feedback at key milestones

### Phase 5: Code Optimization

`[Mode: Optimize]` - Multi-model parallel review:

**Parallel Calls**:
- Codex: Use reviewer prompt, focus on security, performance, error handling
- Gemini: Use reviewer prompt, focus on accessibility, design consistency

Wait for results with `TaskOutput`. Integrate review feedback, execute optimization after user confirmation.

**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**

### Phase 6: Quality Review

`[Mode: Review]` - Final evaluation:

- Check completion against plan
- Run tests to verify functionality
- Report issues and recommendations
- Request final user confirmation

---

## Key Rules

1. Phase sequence cannot be skipped (unless user explicitly instructs)
2. External models have **zero filesystem write access**, all modifications by Claude
3. **Force stop** when score < 7 or user does not approve