GSD Core: Ship Without Context Rot Using Atomic Plans

I have watched too many agent sessions die the same death. You start clean. The model is sharp, the edits are surgical, the plan is crisp. Two hours later it is rewriting code it already wrote, forgetting a decision it made forty messages ago, and confidently re-introducing the exact bug you fixed at the top of the session. Nothing crashed. No error was thrown. The agent just got slowly, quietly worse.

That decay has a name now, and GSD Core is a system built entirely around fighting it. GSD stands for Git. Ship. Done. — and the whole pitch is that the way you keep an agent sharp is not a better prompt or a bigger model, but a discipline: break work into atomic plans, run each one in a fresh context window, and never let your main session carry the weight of everything it has ever touched.

This is an opinionated, sometimes exhausting, occasionally brilliant way to work. Let me walk you through what context rot actually is, why fresh-context atomic plans are a real fix and not a gimmick, how to install and run GSD Core, how it stacks up against Superpowers and GStack, and — honestly — when the token bill is worth it and when it absolutely is not.

What context rot actually is

"Context rot" is the gradual degradation in an agent's output quality as its context window fills up over a long session. It is not a hardware failure and it is not a bug in the model. It is a structural property of how attention works when you keep stuffing more tokens into the same window.

Here is the mechanism, stripped of hype. A language model attends across every token in its context when it generates the next one. When the context is small and clean — a sharp spec, the two files that matter, one clear instruction — attention is concentrated where it should be. When the context is forty messages deep, full of tool output, half-abandoned plans, three different versions of the same function, and a long argument about which approach to take, that same attention is now spread across a swamp. The signal you care about is still in there. It is just diluted.

Rot shows up in a few recognizable ways:

• Instruction drift. A constraint you stated clearly at the top ("never touch the auth module") gets diluted by everything that came after, and the agent eventually touches the auth module.
• Stale-state confusion. The context contains an old version of a file and a new version. The model averages them, or picks the wrong one, and produces an edit that matches neither.
• Decision amnesia. You debated and resolved an approach early. Hours later the model relitigates it, because the resolution is buried under noise and the question is more salient than the answer.
• Confidence without grounding. The model keeps the tone of someone who knows what is going on while the substance quietly erodes. This is the dangerous one, because it does not look like failure.

The thing to internalize is that more context is not free. Every token you add is a token that competes for attention with the tokens that matter. A session that has been running for three hours is not three hours wiser. It is three hours more cluttered.

The counterintuitive truth GSD is built on: the agent that has seen everything performs worse than the agent that has seen exactly the right small thing. Memory is a liability, not an asset, unless it is curated.

Once you believe that, the design follows naturally. If a full context window is a liability, then the goal of your workflow is to keep the window that does the actual generating as small and as clean as possible — for as long as possible.

The atomic plan: GSD's core unit

GSD Core's answer is the atomic plan. An atomic plan is the smallest unit of work that:

1. Has a clearly defined, verifiable outcome.
2. Can be completed without needing to "remember" the broader session.
3. Can be handed to a fresh context window — a subagent — that starts knowing nothing except this plan.

That third property is the whole game. An atomic plan is written so that someone (or some agent) with zero prior context can pick it up, do it, and verify it. If completing the plan requires knowledge that only lives in your bloated main session, the plan is not atomic. You have to push that knowledge into the plan — as an explicit spec — so the executor never needs the swamp.

This is why GSD calls itself spec-driven. The spec is not documentation you write afterward. The spec is the mechanism by which you transfer just-enough context into a clean window, so the actual work happens somewhere the rot has not set in.

A well-formed atomic plan in GSD looks roughly like this:

# Plan: Add rate limiting to the public API

