What Kind of Projects GSD Helps With

GSD is happiest with software-shaped projects: websites, small apps, browser extensions, scripts that automate a chore, a tool that takes a spreadsheet and makes something useful out of it. It also does well with creative software: a little game, an interactive story, a digital zine, an art generator.

It can help you fix a bug in something you already have. It can help you read code someone else wrote and explain it to you. It can help you learn by doing.

It is not a magic wand that builds anything you can imagine with zero effort. You still need to know what you want, and you still need to answer questions the assistant asks you along the way. That part is good news: the better you describe your idea, the better the result.

What You Don’t Need to Know

• You do not need to know how to program.

• You do not need to know what “git” is.

• You do not need to have used a terminal before.

• You do not need a computer science degree.

• You do not need to understand what’s happening “under the hood.”

You will be typing a few commands into a window, and I’ll walk you through every one of them. I’ll also tell you what each command does in plain English before you run it.

What You’ll Be Able to Do by the End

By the time you reach the last page, you will have:

1. Installed GSD on your computer.

2. Started a real project with /gsd-new-project.

3. Watched the assistant build and check its own work.

4. Used /gsd-progress and /gsd-next to navigate the project.

5. Fixed things that weren’t quite right.

6. Finished a milestone and started a new one.

That’s a full loop. Once you’ve done it once, you’ve done it. Everything else is variations on the theme.

In the next chapter we’ll set everything up. It takes about fifteen minutes.

What You’ll Need

1. A computer. Mac, Windows, or Linux. GSD works on all three.

2. An internet connection. The assistant talks to Anthropic’s servers to think.

3. Claude Code. This is Anthropic’s coding assistant. It runs on your computer and is the thing GSD plugs into. You can get it at claude.com/claude-code. A free trial is usually available; a paid plan unlocks more.

4. Node.js. This is a free tool that lets your computer run the GSD installer. You only install it once.

Installing Node.js

Go to nodejs.org, click the big green “LTS” download button, run the installer, click through the defaults. That’s it.

To check that it worked, open a terminal window.

• Mac: press [Cmd]+[Space], type terminal, press [Enter].

• Windows: open the Start menu, type powershell, press [Enter].

• Linux: you already know.

A black (or light, if that’s your taste) window opens with a blinking cursor. Type:

node --version

Press [Enter]. You should see something like v20.11.0. If you do, Node.js is installed and you can close the terminal.

Running the GSD Installer

With Node.js installed, installing GSD is a single command. Open Claude Code (it gives you its own terminal prompt) and type:

npx get-shit-done-cc@latest

Press [Enter]. The installer will ask you two questions.

What the Installer Asks

Question 1: Which runtime? The installer lists several AI coding assistants it supports. Pick Claude Code. (If you’re using a different assistant, pick that one—the rest of this guide still applies; only the way you type commands changes very slightly.)

Question 2: Global or local? Pick Global. “Global” means GSD is available in every project on your computer. “Local” means only in the current folder. For a first project, global is easier.

The installer will print a few lines about copying files, then finish. That’s it. GSD is installed.

Verifying It Worked

In Claude Code, type:

/gsd-help

Press [Enter]. You should see a list of GSD commands scroll past. If you do, congratulations—GSD is working. If you don’t, see Appendix A for troubleshooting.

Next up: a short chapter on what GSD is actually doing, so the commands in Chapter 4 feel like friends instead of strangers.

The Problem: AI Forgets Mid-Conversation

If you’ve used an AI chatbot for anything longer than a quick question, you’ve probably noticed something strange: it gets worse as the conversation gets longer. It forgets what you said earlier. It contradicts itself. It starts giving vaguer answers. People who use AI assistants for real work have a nickname for this: “context rot.”

It happens because an AI assistant has a limited “conversation memory”— the amount of back-and-forth it can hold in its head at once. When the conversation fills up that memory, old things start getting squeezed out or blurred. Try to build a real project in one long chat and the assistant will lose the thread.

The Solution: GSD Keeps the AI Organized

GSD solves the memory problem in a clever way: instead of keeping one long conversation, it writes everything important down into files, and starts fresh conversations when it needs to. Each fresh conversation is given exactly the notes it needs and nothing more.

Think of it like this: imagine you hired a very skilled contractor to build a treehouse, but the contractor had a medical condition that made him forget everything at lunchtime. The only way to get the treehouse built is to:

1. Write down the plan in the morning while he still remembers the conversation.

2. After lunch, hand him the written plan and say “build exactly this.”

3. Check what he built against the plan at the end of the day.

