The Anatomy of Claude Code Workflows: Turning Slash Commands into an AI Development System

Anatomy of a Claude Code Workflow: How Slash Commands become an AI Development System

The tooling surrounding AI-driven development workflows for Claude Code is currently evolving at breathtaking speed.

To understand how such a tool works under the hood, I took a closer look at GSD (Get Shit Done). In this post, using GSD as an example, I will briefly explain how Spec-Driven Development workflows function and which Claude Code tools are utilized in the process. The goal is to understand fundamental patterns in order to apply them to your own workflows.

The Idea of Spec-Driven Development

In short: the idea is to define detailed requirements and the expected behavior of software before implementation. This specification then serves as a guide for development and a basis for testing to ensure the code meets the requirements.

The objective is to create better context for implementation by an LLM.

Tools like GSD use sophisticated question-and-answer workflows to help clearly define requirements. Additionally, they solve a core problem of agentic coding—Context Rot: the gradual loss of quality as limited token context windows fill up during long coding sessions.

What is "Get-Shit-Done"?

With 23k stars on GitHub (as of March 2026), GSD is currently among the most well-known Spec-Driven Development tools. Its complexity is manageable compared to other tools like BMAD or Speckit.

The system relies entirely on native Claude Code features. No proprietary runtime. No framework. Just ~50 Markdown files, a Node.js CLI helper, and a few hooks—orchestrating a complete software development cycle from idea to delivered code.

The GSD workflow is divided into a chain of slash commands. Each command handles a phase—and ideally, each phase runs in a fresh context window.

Command	Purpose
/gsd:new-project	Capture idea, research domain, define requirements & roadmap
/gsd:discuss-phase N	Clarify implementation details for phase N
/gsd:plan-phase N	Create task breakdown for phase N
/gsd:execute-phase N	Execute plans in parallel, one commit per task
/gsd:verify-work N	Validate that phase goals have been achieved
/gsd:complete-milestone	Archive, tag release, initialize next cycle

Behind these commands are exclusively standard Claude Code features:

• 29 Skills — the slash commands called by the user.
• 12 Custom Agents — specialized sub-agents for research, planning, execution, and verification.
• 2 Hooks — a status bar and an update checker running in the background.

During installation, the corresponding files are written to the .claude/ directory structure, making them available in every Claude session, even independent of GSD commands.

Since my focus is on the tools behind the commands, I refer anyone wanting to understand GSD better to the official documentation.

From the commands described above, I have selected /gsd:new-project to break down step-by-step. This command sits at the start of the workflow and initiates a guided process that asks questions, gathers information, starts research agents, defines trackable requirements, and generates a roadmap for further execution.

Slash Commands and Skills

Every GSD command executable in Claude is defined in a Markdown file within claude/commands/gsd/ (hence the /gsd prefix).

The file for /gsd:new-project looks like this:

1---
2name: gsd:new-project
3description: Initialize a new project with deep context gathering and PROJECT.md
4argument-hint: "[--auto]"
5allowed-tools: [Read, Bash, Write, Task, AskUserQuestion]
6---

At the top is the frontmatter, containing metadata for the command:

• argument-hint signals an optional --auto flag (in GSD, this flag skips some user prompts).
• allowed-tools sets explicit privileges for tool execution (all internal tools).
• description appears in the command palette.

Below the frontmatter follows the actual prompt, structured by XML tags (abbreviated here):

1<objective>
2Initialize a new project through unified flow: questioning → research
3(optional) → requirements → roadmap.
4
5**Creates:**
6- `.planning/PROJECT.md` — project context
7- `.planning/config.json` — workflow preferences
8- `.planning/research/` — domain research (optional)
9- `.planning/REQUIREMENTS.md` — scoped requirements
10- `.planning/ROADMAP.md` — phase structure
11- `.planning/STATE.md` — project memory
12
13**After this command:** Run `/gsd:plan-phase 1` to start execution.
14</objective>
15
16<execution_context>
17@./.claude/get-shit-done/workflows/new-project.md
18@./.claude/get-shit-done/references/questioning.md
19@./.claude/get-shit-done/references/ui-brand.md
20@./.claude/get-shit-done/templates/project.md
21@./.claude/get-shit-done/templates/requirements.md
22</execution_context>
23
24<process>
25Execute the new-project workflow from @./.claude/get-shit-done/workflows/new-project.md end-to-end.
26Preserve all workflow gates (validation, approvals, commits, routing).
27</process>

