多模型AI辩论工具

Requirements

This toolkit runs on macOS, Linux, or WSL (Windows Subsystem for Linux). Windows users: install WSL first. Native Windows PowerShell also works for setup and all non-debate commands; only /ask-gpt and /ask-gemini require bash/WSL.

---

`/explore` - Understand before you build

Asks 3-4 focused questions about scope, success criteria, and constraints before any code is written. Has two modes: scoping (you have a concrete idea, pressure-test the scope) and vision (you're thinking big-picture, challenge the premise itself). It picks a mode by reading your input, then asks you to confirm. You can switch modes any time. Useful when you're not yet sure what you're actually building. When the conversation converges (no open questions left, and in vision mode a scope dial reading Hold or Reduce), it hands off to /create-plan on its own.

The design workflow. When the feature has a look (a page, a screen, a component), /explore runs a named "Design exploration" step. It checks whether your repo already has a design system and asks you once, then sets a load level: nothing to design, improve something that exists, or build something new. New work gets an idea list you react to, three seeded working prototypes side by side to pick from, and then, during /execute, a fresh-context design critic that scores each round until the design clears a bar or the round budget runs out. A repo that already has a design system keeps it: only layout, composition, motion, and copy vary, and anything further asks you first. Your repo's answers live in DESIGN-PROFILE.md, a file that is yours (seeded once by setup, never overwritten). Image and video generation are optional and sit behind your own keys; without a key the workflow hands you the prompt to run elsewhere and continues. The rules live in .claude/skills/shared/design-rules.md; the keys are covered in API-KEYS.md.

Full prompt: .claude/commands/explore.md

`/execute` - Build it, update the plan as you go

Walks through the plan step by step, updating status emojis and progress in real time. Spawns parallel agents for [parallel] steps, runs [sequential] steps in order. Small failures get at most 3 fix attempts per step. Stops on critical blockers (e.g. the plan assumed an API supports a feature it doesn't) instead of pushing through a broken plan. On a clean finish it hands off to /review; on a blocker it stops there and asks you.

Full prompt: .claude/commands/execute.md

Manual Setup (run the script yourself)

Prefer to run the setup script yourself? Pick the script that matches your shell:

Bash (WSL, macOS, Linux):

bash /path/to/llm-peer-review/scripts/setup/setup.sh /path/to/your-project

PowerShell (setup and non-debate commands - see Requirements):

powershell -ExecutionPolicy Bypass -File C:\path\to\llm-peer-review\scripts\setup\setup.ps1 -Target "C:\path\to\your-project"

Or run from inside your project directory (no target needed):

cd /path/to/your-project
bash /path/to/llm-peer-review/scripts/setup/setup.sh

Note: If you run the script from inside the toolkit repository without specifying a target, it shows an error to prevent accidentally copying files into the wrong place.

Preview first (optional): add --dry-run (bash) or -DryRun (PowerShell) to see exactly what an install or upgrade would do - version gap, migrations, files that would be overwritten, custom files that are left alone, and where backups go - without changing anything:

bash /path/to/llm-peer-review/scripts/setup/setup.sh /path/to/your-project --dry-run

Every real run prints the same pre-flight report before it touches anything.

Local edits are guarded: if you edited a toolkit-managed file, setup detects it (via a hash manifest at .claude/.toolkit-manifest.json) and asks before overwriting - in a terminal it prompts, in scripts and AI-agent runs it stops and lists the files. Add --force (bash) or -Force (PowerShell) after the target path to proceed without the prompt; every replaced file is still backed up first and listed at the end of the run. The guard needs the hash manifest to compare against, so it applies from the second run onward: a first install into a project that already keeps its own root VERSION or .gitattributes replaces them with a backup and no prompt (the pre-flight labels them "provenance unknown").

What setup does: - Copies into your project: commands, skills (including the prebuilt HTML shells), agent definitions (.claude/agents/ - the worker roles /review, /index, /document, and /execute dispatch, carrying their model, effort, and tool settings), both rules files (toolkit.md, html-outputs.md), and all runtime and helper scripts (ask-gpt.js, ask-gemini.js, browse.js, generate-index.js, render-html.js, session-init.js, pre-push-check.js, correction-ledger.js, gen-media.js, open-artifact.sh), plus VERSION and .env.local.example. Detects and removes any legacy INDEX.md. CODEBASE_MAP.md (a semantic map of your project) is generated on your first /explore run, when Claude auto-invokes /index. Setup also lands .gitignore (merged, not overwritten), .gitattributes, VERSION, artifacts/README.md, and the quarantined .claude/scripts/package.json and package-lock.json, and creates an empty plans/ folder for your plan files. - Preserves your work: CLAUDE.md, LESSONS.md (plus its companion LESSONS-detail.md), DESIGN-PROFILE.md (the design workflow's per-repo answers, see /explore above), and settings.local.json are skipped if they already exist - those are yours to customize. Custom files you add inside .claude/commands/, .claude/skills/, .claude/agents/, .claude/scripts/, or .claude/rules/ are never modified or deleted (the toolkit's installer test suite plants a custom file in each of those folders, .claude/agents/ included, and checks it survives an upgrade byte for byte), and anything setup does overwrite is backed up to a timestamped .toolkit-backup-* folder first. One thing setup does add to settings.local.json even on a first install: the two browse.js permission entries that need your project's absolute path, so /review-browser runs without a prompt. - Always updates: the managed rules files (.claude/rules/toolkit.md, .claude/rules/html-outputs.md). - Stays in the toolkit repo: setup scripts (setup.sh, setup.ps1, install-alias.*) are never copied.

See How It Works for details on which files are yours vs. managed by the toolkit.

One install covers everything - it stays inside .claude/scripts/ so your

For /review-browser, install the Chromium browser:

npx --prefix .claude/scripts playwright-core install chromium

On Linux/WSL, also: sudo npx playwright-core install-deps chromium

```

The debate commands and the browser command are optional. Skip the API keys if you don't want /ask-gpt and /ask-gemini. Skip the Chromium install if you don't want /review-browser. The core workflow commands work either way.

</details>

Never set up a dev environment before? Follow the step-by-step guide in SETUP.md. It covers Windows (WSL), Mac, Node.js, GitHub CLI, Cursor, and API keys - everything you need from scratch.

Not using Cursor? The setup guide assumes Cursor, but the toolkit works with any editor that supports Claude Code. Copy the relevant setup page into any AI assistant and ask it to rewrite the steps for your editor.

---

Install the toolkit's runtime packages (one-time, stays in .claude/scripts/).

npm install --prefix .claude/scripts

Open .env.local and paste your API keys

Edit .env.local and paste your OPENAI_API_KEY and GEMINI_API_KEY

Optional: FAL_KEY for video generation in the design workflow (see API-KEYS.md)

For /ask-gpt and /ask-gemini, set up your API keys:

cp .env.local.example .env.local

AI debate commands (/ask-gpt, /ask-gemini): set up API keys

cp .env.local.example .env.local

The Workflow

Solid arrows run on their own; dotted arrows you start yourself. You type /explore and approve the plan. From there /create-plan, /execute, /review, and /document chain automatically. /worktree and the AI debates stay optional and always start with you. If the diagram doesn't render: you type /explore -> /create-plan writes the plan -> you approve it -> /execute -> /review -> /document. Optional and typed by you: /worktree before the run, /ask-gpt or /ask-gemini after the review.

You don't have to use every command every time. Following the order prevents the most common mistake: coding before you've thought it through.

Two ways to take back control, and they do different things. Say "no chaining" to stop the handoff: that run finishes its own stage and does not start the next one. Say "report only" to stop the changing: the run tells you what it found and edits nothing. They are deliberately separate, so you can have either without the other, and both last for one run only. One thing to know about a chained cycle: the review that follows /execute starts on its own, so there is no moment to type "report only" for it. If you want that review to change nothing, say "no chaining" when you approve the plan, then type /review report only yourself.

Want to see this in action? Follow the 5-minute walkthrough in DEMO-SCRIPT.md.

Working on multiple things at once? Use /worktree first to create an isolated copy, then open it in a new Cursor window and run /explore there.

---

Already Have Your Own Workflow?

The toolkit now runs as a loop rather than a set of one-shot commands, and that is the change most likely to affect you if you arrive with your own commands, scripts, or way of working.

What "a loop" means here. The old behavior was report-first: a command found problems, showed you a list, and waited. The new behavior is that a command finds problems, checks them, fixes the ones that survive the check, verifies the fixes, and hands off to the next stage on its own. You type /explore and approve the plan. The rest runs. Two phrases take control back: say "report only" on a run you start and it reports without changing anything (for the review that chains from /execute, see the note under "How key commands work"), or "no chaining" and it finishes that one stage without starting the next.

You do not have to give up what you already have. The loop is a pattern you can add to your own commands, and the rest of this section is how to do that safely, followed by what to check so your files survive an upgrade.

Adding the loop to your own workflow

Automatic fixing is only safe because of what sits around it. If you take the "fix it automatically" half without these, you get the risk with none of the protection. In rough order of how much they matter:

The short version: auto-fixing is a privilege earned by verification. Add the verification first and the automation second.

project's own package.json is never touched.

npm install --prefix .claude/scripts

Browser QA (/review-browser): install Chromium

npx --prefix .claude/scripts playwright-core install chromium

Troubleshooting

• Commands don't show up in Cursor - Make sure .claude/commands/ exists in your project root with .md files inside. The editor workspace root must be the folder that contains .claude/.
• /ask-gpt or /ask-gemini fails - Check that npm install --prefix .claude/scripts was run and .env.local has valid API keys.
• /ask-gpt or /ask-gemini prints a "deprecated model" warning - v4.5.0 auto-overrides outdated GPT_MODEL or GEMINI_MODEL env values with the current default. Edit .env.local to remove or update the stale value if you want to silence the warning. See API-KEYS.md.
• "setup.sh: command not found" - Run the full command from the setup instructions, not just setup.sh on its own.
• "target directory does not exist" - Create the project folder first: mkdir -p /path/to/project
• Script errors with /bin/bash^M or "bad interpreter" - Line-ending issue. Your shell scripts have Windows-style line endings (CRLF) instead of Unix-style (LF). Easiest fix: delete the folder and clone fresh. Advanced fix: run git add --renormalize . && git checkout -- . in the repo.
• Setup stops with "locally modified file(s) will be overwritten" - You edited a toolkit-managed file, and setup will not silently replace it. Re-run with --force (bash) / -Force (PowerShell) added after the target path to proceed - your version is backed up to .toolkit-backup-<timestamp>/ and listed at the end of the run so re-applying your changes is a checklist.
• I customized a toolkit file and upgraded - where did it go? - The setup script preserves your original at .toolkit-backup-<timestamp>/ at the project root before overwriting. Copy it back if you want to keep your version. Safe to delete the backup directory when done.
• Setup one-liner fails partway through - Safe to rerun the command. Leftover /tmp/tmp.* folders are harmless and can be deleted. .toolkit-backup-*/ directories from prior runs are also safe to delete once you have confirmed you do not need th