/gsd auto

What It Does

/gsd auto is GSD’s autonomous execution mode. Once started, it takes over the full lifecycle: discussing and researching the codebase, planning slices and tasks, executing each unit in a fresh context window, committing changes, running verification, and dispatching the next unit. It continues until the active milestone is complete — or until you stop it.

Unlike bare /gsd (which runs one unit and waits for your input), auto mode loops continuously. Each unit gets a clean context window with pre-loaded, focused context — summaries of prior work, the active plan, architectural decisions, and knowledge base entries. This prevents context degradation across long-running projects.

Usage

/gsd auto
/gsd auto --verbose
/gsd auto --debug

Flag	Effect
`--verbose`	Increases logging detail during dispatch and execution
`--debug`	Enables debug-level output for troubleshooting dispatch issues

If you want to execute just one unit and decide what to do next, use /gsd next instead.

How It Works

Auto mode is a state machine that reads the .gsd/ directory to determine what phase the project is in, then dispatches the right type of work. Here’s the full initialization and dispatch flow:

Initialization sequence

Stale worktree escape — If the process cwd is still inside a previous milestone’s worktree (e.g., after an unclean stop), GSD detects it and escapes back to the project root before proceeding.
Resume check — If a previous session was paused, GSD restores the saved state (base path, current unit, completed units), re-enters the worktree if needed, and jumps straight to dispatch. A recovery briefing is synthesized from the paused session’s tool call history so the next agent knows what already happened.
Git check — Ensures the project is in a git repository. If not, initializes one with the configured main branch, sets up .gitignore baseline patterns, and bootstraps the .gsd/ directory structure.
Crash recovery — Checks for a crash lock file in .gsd/. If found and the process is no longer alive, GSD synthesizes a recovery context from the prior session’s tool call history and prepends it to the first dispatch prompt. If the lock belongs to a live process, GSD aborts to prevent two concurrent sessions.
Derive state — Reads all .gsd/ files to determine the current phase: which milestone is active, which slice, which task. This is the same algorithm used by /gsd status.
Discuss-milestone — If no milestone exists yet, or the active milestone has a draft context file that needs discussion, GSD dispatches a discuss-milestone unit to talk through the project goals and produce a CONTEXT.md before planning begins.
Worktree setup — If worktree isolation is enabled (opt-in via git.isolation: "worktree" in preferences), creates or re-enters .gsd/worktrees/<MID>/ with a milestone/<MID> branch. When re-attaching to an existing branch, GSD forward-merges any plan checkpoint state from the project root into the worktree to handle crash scenarios. A user-configured post-create hook (git.worktree_post_create in preferences) is run after creation — useful for copying .env files or symlinking assets. When worktree isolation is disabled (the default), GSD executes directly in the project root.
Database — Opens or auto-migrates the SQLite database at .gsd/gsd.db. If the database doesn’t exist yet but .gsd/ has markdown files (decisions, requirements, milestones), GSD automatically imports them into the database before the first dispatch.
Metrics & routing initialization — Initializes the metrics ledger, routing history, and (if skill discovery is enabled) takes a snapshot of installed skills. Begins session tracking for cost, tokens, and timing.
Secrets collection gate — If a secrets manifest exists for the active milestone and contains uncollected keys, GSD prompts the user to provide them before the first unit is dispatched.
Self-heal — Clears stale unit runtime records where artifacts already exist on disk (prevents phantom re-dispatch on restart). Also auto-fixes complete-slice records where SUMMARY and UAT files exist but the roadmap checkbox was not flipped (e.g., a crash between writing artifacts and updating the roadmap). Removes stale .git/index.lock files left by prior crashes.
Pre-flight validation — When multiple milestones are queued, checks each for draft context files that will require user discussion before planning. Reports any blockers upfront rather than mid-run.

The dispatch loop

After initialization, GSD enters its core loop. Each iteration:

