--- description: Run multiple AI models in parallel, apply unanimous fixes, repeat until steady state or max 3 rounds. category: general --- flowchart TD _HEADER_[""]:::headerStyle classDef headerStyle fill:none,stroke:none subgraph _MAIN_[" "] direction LR %% Phase 1: Setup subgraph Setup["Phase 1: Setup"] ART[Choose Artifact] --> MODE{Review Mode?} MODE -->|Standard-based| RUB[Load Rubric] MODE -->|Accuracy-based| SRC[Load Source of Truth] RUB --> CFG[Configure Backends] SRC --> CFG end %% Phase 2: Parallel Council Round subgraph Round["Phase 2: Parallel Council Round"] CFG --> RUN[Run council] RUN --> CL[Claude] & GEM[Gemini] & CDX[Codex] & CURA[cursor-agent] CL & GEM & CDX & CURA --> PARSE[Parse Results] end %% Phase 3: Agreement Triage subgraph Triage["Phase 3: Agreement Triage"] PARSE --> UNAN{Unanimous Issues?} UNAN -->|All models agree| MFIX[Mandatory Fix] UNAN -->|Not unanimous| MAJ{Majority Issues?} MAJ -->|2 of 3 agree| DFIX[Discretionary Fix] MAJ -->|No required fixes| NOTE[Note Only] end %% Phase 4: Fix Loop subgraph Loop["Phase 4: Fix Loop"] MFIX & DFIX --> APPLY[Apply Fixes] NOTE --> CONV{Converged?} APPLY --> CONV CONV -->|Issues remain| RUN CONV -->|Clean round confirmed| STEADY[Steady State] CONV -->|Round > 3| STUCK[Report Unresolved] end click ART "#" "**Choose Artifact**\nWhat to review with the council:\n- Documentation files (`.md`, docstrings)\n- Source code files or modules\n- Pull request diff\n- Architecture decision records\n- Standards documents\n- API specs\n\nPass as a file path or PR number to `council`." click MODE "#" "**Review Mode**\n\n*Standard-based:* Check artifact against a written rubric (structure, naming, completeness, style). Use when the artifact should conform to defined rules.\n\n*Accuracy-based:* Check artifact for factual correctness against source code, config, or test output. Use when the artifact describes something that can be verified." click RUB "#" "**Load Rubric / Checklist**\nDefine what 'correct' looks like for standard-based review.\nExamples:\n- Docstring must have Args, Returns, Raises sections\n- All endpoints must have auth docs\n- No TODO comments in production code\n- Error messages must be user-facing\n\nStore as `.claude/rules/*.md` or inline in the prompt.\nAvoid subjective criteria — models need clear pass/fail signals." click SRC "#" "**Load Source of Truth**\nFor accuracy-based review, provide the authoritative source the artifact should match:\n- Source code the docs describe\n- Config files the docs reference\n- Test output the docs claim\n- Schema the API docs spec\n\n`council -C /path/to/repo --locked 'Does the doc at X accurately describe the code at Y?'`" click CFG "#" "**Configure Backends**\nDefault: claude, gemini, codex, cursor-agent (all 4 in parallel)\n\nSelect specific models:\n`council -t claude,gemini PROMPT`\n\nKey flags:\n- `--locked` — no shell execution or writes (recommended for reviews)\n- `--read-only` — read files, no writes\n- `--yolo` — unrestricted (for implementation tasks)\n- `--timeout 900` — extend for large codebases\n\nNeutral prompting: avoid priming models toward agreement." click RUN "#" "**Run Council (--locked)**\nQuery all backends in parallel with a neutral prompt:\n\n`council -C /path/to/artifact --locked 'Review for issues against the rubric. List specific problems found. If no issues, say NO ISSUES.'`\n\nNeutral prompt rules:\n- Ask 'Are there any issues?' not 'What is wrong?'\n- Request explicit NO ISSUES to distinguish from silence\n- Be specific about review criteria\n- Don't prime models toward agreement" click CL "#" "**Claude**\n`claude-sonnet` or `claude-opus` via Claude Code\nStrengths: reasoning, nuance, code understanding\n\nDefault backend in all council invocations." click GEM "#" "**Gemini**\n`gemini-2.5-pro` via Gemini CLI\nStrengths: large context window, code analysis\n\nRequires: `gemini` CLI installed and authenticated" click CDX "#" "**Codex**\n`o4-mini` or `gpt-4o` via OpenAI Codex CLI\nStrengths: code-specific reasoning, diff analysis\n\nRequires: `codex` CLI installed and authenticated" click CURA "#" "**cursor-agent**\nCursor's AI agent\nStrengths: IDE-aware, file navigation, code search\n\nRequires: Cursor IDE installed\nSubstitutable: `council --use-cursor` to route any backend through Cursor" click PARSE "#" "**Parse Results**\nCategorize findings by agreement level:\n- **Unanimous (all agree)** → mandatory fix\n- **Majority (2 of 3)** → fix at discretion\n- **Minority (1 of 3)** → note only, do not fix\n- **All say NO ISSUES** → STEADY STATE\n\nLog to worklog:\n`echo '[Round N] 2 mandatory, 1 discretionary' >> council-convergence.md`" click UNAN "#" "**Unanimous Issues?**\nAll models (3+) independently flag the same issue.\nThis is the strongest signal — fix required before next round.\nIf yes → MANDATORY FIX\nIf no → check for majority agreement" click MFIX "#" "**Mandatory Fix**\nAll models agreed on this issue — must be fixed.\nApply fix backed by evidence from model responses.\nDo NOT fix issues only one model flagged.\nDocument each fix: what was wrong, what changed, why." click MAJ "#" "**Majority Issues?**\n2 of 3 models agree on an issue.\nFix at your discretion — strong signal but not unanimous.\nIf yes → DISCRETIONARY FIX\nIf no (1 of 3 or none) → NOTE ONLY → run more rounds to confirm" click DFIX "#" "**Discretionary Fix**\n2 of 3 models agree — apply if the issue seems valid.\nSkip if it conflicts with context the models lack.\nDocument your decision either way." click NOTE "#" "**Note Only**\nNo unanimous or majority issues found this round.\nDo NOT fix anything — but this does not mean convergence yet.\n\nLog minority findings for reference:\n`echo '[Round N] minority: model X flagged Y' >> council-convergence.md`\n\nProceed to convergence check — may need another round to confirm clean." click APPLY "#" "**Apply Fixes**\nUpdate the artifact based on mandatory (and optionally discretionary) fixes.\nIncrement round counter.\n\n- Mandatory: always apply\n- Discretionary: apply if clearly correct\n- Minority: note in worklog, do NOT apply\n\nCommit after applying to preserve history." click CONV "#" "**Converged?**\nChecks three conditions:\n\n*Issues remain (round <= 3):* Fixes were applied or minority issues exist — run council again on the updated artifact.\n\n*Clean round confirmed:* This round produced no required fixes AND either: the previous round was also clean, OR all models explicitly said NO ISSUES. → STEADY STATE\n\n*Round > 3:* Max rounds exceeded with issues still present. → REPORT UNRESOLVED\n\nMax 3 rounds prevents infinite loops. Remaining issues after 3 rounds typically require human judgment." click STEADY "#" "**Steady State**\nConvergence achieved — consecutive clean rounds with no required fixes.\nArtifact passes the council review.\n\n`echo '[STEADY] Round N - confirmed clean' >> council-convergence.md`" click STUCK "#" "**Report Unresolved**\nMax rounds exceeded with issues remaining.\nReport:\n- Which issues persisted across all rounds\n- Which models flagged them\n- Why they could not be resolved automatically\n\nEscalate to human review or accept as known limitations.\n`cat council-convergence.md` to review full round history." classDef setup fill:#d1ecf1,stroke:#7ec8d8 classDef council fill:#dfe6ff,stroke:#5b7bce classDef triage fill:#fff3cd,stroke:#f0c040 classDef fix fill:#ffeaa7,stroke:#e0c040 classDef approved fill:#d4edda,stroke:#5cb85c classDef flagged fill:#f8d7da,stroke:#e06070 class ART,MODE,RUB,SRC,CFG setup class RUN,CL,GEM,CDX,CURA,PARSE council class UNAN,MAJ triage class MFIX,DFIX,NOTE,APPLY,CONV fix class STEADY approved class STUCK flagged end style _MAIN_ fill:none,stroke:none,padding:0 _HEADER_ ~~~ _MAIN_