cursor-groupthink

Multi-model peer review for AI-assisted development: stress-test a plan with multiple independent frontier models before a single line is executed.

Why

Single models have blind spots — and so do single reviewers. Running a plan through 2–3 different models (each with different architectures, training data, and failure modes) catches edge cases, deflates over-confidence, and surfaces better alternatives, like a team of senior engineers reviewing each other's designs.

   Plan                Review (parallel)          Synthesize            Execute
┌───────────┐      ┌──────────────────────┐    ┌──────────────┐
│ primary   │      │ model A ──► review A │    │ primary model│
│ model     │ ───► │ model B ──► review B │ ─► │ triages every│ ───►  build it
│ writes    │      │ model C ──► review C │    │ finding into │
│ plan.md   │      │  (independent files) │    │ plan_v2.md   │
└───────────┘      └──────────────────────┘    └──────────────┘

Each finding is triaged explicitly: incorporate, defer (with reason), or won't do (with reason). Conflicting reviews don't cancel out — they get adjudicated on the record.

Quick Start

1. Plan — Tell primary model what you want → writes plan_{{TOPIC}}.md
2. Review — Paste review prompt into multi-model chat (Agent mode)
3. Check — Verify expected review files exist before proceeding
4. Synthesize — Primary model reads all files → creates plan_{{TOPIC}}_v2.md

No copy-paste needed between steps — everything is file-based.

A real run, preserved in this repo

This workflow was used on itself. .cursor/archive/ contains a complete review cycle for this repo's portability refactor:

• The original plan: plan_portability.md
• Independent reviews from Claude Opus, Claude Sonnet, and Gemini Pro: reviews_portability_*.md
• The synthesized result: plan_portability_v2.md

Read them in order to see exactly what the workflow produces.

---

New Project Setup

Option 1: Run the Setup Script (Easiest)

# From anywhere, run:
/path/to/cursor-groupthink/setup.sh /path/to/your-new-project

# Or if you're in the new project directory:
/path/to/cursor-groupthink/setup.sh .

Option 2: Add to PATH (Run from Anywhere)

# Add to your shell profile (~/.zshrc or ~/.bashrc):
export PATH="$PATH:/path/to/cursor-groupthink"

# Then from any project:
cd /path/to/new-project
setup.sh .

Option 3: Git Submodule (Recommended for Multiple Projects)

Use this approach if you want to keep the workflow in sync across multiple projects:

# Add as submodule
git submodule add https://github.com/kevglynn/cursor-groupthink.git .cursor-groupthink
git submodule update --init --recursive

# Run the submodule setup script
.cursor-groupthink/setup-submodule.sh

This creates symlinks so updates to the workflow automatically propagate. See SUBMODULE_SETUP.md for details.

Option 4: Manual Copy

cp -r /path/to/cursor-groupthink/.cursor /path/to/new-project/
cp /path/to/cursor-groupthink/.cursorrules /path/to/new-project/

Verify Setup

Open a new Cursor chat in the project and ask:

"What project rules are active?"

You should see "Peer Review Workflow Rules".

---

Files

Path	Purpose
setup.sh	One-command setup for new projects (copies files)
setup-submodule.sh	Setup script for git submodule usage (creates symlinks)
SUBMODULE_SETUP.md	Detailed guide for submodule setup
.cursorrules	Project rules (auto-loaded by Cursor)
.cursor/prompts/peer_review_prompt.md	All prompts (plan, review, synthesize)
.cursor/archive/plan_<topic>.md	Original plan
.cursor/archive/plan_<topic>_v2.md	Updated plan after synthesis
.cursor/archive/reviews_<topic>_<model>_<ts>.md	Individual reviews

---

Lessons Learned

• Concurrent writes overwrite — Use unique filenames (model + timestamp), not single file.
• LLM "random" isn't random — Use timestamps, not model-generated strings.
• Keep originals — Synthesis creates _v2.md, preserving the original for comparison.
• Project-scoped rules only — Don't modify global User Rules; keep everything in .cursorrules for portability.
• Planner/Executor conflict — Review prompt now explicitly tells models to ignore Planner/Executor rules.

---

Compatibility

Works with existing Planner/Executor workflows. The review prompt includes instructions to bypass Planner/Executor mode selection.