Dispatch — Evaluates a declarative table of 19 ordered dispatch rules. The first matching rule determines the unit type and builds the prompt for that unit.
Execute — Creates a fresh agent session with the unit’s plan pre-loaded. The agent has no memory of prior sessions — everything it needs is in the dispatch prompt.
Artifact verification — After the unit completes, GSD checks that the expected artifact was written to disk (e.g., a PLAN.md for plan-slice, a task SUMMARY.md and [x] checkbox for execute-task). For complete-slice, both a SUMMARY.md and UAT.md must exist and the slice must be marked [x] in the roadmap. If verification fails, the unit is re-dispatched.
Auto-commit — All changes are committed to the active milestone branch with a structured commit message.
Doctor checks — Runs health checks on the .gsd/ directory structure. Catches file corruption, missing summaries, or inconsistent state.
Worktree sync — Synchronizes state between the worktree and the project root (when worktree isolation is enabled).
Next dispatch — Re-derives state from disk and loops back to step 1.

When the final unit (complete-milestone) finishes, GSD squash-merges the milestone/<MID> branch into the integration branch (default: main) with a rich commit message listing all completed slices, then tears down the worktree.

Unit types

The dispatch table maps project phases to these unit types:

Unit type	Phase	What it does
`discuss-milestone`	`pre-planning` / `needs-discussion`	Discusses project goals with the user and writes `CONTEXT.md`; runs before research when no context exists or when the milestone has a draft
`research-milestone`	`pre-planning`	Scouts the codebase and writes RESEARCH.md
`plan-milestone`	`pre-planning`	Creates the milestone ROADMAP.md
`research-slice`	`planning`	Researches implementation approach for a slice (skipped for S01 when milestone research exists)
`plan-slice`	`planning`	Decomposes a slice into tasks and writes PLAN.md + per-task PLAN files
`gate-evaluate`	`evaluating-gates`	Evaluates pending verification gates for a slice; opt-in via `gate_evaluation.enabled` preference
`execute-task`	`executing`	Implements a task in a fresh session
`reactive-execute`	`executing`	Executes multiple dependency-independent tasks in parallel; only dispatched when `reactive_execution.enabled` is set and the task graph has ≥2 ready tasks
`replan-slice`	`replanning-slice`	Rewrites the slice plan when a blocker is found; writes REPLAN.md
`complete-slice`	`summarizing`	Writes the slice SUMMARY.md, UAT.md, and marks the slice `[x]` in the roadmap
`run-uat`	post-completion	Runs automated UAT checks against the completed slice; pauses for user interaction when UAT is not artifact-driven
`reassess-roadmap`	post-completion	Reviews the roadmap after a slice completes and writes ASSESSMENT.md; opt-in via `phases.reassess_after_slice` preference
`validate-milestone`	`validating-milestone`	Final QA check before milestone completion; can be skipped via `skip_milestone_validation` preference
`complete-milestone`	`completing-milestone`	Writes milestone SUMMARY.md and triggers squash-merge
`rewrite-docs`	any (override gate)	Applies a `/gsd steer` override to plan documents
`custom-step`	any (workflow)	Executes a custom workflow step defined in the active workflow template

Some phases can be skipped entirely via preferences: skip_research (milestone and slice research), skip_slice_research (slice research only), skip_reassess (roadmap reassessment), and skip_milestone_validation (milestone validation). Roadmap reassessment only runs when phases.reassess_after_slice is also set to true.

UAT verdict gate

When the uat_dispatch preference is enabled, GSD checks all completed slices for non-PASS UAT verdicts before advancing. If any UAT-RESULT.md file contains a verdict other than pass or passed, GSD stops with a warning rather than progressing to the next slice. Fix the issue and set the verdict to PASS, then resume auto mode.

Reactive execution

