In this guide (66 items)

GSD Workflow Guide

Get Shit Done (GSD) — Project Automation Guide

Automates projects with phases, executable plans, and parallel agents. Pipeline: Idea → Project → Milestone → Phase → Plan → Execution → Verification → Ship. Every step writes durable artefacts to .planning/ so context persists across sessions.

Project-agnostic. This guide describes the GSD framework itself; it doesn’t assume a specific repo.

Companion guides:

hexagonal-architecture.md / java-code-style.md / kotlin-code-style.md — what the executor agent applies when generating JVM code.
testing.md — how gsd-verifier + gsd-nyquist-auditor validate output.
adr.md — phase decisions captured as ADRs.
arch-doc-spec.md — phase-level architecture deliverables.
claude-code-guide.md — code generation conventions the executor follows.

Concept
Happy Path
Execution Modes
Lifecycle Hierarchy
Namespaces (Routers)
Command Reference
.planning/ Structure
Agents (33)
Quality Gates
Codebase Intelligence
Ideation Track
AI Integration Phases
Cross-AI Peer Review
Parallelization
Configuration & Gates
Recipes
Core Concepts
Backend JVM Tips
Common Pitfalls

1. Concept

GSD transforms an idea into running code through a structured pipeline. Each step produces durable artefacts under .planning/ that serve as persistent memory across sessions, context resets, and team members.

Inputs: idea, PRD, existing codebase, or partial planning docs. Outputs: executable phase plans, atomic commits, traceable requirements, verified deliverables.

Three properties distinguish GSD from ad-hoc Claude usage:

Goal-backward: plans derive from “what must this phase deliver?”, not from “what tasks should we do?”.
Persistent state: STATE.md records progress, velocity, decisions, and blockers; reloaded at every command.
Quality gates everywhere: configurable approval points before plan, before execute, before ship.

2. Happy Path

1
/gsd-new-project            ← vision + requirements + roadmap
2
   ↓
3
/gsd-spec-phase 1           ← (optional) clarify WHAT with ambiguity scoring → SPEC.md
4
   ↓
5
/gsd-discuss-phase 1        ← gather decisions + gray areas → CONTEXT.md
6
   ↓
7
/gsd-plan-phase 1           ← executable PLAN.md (verified by plan-checker)
8
   ↓
9
/gsd-execute-phase 1        ← atomic commits + SUMMARY.md
10
   ↓
11
/gsd-verify-work 1          ← conversational UAT → UAT.md
12
   ↓
13
/gsd-ship 1                 ← PR + review + merge-ready

Single-command shortcut that auto-detects state and advances:

/gsd-progress               # situational: status + next step + dispatch

The classic /gsd-next was folded into /gsd-progress — use /gsd-progress for both inspection and progression.

3. Execution Modes

Mode	Command	When
Interactive	`/gsd-plan-phase N`	Max control; confirm every decision
Semi-auto	`/gsd-plan-phase N --auto`	GSD picks defaults; you validate result
Quick	`/gsd-quick`	Ad-hoc work with tracking but no roadmap
Fast	`/gsd-fast <description>`	Trivial task inline, no subagents, no planning
Autonomous	`/gsd-autonomous`	All remaining phases without intervention
Manager	`/gsd-manager`	Dashboard managing multiple phases in parallel
Ultraplan (BETA)	`/gsd-ultraplan-phase N`	Offload planning to Claude Code cloud; review in browser
MVP	`/gsd-mvp-phase N`	Plan phase as vertical MVP slice (user story + SPIDR)

4. Lifecycle Hierarchy

GSD splits work into nested scopes. Each has its own commands and artefacts.

1
PROJECT
2
  └── MILESTONE (v1.0, v1.1, v2.0)
3
        └── PHASE (1, 2, 3, ...)
4
              └── PLAN (01, 02, 03, ...)
5
                    └── TASK (atomic commits)