GSD is the clipboard. The assistant is the contractor. You are the homeowner who hired him. GSD keeps notes, hands out plans, and checks work, so the assistant can stay focused on one small task at a time and do it well.

The Workflow, As a Story

Here’s the whole GSD workflow in one paragraph:

You describe what you want. GSD asks you questions until it understands. It writes down everything it learned—what you want, how it’s going to build it, in what order. It breaks the work into phases. For each phase: it makes a plan, it does the work, it checks the work. When all phases are done, you ship a version. When you want to add more, you start a new version.

That’s it. That’s GSD. The commands in Chapter 4 each correspond to one step of that story.

What “Spec-Driven Development” Means

You might see the phrase spec-driven development in GSD’s documentation. It sounds jargony but the idea is homey: before you build something, write down what you’re building. The written description is called a “spec” (short for specification). Spec-driven development just means: write the spec first, then build from the spec.

GSD writes the spec with you, by asking questions. You don’t have to know how to write a spec. You just have to answer the questions honestly.

Enough theory. Let’s build something.

Start a Project Folder

Before you run any GSD commands, make a folder for your project. In the terminal:

mkdir my-website
cd my-website

mkdir means “make directory” (a directory is the same thing as a folder). cd means “change directory”—it’s how you walk into the folder you just made. After cd my-website, your terminal is “inside” that folder.

Now open Claude Code in this folder. (In most setups, Claude Code picks up the folder you started it in.)

The First Command: /gsd-new-project

This command is how you tell GSD “I have an idea and I want to start a project.” Type:

/gsd-new-project

Press [Enter]. GSD wakes up and starts asking questions.

What GSD Asks You, and Why

GSD’s first job is to understand your idea well enough to build it. It does this by asking a series of questions. The exact questions vary, but they usually cover things like:

• What is the project? (One or two sentences is fine.)

• Who is it for? (Yourself? Your friends? Strangers on the internet?)

• What should it do when you’re done? (Three or four bullet points.)

• Are there things that are explicitly out of scope? (Things you do not want, so the assistant doesn’t gold-plate.)

• Is there anything it should look like or feel like? (A mood, a color, another site you admire.)

Answer each question the way you’d answer a friend. If you’re not sure about an answer, say “I’m not sure, what do you recommend?”—the assistant will offer options.

What Gets Created

When the question session finishes, GSD will write a handful of files into a folder called .planning/ inside your project. The important ones are:

• .planning/PROJECT.md — the summary of your idea. The thing you just described, written up cleanly.

• .planning/REQUIREMENTS.md — a more detailed breakdown of what “done” looks like.

• .planning/ROADMAP.md — the plan. A list of phases (numbered 1, 2, 3…) that together add up to your project.

• .planning/STATE.md — a living status file. GSD updates it as you progress.

You don’t have to read any of these files. But if you’re curious, open PROJECT.md in any text editor and read it. It should feel like your idea, written back to you.

Understanding the Roadmap

The roadmap is the most interesting of the files. It divides your project into phases. A phase is a bite-sized chunk of work that ends in something working. For a personal website, GSD might generate phases like:

1. Phase 1: Project skeleton and layout.

2. Phase 2: Bio and about section.

3. Phase 3: Projects list.

4. Phase 4: Contact section and polish.

Each phase is completed on its own. You finish Phase 1 (and see it working) before Phase 2 starts. This is how GSD keeps itself honest: small chunks, visible progress, no six-week silent marathon that ends in a pile of broken files.

Checking Where You Are

At any point, you can ask GSD to tell you where you are in the project:

/gsd-progress

This prints a small status report: which phase you’re on, what’s done, what’s next. It’s a friendly “you are here” sign, and you’ll use it constantly.

You now have a project, a plan, and a roadmap. Nothing has been built yet—that’s what the next chapter is for.

What a “Phase” Is, Again

A phase is a chunk of work with a clear beginning and end. For your first phase, GSD will pick something small enough to finish quickly but big enough that you can see real progress. In our website example, Phase 1 is usually just “set up the skeleton”: a page that loads and shows “Hello, world” or similar.

Each phase goes through three steps:

1. Plan — GSD researches and writes a detailed plan for the phase.

2. Execute — GSD does the work in the plan.

3. Verify — GSD checks the work and asks you to double-check.

Let’s go.

Step One: /gsd-plan-phase

Type:

/gsd-plan-phase 1

Press [Enter]. (The 1 at the end means “phase 1.” If you leave it off, GSD uses the next phase that needs planning, which is also fine for a first-time run.)

