GSD-Build Quick Mode vs Full Phases: When to Use Each Workflow

GSD-build quick mode is a lightweight, ad-hoc workflow designed for single atomic tasks that skips the research-heavy scaffolding of full phases while maintaining core guarantees like atomic commits and STATE.md tracking.

The gsd-build/get-shit-done repository provides structured workflows for software development, offering both comprehensive phase-based lifecycle management and a streamlined quick mode for rapid execution. Understanding when to use gsd-build quick mode versus the full phase workflows is essential for optimizing development velocity without sacrificing code quality or project traceability.

What is GSD-Build Quick Mode?

Quick mode is implemented in get-shit-done/workflows/quick.md as a lightweight, ad-hoc workflow that executes a single, self-contained task while preserving GSD’s core guarantees. According to the source code, it spawns a quick planner, an optional plan-checker, an executor, and (if requested) a verifier, then records results in .planning/quick/<num>-<slug>/ directories and the "Quick Tasks Completed" table of STATE.md.

Unlike full phases, quick mode does not require a research step or multi-iteration planning loops. It operates directly on the existing codebase state, making it ideal for tasks that fit into 1–3 focused subtasks expressed in a single sentence.

Understanding Full-Phase Workflows

Full-phase workflows represent the canonical GSD lifecycle for a milestone phase, defined by the commands /gsd:discuss-phase, /gsd:plan-phase, /gsd:execute-phase, and /gsd:verify-work. As implemented in the repository, these workflows involve:

• A research step to gather domain context
• Multi-iteration planning loops with parallel execution waves
• Manual UAT verification steps
• Explicit phase tracking in ROADMAP.md and STATE.md

Full phases create dedicated directories under phases/XX-feature-name/ containing research documents, plan files, execution logs, and verification reports.

When to Use GSD-Build Quick Mode Over Full Phases

Small Atomic Tasks and Bug Fixes

Use quick mode (/gsd:quick) for small bug fixes, UI tweaks, config changes, or any task expressible in a single sentence. The source code specifies that these tasks fit into a single atomic plan with 1–3 focused subtasks and do not require the full research and roadmap scaffolding of a phase.

Mid-Phase Interruptions

Quick mode can be executed mid-phase without disrupting active full-phase workflows. According to get-shit-done/workflows/quick.md, quick tasks only require the existence of ROADMAP.md and do not require the roadmap to be in a specific phase state. This makes quick mode ideal for urgent fixes that must interrupt current milestone work.

Speed vs. Safety Trade-offs

The repository provides three safety levels for quick mode:

• Default quick mode: Skips plan-checking and verification, minimizing token usage and runtime for "yolo" iterations where speed outweighs thoroughness.
• Quick mode with --full flag: Enables the plan-checker (max 2 iterations) and verifier steps, providing the same quality guarantees as full phases without creating a new phase entry in the roadmap.
• Full phases: Maximum safety with research, unlimited planning iterations, and manual UAT.

Use quick mode with --full when you need the full safety net (plan-checking, verification, status columns in STATE.md) but want to avoid the overhead of a complete phase lifecycle.

Implementation and Code Examples

Simple Quick Task (Default, Lightweight)

/gsd:quick
> "Update the npm scripts.test command to run npm run lint && npm run test"

Result:

• The planner creates a one-step plan in .planning/quick/001-update-npm-test/001-PLAN.md
• The executor commits the change atomically
• STATE.md receives a new row in "Quick Tasks Completed" (no status column)

Quick Task with Full Guarantees (--full)

/gsd:quick --full
> "Refactor the authentication middleware to use async/await and add unit tests"

Result:

• Same flow as above, but the plan-checker runs (max 2 revisions)
• A verifier creates 001-VERIFICATION.md
• The row in STATE.md includes a "Status" column (e.g., Verified, Needs Review)

Full-Phase Example for Comparison

/gsd:plan-phase 3   # research → plan → verify

# after successful plan:

/gsd:execute-phase 3
/gsd:verify-work 3

Result:

• Creates a new phase directory phases/03-my-feature/ with research, plan, execution, and verification files
• Updates ROADMAP.md and STATE.md with a new phase entry

Key Files and Architecture

File	Role in Quick Mode
get-shit-done/workflows/quick.md	Full specification of the quick workflow, argument parsing, plan-checker, executor, verifier, and STATE.md updates
bin/gsd-tools.cjs	CLI helper used by quick mode to bootstrap the task (init quick …)
agents/gsd-planner.md	Planner agent instructions used by quick mode
agents/gsd-executor.md	Executor agent that runs the plan created by quick mode
agents/gsd-plan-checker.md	Optional plan-checker invoked when --full is supplied
agents/gsd-verifier.md	Optional verifier invoked in full quick mode
.planning/quick/<num>-<slug>/	Runtime directory containing -PLAN.md, -SUMMARY.md, optional -VERIFICATION.md
.planning/STATE.md	Holds the "Quick Tasks Completed" table

Summary

• GSD-build quick mode provides a lightweight, ad-hoc workflow for single atomic tasks that fits into 1–3 subtasks, storing artifacts in .planning/quick/ and updating STATE.md without modifying the roadmap.
• Use default quick mode for speed-critical fixes where plan-checking overhead is unnecessary, or quick mode with --full when you need plan-checking (max 2 iterations) and verification without creating a new phase.
• Use full-phase workflows for multi-step features requiring research, unlimited planning iterations, and explicit roadmap tracking via ROADMAP.md and phases/ directories.
• Quick mode can execute mid-phase without disrupting active full-phase workflows, making it ideal for urgent interruptions.

Frequently Asked Questions

What is the difference between gsd-build quick mode and full phases?

GSD-build quick mode is designed for single, self-contained tasks that require minimal planning overhead, spawning only a quick planner, optional plan-checker, executor, and optional verifier. Full phases implement the complete GSD lifecycle including research steps, multi-iteration planning loops, parallel execution waves, and manual UAT verification, creating dedicated directories under phases/ and updating ROADMAP.md with explicit phase tracking.

Can I run gsd-build quick mode during an active phase?

Yes, quick mode can be executed mid-phase without disrupting active full-phase workflows. According to the workflow specification in get-shit-done/workflows/quick.md, quick tasks only require the existence of ROADMAP.md and do not require the roadmap to be in a specific phase state, making it ideal for urgent fixes that must interrupt current milestone work.

Does gsd-build quick mode support verification and plan-checking?

Yes, but only when invoked with the --full flag. The default quick mode skips plan-checking and verification to minimize token usage and runtime. When using /gsd:quick --full, the workflow enables the plan-checker agent (limited to maximum 2 iterations) and the verifier agent, providing the same quality guarantees as full phases without creating a new roadmap phase entry.

Where does gsd-build quick mode store its artifacts?

Quick mode stores artifacts in .planning/quick/<num>-<slug>/ directories within the project root, containing files such as -PLAN.md, -SUMMARY.md, and optional -VERIFICATION.md. It also updates the "Quick Tasks Completed" table in .planning/STATE.md to track task status and completion, unlike full phases which store artifacts in phases/ directories and update ROADMAP.md with phase entries.

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