557d46984e
* docs(#2782): how-to for declaring a reviewer lane in a capability ADR-2782 shipped the Reviewer Lane capability surface in 1.9.0, but the only documentation was reference (capability-manifest.md) and rationale (ADR-2782). A capability author had no task-oriented path from "I have a review CLI" to "/gsd:review invokes it". Adds docs/how-to/ship-a-reviewer-lane.md: role selection, the spawn and openai-http worked examples, federated config ownership, the review-lane query surface as the verification step, what the install disclosure and egress-host re-verification mean for the author, and the data-only boundary with the two named CLIs that do not fit today. Also corrects the manifest reference's `invoke` row, which understated three enums against the shipped validator: promptChannel omitted `argv`, effortChannel omitted `env`, and the openai-http sub-shape plus the required-with-file-arg `outputArg` were undocumented entirely. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(#2782): correct four claims found by the two orthogonal reviews Security review (1 major, 2 minor): - "a reserved slug" implied the gsd-/anthropic- namespace rule, which guards the capability id, not reviewer.slug. The slug guard is isReservedName (__proto__/constructor/prototype), a prototype-pollution barrier. Both rules are now stated and kept apart. - Added ADR-2782 D5's own caveat verbatim: disclosure and host pinning make the channel visible, pinned and revocable, not safe, and consent-at-install is a weaker gate for a standing egress channel than for a hook. - Named integrity/SHA pinning and engines.gsd as the controls that make the disclosure tamper-evident and the version range enforceable. Correctness review (1 major, 1 minor): - Claimed a name collision is "a hard failure at install". It is not. installCapability never runs validateCrossCapability; the check runs in loadRegistry, and a colliding overlay is dropped from acceptedMap with a warning while the install reports success. Documented as the quiet failure mode it is, with the symptom to look for. - The feature-only field list omitted hooks and activationKey, both of which FEATURE_FIELDS_FORBIDDEN_ON_REVIEWER rejects. Both worked examples re-validated against validateCapability() -> []. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(#2782): restore Kimi Code to the cross-AI reviewer list set-up-cross-ai-review.md named eleven reviewers; twelve lanes ship. The kimi-code lane (added by #2718, declared as manifest data by #2798) was never added here — the same roster-drift class as #2781, which #2800's parity gate covers for COMMANDS.md and FEATURES.md but not for how-to prose. Also points readers at the declared-lane model rather than a static list: the roster is now generated, a capability can ship its own lane, and `gsd-tools review-lane sections` answers "what do I actually have". Verified against the twelve declared bodies in capabilities/*/capability.json. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(#2782): use the invocation form the runtime descriptors actually declare The new guide used /gsd:review. Nothing in this repo produces that form. - capability-validator VALID_COMMAND_STYLES is {slash-hyphen, shell-var}; there is no colon/namespaced style in the vocabulary at all. - 18 of 19 runtime capabilities declare commandStyle "slash-hyphen", claude included; codex is "shell-var". Every artifactLayout prefix is "gsd-". - A plain-file command install never namespaces, so .claude/commands/ gsd-review.md is typed /gsd-review. - The Claude Code plugin surface would namespace on plugin.json "name", which is "gsd-core" -- so the plugin form would be /gsd-core:review. The commands/gsd/ subdirectory is cosmetic and contributes nothing to the invoked name. So /gsd:review is neither the installed form nor the plugin form. Uses /gsd-review, matching set-up-cross-ai-review.md and the 18 descriptors. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(#2782): state that lane listing is not wired yet The guide could describe authoring, validating, and installing a lane but implied a publishing path that does not exist. Neither discoverability catalog can accept one: a Community Capability Registry entry requires a non-empty loopExtensionPoints plus hookKinds, and a role:"reviewer" capability is forbidden from declaring steps/contributions/gates, so both fields are unsatisfiable rather than merely unset. The EoS Registry is ADR-1239 host integrations, which a lane is not. The registry schema predates the reviewer role by 17 days (#2182 Jul 11, ADR-2782 Jul 28) and registry-schema.cjs has zero occurrences of "reviewer". Tracked for a 1.9.x point release by #2904. Says so explicitly, and tells authors NOT to file a loop extension point they do not use to get past validation -- a schema satisfiable only by lying is one that will be lied to. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * chore(#2782): backfill PR number and fix the changeset invocation form pr: 0 -> 2906. Also corrects /gsd:review -> /gsd-review in the fragment body. The fragment renders into CHANGELOG.md, which is a reader-facing docs surface and is never passed through the install-time converter -- so the colon form would ship the #2903 drift into a permanent release artifact. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(#2907): propagate the invocation-form fix and restore lane order Two findings from an isolated review of the post-review delta. - docs/README.md and develop-a-capability.md still said /gsd:review in the cross-links added for the new guide. The form was corrected in the guide itself but not in the two entries pointing at it, leaving three docs making the same claim in two different forms. - set-up-cross-ai-review.md inserted Kimi Code between Antigravity and Ollama. REVIEWER_LANES is ordered by write_reviews order and kimi-code is 12th, appended after llama_cpp; the prose list mirrored declaration order before this change and now does again. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Test <test@example.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
165 lines
6.0 KiB
Markdown
165 lines
6.0 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, llama.cpp, and Kimi Code.
|
||
|
||
That list is not fixed. Each of those is a declared reviewer lane, and a capability can ship its own — see [Ship a reviewer lane in your capability](ship-a-reviewer-lane.md). To see exactly which lanes your installation has, run `gsd-tools review-lane sections`.
|
||
|
||
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).
|
||
|
||
If you need multiple independent reviewer voices from the same adapter, configure `review.reviewer_instances` and add those instance names to `review.default_reviewers`. Instance names run only through `review.default_reviewers`; they are not valid `/gsd-review` flags. See [Reviewer instances](../CONFIGURATION.md#reviewer-instances) for the schema.
|
||
|
||
---
|
||
|
||
## 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)
|
||
- [Ship a reviewer lane in your capability](ship-a-reviewer-lane.md) — add a reviewer GSD does not ship with, by declaring it in a capability manifest
|
||
- [Configuration](../CONFIGURATION.md)
|
||
- [Commands](../COMMANDS.md)
|
||
- [docs index](../README.md)
|