From b44e16a47af0126b8ec08d7572eb2824e05f4dd8 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Fri, 5 Jun 2026 17:43:19 -0400 Subject: [PATCH] docs: document --only and --text flags for /gsd-autonomous (#695) (#716) Adds --only N and --text to the COMMANDS.md reference table and the run-phases-autonomously how-to guide, revised to fit the Diataxis framework (reference: factual/parallel rows; how-to: goal-framed sections). --- docs/COMMANDS.md | 4 ++++ docs/how-to/run-phases-autonomously.md | 27 +++++++++++++++++++++++++- 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index f9d337f78..0d71fa243 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -713,13 +713,17 @@ Run all remaining phases autonomously. |------|-------------| | `--from N` | Start from a specific phase number | | `--to N` | Stop after completing a specific phase number | +| `--only N` | Restrict execution to phase N; lifecycle step is skipped | | `--interactive` | Lean context with user input | +| `--text` | Replace `AskUserQuestion` prompts with plain numbered lists | ```bash /gsd-autonomous # Run all remaining phases /gsd-autonomous --from 3 # Start from phase 3 /gsd-autonomous --to 5 # Run up to and including phase 5 /gsd-autonomous --from 3 --to 5 # Run phases 3 through 5 +/gsd-autonomous --only 4 # Run only phase 4 +/gsd-autonomous --text # Run with text-mode prompts ``` ### `/gsd-debug` diff --git a/docs/how-to/run-phases-autonomously.md b/docs/how-to/run-phases-autonomously.md index ebd0bd428..ecfb99662 100644 --- a/docs/how-to/run-phases-autonomously.md +++ b/docs/how-to/run-phases-autonomously.md @@ -42,6 +42,18 @@ Resume with: /gsd-autonomous --from 6 --- +## Run a single phase + +To run exactly one phase without triggering the milestone lifecycle, use `--only N`: + +```bash +/gsd-autonomous --only 4 +``` + +If the phase is already complete, autonomous mode exits immediately with a message rather than re-running it. + +--- + ## Run with interactive discuss By default, autonomous mode answers discuss questions automatically using smart discuss (batch table proposals). If you want to answer design questions yourself while keeping plan and execute out of the main context: @@ -57,6 +69,19 @@ In interactive mode: --- +## Run on a non-Claude runtime + +To run autonomously on a runtime that does not support the `AskUserQuestion` tool (for example Codex CLI or Gemini CLI), add `--text`: + +```bash +/gsd-autonomous --text +/gsd-autonomous --from 3 --text +``` + +All interactive prompts become plain numbered lists; type the choice number to respond. + +--- + ## What safety gates still apply Autonomous mode does not bypass GSD's quality pipeline. Each phase still: @@ -78,7 +103,7 @@ Do not use `/gsd-autonomous` when: - **Phases have unsettled design decisions.** If you have not run `/gsd-discuss-phase` and your `PROJECT.md` does not capture your preferences, smart discuss will make autonomous choices you may not agree with. Run discuss interactively first, or use `--interactive`. -- **You need fine-grained control over a single phase.** For one phase, `/gsd-execute-phase N` gives you step-by-step output and lets you react before continuing. Autonomous mode is designed for bulk unattended runs. +- **You need fine-grained control over a single phase.** For one phase, `/gsd-execute-phase N` gives you step-by-step output and lets you react before continuing. Use `--only N` if you want the autonomous quality pipeline on a single phase but do not need step-by-step interaction. - **The phase has novel or high-risk work.** Autonomous mode skips pauses unless it hits a blocker. On a phase where you expect surprises, stay in the loop with manual execution.