Skip to main content

Get Shit Done: qrx's planning system I used for 19 portfolio phases

How Get Shit Done works: the .planning folder, the phase loop, the waves of plans and the plan-checker, with a script to compute the waves.

What do you think about this article?

Get Shit Done: qrx's planning system I used for 19 portfolio phases
Sub-pagePhoto:PixabayPexels

At a Glance

How Get Shit Done works: the .planning folder, the phase loop, the waves of plans and the plan-checker, with a script to compute the waves.

If a feature you ask an assistant for is big enough not to fit in a single conversation, the risk is not that the work is hard: it is that halfway through the context is full of old hypotheses and the answers get worse without you noticing. Get Shit Done (GSD) answers with a rule: the plan lives in files in the repository, and every executor restarts from an empty context that reads only what it needs. Here I explain how it is built, in which order it is used, and where I have seen it help and where not.

Independence: I am not affiliated with the authors of GSD or with Anthropic. I read the GSD Core README and documentation on 2026-11-13; I did not run GSD to write this page, so the commands are those of the documentation and the steps that depend on the assistant are declared as such. Where I tell an experience of my own I do it without figures I have not measured. The context of the series is in the opening guide; the part on skills is in the Superpowers page.

What it is and where to get it today

GSD presents itself as a lightweight meta-prompting, context engineering and spec-driven development system for Claude Code, and today for other environments too. The original repository, gsd-build/get-shit-done, attributes it to TÂCHES, is under the MIT licence and has been archived with a pointer: development continues in open-gsd/gsd-core. A qrx/get-shit-done repository, which you find cited in old texts, is not the project: the source to use is the new repository, whose installation goes through npx @opengsd/gsd-core@latest, as the README writes.

Its thesis is in the README and in the page on the phase loop: quality degradation grows with the context, so the heavy work (research, planning, execution) runs in sub-agents with a fresh context, while the main session stays light and state lives in files. It is not magic and it is not a runtime: it is commands that start agents, plus a folder of Markdown files. If you do not want the commands, the files remain readable by you anyway.

What is inside .planning/

The state of a GSD project lives in a .planning/ folder at the root of the repository. The GSD Core architecture document shows the base files, which I list with the role each has in the loop.

  • PROJECT.md: what the project is and the decisions that hold for everything else.
  • REQUIREMENTS.md: the requirements, which the plans refer back to.
  • ROADMAP.md: the phases, each with its own goal.
  • STATE.md: where you have got to; the documentation describes a lock on the file to prevent two agents writing it at the same time.
  • config.json, phases/ and research/: settings, one folder per phase with plans, context and research, and the research material.
  • codebase/: the map of an existing project, produced by /gsd-map-codebase.

The useful reading is this: PROJECT.md and REQUIREMENTS.md rarely change and say why, ROADMAP.md and phases/ say what and in which order, STATE.md says where you stand. Everything is versionable text, and when you return to a phase months later you have the trace of what had been decided. This is the part of the method that has mattered most to me, more than the commands themselves.

The phase loop, command by command

Every phase repeats five steps: discuss, plan, execute, verify, ship. The commands are those of the GSD Core reference, with the hyphen in the name (in older articles you find the colon form, which is no longer the documented one).

/gsd-phase                     adds a phase to the ROADMAP
/gsd-discuss-phase 3           gathers the decisions in CONTEXT.md
/gsd-plan-phase 3              research, plans and plan verification
/gsd-execute-phase 3           runs the plans in waves
/gsd-verify-work 3             verifies with you and produces UAT.md
/gsd-ship                      pull request and closing of the phase
/gsd-quick                     a small task, without the loop

They are commands internal to Claude Code: I did not run them, the block is a schema to adapt. The 3 is the number of the phase; without a number /gsd-plan-phase takes the next phase not yet planned. The separation between discussing and planning is the least obvious and the most useful: the documentation explains that without the discussion step the planner has to decide on its own how to build, and when it guesses «plausibly but badly» you find out when execution is over. The step produces a CONTEXT.md file read by planner, executor and verifier.