GSD now goes off and thinks. It may take a few minutes. It might ask you a clarifying question or two. When it’s done, it will have written a detailed plan file for the phase into the .planning/ folder. You don’t have to read it, but if you do, you’ll see something refreshingly clear: here’s what we’ll build, here’s what each part does, here’s how we’ll know it worked.

Step Two: /gsd-execute-phase

Once the plan exists, ask GSD to build it:

/gsd-execute-phase 1

This is the fun part. The assistant will start creating files, writing code, and generally making things happen. You’ll see a running log of what it’s doing. At some points it will stop and ask for your permission before doing something potentially important—for example, before running a command that changes files in a significant way.

When the phase finishes, GSD will usually have created several new files in your project. Congratulations—something real exists now.

Step Three: /gsd-verify-work

Before moving on, ask GSD to check its own work:

/gsd-verify-work 1

This runs a short self-review. GSD looks at what was built, compares it to what the plan said should happen, runs any tests that were written, and reports back. If everything passed, you’ll see a cheerful summary. If something is off, GSD will tell you exactly what and suggest a fix plan.

What to Do If Something Isn’t Right

Sometimes the phase finishes and the result doesn’t match what you had in your head. That’s normal. Here’s the order of things to try:

1. Describe what’s wrong. Tell the assistant, in plain English, what you expected versus what you got. “The page loads, but the heading says ‘Hello world’ and I wanted it to say my name.”

2. Let it fix. The assistant will usually propose a small fix and, with your permission, apply it.

3. Re-run verify. Type /gsd-verify-work again to confirm the fix worked.

4. If you’re stuck, try /gsd-debug followed by a description: /gsd-debug "Heading doesn’t update when I change my name". GSD has a systematic debugging mode that walks through the problem step by step.

If you ever feel truly lost, Appendix A has more help.

You now know the full rhythm: plan, execute, verify, repeat for the next phase. The next chapter covers the little commands that help you find your way around a project in progress.

/gsd-progress — “Where am I?”

Run this any time you want a bird’s-eye view:

/gsd-progress

You’ll see a summary of the project, which phase is current, what’s complete, and what’s on deck. This is the command to run when you come back to the project after a break and have no idea what you were doing.

/gsd-next — “What should I do next?”

If /gsd-progress says “where am I,” /gsd-next says “what next.” Run it and GSD figures out the correct next step for your project and either does it or tells you the command to run:

/gsd-next

If Phase 1 is planned but not executed, /gsd-next will execute it. If Phase 2 hasn’t been planned, it will plan it. If every phase is done, it will suggest completing the milestone. It’s the “just keep going” button.

/gsd-help — “What commands exist?”

If you forget which commands GSD offers:

/gsd-help

You’ll see the full list. You won’t need most of them for a while, but it’s nice to know they’re there.

The .planning/ Directory

I mentioned this folder earlier; it’s worth a section of its own because you’ll see it a lot. .planning/ is where GSD keeps the project’s brain: the spec, the roadmap, the plans for each phase, the status file, notes. It lives inside your project folder, right alongside the code GSD writes.

Pausing and Resuming

If you have to stop mid-work (lunch, the end of the day, the cat pressed a key), GSD has two commands to make coming back painless:

/gsd-pause-work
/gsd-resume-work

/gsd-pause-work writes a short handoff note summarizing where you are. /gsd-resume-work reads it back and brings the assistant up to speed in a fresh session. Use them whenever you close your laptop.

That’s navigation. The next chapter covers the “quick task” mode for when you don’t need the full phase workflow.

When to Use /gsd-quick

Use it for small, self-contained tasks that you could describe in one or two sentences. Things like:

• “Add a footer with my copyright to the bottom of every page.”

• “Change the background color to a warm beige.”

• “Fix this bug where the submit button does nothing.”

• “Add a favicon.”

For anything that feels bigger than a sentence or two—a new section, a new feature, a rethink of the layout—use the full planning workflow (Chapter 4 and 5) instead.

How to Use It

/gsd-quick

GSD will ask you what you want done. Describe it in plain English. It will propose a short plan, ask your permission to proceed, and then do the work.

If you’d like GSD to be a little more thorough for a particular quick task, you can add flags:

• --discuss — have a short pre-planning discussion first.

• --research — let GSD look things up before planning.

• --full — run the full plan-check and verification steps.

For example: /gsd-quick –full.

The next chapter is a collection of small habits that make the whole experience smoother.

Be Specific About What You Want