Scope	Create	Audit	Archive
Project	`/gsd-new-project`	`/gsd-stats`	—
Milestone	`/gsd-new-milestone`	`/gsd-audit-milestone`	`/gsd-complete-milestone`
Phase	`/gsd-phase --insert`	`/gsd-audit-uat`	`/gsd-cleanup`
Plan	inside `/gsd-plan-phase`	`/gsd-plan-review-convergence`	—
Task	`/gsd-execute-phase`	`/gsd-verify-work`	one commit per task

Roadmap CRUD (was 3 separate commands; now one):

/gsd-phase --insert 3.1     # add phase between 3 and 4
/gsd-phase --remove 5       # remove and renumber
/gsd-phase --edit 2         # edit existing phase

5. Namespaces (Routers)

GSD ships 6 namespace skills (gsd-ns-*) that route to sub-skills by topic. Useful when you remember the area but not the exact command:

Namespace	Topics	Covers
`/gsd-ns-workflow`	workflow	`discuss-phase`, `plan-phase`, `execute-phase`, `verify-work`, `phase`, `progress`
`/gsd-ns-review`	quality gates	`code-review`, `debug`, `audit-uat`, `secure-phase`, `eval-review`, `ui-review`
`/gsd-ns-project`	project lifecycle	`new-milestone`, `complete-milestone`, `audit-milestone`, `milestone-summary`
`/gsd-ns-context`	codebase intelligence	`map-codebase`, `graphify`, `docs-update`, `extract-learnings`
`/gsd-ns-ideate`	exploration	`explore`, `sketch`, `spike`, `spec-phase`, `capture`
`/gsd-ns-manage`	workspace	`config`, `workspace`, `workstreams`, `thread`, `update`, `ship`, `inbox`

Use them when uncertain: each namespace prints a sub-menu. Power users skip them and call leaf skills directly.

6. Command Reference

6.1 Initialization

/gsd-new-project                              # vision → requirements → roadmap
/gsd-new-project --auto                       # fewer confirmations
/gsd-map-codebase                             # brownfield: parse existing code first
/gsd-ingest-docs                              # bootstrap from existing ADRs/PRDs/SPECs
/gsd-ingest-docs --mode merge --resolve auto  # merge external docs into existing .planning/

6.2 Per-phase workflow

/gsd-spec-phase N             # (optional) clarify WHAT + ambiguity scoring → SPEC.md
/gsd-discuss-phase N          # capture decisions + gray areas → CONTEXT.md
/gsd-mvp-phase N              # plan phase as vertical MVP slice (SPIDR splitting)
/gsd-ai-integration-phase N   # phases involving AI systems → AI-SPEC.md
/gsd-plan-phase N             # executable plan with goal-backward verification
/gsd-plan-phase N --research  # research first via gsd-phase-researcher
/gsd-execute-phase N          # wave-based parallelized execution
/gsd-verify-work N            # conversational UAT
/gsd-ship N                   # PR + review + merge-ready

/gsd-progress                 # situational: status + next step + dispatch
/gsd-stats                    # project metrics
/gsd-health                   # diagnose .planning/ + repair offer
/gsd-forensics                # post-mortem on failed workflow

6.4 Roadmap & lifecycle

/gsd-phase --insert 3.1       # CRUD on ROADMAP.md
/gsd-new-milestone "v1.1"     # start new milestone cycle
/gsd-complete-milestone v1.0  # archive completed milestone
/gsd-milestone-summary v1.0   # generate team-onboarding summary
/gsd-audit-milestone v1.0     # verify milestone vs original intent
/gsd-audit-uat                # cross-phase UAT outstanding items
/gsd-cleanup                  # archive completed phase dirs

6.5 Quick / ad-hoc

/gsd-quick                    # tracked task, no roadmap
/gsd-quick --full             # + research + plan-check + verification
/gsd-fast add email field to User entity   # trivial task inline
/gsd-capture --note "kafka retry idea"     # capture without acting
/gsd-capture --backlog "GraphQL support"   # park in backlog
/gsd-capture --seed "MCP server"           # save as long-term seed
/gsd-review-backlog           # promote backlog items to active milestone