Claude models were trained to recognize XML tags as structural boundaries, as it is not always clear where a section ends with Markdown headers.

The sections follow an internal GSD convention to divide responsibilities:

• <objective>: What should be achieved.
• <execution_context>: Which files are loaded (via @-references).
• <process>: How it is executed—usually a reference to a workflow file.

The entire logic—Questioning, Research, Requirements, Roadmap—resides in the referenced workflow file.

@-File References for Context Injection

In the <execution_context> of the slash command, references to other files are inserted via @./. This helps structure complex prompts:

• Slash Command: WHAT is allowed (permissions, goal).
• Workflow File: HOW it is done (step-by-step process).
• References: Reusable knowledge (techniques, rules).
• Templates: Output formats (file structures).

Advantages of Fragmented Prompts

• Modularity: Define once (e.g., questioning techniques), use everywhere.
• Token Efficiency: Sub-agents load only what they truly need.
• Maintainability: Clear separation between "What" (Command) and "How" (Workflow).

User Input via $ARGUMENTS

As described above, /gsd:new-project can be called with an --auto flag. The prompt can access all passed parameters via $ARGUMENTS. Essentially, the variable is replaced with the passed value. In the new-project workflow example:

1<auto_mode>
2## Auto Mode Detection
3Check if `--auto` flag is present in $ARGUMENTS.
4
5**If auto mode:**
6(…) skip the interactive questioning phase
7</auto_mode>

Bash Scripts for Efficient Project State Capture

The first step in almost every GSD workflow is a Bash command:

1INIT=$(node ./.claude/get-shit-done/bin/gsd-tools.cjs init new-project)

Many prompts require information about the project state—does .planning/ exist? Is there already code? Which model profile is configured? Since querying this via Claude tools would require multiple separate calls, GSD uses a script for efficiency that returns this information as a JSON object.

This follows an important design principle: Deterministic logic belongs in code, not in prompts. Checking file existence, loading configurations, or calculating phase numbers are tasks where a script is more reliable than an LLM prompt.

AskUserQuestion — Interactive Decisions

GSD frequently uses a mix of automation and targeted decision points, utilizing the AskUserQuestion tool. For example, immediately after the command call:

1Use AskUserQuestion:
2
3- header: "Existing Code"
4- question: "I detected existing code in this directory. Would you like to map the codebase first?"
5- options:
6  - "Map codebase first" — Run /gsd:map-codebase to understand existing architecture (Recommended)
7  - "Skip mapping" — Proceed with project initialization

The user can then make a selection in the terminal, and Claude branches the flow accordingly. AskUserQuestion supports both multiple and exclusive selections via the multiSelect flag.

In new-project, this creates a chain of questions with gates and feedback loops:

• Brownfield Detection — "Analyze existing code?" (yes/no)
• Readiness Gate — "Enough context for PROJECT.md?" (create/explore further)
• Workflow Settings — Mode, depth, parallelization, Git tracking.
• Agent Toggles — Three questions: Activate Researcher, Plan-Checker, Verifier?
• Requirements Scoping — Per category: Which features in v1? (multiSelect: true)
• Roadmap Approval — "Does the roadmap look right?" (approve/adjust/view file)

Other sections are designed as free-text conversations, e.g.:

1**Open the conversation:**
2Ask inline (freeform, NOT AskUserQuestion):
3
4"What do you want to build?"
5Wait for their response. This gives you the context needed to ask intelligent follow-up questions.

Agents & the Task Tool — Parallel Orchestration

After the Claude process has ingested all information, research is handed over to four agents. This offers the advantage of parallel work and ensures each agent starts with a fresh context window.

1◆ Spawning 4 researchers in parallel...
2→ Stack research
3→ Features research
4→ Architecture research
5→ Pitfalls research

The Task tool is the mechanism behind this. Each call starts a new sub-agent as an independent process. Here is the call for "Stack research":

1Task(
2      prompt="
3            First, read ./.claude/agents/gsd-project-researcher.md ...
4            <research_type>Stack dimension for [domain]</research_type>
5            <question>What's the standard 2025 stack for [domain]?</question>
6            <project_context>[PROJECT.md summary]</project_context>
7            <output>Write to: .planning/research/STACK.md</output>
8      ",
9      subagent_type="general-purpose",
10      model="{researcher_model}",
11      description="Stack research")

• prompt: The full assignment. The agent gets everything it needs in a single prompt.
• model: Determines which Claude model the agent uses. The value comes from the init script and depends on the selected profile.
• subagent_type: Defines what type of agent is instantiated.

