get-shit-done: GSD: The Industrial State Machine for Autonomous Agents
How a "Planning-as-Code" framework solves context rot and turns Claude into a spec-driven lead engineer.
I'm a solo developer. I don't write code — Claude Code does.
- GSD prevents hallucination by treating the filesystem as a machine-parsable state machine to prune the active context window.
- The framework enforces a goal-backward protocol that derives tactical tasks from predefined observable truths.
- A specialized hierarchy of agents uses a system of checks and balances to verify code against the original specification.
- Markdown files serve as the primary database for maintaining project continuity across stateless LLM execution turns.
The Context Rot Crisis
Anyone who has tried to build a non-trivial project with an AI coding assistant knows the feeling. After 20 minutes of rapid progress, the agent begins to hallucinate. It forgets architectural decisions made earlier in the session, introduces regressions, and gets stuck in endless debugging loops. This phenomenon is known as context rot.
The standard industry response to context rot has been to increase the size of the context window. However, throwing a million tokens at an LLM often makes it stupider. The AI loses the signal in the noise. GSD (get-shit-done) takes the opposite approach. It is a "Context Engineering" framework that treats an LLM like a CPU with a limited L1 cache. By forcing the agent into a rigid, file-based state machine, it prevents the hallucination spiral entirely.
Markdown as a Database
To keep the active context small, GSD externalizes the agent's memory to the filesystem. It uses a suite of JavaScript utilities to treat human-readable Markdown files as a machine-parsable database. Files like STATE.md and ROADMAP.md act as the system's volatile memory and strategic plan.
In a stateless environment like a CLI tool invoked by an LLM, the STATE.md file is the only way to maintain continuity across multiple turns. It tracks the current milestone, branching strategy, and configuration. A custom YAML parser handles the messy reality of LLM-generated Markdown, ensuring the system can recover even if the formatting is slightly corrupted.
The "Goal-Backward" Protocol
GSD enforces a Spec-Driven Development (SDD) process. Before a single line of code is written, a specialized planner agent must define "Observable Truths" or success criteria. This goal-backward approach forces the AI to derive its tasks from the desired end state, drastically reducing scope creep.
The absolutely bonkers part is that your main context window stays at 30-40% even after deep research or thousands of lines of code getting written. All heavy lifting happens consistently in fresh 200k subagent contexts.
The planner creates a strict hierarchy for decision-making. Locked decisions are non-negotiable, while deferred ideas are explicitly forbidden from entering the current scope. This keeps the execution phase highly focused and deterministic.
A Hierarchy of Agents
Instead of relying on a single omniscient prompt, GSD injects specialized personas into the LLM's context at different stages of the lifecycle. This multi-agent orchestration acts as a built-in system of checks and balances.
| Agent Persona | Role in Workflow | Output File |
|---|---|---|
| Planner | Breaks down milestones into discrete, atomic tasks based on observable truths. | PLAN.md |
| Executor | Consumes the plan, writes code, and makes atomic commits per task. | SUMMARY.md |
| Nyquist Auditor | Acts as a second pair of eyes to verify the executor's work against the original spec. | WAITING.json |
If the auditor detects a failure, the system automatically spawns a debug agent to find the root cause, create a fix plan, and verify the solution. The human operator simply approves the next phase.
The Exit from Enterprise Theater
GSD is ultimately a rejection of enterprise software development bloat. It strips away the ceremonial aspects of agile workflows (story points, sprint planning meetings) in favor of raw, autonomous execution.
For solo creators and small teams, this framework offers a way to act as a lead architect while the AI handles the granular implementation. It is an industrial-grade workflow designed for the speed of an individual.
I still don't want to cosplay as an enterprise team. I still just want to describe what I want and have it built correctly.
Sources:
- Repository: gsd-build/get-shit-done
- Reddit Announcement: I've Massively Improved GSD