6.6 Session continuity

/gsd-pause-work               # save context for resume
/gsd-resume-work              # restore prior session context
/gsd-thread list              # persistent cross-session threads
/gsd-thread close <slug>      # close a thread

6.7 Workspace & branching

/gsd-workspace --new <name>   # isolated workspace
/gsd-workspace --list
/gsd-workstreams create "api-refactor"   # parallel workstream
/gsd-workstreams switch "api-refactor"
/gsd-workstreams status
/gsd-pr-branch                # clean PR branch filtering out .planning/ commits

6.8 Configuration

/gsd-settings                 # interactive workflow toggles
/gsd-config --advanced        # advanced knobs
/gsd-config --integrations    # cross-AI + external integrations
/gsd-config --profile <name>  # apply model profile
/gsd-surface list             # which skills are surfaced
/gsd-surface profile backend  # apply a surface profile
/gsd-update                   # update GSD to latest version
/gsd-update --sync            # re-sync local patches
/gsd-profile-user             # generate developer behavioral profile
/gsd-help                     # discover commands

6.9 Debug & undo

/gsd-debug                    # scientific-method debugging; persists across resets
/gsd-undo --last 1            # safe revert of last N commits
/gsd-undo --phase 03          # roll back a whole phase with dep checks
/gsd-undo --plan 03-02        # roll back a single plan

7. `.planning/` Structure

After /gsd-new-project, the directory looks like this:

1
.planning/
2
├── PROJECT.md                  # vision, requirements (v1 / v2 / out-of-scope)
3
├── USER-STORIES.md             # stories with hexagonal sizing
4
├── REQUIREMENTS.md             # traceable REQ-IDs
5
├── ROADMAP.md                  # phases with dependencies + success criteria
6
├── STATE.md                    # live memory: progress, velocity, decisions
7
├── config.json                 # workflow config
8
├── research/                   # domain research (optional)
9
│   ├── STACK.md
10
│   ├── FEATURES.md
11
│   ├── ARCHITECTURE.md
12
│   └── PITFALLS.md
13
├── codebase/                   # parallel mapper outputs (gsd-map-codebase)
14
│   ├── TECH.md
15
│   ├── ARCH.md
16
│   ├── QUALITY.md
17
│   └── CONCERNS.md
18
├── intel/                      # codebase intel updates (gsd-intel-updater)
19
├── graphs/                     # project knowledge graph (gsd-graphify)
20
├── threads/                    # cross-session threads (gsd-thread)
21
├── backlog/                    # captured ideas pending promotion
22
├── milestones/
23
│   ├── v1.0/                   # archived milestones
24
│   └── current → v1.1/
25
└── phases/
26
    ├── 01-setup-base/
27
    │   ├── 01-SPEC.md          # WHAT (optional, from spec-phase)
28
    │   ├── 01-CONTEXT.md       # locked decisions (from discuss-phase)
29
    │   ├── 01-AI-SPEC.md       # AI design contract (if AI phase)
30
    │   ├── 01-RESEARCH.md      # phase-level research
31
    │   ├── 01-PATTERNS.md      # patterns mapped pre-plan
32
    │   ├── 01-01-PLAN.md       # executable plan 1
33
    │   ├── 01-02-PLAN.md       # executable plan 2 (parallel-safe)
34
    │   ├── 01-SUMMARY.md       # execution result
35
    │   ├── 01-UAT.md           # acceptance tests
36
    │   ├── 01-VERIFICATION.md  # gap analysis
37
    │   ├── 01-REVIEW.md        # code-review findings
38
    │   ├── 01-SECURITY.md      # threat mitigation evidence
39
    │   ├── 01-EVAL-REVIEW.md   # AI evaluation audit
40
    │   ├── 01-UI-REVIEW.md     # frontend visual audit