When reactive_execution.enabled is set to true with max_parallel > 1, GSD derives a dependency graph from each slice’s task I/O definitions before dispatching. If two or more tasks have no dependency on each other and no file-write conflicts, GSD dispatches them in parallel as a single reactive-execute unit. The batch is encoded in the unit ID (M001/S01/reactive+T02,T03) for verification and recovery. Setting max_parallel: 1 keeps the graph derivation active (logged for observability) without enabling parallel dispatch — useful for inspecting graph quality before enabling parallelism.

Rewrite circuit breaker

When a /gsd steer override is pending, the rewrite-docs rule fires before all other rules. The circuit breaker caps retries at 3 attempts (MAX_REWRITE_ATTEMPTS). If the rewrite unit is dispatched 3 times without consuming the override, GSD automatically resolves all pending overrides and resets the counter — preventing the override gate from blocking the pipeline indefinitely.

Safety guards

Three safety guards block milestone completion when the pipeline state is inconsistent:

Missing SUMMARY guard — Both validating-milestone and completing-milestone check that every slice in the roadmap has a SUMMARY file before proceeding. If any slice is missing a summary, auto mode stops with an error and a list of the affected slices.
Remediation verdict guard — completing-milestone checks the VALIDATION file verdict. If the verdict is needs-remediation, GSD stops rather than completing — remediation work must be addressed first. (Note: the state machine treats needs-remediation as terminal to prevent validation loops, but completion is blocked regardless.)
Implementation artifact guard — completing-milestone verifies that the milestone branch contains at least one non-.gsd/ file change compared to the integration branch. A milestone that only wrote plan files and no implementation code is not considered complete.

Stuck detection

If the same unit is re-dispatched 3 times without producing its expected artifact (MAX_UNIT_DISPATCHES = 3), GSD flags it as stuck. A lifetime limit of 6 stuck detections per session (MAX_LIFETIME_DISPATCHES = 6) prevents infinite loops. When stuck detection triggers, GSD either writes a blocker placeholder artifact to advance the pipeline, or stops with a diagnostic message and manual remediation steps.

While auto mode runs, a live progress widget is displayed in the terminal. The widget shows the current unit, milestone/slice context, slice progress bar, task checklist, cost, cache hit rate, and context window usage. Four display modes are available — cycle through them with Esc:

Mode	What’s shown
`full`	Two-column layout: progress bar + task checklist, stats, last commit
`small`	Compact: current action + progress bar + cost/context
`min`	Header line only
`off`	Hidden

The selected mode is persisted to preferences so it survives restarts.

What Files It Touches

Reads

File	Purpose
`.gsd/STATE.md`	Quick-glance status (cache of derived state)
`.gsd/KNOWLEDGE.md`	Accumulated patterns and gotchas
`.gsd/DECISIONS.md`	Architectural decision register
`.gsd/OVERRIDES.md`	User-issued steering overrides
`.gsd/milestones/<MID>/<MID>-ROADMAP.md`	Slice ordering and completion status
`.gsd/milestones/<MID>/<SID>/<SID>-PLAN.md`	Task breakdown for a slice
`.gsd/milestones/<MID>/<SID>/tasks/<TID>-SUMMARY.md`	Prior task outcomes fed as context to next tasks

Writes

File	Purpose
`.gsd/STATE.md`	Updated after each unit completes
`.gsd/auto.lock`	Written at startup, cleared on stop — used for crash detection and cross-process signaling
`.gsd/gsd.db`	SQLite database opened or auto-migrated at startup
`.gsd/milestones/<MID>/<SID>/tasks/<TID>-SUMMARY.md`	Written by each task executor
`.gsd/milestones/<MID>/<SID>/<SID>-SUMMARY.md`	Written at slice completion
`.gsd/milestones/<MID>/<SID>/<SID>-UAT.md`	Acceptance criteria written at slice completion
`.gsd/milestones/<MID>/<SID>/<SID>-UAT-RESULT.md`	UAT execution results written by `run-uat`
`.gsd/milestones/<MID>/<SID>/<SID>-ASSESSMENT.md`	Roadmap reassessment written by `reassess-roadmap`
`.gsd/milestones/<MID>/<MID>-VALIDATION.md`	Written at milestone validation
`.gsd/milestones/<MID>/<MID>-SUMMARY.md`	Written at milestone completion
`.gsd/runtime/`	Lock files, per-unit runtime records, session metadata
`.gsd/runtime/rewrite-count.json`	Disk-persisted rewrite attempt counter (survives restarts)
`.gsd/activity/`	JSONL execution logs (timestamps, costs, outcomes)
`.gsd/completed-units.json`	Disk-backed idempotency log of completed unit keys

