Review of gsd-build/gsd-2

/ Naixian Zhang

GSD(get the shit done) is an autonomous AI agent CLI that runs multi-phase software projects end-to-end. The tagline: “One command. Walk away. Come back to a built project.”

Its key innovation is Each task gets a fresh context window so the context doesn’t degrade over a long run. It creates and maintains four files: state.md, decisions.md, knowledge.md and runtime.md.

Here’s how to use it for your work:

 Setup

  npm install -g gsd-pi@latest
  cd C:\Users\ncarucci\Documents\Gitfolder\<your-project>
  gsd
  /login   # pick Anthropic with your API key

  ---
  Practical Workflow for Your Projects

  Starting a new AI agent or quant project:

  gsd
  /gsd discuss    # describe what you want to build
  /gsd            # step mode — GSD researches, then proposes a roadmap

  Review the generated .gsd/M001-ROADMAP.md, then:

  /gsd auto       # let it build milestone 1

  Two-terminal pattern (recommended):
  - Terminal 1: /gsd auto - building
  - Terminal 2: /gsd discuss or /gsd status - steering without interrupting

It’s not perfect but definitely aligned to future AI work, so I need to peek into its design, turns out GSD’s context engineering isn’t magic – it’s disciplined file I/O. The patterns are simple enough to steal and apply manually in my own projects:

Pattern 1: Pre-inlining Files into the System Prompt

From system-prompt.ts – the actual code:

for (const { path: filePath, content } of contextFiles) {
prompt += ## ${filePath}\n\n${content}\n\n;
}

That’s it. Before each task dispatch, GSD reads relevant files and dumps them directly into the system prompt as markdown sections. No tool calls needed – the LLM has the context before it starts.

In my work, pre-load DECISIONS.md, the relevant slice plan, and prior task summaries into the system prompt instead of letting the agent read_file them.

Pattern 2: DECISIONS.md – Append-Only Log

From GSD-WORKFLOW.md:

▎ “Decisions register is append-only — decisions are never removed, only superseded by new entries with explicit rationale and revisability notes.”

The format is dead simple – a markdown file where you only ever add, never delete. Each entry has:

  • The decision made
  • Why
  • Whether it can be revisited What you can steal: Add a .gsd/DECISIONS.md to any of your projects manually right now. Even without GSD installed, maintaining this file gives future Claude Code sessions full
    architectural context.

Pattern 3: Fresh Context Per Task + continue.md

The iron rule: one task = one context window. When context runs out mid-task:

continue.md contains:

  • completed work so far
  • remaining steps
  • decisions made
  • exact next action New session reads STATE.md first, checks for continue.md, loads only relevant summaries, then executes. What you can steal: When you start a new Claude Code session on an existing project, paste a STATE.md-style summary at the top of your first message.

Pattern 4: Specialized Agents per Role

Three distinct agents:

  • scout.md – reads code, never writes. Returns compressed findings
  • worker.md – executes tasks in isolation, never orchestrates
  • researcher.md – broad investigation, feeds into planning Each agent definition is just a markdown prompt file – no code. The specialization is entirely prompt-driven.

Leave a Reply