docs: rebrand to GSD Core and restructure docs with Diataxis (#605)
* 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>
This commit is contained in:
Tom Boucher
124
docs/how-to/run-phases-autonomously.md
Normal file
124
docs/how-to/run-phases-autonomously.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# How to run phases autonomously
|
||||
|
||||
Run all remaining phases — or a bounded range of them — unattended, so GSD moves through discuss → plan → execute for each phase without you driving every step.
|
||||
|
||||
For background on what the phase loop is doing during an autonomous run, see [The phase loop](../explanation/the-phase-loop.md).
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- An active project with `.planning/ROADMAP.md` and `.planning/STATE.md`
|
||||
- All phases you want to run must be in a state that autonomous mode can drive (pending or in-progress; not already complete)
|
||||
- Any design decisions you care about should already be in `PROJECT.md` or captured via a prior `/gsd-discuss-phase` — autonomous mode can surface grey areas interactively only when you use `--interactive`
|
||||
|
||||
---
|
||||
|
||||
## Run all remaining phases
|
||||
|
||||
```bash
|
||||
/gsd-autonomous
|
||||
```
|
||||
|
||||
GSD reads `ROADMAP.md`, discovers every incomplete phase in numeric order, and runs discuss → plan → execute on each one. After all phases complete it automatically runs the milestone lifecycle: audit → complete → cleanup.
|
||||
|
||||
---
|
||||
|
||||
## Run a specific range of phases
|
||||
|
||||
Use `--from` and `--to` to bound the run. Both flags accept decimal phase numbers (e.g. `3.1`).
|
||||
|
||||
```bash
|
||||
/gsd-autonomous --from 3 # phases 3, 4, 5 … (skip already-done phases 1 and 2)
|
||||
/gsd-autonomous --to 5 # phases up to and including 5
|
||||
/gsd-autonomous --from 3 --to 5 # exactly phases 3, 4, and 5
|
||||
```
|
||||
|
||||
When `--to` is reached the lifecycle step is skipped, because not all milestone phases are done. The completion banner tells you how to resume:
|
||||
|
||||
```text
|
||||
Resume with: /gsd-autonomous --from 6
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
/gsd-autonomous --interactive
|
||||
```
|
||||
|
||||
In interactive mode:
|
||||
- `/gsd-discuss-phase` runs inline and waits for your answers
|
||||
- Planning and execution are dispatched as background agents so you can discuss the next phase while the current one builds
|
||||
- The main context stays lean — only discuss conversations accumulate
|
||||
|
||||
---
|
||||
|
||||
## What safety gates still apply
|
||||
|
||||
Autonomous mode does not bypass GSD's quality pipeline. Each phase still:
|
||||
|
||||
- Runs the plan-checker before execution
|
||||
- Reads `VERIFICATION.md` after execution and routes on the result
|
||||
- Pauses and asks you what to do when verification status is `human_needed` or `gaps_found`
|
||||
- Stops and presents options (fix and retry, skip phase, or stop) if any step fails
|
||||
|
||||
The only difference from manual execution is that `passed` verification advances automatically — you are not prompted between phases unless a decision is required.
|
||||
|
||||
The package legitimacy gate also remains active. If a plan includes a `checkpoint:human-verify` task for a suspicious package, the executor will stop and surface the checkpoint. Autonomous mode will not silently install flagged packages.
|
||||
|
||||
---
|
||||
|
||||
## When not to use autonomous mode
|
||||
|
||||
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.
|
||||
|
||||
- **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.
|
||||
|
||||
- **You are mid-phase with partial execution.** Autonomous mode picks up incomplete phases but it does not resume a partially-executed wave. Use `/gsd-execute-phase N` to finish a phase that is already in progress.
|
||||
|
||||
If a run stops partway through, see [Debug a failed execution](debug-a-failed-execution.md) for how to diagnose what went wrong.
|
||||
|
||||
---
|
||||
|
||||
## Checking progress during a run
|
||||
|
||||
Autonomous mode prints a progress banner before each phase:
|
||||
|
||||
```text
|
||||
GSD ► AUTONOMOUS ▸ Phase 3/7: Auth Middleware [████░░░░] 28%
|
||||
```
|
||||
|
||||
If you need to check where the run stands mid-session, open another terminal and run:
|
||||
|
||||
```bash
|
||||
/gsd-progress
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resuming after a stop
|
||||
|
||||
If autonomous mode stops — whether you chose "Stop autonomous mode" from the blocker prompt, or the session was interrupted — resume from where it left off:
|
||||
|
||||
```bash
|
||||
/gsd-autonomous --from 4 # replace 4 with the first incomplete phase number
|
||||
```
|
||||
|
||||
GSD skips already-complete phases automatically, so it is safe to re-run from an earlier phase number if you are not sure where the run stopped.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Execute a phase](execute-a-phase.md)
|
||||
- [Debug a failed execution](debug-a-failed-execution.md)
|
||||
- [Commands](../COMMANDS.md)
|
||||
- [Docs index](../README.md)
|
||||
Reference in New Issue
Block a user