GSD Beyond the Happy Path
Auto-advance quirks, Nyquist validation gaps, three verification layers, and a brief detour through GSD-2 — what I've learned using GSD across several projects.
This is a companion to my first post on GSD, which covers the basics — how the process works, what surprised me, and the core commands outside the main workflow. This post is what I’ve learned since, after several more projects and more time spent in the corners of the system. The short version: auto-advance can silently run through your discussions, Nyquist validation is only half-automated, and GSD-2 exists but isn’t there yet.
Beyond the main workflow
The original post covers debug, quick, insert-phase, and verify-work. Here are a few more I’ve picked up since.
Check assumptions before planning — /gsd:list-phase-assumptions N surfaces what Claude thinks before you commit to a plan: which libraries it would use, what order it would build things, what it considers in and out of scope. Purely conversational, no files created — a lightweight checkpoint that takes a minute.
Already have a spec — /gsd:plan-phase N --prd path/to/spec.md generates context from a PRD and jumps straight to planning. Skips discussion entirely when you’ve already done that work elsewhere.
Quick, but with guardrails — /gsd:quick --discuss --full adds the discussion and verification that plain /gsd:quick skips. The flags are composable — use either or both.
Automatic mode
I enabled auto-advance in the project settings, ran /gsd:discuss-phase for phase 1, and the pipeline ran through the entire milestone without stopping. Discussion, planning, and execution for phase 1 — then straight into phase 2, phase 3, and beyond. I wasn’t there to shape any of the discussions after the first one.
GSD has an auto-advance setting in /gsd:settings and an --auto flag you can pass to individual commands. They’re not the same thing. The --auto flag on /gsd:discuss-phase chains discuss → plan → execute for that single phase, then stops. The auto_advance config setting powers through your entire milestone — once execution completes, transition logic invokes the next phase’s discussion automatically.
If you want the convenience of auto-advance within a phase but still want to be present for every discussion, don’t enable auto-advance in settings. Run each phase’s cycle manually, or use --auto on individual commands where you want the chaining.
Three verification layers
GSD has three distinct verification mechanisms. They’re complementary, not redundant — each catches different things.
Execution verifier (workflow.verifier in settings) — runs automatically at the end of /gsd:execute-phase. Checks that artifacts actually exist, aren’t stubs, and are properly wired together. This is a goal-backward check: does the codebase deliver what the phase promised? You don’t invoke this — it runs as a sub-agent during execution when the setting is enabled.
Interactive UAT (/gsd:verify-work) — this is the one where you test. Claude presents expected behaviors derived from the execution summaries, and you confirm or deny each one. On failures, it spawns parallel debug agents to investigate root causes and creates fix plans automatically. Run /gsd:execute-phase N --gaps-only to execute those fixes.
Nyquist validation (/gsd:validate-phase N) — audits automated test coverage after execution. Checks whether each requirement has a corresponding test, identifies gaps, and spawns a dedicated agent to write the missing tests. Only works when workflow.nyquist_validation is enabled in settings.
Nyquist: half-automated
When you enable Nyquist during project setup, it adds test coverage research to your planning phase automatically — plans include verification requirements and can be blocked if tasks lack automated tests. That part works well.
What I didn’t realize: that’s only half of it. After execution, you still need to run /gsd:validate-phase N manually to audit whether the tests actually exist and generate any that are missing. Planning validates the plan, the audit validates the execution — but if the first half is baked into the automatic pipeline, the second half should be too. Having to remember a manual step after every execution is exactly the kind of discipline erosion GSD is supposed to prevent.
GSD-2
GSD-2 is a separate product — a standalone CLI built on the Pi coding agent, not a Claude Code plugin. It supports 20+ LLM providers, has a real state machine for auto mode with crash recovery and budget ceilings, and uses git worktree isolation with squash merges per milestone. Different philosophy: more autonomous, less interactive.
I tried it with GPT 4.5 and went straight into auto mode. That was probably a mistake — it skipped steps I was used to having, and the experience felt untethered compared to v1’s structured control. Configuration wasn’t obvious, and my Claude Code plugins didn’t carry over. Combined with the lack of a “wow” moment, I went back to v1.
The architecture is interesting. If GSD-2 matures and the interactive discussion model from v1 makes it in, it could be compelling. If the maintainers move on from v1 and GSD-2 isn’t there yet, I’d consider forking v1 — the core workflow is too valuable to let go.
What I’d change
The original post has my earlier wishlist. Three more since:
Nyquist should be fully automatic. If planning-time Nyquist is part of the pipeline, the post-execution audit should be too. Having to remember /gsd:validate-phase after every execution defeats the purpose of enabling it during project setup.
Auto-advance should be one thing, not two. The config setting and the --auto flag behave differently in ways that aren’t obvious. The setting powers through your entire milestone; the flag chains within a single phase. If you don’t know this, you’ll end up where I did — watching your discussions happen without you.
UAT should be automatable. Interactive UAT makes sense as an option, but sometimes you just want the system to verify on its own. I end up running acceptance tests through /gsd:debug as a workaround. A hands-off verification mode — where GSD runs the tests, checks the results, and only pulls you in when something fails — would close the last manual gap in the pipeline.
These aren’t dealbreakers — they’re friction points in a system that’s otherwise remarkably disciplined. The original post’s thesis still holds: the value of GSD is that it doesn’t get lazy when you do. These are the edges where that promise has room to grow.
Written with AI assistance. How that works →
Found this useful?
Get notified when I publish something new. No spam, unsubscribe anytime.