41
    │   └── 01-LEARNINGS.md     # extracted decisions + patterns
42
    └── 02-core-feature/
43
        └── ...

Not every file is mandatory per phase — only those produced by the commands run.

8. Agents (33)

GSD spawns specialized subagents in isolated contexts. Each returns a structured artefact.

8.1 Core pipeline (4)

Agent	Role	Triggered by
`gsd-planner`	Builds PLAN.md from CONTEXT + RESEARCH + PATTERNS	`/gsd-plan-phase`
`gsd-plan-checker`	Verifies plan delivers phase goal	post-planner
`gsd-executor`	Wave-parallelized execution with atomic commits	`/gsd-execute-phase`
`gsd-verifier`	Goal-backward verification of code	post-execute

8.2 Discuss + research (5)

Agent	Role
`gsd-assumptions-analyzer`	Detects assumptions in approach via codebase analysis
`gsd-advisor-researcher`	Researches single gray area, returns comparison table
`gsd-phase-researcher`	Researches HOW to implement a phase
`gsd-research-synthesizer`	Synthesizes parallel researcher outputs
`gsd-pattern-mapper`	Maps new files to existing codebase patterns

8.3 Project intake (4)

Agent	Role
`gsd-project-researcher`	Domain ecosystem research before roadmap
`gsd-roadmapper`	Requirements → phases with dep mapping
`gsd-codebase-mapper`	Parallel codebase analysis (tech/arch/quality/concerns)
`gsd-user-profiler`	Behavioral profile of the developer

8.4 Quality gates (8)

Agent	Role	Trigger
`gsd-code-reviewer`	REVIEW.md with severity-classified findings	`/gsd-code-review`
`gsd-code-fixer`	Applies fixes from REVIEW.md atomically	`/gsd-code-review --fix`
`gsd-security-auditor`	Verifies PLAN.md threat mitigations exist	`/gsd-secure-phase`
`gsd-eval-auditor`	Audits AI phase evaluation coverage	`/gsd-eval-review`
`gsd-ui-auditor`	6-pillar visual audit of frontend code	`/gsd-ui-review`
`gsd-ui-checker`	Validates UI-SPEC against quality dimensions	`/gsd-ui-phase`
`gsd-nyquist-auditor`	Generates tests for coverage gaps	`/gsd-validate-phase`
`gsd-integration-checker`	Cross-phase E2E integration	post multi-phase

8.5 Debug (2)

Agent	Role
`gsd-debug-session-manager`	Multi-cycle checkpoint orchestration
`gsd-debugger`	Scientific-method bug investigation

8.6 AI integration (4)

Agent	Role
`gsd-ai-researcher`	Framework docs research → AI-SPEC.md
`gsd-domain-researcher`	Domain expert criteria for AI evals
`gsd-eval-planner`	Designs eval strategy + rubrics + dataset spec
`gsd-framework-selector`	Decision matrix for AI framework picking

8.7 Docs ingestion (4)

Agent	Role
`gsd-doc-classifier`	Classifies external doc as ADR/PRD/SPEC/DOC
`gsd-doc-synthesizer`	Consolidates classified docs + detects conflicts
`gsd-doc-writer`	Writes/updates project docs
`gsd-doc-verifier`	Verifies factual claims vs codebase

8.8 Intel + UI (2)

Agent	Role
`gsd-intel-updater`	Writes structured intel to `.planning/intel/`
`gsd-ui-researcher`	UI-SPEC.md design contract for frontend phases

8.9 Removed since 1.30

The older guide referenced gsd-story-writer and gsd-epic-writer. Those were rolled into gsd-roadmapper + intake workflow.

9. Quality Gates

GSD ships post-execution audits per concern. Each produces a scored artefact.