Waves: where they come from, and how to check them

A GSD plan is a bounded unit of work: the files to touch, the changes, the acceptance criteria. Plans are ordered into dependency waves: those with no dependencies go in the first, those that depend on the first in the second, and so on; the executors of a single wave run in parallel, those of different waves in sequence. The documentation shows it with five plans: 01 and 02 with no dependencies, 03 depending on 01, 04 on 02, 05 on 03 and 04. The result is three waves: 01 and 02, then 03 and 04, then 05.

I reproduced that example with a script, which reads the depends_on field from the frontmatter of five test files and computes the waves. It also checks the two errors that make a set of plans impossible to execute: a dependency on a plan that does not exist and a circular dependency. It is a rewrite of mine to understand the rule, not GSD's code, and it does not claim to describe how the program really computes it.

# phases/ok/03-PLAN.md (the other four have the same shape; 01 and 02 have depends_on: [])
---
phase: 03
depends_on: ["01"]
---
# Plan 03

# onde.py
"""Groups the plans of a phase into waves, starting from `depends_on` in the frontmatter of each PLAN.md."""
import glob
import re
import sys


def leggi_piani(cartella):
    piani = {}
    for percorso in sorted(glob.glob(f"{cartella}/*-PLAN.md")):
        sigla = percorso.split("/")[-1].split("-")[0]
        testo = open(percorso, encoding="utf-8").read()
        m = re.search(r"^depends_on:\s*\[(.*?)\]\s*$", testo, re.M)
        elenco = [d.strip().strip("\"'") for d in m.group(1).split(",")] if m and m.group(1).strip() else []
        piani[sigla] = elenco
    return piani


def ondate(piani):
    sconosciuti = {(p, d) for p, deps in piani.items() for d in deps if d not in piani}
    if sconosciuti:
        raise ValueError(f"dependencies on non-existent plans: {sorted(sconosciuti)}")
    livello = {}
    while len(livello) < len(piani):
        pronti = [p for p, deps in piani.items() if p not in livello and all(d in livello for d in deps)]
        if not pronti:
            raise ValueError(f"circular dependency among: {sorted(set(piani) - set(livello))}")
        for p in pronti:
            livello[p] = 1 + max((livello[d] for d in piani[p]), default=0)
    return {n: sorted(p for p, v in livello.items() if v == n) for n in sorted(set(livello.values()))}


for cartella in sys.argv[1:]:
    print(f"== {cartella}")
    try:
        for n, gruppo in ondate(leggi_piani(cartella)).items():
            print(f"wave {n}: {', '.join(gruppo)}")
    except ValueError as errore:
        print(f"ERROR: {errore}")

# Output (python3 -I onde.py phases/ok phases/broken phases/cycle):
# == phases/ok
# wave 1: 01, 02
# wave 2: 03, 04
# wave 3: 05
# == phases/broken
# ERROR: dependencies on non-existent plans: [('02', '07')]
# == phases/cycle
# ERROR: circular dependency among: ['01', '02']

In the first case the output matches the documentation's example. In the second, plan 02 declares a dependency on a 07 that does not exist, and the script rejects it with the name of the guilty pair. In the third, 01 and 02 wait for each other and no plan is found ready to run, and it is the cycle that gives the message. The level of a plan is one plus the maximum of the levels it depends on: you see it in the line livello[p] = 1 + max(...). Run twice with identical output; the test files are created in a folder of mine outside the repository.

Parallelism has a cost that the documentation declares: the executors of the same wave must touch non-overlapping parts, and to avoid conflicts there are two mechanisms, commits with --no-verify (the pre-commit hooks run once at the end of the wave) and the lock on STATE.md. How much time you save depends on your plans, and I have no measurement to give you: I have no factor to guarantee. Article 11 starts from here.

The plan-checker and the size of the phase