“Make me a website” gets you an average website. “Make me a one-page site for my grandmother’s 80th birthday, with her photo, a short tribute, a photo gallery of the grandkids, and a guestbook where people can leave messages” gets you that website. The more specific you are, the closer the result is to what you pictured.

This is the #1 habit. It outweighs every other piece of advice in this chapter combined.

Let GSD Ask Questions

When GSD asks a question—during /gsd-new-project, during planning, during execution—answer it. Don’t skip it, don’t say “whatever,” don’t type “idk.” Every question it asks is because it noticed a place where the result could go in two different directions and it wants you to pick. If you don’t pick, it picks for you, and you may not like its choice.

Don’t Edit .planning/ Files by Hand

I said this earlier but it bears repeating. If you want to change the plan, talk to the assistant. Editing .planning/ files directly is like rewriting the blueprints while the contractor is still reading them: confusing, and things will fall out of sync.

Capture Ideas With /gsd-add-todo

You’ll get ideas while the assistant is working on something else. “Oh, I should add a search box.” “It would be nice if the images had captions.” Don’t try to hold those in your head. Run:

/gsd-add-todo "Add search box to the bio page"

GSD will save it to a list. Later, when you’re ready, you can review the list:

/gsd-check-todos

You’ll see everything you captured and can pick one to work on.

Take Breaks

This is less about GSD and more about you. A fresh set of eyes catches things tired eyes miss. If something is going in circles, step away for twenty minutes. When you come back, run /gsd-resume-work and you’ll be picked up exactly where you left off.

Celebrate Small Wins

The first time a phase completes successfully, stop and look at what you made. Open the thing in a browser, run the script, see the output. Tell someone. Building real things is a big deal, and the whole point of GSD is that you get to do it.

The final chapter covers what happens when you finish your first project and want to do more.

Complete the Milestone

A “milestone” in GSD is a completed version of your project. When all phases of a milestone are done, run:

/gsd-complete-milestone

GSD will archive the planning documents for this milestone, update a historical log of everything you’ve shipped, and (if you’re using version control) tag a release. It’s your graduation ceremony for that version of the project.

Start a New Milestone

When you’re ready to add more—new features, a bigger redesign, whatever—start a new milestone:

/gsd-new-milestone

GSD will ask you what the new milestone is about, generate a new roadmap for it, and you’re back in the plan-execute-verify loop for this new version. The old milestone is still there, archived, so you can always look back.

When You’re Ready for More

This guide has covered the core workflow. GSD has many more commands for special situations: bringing GSD into an existing codebase, running phases in the background, reviewing code, generating tests, digging into bugs, and more. Run /gsd-help any time to see the full list.

Everything you learned here still applies. The extra commands are just variations on the same rhythm: describe, plan, do, check.

Getting Help

GSD has an active community on Discord. If you’re stuck, have a question, or just want to share what you built, the people there are friendly and have probably run into the same thing you’re running into. You can join from inside GSD:

/gsd-join-discord

“Command Not Found”

Symptom: you type /gsd-help (or any GSD command) and the assistant says it doesn’t recognize it.

Fix: close Claude Code completely and open it again. GSD commands get picked up when the assistant starts, so a fresh start usually does it. If that doesn’t work, re-run the installer (npx get-shit-done-cc@latest) and pick the same options as before.

“Something Went Wrong With the Project”

Symptom: you get errors mentioning missing files, or /gsd-progress reports something confusing about the project state.

Fix: run the health check:

/gsd-health

It will tell you what’s wrong. If it offers to repair, let it:

/gsd-health --repair

This fixes most common issues automatically.

“I’m Completely Lost”

Symptom: you stepped away from a project for a week and you have no idea what you were doing.

Fix: two commands, in order:

/gsd-resume-work
/gsd-progress

/gsd-resume-work brings the assistant up to speed; /gsd-progress reminds you. Between them you’ll be re-oriented in under a minute.

“The Phase Produced Something I Don’t Want”

Symptom: /gsd-execute-phase finished, but the result is wrong in some way.

Fix: first, describe the problem to the assistant in your own words. Most issues resolve with a short conversation. If you’d rather undo the phase entirely and start over:

/gsd-undo --phase 1

This rolls back the phase’s changes safely. You can then re-plan and re-execute it.

“Everything Is Fine, I’m Just Anxious”

Symptom: things are working but you’re worried you’re doing it wrong.

Fix: you’re not. Run /gsd-progress, see that you’re in a valid state, take a breath, and keep going. The workflow is forgiving. Mistakes are recoverable. You are allowed to be a beginner.