Command	Audits	Output	When
`/gsd-code-review N`	Bugs, security, code quality	`REVIEW.md`	After execute
`/gsd-code-review N --fix`	+ applies fixes	REVIEW + commits	After review
`/gsd-secure-phase N`	Threat mitigations vs PLAN	`SECURITY.md`	After execute, before ship
`/gsd-eval-review N`	AI evaluation coverage	`EVAL-REVIEW.md`	After AI phase execute
`/gsd-ui-review N`	6-pillar frontend audit	`UI-REVIEW.md`	After frontend phase
`/gsd-validate-phase N`	Nyquist gap detection + test fill	tests + verification	After verify
`/gsd-audit-uat`	Cross-phase UAT outstanding	report	Pre-milestone close
`/gsd-audit-milestone vN`	Milestone vs original intent	report	Pre-archive
`/gsd-audit-fix --source <audit>`	Autonomous classify → fix → test → commit	commits	After any audit
`/gsd-add-tests N`	Generate tests from UAT criteria	tests + commits	Coverage backfill

10. Codebase Intelligence

For brownfield and ongoing intel:

/gsd-map-codebase             # parallel mapper: tech, arch, quality, concerns
/gsd-graphify build           # build .planning/graphs/ knowledge graph
/gsd-graphify query <term>    # query the graph
/gsd-graphify diff            # diff vs last build
/gsd-graphify status          # show graph stats
/gsd-docs-update              # generate/refresh project docs, verify vs code
/gsd-docs-update --verify-only # check existing docs for drift
/gsd-extract-learnings N      # mine completed phase for decisions + patterns

Outputs land under .planning/codebase/, .planning/graphs/, .planning/intel/, docs/.

11. Ideation Track

For pre-commit exploration:

/gsd-explore                  # Socratic ideation routing
/gsd-sketch <design idea>     # throwaway HTML mockup
/gsd-sketch frontier          # propose next sketch
/gsd-spike <idea to validate> # experiential exploration
/gsd-spike frontier           # propose next spike
/gsd-spec-phase N             # crystallize WHAT with ambiguity scoring
/gsd-capture --note "<text>"
/gsd-capture --backlog "<text>"
/gsd-capture --seed "<text>"
/gsd-capture --list
/gsd-review-backlog           # promote backlog into active milestone

Ideation outputs feed back into discuss-phase and plan-phase.

12. AI Integration Phases

When the phase builds AI systems:

/gsd-ai-integration-phase N   # generate AI-SPEC.md
/gsd-eval-review N            # audit eval coverage post-execute

Pipeline:

gsd-domain-researcher — what does “good” look like in this domain?
gsd-framework-selector — pick AI framework via decision matrix.
gsd-ai-researcher — framework docs → implementation guidance.
gsd-eval-planner — eval strategy, rubrics, reference dataset spec.
Output: AI-SPEC.md with all of the above + production monitoring plan.
Post-execute: gsd-eval-auditor verifies coverage vs AI-SPEC.

13. Cross-AI Peer Review

External AI peer review of phase plans:

/gsd-review --phase N --gemini --claude --codex
/gsd-plan-review-convergence N --codex --gemini   # loop until no HIGH concerns
/gsd-import --from <file>                          # ingest external plan with conflict detection
/gsd-import --from-gsd2                            # ingest from another GSD instance

Useful when you want a second opinion before executing a costly phase.

14. Parallelization

14.1 Waves

Plans group by dependencies; independent plans execute concurrently.

1
Wave 1: [Plan A, Plan B]      ← independent, parallel
2
Wave 2: [Plan C]               ← depends on A + B
3
Wave 3: [Plan D, Plan E]      ← independent, parallel

14.2 Config

1
{
2
  "parallelization": {
3
    "enabled": true,
4
    "max_concurrent_agents": 3,
5
    "min_plans_for_parallel": 2,
6
    "plan_level": true,
7
    "task_level": false
8
  }
9
}

14.3 Workstreams (cross-phase parallelism)

Isolated streams for parallel feature work:

/gsd-workstreams create "api-refactor"
/gsd-workstreams list
/gsd-workstreams switch "api-refactor"
/gsd-workstreams status
/gsd-workstreams progress
/gsd-workstreams complete
/gsd-workstreams resume

