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

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. 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, 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 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 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, STATE.md, and 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 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.

Users can toggle auto-advance globally by running:

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 and execute-phase.md use this logic to determine whether to auto-advance:

# 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 lines 46-49 and execute-phase.md lines 64-66.

Inline Transition Invocation

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

### 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 lines 72-83.

Transition Routing Logic

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

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 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.
• 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 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 and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}