Creates

File	Condition
`.gsd/worktrees/<MID>/`	When `git.isolation: "worktree"` is set in preferences
`milestone/<MID>` git branch	When a new worktree is created for the milestone
Milestone CONTEXT.md / RESEARCH.md / ROADMAP.md	When dispatch rules determine these are needed
Slice RESEARCH.md / PLAN.md	When a new slice starts

Examples

Starting auto mode on a project with an active milestone:

> /gsd auto

● Deriving project state...
  Active milestone: M001 (Core Recipe Platform)
  Active slice: S01 (Database schema and auth)
  Phase: executing
  Active task: T01

● Dispatching unit: execute T01 (Build Prisma schema and seed data)
  Type: execute-task
  ─────────────────────────────────

  ... agent executes T01 ...

  ✓ T01 complete — 4 files changed, 1 migration created
  ✓ Artifact verified: task summary written and [x] checked in plan
  ✓ Auto-committed: "T01: Build Prisma schema and seed data"
  ✓ Doctor: all checks passed

● Dispatching unit: execute T02 (NextAuth configuration)
  Type: execute-task
  ─────────────────────────────────

  ... continues until milestone complete or stopped ...

● Milestone M001 complete — squash-merging to main
  ✓ Merged: "feat(M001): Core Recipe Platform"

Resuming after a pause:

> /gsd auto

● Detected paused session
  Resuming from: T03 (Signup and login pages)
  Completed: T01, T02
  ─────────────────────────────────

● Dispatching unit: execute T03
  ...

Resuming after a crash:

> /gsd auto

⚠ Crash detected — previous session (PID 12345) exited unexpectedly
  Recovered 47 tool calls from crashed session. Resuming with full context.

● Dispatching unit: execute T03 (with recovery context)
  ...

UAT verdict blocking progression:

> /gsd auto

⚠ UAT verdict for S01 is "fail" — blocking progression until resolved.
  Review the UAT result and update the verdict to PASS, or re-run /gsd auto after fixing.

Prompts Used

complete-milestone — Closes out a milestone after all slices are done
complete-slice — Verifies that all tasks in a slice actually deliver the slice goal, then writes the summary and UAT
discuss-milestone — Collects project context from the user and writes CONTEXT.md before planning begins
execute-task — The core executor prompt
plan-milestone — Reads milestone research and decomposes the work into demoable, risk-ordered slices
plan-slice — Decomposes a slice into a set of executable tasks, each sized to fit one context window
reassess-roadmap — Reviews the milestone roadmap after each slice completes, deciding whether remaining slices still make sense
replan-slice — Rewrites the remaining tasks in a slice when a blocker is discovered mid-execution
research-milestone — Opens the auto-mode pipeline by scouting the codebase and producing a research document
research-slice — Scouts the codebase at the start of each slice, producing a research document for the planner
rewrite-docs — Documentation refresh prompt
run-uat — User acceptance testing prompt
validate-milestone — Reconciliation gate before milestone completion

/gsd stop — Gracefully terminate auto mode
/gsd next — Execute one unit, then pause for input
/gsd status — View progress dashboard without interrupting
/gsd steer — Inject a course-correction override while auto mode runs
/gsd capture — Record a thought without interrupting auto mode

Previous
/gsd next Next
/gsd stop