14.4 Workspaces (isolated environments)

For multi-repo / multi-project scenarios:

/gsd-workspace --new project-a
/gsd-workspace --list
/gsd-workspace --remove project-a

15. Configuration & Gates

15.1 Interactive

/gsd-settings                 # quick toggles
/gsd-config                   # full menu
/gsd-config --advanced
/gsd-config --integrations
/gsd-config --profile <name>

15.2 Key options in `config.json`

Option	Default	Effect
`workflow.research`	`true`	Research before planning
`workflow.plan_check`	`true`	Verify plan before execute
`workflow.verifier`	`true`	Verify result post-execute
`workflow.discuss_mode`	`"discuss"`	`discuss` = ask user; `assumptions` = analyze code
`git.branching_strategy`	`"none"`	`none` / `phase` / `milestone`
`parallelization.enabled`	`true`	Wave-parallel execution
`parallelization.max_concurrent_agents`	`3`	Concurrent agents
`gates.confirm_project`	`true`	Confirm project intake
`gates.confirm_phases`	`true`	Confirm phase breakdown
`gates.confirm_roadmap`	`true`	Confirm ROADMAP.md
`gates.confirm_plan`	`true`	Confirm plan before execute
`gates.execute_next_plan`	`true`	Confirm before each plan in execute-phase
`gates.confirm_transition`	`true`	Confirm phase → phase transition
`model_profile`	(n/a)	Per-task model selection (haiku/sonnet/opus)

15.3 Max autonomy preset

1
{
2
  "gates": {
3
    "confirm_project": false,
4
    "confirm_phases": false,
5
    "confirm_roadmap": false,
6
    "confirm_plan": false,
7
    "execute_next_plan": false,
8
    "confirm_transition": false
9
  }
10
}

Pair with /gsd-autonomous for end-to-end execution without prompts.

15.4 Surface profiles

Toggle which skills are surfaced without reinstalling:

/gsd-surface list
/gsd-surface status
/gsd-surface profile backend       # apply backend-focused profile
/gsd-surface disable ui            # hide UI-related skills
/gsd-surface enable ai             # surface AI-integration skills
/gsd-surface reset                 # revert to default

16. Recipes

16.1 Greenfield, max autonomy

/gsd-new-project --auto
/gsd-autonomous

16.2 From an existing PRD/spec

/gsd-ingest-docs --mode new        # bootstrap from PRDs/ADRs in repo
/gsd-plan-phase 1

16.3 Brownfield (existing codebase)

/gsd-map-codebase
/gsd-graphify build
/gsd-new-project                   # vision over existing code
/gsd-plan-phase 1

16.4 Quick feature (no ceremony)

/gsd-quick                         # plan + execute + tracking
# or trivial:
/gsd-fast add email field to UserEntity

16.5 Persistent debugging

/gsd-debug                         # scientific method; persists across resets
# context reset later:
/gsd-debug                         # auto-resumes

16.6 Resume after pause

/gsd-resume-work
/gsd-progress                      # auto-advance

16.7 Status sweep

/gsd-progress
/gsd-stats
/gsd-health

16.8 Pre-PR cleanup

/gsd-audit-uat                     # outstanding UAT items
/gsd-audit-fix --source audit-uat  # autonomous classify + fix
/gsd-pr-branch                     # filter out .planning/ commits
/gsd-ship N

16.9 Milestone close

/gsd-audit-milestone v1.0          # vs original intent
/gsd-milestone-summary v1.0        # team-onboarding summary
/gsd-complete-milestone v1.0       # archive
/gsd-new-milestone "v1.1"          # next cycle

16.10 AI-system phase

/gsd-ai-integration-phase N        # AI-SPEC.md
/gsd-plan-phase N
/gsd-execute-phase N
/gsd-eval-review N                 # audit eval coverage

16.11 Cross-AI second opinion