After the planner has written the plans, a third agent, the plan-checker, verifies that they are complete, coherent and within scope. The architecture document frames it in a verification loop with a maximum of three iterations; there is an option to skip it, --skip-verify, but I do not recommend it as a habit. One note that made me revise an idea: when it compares each plan against a token budget, the checker produces an estimate that the documentation declares advisory, which never blocks planning. A warning is not a ban.

I remember a phase in which the plan-checker pointed out to me that a plan depended on a component that the previous plan had only sketched: I found out before executing, and it is the kind of error that a well-written plan does not reveal. It is an episode, not a statistic; for the number of errors a plan check intercepts on average I have no data. On size, the documentation on the loop is clear: a phase that is too big becomes a research project of its own, and when in doubt it is better to split it.

A project that already exists

To start from an existing codebase the README points to /gsd-onboard, which goes through /gsd-map-codebase to create the map in .planning/codebase/, with four parallel agents or, with --fast, just one. If you already have planning documents, ADRs or specifications, /gsd-ingest-docs builds or merges the .planning/ folder from those documents and produces a report of the conflicts. They are three different entry points for three different situations: code without documents, code with documents, new project.

When it is not needed

GSD has a fixed ceremony cost: discuss, plan, check. For a fix of a few minutes the cost exceeds the work, and it is the documentation itself that says so: below the threshold at which the loop adds value, for example fixing a typo in the README, you use /gsd-quick. That command can still add discussion, research and plan checking with the --discuss, --research and --validate options; with --validate the plan check has a maximum of two iterations. My personal rule is that if the work fits in a single sentence, I do not open a phase.

Frequently asked questions

Who created Get Shit Done?

The original repository, gsd-build/get-shit-done, describes it as the work of TÂCHES. It has been archived and development continues as GSD Core in open-gsd/gsd-core; for current code and documentation use that repository.

Does GSD only work with Claude Code?

No. The GSD Core README also lists OpenCode, Codex, Copilot, Cursor, Windsurf and other environments, and the installer asks for the runtime. This series covers the Claude Code case.

What is the difference between a phase and a plan?

A phase is a goal in the ROADMAP, inside a milestone. A plan is a bounded unit of work inside the phase, with files to touch and acceptance criteria; plans are grouped into waves according to their dependencies.

Can I skip the plan check?

Yes, with --skip-verify on /gsd-plan-phase, as the command reference says. The check serves to catch ambiguities before execution, when they cost less: skip it only when the phase is truly trivial.

What you can do now

You know where the state of a GSD project lives and what each file contains, you know in which order the commands of the loop are used and which repository to consult today. You can compute by hand the waves of a set of plans and immediately recognise a missing or circular dependency. You can also choose between a full phase and /gsd-quick. The next step is the comparison between horizontal and vertical phases.

Back to the opening guide Go to Superpowers

The same series also includes the brainstorming skill and the plan-checker.

Sources

  • GSD Core, README - five-step loop, installation, the /gsd-new-project and /gsd-onboard commands, supported environments, accessed 2026-11-13
  • GSD Core, command reference - options of /gsd-plan-phase, /gsd-execute-phase, /gsd-quick, /gsd-map-codebase, /gsd-ingest-docs, accessed 2026-11-13
  • GSD Core, architecture - files of .planning/, wave model, verification loop with a maximum of three iterations, safety of parallel commits, accessed 2026-11-13
  • GSD Core, the phase loop - role of discussion, planning and execution, scope of a phase, accessed 2026-11-13
  • gsd-build/get-shit-done, original archived repository - attribution to TÂCHES, MIT licence and pointer to the new repository, accessed 2026-11-13
  • Measurement in the repository: python3 -I onde.py on test files, run twice with identical output, 2026-11-13

Try These Tools

Free developer tools related to this topic.

Commenti

Caricamento commenti...

Sign in to comment

New articles and tools on Telegram too

The Telegram channel flags the site's new articles and tools.

Did you like this article?

Explore other content on the blog or discover my projects