3bb2f8f1c5
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
160 lines
5.3 KiB
Markdown
160 lines
5.3 KiB
Markdown
# How to set up cross-AI review
|
||
|
||
**Goal:** Configure which AI reviewers participate in plan review, run a review of a planned phase, and use the feedback to converge on a plan with no HIGH-severity concerns.
|
||
|
||
**Prerequisites:** The phase has been planned (`{phase}-PLAN.md` files exist in `.planning/phases/`). At least one external AI CLI is installed and authenticated.
|
||
|
||
---
|
||
|
||
## Decide which reviewers to use
|
||
|
||
GSD Core can route review requests to any combination of: Gemini CLI, Claude (separate session), Codex CLI, CodeRabbit, OpenCode, Qwen Code, Cursor, Antigravity CLI, Ollama, LM Studio, and llama.cpp.
|
||
|
||
Each reviewer runs the same structured prompt against your `PLAN.md` files independently. Because different models have different blind spots, multi-reviewer consensus catches more issues than any single reviewer.
|
||
|
||
**If you have no external CLIs installed yet**, install at least one:
|
||
|
||
```bash
|
||
# Gemini CLI (free with Google credentials)
|
||
npm install -g @google/gemini-cli
|
||
|
||
# Antigravity CLI (free with Google credentials)
|
||
curl -fsSL https://antigravity.google/cli/install.sh | bash
|
||
|
||
# Codex CLI
|
||
npm install -g @openai/codex
|
||
```
|
||
|
||
---
|
||
|
||
## Set default reviewers (optional)
|
||
|
||
By default, `/gsd-review` runs all detected CLIs. To pin a subset as project defaults:
|
||
|
||
```bash
|
||
/gsd-config --integrations
|
||
```
|
||
|
||
The integrations wizard covers API keys, code-review CLI routing, and the `review.default_reviewers` list. Set the list to the reviewers you want as the no-flag default — for example `["gemini","codex"]`.
|
||
|
||
Alternatively, set it directly with `gsd-tools`:
|
||
|
||
```bash
|
||
gsd config-set review.default_reviewers '["gemini","codex"]'
|
||
```
|
||
|
||
For the full integration settings schema (API keys, model overrides per reviewer, local server host addresses), see [Configuration](../CONFIGURATION.md).
|
||
|
||
---
|
||
|
||
## Run a review
|
||
|
||
### Standard review (uses your configured defaults or all detected CLIs)
|
||
|
||
```bash
|
||
/gsd-review --phase 3
|
||
```
|
||
|
||
GSD invokes each reviewer in sequence, collects structured feedback (Summary, Strengths, Concerns at HIGH/MEDIUM/LOW, Suggestions, Risk Assessment), and writes the combined output to `.planning/phases/03-.../03-REVIEWS.md`.
|
||
|
||
### Select a single reviewer for a one-off run
|
||
|
||
```bash
|
||
/gsd-review --phase 3 --gemini
|
||
/gsd-review --phase 3 --codex
|
||
/gsd-review --phase 3 --cursor
|
||
```
|
||
|
||
Any explicit flag overrides both the `--all` default and `review.default_reviewers` for that run.
|
||
|
||
### Run every available reviewer in parallel
|
||
|
||
```bash
|
||
/gsd-review --phase 3 --all
|
||
```
|
||
|
||
`--all` always overrides config and runs the full detected set, including any configured local model servers (Ollama, LM Studio, llama.cpp).
|
||
|
||
### Local model server reviewers
|
||
|
||
If you run Ollama or LM Studio locally, they are included automatically with `--all` when the server is reachable. You can also target them explicitly:
|
||
|
||
```bash
|
||
/gsd-review --phase 3 --ollama
|
||
/gsd-review --phase 3 --lm-studio
|
||
```
|
||
|
||
Configure the host addresses and model selection under `review.*` keys via `/gsd-config --integrations` if the defaults (`localhost:11434` / `localhost:1234`) do not apply.
|
||
|
||
---
|
||
|
||
## Read the review output
|
||
|
||
The `{padded_phase}-REVIEWS.md` file contains:
|
||
|
||
- Individual reviews from each reviewer with severity-classified concerns
|
||
- A **Consensus Summary** section that synthesises concerns raised by two or more reviewers — start here for the highest-priority signal
|
||
- A **Divergent Views** section for areas where reviewers disagreed
|
||
|
||
---
|
||
|
||
## Incorporate feedback into the plan
|
||
|
||
Once you have reviewed the output, replan incorporating the feedback:
|
||
|
||
```bash
|
||
/gsd-plan-phase 3 --reviews
|
||
```
|
||
|
||
The planner reads `REVIEWS.md` and adjusts the plans to address the concerns before saving.
|
||
|
||
---
|
||
|
||
## Automate the plan–review–replan loop
|
||
|
||
For phases where you want to iterate until all HIGH-severity concerns are resolved, use the convergence loop:
|
||
|
||
```bash
|
||
/gsd-plan-review-convergence 3
|
||
```
|
||
|
||
This runs `plan-phase → review → replan → re-review` up to three cycles (default). The loop exits when the HIGH-concern count reaches zero.
|
||
|
||
### Convergence with a specific reviewer
|
||
|
||
```bash
|
||
/gsd-plan-review-convergence 3 --codex
|
||
/gsd-plan-review-convergence 3 --gemini
|
||
```
|
||
|
||
### Convergence with all reviewers and a higher cycle cap
|
||
|
||
```bash
|
||
/gsd-plan-review-convergence 3 --all --max-cycles 5
|
||
```
|
||
|
||
**Stall detection:** if the HIGH-concern count is not decreasing across cycles, GSD warns you. When the cycle cap is reached with open HIGH concerns, an escalation gate asks whether to proceed or review manually.
|
||
|
||
---
|
||
|
||
## Conditionals: which reviewers to choose
|
||
|
||
| Situation | Recommended approach |
|
||
|-----------|---------------------|
|
||
| You have Gemini CLI already installed | `--gemini` is always a good starting reviewer |
|
||
| You want free multi-reviewer coverage | `--gemini` + `--agy` (both use Google credentials) |
|
||
| Your project is OpenAI-heavy | add `--codex` for an OpenAI-model perspective |
|
||
| You want GitHub Copilot's model | add `--opencode` |
|
||
| You want to avoid API costs entirely | configure Ollama with a local model and use `--ollama` |
|
||
| You need maximum coverage before a release | `/gsd-plan-review-convergence N --all` |
|
||
| You're iterating quickly and want fast feedback | pick one CLI: `/gsd-review --phase N --gemini` |
|
||
|
||
---
|
||
|
||
## Related
|
||
|
||
- [Verify and ship](verify-and-ship.md)
|
||
- [Configuration](../CONFIGURATION.md)
|
||
- [Commands](../COMMANDS.md)
|
||
- [docs index](../README.md)
|