/gsd-plan-phase N
/gsd-plan-review-convergence N --codex --gemini
/gsd-execute-phase N

16.12 Failed workflow forensics

/gsd-forensics                     # diagnose what went wrong
/gsd-undo --last 1                 # roll back if needed

17. Core Concepts

Goal-Backward Thinking

GSD plans from the goal back. The planner agent asks “what must this phase deliver?” then derives tasks — not the reverse. Stops over-engineering.

Gray Areas → CONTEXT.md

Ambiguous decisions get captured by discuss-phase and locked in CONTEXT.md. Downstream agents (planner, executor) cannot reinterpret locked decisions — they branch off the CONTEXT, not the discussion.

Atomic Commits

Each executed task = one commit. Failed task rolls back cleanly. /gsd-undo walks the manifest with dependency checks.

STATE.md as Live Memory

Persists across sessions: progress, velocity, decisions, blockers. Every GSD command reads it on entry, writes it on exit.

Nyquist Validation

Post-execute audit that detects gaps between “what the phase promised” (per PLAN.md goal-backward) and “what exists in the code”. Auto-generates tests for uncovered behaviour.

Manifest-Backed Undo

Every phase + plan tracked in a manifest. /gsd-undo --phase NN reverts the manifest tail with dependency checks — safer than raw git reset.

Workstreams ≠ Workspaces

Workstream: parallel feature stream within one project (/gsd-workstreams).
Workspace: isolated environment (a project, a separate repo, a sandbox) (/gsd-workspace).

Surfaces vs Installation

/gsd-surface toggles which skills appear in Claude’s discovery without uninstalling. Lets a single install serve different roles (backend, frontend, AI).

18. Backend JVM Tips

/gsd-discuss-phase --auto lets GSD make hexagonal-architecture decisions based on your guidelines without prompting.
gsd-executor honours your hexagonal-java / hexagonal-kotlin skills — places generated code in the correct layer.
Combine with /tdd skill during execution to force Red-Green-Refactor.
/gsd-quick --research is the right scope when exploring a library before integrating it.
Set git.branching_strategy: "phase" to auto-create a branch per phase.
For DB phases, the executor will trigger arch-liquibase-migrator if you have /arch-migrate available — pair with /gsd-secure-phase post-execute.
For event-publishing phases, gsd-executor + arch-outbox-pattern skill generate the canonical outbox shape; verify with /arch-outbox.
For API phases, pair /gsd-plan-phase with /arch-api post-execute to catch breaking changes.

19. Common Pitfalls

Symptom	Cause	Fix
Planner re-asks decisions you already made	`discuss-phase` not run; or CONTEXT not locked	Run `/gsd-discuss-phase` first; verify CONTEXT.md exists
Executor diverges from intent	Plan was approved without `plan-check`	Enable `workflow.plan_check`; re-run plan
Phase loops on verify-work	UAT criteria unclear in PLAN	Tighten plan acceptance criteria; rerun verify
Multiple agents collide on same file	`parallelization.task_level = true`	Disable task-level; keep plan-level only
`.planning/` polluted with stale phases	Old milestones never archived	`/gsd-cleanup` after `/gsd-complete-milestone`
PR includes `.planning/` commits	Branched off without filter	`/gsd-pr-branch` strips `.planning/` commits
`gsd-debugger` loses context after reset	Not a problem — `/gsd-debug` reuses session state	Just rerun `/gsd-debug`
“Command not found” for old names	Renamed: `add/insert/remove-phase` → `/gsd-phase`; `add-todo/backlog` → `/gsd-capture`; `next` → `/gsd-progress`	Use new names
Re-asks gray areas every session	`discuss_mode` set wrong	Use `discuss` for first run; switch to `assumptions` for automated subsequent runs
Coverage report empty	`verifier` disabled or `jacocoTestReport` not wired	Enable `workflow.verifier`; see gradle.md §4.3
Plan rejected by plan-checker	Plan lacks goal-backward justification	Re-plan with `--research` or split into smaller phases