From e35b2f857388c6d6dcc85127c45c10a5afb3f750 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 16 Jun 2026 13:12:47 +0000
Subject: [PATCH] docs: document /gsd-progress --converge primary convergence
surface
---
core/commands/workflow-commands.mdx | 16 ++++++++++++++++
core/guides/cross-ai-review.mdx | 15 ++++++++++++++-
2 files changed, 30 insertions(+), 1 deletion(-)
diff --git a/core/commands/workflow-commands.mdx b/core/commands/workflow-commands.mdx
index 9df7e35..4f42944 100644
--- a/core/commands/workflow-commands.mdx
+++ b/core/commands/workflow-commands.mdx
@@ -322,6 +322,8 @@ Check where you are and what comes next.
/gsd-progress
/gsd-progress --next
/gsd-progress --next --auto
+/gsd-progress --next --auto --converge
+/gsd-progress --next --auto --converge --codex --max-cycles 4
/gsd-progress --do "add rate limiting to the API"
/gsd-progress --forensic
```
@@ -330,6 +332,8 @@ Check where you are and what comes next.
Your unified situational command. In default mode it shows a progress report and intelligently routes to the next action. With `--next` it advances automatically. With `--do` it maps natural language intent to the most appropriate GSD command, confirms the match, and hands off.
+`/gsd-progress --next --auto --converge` is the primary hands-free entry point for plan-review convergence: when the next action is planning, the step is routed through `/gsd-plan-review-convergence` instead of `/gsd-plan-phase`, and the converge mode is preserved across the rest of the `--auto` chain.
+
**Flags**
@@ -340,6 +344,14 @@ Your unified situational command. In default mode it shows a progress report and
Like `--next`, but after the determined step completes, re-invokes `/gsd-progress --next --auto` automatically to keep chaining steps. Enables hands-free plan → execute → verify progression until a blocking decision is required.
+
+ When the next routed action is planning (Route 3), run it through the cross-AI plan-review **convergence** loop instead of `/gsd-plan-phase`. `--cross-ai` is accepted as an alias. Requires `workflow.plan_review_convergence: true` — if the flag is set while the feature gate is off, the command fails fast and prints the enable hint instead of silently falling back to standard planning. When combined with `--auto`, converge mode is forwarded into every re-invocation so the entire chain stays under the convergence policy.
+
+
+
+ With `--converge`, reviewer selectors and `--max-cycles N` are forwarded to `/gsd-plan-review-convergence` unchanged: `--codex`, `--gemini`, `--claude`, `--opencode`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--all`, and `--max-cycles N`. See [Cross-AI review](/core/guides/cross-ai-review) for the full reviewer matrix.
+
+
Smart dispatcher. Matches freeform natural language to the best GSD command using routing rules, confirms the match, then hands off execution.
@@ -348,6 +360,10 @@ Your unified situational command. In default mode it shows a progress report and
Append a 6-check integrity audit after the standard progress report.
+
+ `workflow.plan_review_convergence` is disabled by default. Enable it with `gsd config-set workflow.plan_review_convergence true` before using `--converge`, or the command will exit with the enable hint.
+
+
---
## `/gsd-autonomous`
diff --git a/core/guides/cross-ai-review.mdx b/core/guides/cross-ai-review.mdx
index 808324f..13faa88 100644
--- a/core/guides/cross-ai-review.mdx
+++ b/core/guides/cross-ai-review.mdx
@@ -66,15 +66,28 @@ After `/gsd-review` completes, pass `--reviews` to `/gsd-plan-phase` to replan u
## Automated convergence loop
-Run `/gsd-plan-review-convergence N` to automate the plan → review → replan cycle until no HIGH concerns remain. The command spawns a planning agent and one or more review agents, counts unresolved HIGH concerns in each cycle's `CYCLE_SUMMARY`, and replans automatically until the plan converges or the cycle cap is reached.
+GSD exposes two entry points into the plan → review → replan loop:
+
+- **`/gsd-progress --next --auto --converge`** — the preferred hands-free surface. When `--next` routes to planning, the step is dispatched through `/gsd-plan-review-convergence` automatically, and converge mode is preserved across the rest of the `--auto` chain (plan → execute → verify → next phase). Use this when you want one command to drive the whole milestone under the convergence policy.
+- **`/gsd-plan-review-convergence N`** — the direct command. Use this when you only want to converge the plan for a specific phase without running the rest of the workflow.
+
+Both surfaces require `workflow.plan_review_convergence: true` and accept the same reviewer flags and `--max-cycles N`. `--cross-ai` is accepted as an alias for `--converge` on `/gsd-progress`.
```bash
+# Direct convergence on a single phase
/gsd-plan-review-convergence 3 # Default reviewers, 3 cycles max
/gsd-plan-review-convergence 3 --codex # Codex-only convergence loop
/gsd-plan-review-convergence 3 --all # All reviewers
/gsd-plan-review-convergence 3 --all --max-cycles 5 # Extend cap to 5 cycles
+
+# Hands-free via /gsd-progress (planning steps route through convergence)
+/gsd-progress --next --auto --converge
+/gsd-progress --next --auto --converge --codex --max-cycles 4
+/gsd-progress --next --auto --cross-ai --all
```
+Either way, the underlying loop is the same — `/gsd-progress --next --auto --converge` just wires it into the standard workflow router so you do not have to invoke it phase-by-phase. If you request `--converge` while `workflow.plan_review_convergence` is `false`, the command stops before planning and prints the enable hint instead of silently falling back to `/gsd-plan-phase`.
+
Spawns a planning agent to produce PLAN.md for the phase.