## Outcome
Requests to /api/public/* are limited to 100/min per API key.
Over-limit returns 429 with a Retry-After header.

## Context the executor needs
- Auth keys live in `src/auth/keys.ts`, validated by `verifyKey()`.
- The router is `src/api/router.ts`; middleware mounts at line ~40.
- We use Redis (`src/lib/redis.ts`) — use it for the counter.

## Constraints
- Do NOT modify verifyKey or anything in src/auth/.
- No new dependencies; redis client already exists.

## Verification
- `npm test src/api/ratelimit.test.ts` passes.
- Manual: 101 rapid requests -> last one is 429 with Retry-After.

## Done means
Tests green, lint clean, one focused commit.

Notice what is in there: the outcome, the minimum context to do it, hard constraints, and — critically — how to verify the work is correct. Notice what is not in there: the history of the project, the seven other features in flight, the debate about whether you should be rate-limiting at all. That debate happened in the planning session. Its conclusion lives here. Its transcript does not.

Why "atomic"

The word matters. Atomic means indivisible and it means the unit either fully succeeds or you throw it away and redo it cleanly. Because a plan runs in a fresh window, a failed plan does not poison your main session. You discard the subagent, fix the plan, and spawn a new clean executor. Compare that to a monolithic session, where a single bad detour pollutes everything downstream for the rest of the day.

Why fresh context windows actually help

Let me make the case concretely, because "use fresh context" can sound like cargo-culting.

Consider two ways to build a feature with four parts.

The monolith. One long session. By part four, the context contains all the tool output, all the file versions, all the dead ends from parts one through three. The model generating part four is wading through everything. Quality on part four is measurably worse than quality on part one, even though part four is no harder.

The atomic decomposition. A lightweight planning session produces four atomic plans. Each plan is executed by a fresh subagent that sees only its own plan plus the live state of the repo. The subagent for part four starts as sharp as the subagent for part one, because its window contains four hundred tokens of crisp spec instead of forty thousand tokens of accumulated session.

The difference is not subtle once you have a task big enough to feel it. Here is the same idea as a table:

Property	Monolithic session	GSD atomic plans
Context per unit of work	Grows unbounded	Bounded, small, fresh
Quality over time	Degrades (rot)	Roughly constant
Failure blast radius	Whole session	One plan
Parallelism	None (one thread)	Multiple subagents at once
Token efficiency per message	High (no re-load)	Lower (re-load spec each plan)
Total tokens	Often lower	Often higher
Auditability	Tangled transcript	Discrete plans + commits

That last block is the honest tension. Fresh context costs tokens, because every subagent has to be re-briefed. You are trading raw token efficiency for sustained quality and parallelism. Whether that trade is good depends entirely on the size and stakes of the work — I will come back to that.

The main session stays light

The other half of the trick is what happens to your session — the one you are actually sitting in. In GSD, your main session is a conductor, not a performer. It plans, it dispatches, it reviews handoffs, it decides what is next. It does not do the heavy lifting of writing and rewriting code, because that is exactly the activity that bloats a window fastest.

So the main session stays small and sharp too. It is reasoning about the shape of the work — a handful of plans and their statuses — not holding the full content of every file in its head. You can run a GSD conductor for a very long time without it rotting, because you have deliberately kept the high-volume work out of it.

How GSD Core is built

GSD Core targets 12+ agent runtimes. The project lives at open-gsd/gsd-core (it moved from the old gsd-build org — if you have old bookmarks, update them). The installer is runtime-aware: it asks what you are running and lays down the right adapter.

The pieces you will actually touch:

• The planner. Turns a goal into a set of atomic plans with explicit specs and verification steps. This runs in your main session.
• The dispatcher. Spawns a fresh subagent per plan, hands it the spec, and collects the result. This is the fresh-context machinery.
• The handoff protocol. A structured format for what a subagent returns when it is done — what it changed, what it verified, what it could not do, and what the next plan needs to know.
• The verifier. Each plan carries its own definition of done; GSD runs (or asks you to run) that verification before marking a plan complete.
• The ledger. A running record of plans, their statuses, and their handoffs — so your light main session can reason about progress without holding all the detail.

Installing and running it

Installation is a single command. The installer prompts for your runtime, so you do not need to hand-pick an adapter.

npx @opengsd/gsd-core@latest

You will get a short interactive prompt:

GSD Core installer
? Which agent runtime are you using? › (use arrow keys)
❯ Claude Code
  Cursor
  Cline
  Aider
  Windsurf
  ... (12+ supported)
? Install location? › ./.gsd
? Set up the conductor skill now? › Yes

After it finishes, you will have a .gsd/ directory with the planner, dispatcher config, handoff templates, and a ledger file. From there the loop looks like this.

1. State the goal. In your main session, give GSD a real objective, not a micro-task. "Add per-key rate limiting to the public API, with tests and docs." Big enough to decompose; small enough to define done.

2. Plan. Ask GSD to plan. It produces a set of atomic plans, each with outcome, minimal context, constraints, and verification. Read them. This is the highest-leverage thirty seconds in the whole workflow. If a plan is not actually atomic — if it leans on context only your session has — fix it now, before any tokens get spent executing.

3. Dispatch. Tell GSD to execute. It spawns a fresh subagent per plan. Each one boots cold, reads its spec, does the work, runs its verification, and returns a handoff. Independent plans can run in parallel.

4. Review handoffs. Each returned handoff is small and structured. Your conductor session reads them — not the full transcript of each subagent, just the summary of what changed and what was verified. You approve, or you send a plan back with a correction.

5. Ship. GSD's bias is toward small, focused commits — one per plan where it makes sense. Git. Ship. Done. The name is the workflow.

A note on discipline

GSD will feel slow at the start of a task and fast at the end. The planning step is friction you pay up front. If you skip it and just start dispatching, you lose the entire benefit — you are back to a monolith with extra steps. The system only pays off if you actually invest in writing atomic, self-contained plans. That is the deal.

Managing handoffs well

The handoff is where GSD lives or dies, so it is worth being deliberate. A subagent that finishes a plan must return enough for the conductor to (a) trust the work and (b) brief the next plan — without dumping its entire context back into the main session, which would defeat the purpose.

A good handoff is structured and lossy on purpose:

## Handoff: Add rate limiting

### Status: complete

### Changed
- src/api/ratelimit.ts (new) — sliding-window limiter on Redis
- src/api/router.ts — mounted middleware before public routes

### Verified
- npm test src/api/ratelimit.test.ts — 9 passing
- Manual 101-request burst -> 429 + Retry-After confirmed

### For the next plan
- Limiter exposes `getRemaining(key)` if docs plan needs it.
- Redis key prefix is `rl:` — relevant if anyone adds eviction.

### Did NOT do
- No metrics/alerting on limit hits — out of scope, flag if wanted.

The "For the next plan" and "Did NOT do" sections are the ones people skip, and they are the ones that matter. They are how curated context flows forward without dragging the whole transcript along. The conductor reads this, updates the ledger, and the next fresh subagent gets exactly the breadcrumb it needs — getRemaining(key) exists — without inheriting nine thousand tokens of how the limiter was built.

How GSD compares to Superpowers and GStack

These three get mentioned together a lot, and they solve overlapping problems with different philosophies. Here is how I think about choosing.

GSD Core vs Superpowers

Superpowers is a broad library of composable skills — a toolkit of capabilities you reach for. Its center of gravity is breadth: lots of well-built skills you can mix into whatever you are doing. GSD is narrow and deep: it is one strong opinion about how the whole session is structured to fight rot.

You can run Superpowers skills inside a GSD plan — they are not mutually exclusive. But if your problem is "I want more capabilities," that is Superpowers. If your problem is "my long sessions degrade and I lose the thread," that is GSD. Superpowers makes each step better; GSD makes the sequence of steps survivable.

GSD Core vs GStack

GStack is a more conventional stacked-workflow system — it layers tooling and conventions to standardize how you build. It is lighter-touch than GSD and less total-takeover. GStack tends to coexist quietly with your existing habits. GSD does not coexist; it replaces your workflow. When you adopt GSD, the planning-dispatch-handoff loop becomes the way you work, full stop.

The honest framing:

	Superpowers	GStack	GSD Core
Primary value	Breadth of skills	Standardized stacked workflow	Anti-rot via atomic plans
Footprint	Additive	Light-to-moderate	Total takeover
Token cost	Low–moderate	Moderate	High
Best for	More capability	Consistency across a team	Large, long, high-stakes work
Plays with the others	Yes	Yes	Yes (as the outer loop)

In practice the strongest setup I have seen is GSD as the outer loop — running the planning and dispatch — with Superpowers skills available inside each atomic plan and GStack-style conventions enforced in the verification step. They are not competitors so much as different layers.

The honest caveats

I promised zero hype, so here are the two real costs, stated plainly.

It burns tokens fast. Fresh context is not free. Every subagent re-loads its spec; every handoff is read and written; the planner spends tokens decomposing before any work happens. For a small task, GSD can easily cost several times what a single straightforward session would. You are paying for sustained quality and parallelism, and on small tasks there is nothing to sustain — the rot never had time to set in. Using GSD for a ten-minute fix is like renting a freight train to carry a sandwich.

It takes over your whole workflow. This is not a skill you sprinkle on. Adopting GSD means adopting the planning-dispatch-handoff-verify loop as your default mode of operation. The discipline is the product. If you fight it — skipping planning, dumping context into the conductor, ignoring handoff structure — you get the cost without the benefit. People who try GSD halfway usually conclude it does not work, and they are right, because halfway GSD is just a normal session wearing a costume.

There is also a learning curve to writing genuinely atomic plans. Your first several will leak — they will assume context the executor does not have, and the subagent will flail or ask for things it cannot see. That is normal. Writing tight specs is a skill, and GSD is, among other things, a forcing function for learning it. (If you want to get better at the spec-writing itself, my spec-driven development guide goes deep on it.)

When it is worth the token cost

Here is my decision rule, plainly.

Use GSD when:

• The task is large enough that a single session would visibly rot before you finish — multi-file features, refactors, anything that would run for hours.
• The work decomposes cleanly into independent or loosely-coupled pieces (so parallel subagents earn their keep).
• Correctness matters enough that paying extra tokens for sustained quality is obviously worth it.
• You will repeat the work pattern, so the up-front discipline amortizes.

Do not use GSD when:

• The task is small enough to finish before rot sets in. Just do it in one session.
• The work is exploratory and you do not yet know the shape — you cannot write atomic plans for a problem you have not understood. Explore first, GSD second.
• Token budget is tight and the stakes are low.

A useful gut check: if you can hold the entire task comfortably in your own head and a single clean session, GSD is overkill. If the task is the kind where you would want to write things down so you do not lose track — that is exactly where the agent benefits from the same structure, and GSD pays for itself.

Where this fits in the bigger picture

GSD Core is one strong answer to a question the whole field is converging on: how do you keep agents effective over long, real work instead of just impressive demos? The answer keeps coming back to context engineering — being deliberate about what is in the window and what is kept out of it. GSD is context engineering crystallized into a workflow. If you want the underlying theory rather than the packaged system, the context engineering skill is the companion piece, and it is what will let you adapt GSD's ideas even when you are not running GSD itself.

The deeper skill GSD trains is decomposition. Learning to look at a fuzzy goal and carve it into atomic, verifiable, self-contained units is valuable whether or not you ever spawn a single subagent. That is the part worth keeping even if you decide the token cost is not for you.

Resources & links

• GSD Core repository — github.com/open-gsd/gsd-core (moved from the old gsd-build org)
• Install — npx @opengsd/gsd-core@latest
• Related skill: Superpowers — broad composable skill library that runs nicely inside GSD plans
• Related skill: GStack — lighter stacked-workflow system to compare against
• Related skill: Context Engineering — the theory behind why fresh-context atomic plans work
• Related skill: Grill Me — adversarial review you can wire into a GSD verification step
• Guide: Spec-Driven Development with AI Agents — how to write the atomic specs GSD depends on
• Guide: The Most Popular AI Coding Skills — where GSD sits in the landscape
• Track: Agentic Automation — the full learning path this skill belongs to