/gsd-workflow

name: gsd-workflow
description: Use when the user asks "what should I work on", mentions GSD phases, ROADMAP, or .planning/ artifacts. Routes to the correct GSD command for the current project state.
description-frequency: on-demand
user-invocable: true
version: 1.0.0
format: 2025-10-02
triggers:
  - "what should I work on next"
  - "which GSD command do I run"
updated: 2026-04-25
status: ACTIVE

GSD Workflow Routing

Route user intent to GSD commands. Explicit /gsd: commands bypass routing -- read `.claude/commands/gsd/[command].md` directly.

5-Stage Classification Pipeline

When the user provides natural language related to project workflow, route through the GSD Orchestrator's classification pipeline:

1. **Exact match** -- direct command mapping (fastest) 2. **Lifecycle filtering** -- narrow candidates by current project phase 3. **Bayesian classification** -- probabilistic intent matching 4. **Semantic fallback** -- embedding-based similarity for ambiguous requests 5. **Confidence resolution** -- threshold check; ask user if uncertain

**When to use the orchestrator:** The user says something like "review the requirements," "what's the project status," "let's verify phase 3," or any natural language that maps to a GSD lifecycle action but doesn't use explicit slash commands.

**When to bypass it:** The user types an explicit GSD slash command. Execute directly.

**When confidence is low:** Ask the user to clarify rather than guessing. A wrong routing is worse than a clarifying question.

Quick Command Routing

The top-10 most common routes:

| User Says | Route To | |-----------|----------| | "what should I work on" | `/gsd:progress` | | "continue where I left off" | `/gsd:progress` | | "build phase X" | `/gsd:execute-phase X` | | "plan the next phase" | `/gsd:plan-phase N` | | "discuss how phase X should work" | `/gsd:discuss-phase N` | | "something's broken" | `/gsd:debug` | | "quick fix / small task" | `/gsd:quick` | | "verify phase X" | `/gsd:verify-work X` | | "add a phase" | `/gsd:phase` | | "start new project" | `/gsd:new-project` |

For full routing tables including skill-creator actions, see `references/command-routing.md`.

Guidance Heuristics

When to Suggest GSD

**Always suggest GSD when:**

• User asks to build, create, or implement something substantial
• User seems unsure where to start
• Work would benefit from planning before coding
• Context is fresh (session just started)

**Suggest with explanation:**

This looks like a good candidate for `/gsd:plan-phase N` -- it'll break this
down into atomic tasks with verification criteria. Want me to run that,
or would you prefer to dive in directly?

When to Suggest skill-creator

**Suggest skill-creator when:**

• You notice the same sequence of steps has occurred 3+ times
• The user corrects the same kind of output repeatedly
• A workflow is complex enough to benefit from codification
• The user asks "why do I keep having to tell you this?"

**Suggest naturally:**

I've noticed we run the same lint -> test -> fix cycle after every code change.
Want me to capture this as a skill so it happens automatically?

When to Allow Override

**Respect user override when:**

• They explicitly say "just do it" or "skip the ceremony"
• The task is genuinely trivial (< 5 minutes)
• They're exploring/experimenting, not building
• They have domain expertise and know what they want

**Acknowledge gracefully:**

Got it -- working on this directly. If it grows in scope, we can always
capture it in a plan retroactively with `/gsd:quick`.

When to Push Back

**Gently push back when:**

• User is about to make changes without understanding current state
• Work would conflict with existing plans
• The request is ambiguous and needs questioning

**Push back helpfully:**

Before I make changes, let me check `/gsd:progress` -- there might be
existing plans that touch this area. One moment...

Phase Behavior

Instruction Markers

| Marker | Meaning | Claude Action | |--------|---------|---------------| | `## > Next Up` | Next command to run | Read the instruction and execute it | | `/clear first ->` | Context window full, needs reset | Tell user to run `/clear`, then continue | | `Ready to build` | Planning complete, execution ready | Proceed to `/gsd:plan-phase` or `/gsd:execute-phase` | | `ROADMAP CREATED` | Roadmap agent finished | Review output, proceed to next phase | | `PLAN CREATED` | Planning agent finished | Proceed to execution |

Workflow Patterns

**Standard Cycle:**

/gsd:plan-phase N -> /clear -> /gsd:execute-phase N -> /gsd:verify-work N

**Fresh Session Recovery:**

/gsd:progress  (or)  /gsd:resume-work

**Mid-Work Context Reset:**

/gsd:pause-work -> /clear -> /gsd:resume-work

**Debugging Flow:**

/gsd:debug "description" -> investigate -> /clear -> /gsd:debug (resume)

For phase transition details and response patterns, see `references/phase-behavior.md`.

YOLO Mode

**Detection:** Read `.planning/config.json`. If `"mode": "yolo"`, autonomous operation is active.

**6-Step Autonomous Protocol:** 1. **Read GSD command output carefully** -- it contains your next instruction 2. **Execute the suggested command** -- don't wait for user confirmation 3. **Handle `/clear` requirements** -- inform user when context reset is needed 4. **Continue the workflow** -- GSD is a pipeline, keep it moving 5. **Load relevant skills** -- even in YOLO mode, check for applicable skills before phases 6. **Record observations** -- YOLO sessions generate high-value pattern data

For example recognition and edge cases, see `references/yolo-mode.md`.

Running GSD Commands

To run a GSD command, read the command file from `.claude/commands/gsd/[command].md` and follow its process. The command file contains:

• `<objective>` -- What the command achieves
• `<process>` -- Step-by-step instructions to follow
• `<success_criteria>` -- How to know it's complete