# How GSD-Build's Auto-Advance Chain Workflow Automatically Advances Stages

> Discover how GSD-Build's auto-advance chain workflow automatically progresses project stages, enabling seamless transitions without manual intervention. Learn the mechanics behind automated stage advancement.

- Repository: [GSD/get-shit-done](https://github.com/gsd-build/get-shit-done)
- Tags: how-to-guide
- Published: 2026-02-16

---

**GSD-Build's auto-advance chain workflow automatically progresses through project stages by checking for the `--auto` flag or `workflow.auto_advance` configuration after each successful phase completion, then inline-invoking the transition workflow to determine and launch the next appropriate stage without user interaction.**

The `gsd-build/get-shit-done` repository implements a sophisticated auto-advance chain workflow that eliminates manual intervention between project phases. This system chains together planning, execution, and transition workflows to create a seamless pipeline where successful stage completion automatically triggers the next logical step. Understanding how this auto-advance mechanism detects completion states and routes to subsequent phases reveals how GSD-Build maintains project momentum without constant user prompts.

## What Triggers the Auto-Advance Chain?

The auto-advance chain workflow activates based on two distinct triggers that signal the system to proceed without user confirmation.

### The `--auto` Flag

Users can explicitly enable auto-advance for a single workflow invocation by appending the `--auto` flag to their command. For example, invoking `/gsd:plan-phase X --auto` tells the system to automatically proceed to the transition workflow upon successful completion of the planning phase. This flag is parsed from the `$ARGUMENTS` environment variable within the workflow scripts.

### The `workflow.auto_advance` Configuration

Projects can persistently enable auto-advance by setting the `workflow.auto_advance` flag to `true` in [`.planning/config.json`](https://github.com/gsd-build/get-shit-done/blob/main/.planning/config.json). The workflow queries this configuration using the `gsd-tools.cjs` CLI utility. When this global setting is enabled, every successful phase completion automatically triggers the next stage unless explicitly overridden with `--no-auto`.

## How the Chain Workflow Advances Through Stages

The auto-advance chain workflow operates as a sequential pipeline across three primary stages, with each stage responsible for validating completion and triggering the next link in the chain.

### Stage 1: Planning Phase Auto-Advance

In [`get-shit-done/workflows/plan-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/workflows/plan-phase.md), the auto-advance check occurs immediately after the planner and optional plan-checker finish verification (lines 46-55). The script parses the `--auto` flag from `$ARGUMENTS` and reads the `workflow.auto_advance` configuration. If either trigger is active and verification passed, the workflow prints an "AUTO-ADVANCING → TRANSITION" banner and invokes the transition workflow inline.

This inline invocation is critical: it avoids creating a separate `Task`, keeping the orchestration context minimal and ensuring the chain proceeds without manual intervention.

### Stage 2: Execution Phase Auto-Advance

The [`get-shit-done/workflows/execute-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/workflows/execute-phase.md) script repeats the same detection logic (lines 64-73) after all execution waves complete and pass spot-checks. When auto-advance is enabled, it spawns the transition workflow directly, maintaining the seamless chain from execution to the next project phase.

This ensures that fully-verified execution plans automatically progress to transition without requiring the user to manually select "what's next" from a menu.

### Stage 3: Transition Logic and Next Phase Selection

The [`get-shit-done/workflows/transition.md`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/workflows/transition.md) workflow serves as the router for the auto-advance chain. Upon invocation, it reads the current phase state, marks it complete, and updates [`ROADMAP.md`](https://github.com/gsd-build/get-shit-done/blob/main/ROADMAP.md), [`STATE.md`](https://github.com/gsd-build/get-shit-done/blob/main/STATE.md), and [`PROJECT.md`](https://github.com/gsd-build/get-shit-done/blob/main/PROJECT.md) files.

The auto-advance detection block (lines 64-73) then determines the next step:

- **Route A**: When additional phases remain, the workflow automatically invokes either `/gsd:plan-phase NEXT --auto` or `/gsd:discuss-phase NEXT --auto` depending on whether a [`CONTEXT.md`](https://github.com/gsd-build/get-shit-done/blob/main/CONTEXT.md) file exists for the next phase.
- **Route B**: When the milestone is finished, the workflow automatically invokes `/gsd:complete-milestone VERSION --auto`.

This routing logic ensures the chain continues through the entire project lifecycle until completion.

## Configuration Management and CLI Tools

The auto-advance chain workflow relies on `bin/gsd-tools.cjs` for configuration management. This CLI utility provides the `config-get` and `config-set` commands that read and write the `workflow.auto_advance` flag to [`.planning/config.json`](https://github.com/gsd-build/get-shit-done/blob/main/.planning/config.json).

Users can toggle auto-advance globally by running:

```bash
node bin/gsd-tools.cjs config-set workflow.auto_advance true

```

Once set, every workflow invocation checks this configuration unless overridden by explicit command-line flags.

## Code Examples

### Detecting the `--auto` Flag

Both [`plan-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/plan-phase.md) and [`execute-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/execute-phase.md) use this logic to determine whether to auto-advance:

```bash

# Parse explicit flag from arguments

AUTO_FLAG=$(echo "$ARGUMENTS" | grep -o -- '--auto' || true)

# Read persistent configuration

AUTO_CFG=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")

# Determine if auto-advance should activate

if [[ -n "$AUTO_FLAG" || "$AUTO_CFG" == "true" ]]; then
  # Auto-advance path triggered

fi

```

*Source:* [`plan-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/plan-phase.md) lines 46-49 and [`execute-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/execute-phase.md) lines 64-66.

### Inline Transition Invocation

When auto-advance triggers in the planning phase, the workflow invokes transition directly:

```markdown

### Auto-Advance Check

Parse `--auto` flag …  
If auto-advance is enabled:

```

╔══════════════════════════════════════════╗
║  AUTO-ADVANCING → TRANSITION            ║
║  Phase {X} verified, continuing chain   ║
╚══════════════════════════════════════════╝

```

Read and follow `~/.claude/get-shit-done/workflows/transition.md`,
passing through the `--auto` flag so it propagates to the next phase.

```

*Source:* [`plan-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/plan-phase.md) lines 72-83.

### Transition Routing Logic

The transition workflow determines the next step based on project state:

```bash
if [[ "$is_last_phase" == "false" ]]; then
  # Next phase exists – check for CONTEXT.md

  if [[ -f ".planning/phases/${next_phase}/*-CONTEXT.md" ]]; then
    # Auto-plan the next phase

    /gsd:plan-phase "${next_phase}" --auto
  else
    # Auto-discuss to gather context first

    /gsd:discuss-phase "${next_phase}" --auto
  fi
else
  # Milestone complete – auto-complete it

  /gsd:complete-milestone "${version}" --auto
fi

```

*Source:* [`transition.md`](https://github.com/gsd-build/get-shit-done/blob/main/transition.md) lines 57-89 (Route A) and lines 52-56 (Route B).

## Summary

- **GSD-Build's auto-advance chain workflow** eliminates manual intervention by automatically progressing through planning, execution, and transition stages upon successful completion.
- **Dual trigger system**: Activation requires either the `--auto` command-line flag or the `workflow.auto_advance` configuration set to `true` in [`.planning/config.json`](https://github.com/gsd-build/get-shit-done/blob/main/.planning/config.json).
- **Inline invocation**: Workflows invoke the transition stage directly without creating separate `Task` objects, maintaining minimal orchestration context.
- **Intelligent routing**: The transition workflow selects the next appropriate stage (plan, discuss, or milestone completion) based on project state and existing context files.
- **Configuration management**: The `gsd-tools.cjs` CLI provides persistent configuration storage for auto-advance preferences.

## Frequently Asked Questions

### What is the gsd-build auto-advance chain workflow?

The gsd-build auto-advance chain workflow is an autonomous pipeline implemented in the `gsd-build/get-shit-done` repository that connects planning, execution, and transition phases into a continuous sequence. When enabled, it automatically triggers the next project stage immediately after the current stage completes successfully, eliminating the need for manual "what's next" prompts.

### How do I enable auto-advance in gsd-build?

You can enable auto-advance in two ways: temporarily by appending the `--auto` flag to any workflow command (such as `/gsd:plan-phase X --auto`), or persistently by setting the configuration value using the CLI tool: `node bin/gsd-tools.cjs config-set workflow.auto_advance true`. The persistent setting stores the flag in [`.planning/config.json`](https://github.com/gsd-build/get-shit-done/blob/main/.planning/config.json) and applies to all subsequent workflow invocations unless overridden with `--no-auto`.

### What happens if a stage fails during auto-advance?

If a stage fails verification or execution checks, the auto-advance chain halts immediately and presents the standard "what's next?" menu to the user. The auto-advance logic in both [`plan-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/plan-phase.md) and [`execute-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/execute-phase.md) explicitly checks for successful verification before proceeding to the transition workflow. A failed stage does not trigger the next phase, allowing users to address issues before manually continuing.

### Can I disable auto-advance for specific stages only?

While there is no per-stage configuration flag in the current implementation, you can effectively disable auto-advance for specific invocations by omitting the `--auto` flag when the global `workflow.auto_advance` is set to `true`, or by explicitly using `--no-auto` if supported by the CLI parser. The workflow checks both the explicit flag and the global config, so strategic use of command-line overrides allows granular control over which stages auto-advance.