Two Spawning Patterns

GSD uses two different approaches to assign roles to agents:

1. General-Purpose with manual role assignment: The four Researchers are spawned as subagent_type="general-purpose". They receive their role via the prompt: "First, read ./.claude/agents/gsd-project-researcher.md for your role and instructions." The agent reads its own definition as the first step.
2. Registered Agent Type: The Roadmapper is spawned as subagent_type="gsd-roadmapper". Claude Code automatically loads the agent definition from .claude/agents/gsd-roadmapper.md—the agent knows its role before it even sees the prompt.

The four Researchers share the same agent definition (gsd-project-researcher.md), but each handles a different dimension (Stack, Features, Architecture, Pitfalls). The specialization comes from the prompt, not the role. The Roadmapper, however, has a unique, constant task.

The Orchestration

The workflow orchestrates the agents in two waves:

1. Four Researchers start in parallel. Each writes its results to its own file under .planning/research/.
2. Only when all four are finished does the Synthesizer start. It reads the four result files and distills them into a SUMMARY.md.

Afterward, a third wave starts: the Roadmapper, which receives the synthesis, requirements, and project context to create the roadmap.

The pattern is always: parallelize independent work, sequence dependent work. Communication between agents happens exclusively via files.

Agent Definitions

In the .claude/agents/ directory, Markdown files give an agent its identity. GSD has twelve definitions there—from Researcher to Planner to Verifier. The structure is similar to the commands: Frontmatter + Prompt body with XML sections:

• <role>: Who am I, what is my mission, who consumes my results.
• <philosophy>: Guiding principles—e.g., "Be comprehensive but opinionated. 'Use X because Y' not 'Options are X, Y, Z.'"
• <tool_strategy>: When to use which tool, confidence level system.
• <output_formats>: Exact templates for every output file.
• <execution_flow>: Step-by-step process.
• <success_criteria>: Checklist for when the work is considered finished.

Persistent State — Surviving Between Sessions

Claude has no memory between context windows. If I type /clear or start a new session, everything is gone. GSD solves this pragmatically by recording everything in files within the .planning/ directory:

• PROJECT.md: What are we building and why.
• config.json: Workflow settings.
• REQUIREMENTS.md: Exactly what, with IDs.
• ROADMAP.md: In what order.
• STATE.md: Where we are right now.

Additionally, after every completed step, a Git commit is performed.

This allows GSD to reconstruct the previous state in any new session using /gsd:resume-work.

Another advantage: Every intermediate stage is inspectable. If the roadmap looks weird, I can check SUMMARY.md to see if the synthesis is the problem. If the synthesis seems wrong, I look into the individual research files. The entire chain is traceable.

Hooks — Background Automation

Hooks are event listeners that Claude Code triggers automatically upon specific events. The configuration is found in .claude/settings.json:

1{
2  "hooks": {
3    "SessionStart": [
4      { "hooks": [{ "type": "command", "command": "node .claude/hooks/gsd-check-update.js" }] }
5    ],
6    "PostToolUse": [
7      { "matcher": "Edit", "hooks": [{ "command": "npx prettier --write \"$FILE_PATH\"" }] },
8      { "matcher": "Write", "hooks": [{ "command": "npx prettier --write \"$FILE_PATH\"" }] }
9    ]
10  },
11  "statusLine": {
12    "type": "command",
13    "command": "node .claude/hooks/gsd-statusline.js"
14  }
15}

Three mechanisms are in use here:

1. SessionStart: Fires once when opening a new session. GSD uses this for an update check: a Node.js script queries the npm registry to see if a newer version exists.
2. PostToolUse: Fires after every tool call. The matcher filters which tool triggers the hook. Here, Prettier runs automatically after every Edit and Write.
3. statusLine: Not a hook in the strict sense, but a permanently running display at the bottom of the terminal. GSD shows the current model, the active task, and a progress bar for context usage—which turns red at high capacity.

Bringing it all together — An overview of the workflow

Conclusion

While using GSD, I expected a complex system based on numerous scripts. In hindsight, I am surprised by how powerful LLMs like Claude Code have become and that complex workflows can be built almost entirely with standard tools and Markdown files.

The beauty is that every instruction is formulated in human language, eliminating a large portion of the abstraction layers normally represented by code.

Get-Shit-Done is designed to quickly automate a wide range of small to medium-sized projects. It doesn't fit every requirement; it might not go deep enough in some places and lack detail in others. But once you understand how the workflows are implemented, it is not difficult to build your own specific systems.