GSD Framework: Turning AI Programming into an Industrial Pipeline

01 | Why Choose GSD as the Representative of Context Engineering?

GSD attacks the core problem of AI programming—how to use the context window—by turning uncontrolled "conversation‑style" coding into an observable, schedulable, recoverable industrial pipeline.

02 | Design Philosophy: Context Is a Scarce Resource, Pipelines Beat Artisans, Filesystem as Memory

Philosophy 1: Context is scarce and must be managed explicitly. GSD treats context as a budget: the main session keeps 30‑40% token usage, each sub‑task gets a 200K‑token limit, and contexts are cleared with /clear. Information is stored in the filesystem and loaded on demand, similar to OS memory management.

Philosophy 2: Pipelines beat artisans. Instead of ad‑hoc, mood‑dependent coding, GSD enforces a five‑stage pipeline (Discuss → Plan → Execute → Verify → Ship) with clear inputs, outputs, and acceptance criteria, allowing local rollback without affecting other stages.

Philosophy 3: Cross‑session memory via the filesystem. Files such as .planning/PROJECT.md, .planning/ROADMAP.md, .planning/STATE.md, .planning/CONTEXT.md, and .planning/plan.xml serve as long‑term memory, enabling a new session to restore state in seconds without token waste.

03 | Core Architecture: .planning/ Directory, Three‑Level Decomposition Model, XML Plan, State Machine

The architecture consists of four concepts:

.planning/ directory – the project’s "operating system", analogous to .git/ but for workflow metadata.

Three‑level decomposition – Milestone (1‑2 weeks, business deliverable), Phase (1‑3 days, technical unit), Task (≤30 minutes, single‑context unit).

XML plan.xml – a strongly‑typed, machine‑parseable plan that defines objective, validation_criteria, and a list of atomic tasks with description, validation, depends_on, and context_files.

STATE.md – a state‑machine document that records the current Milestone, Phase, Task, completed items, and pending tasks, enabling "breakpoint‑resume" capability.

your-project/
├── .planning/
│   ├── PROJECT.md        ← project vision & constraints
│   ├── ROADMAP.md        ← milestone roadmap
│   ├── STATE.md          ← real‑time progress (auto‑maintained)
│   ├── CONTEXT.md        ← key decisions
│   └── milestones/
│       ├── M1-foundation/
│       │   └── phases/
│       │       ├── phase-1-auth/
│       │       │   ├── plan.xml        ← XML plan with validation
│       │       │   ├── tasks/          ← atomic task list
│       │       │   └── results/        ← task results
│       │       └── phase-2-payment/
│       └── M2-features/
└── src/                     ← actual code

04 | Five‑Stage Workflow: Discuss → Plan → Execute → Verify → Ship

Stage 1: Discuss – command /gsd-discuss-phase N. Goal: clarify requirements and lock key decisions into CONTEXT.md. Discipline: do not proceed without a clear discussion.

Stage 2: Plan – command /gsd-plan-phase N. Goal: decompose work into atomic tasks, generate plan.xml and a DAG of dependencies. Discipline: planning only, no code writing.

Stage 3: Execute – command /gsd-execute-phase N. Goal: run tasks in parallel waves. The main agent reads plan.xml, creates independent sub‑agents for each wave, each sub‑agent works in an isolated context and commits its result.

Wave execution – parallel for independent tasks, serial for dependent ones.

Context isolation – each sub‑agent sees only its relevant files.

Atomic commits – one Git commit per task for easy rollback.

Stage 4: Verify – command /gsd-verify-work N. Goal: Goal‑Backward verification, i.e., ask whether the user can achieve the intended outcome rather than merely checking implementation details. Example: instead of confirming that login() returns a token, verify that the user can log in and view the personal homepage.

Stage 5: Ship – command /gsd-ship N. Goal: generate a PR, archive the milestone, update ROADMAP.md, and link related issues.

05 | Wave Execution: Turning Serial into Parallel Engineering

Wave execution follows a DAG scheduler. For a Phase with eight tasks and the dependency graph shown, GSD creates four waves: Wave 1 (tasks 1‑4 parallel), Wave 2 (tasks 5‑6 parallel), Wave 3 (task 7), Wave 4 (task 8). Theoretical speed‑up is 2× (8N → 4N). More importantly, parallelism prevents a single session from becoming overloaded, keeping the main context lightweight.

06 | Three Engineering Practices to Counter Context Rot

Practice 1: Context Isolation – the main session only schedules; each task runs in a fresh sub‑agent whose context is cleared with /clear. Token usage stays at 30‑40%.

Practice 2: Cross‑Session Memory – new sessions automatically load .planning/STATE.md, .planning/CONTEXT.md, and .planning/plan.xml, eliminating the need to repeat prior information.

Practice 3: Parallel Execution Instead of Linear – tasks are parsed into a DAG, then executed in waves, reducing total time and avoiding context bloat.

07 | GSD’s Relationship with the Three Core Principles

GSD uniquely pushes all three principles to the extreme:

Decision Externalization – decisions are stored in files (PROJECT.md, ROADMAP.md, CONTEXT.md, STATE.md, plan.xml).

Stage‑Based Process – the five stages provide the most complete harness framework.

Task Atomicity – explicit 200K‑token task limit, sub‑agent isolation, wave‑parallel scheduling, and DAG dependency management.

08 | Clever Designs: Five Engineering Insights of GSD

Design 1: XML over Markdown – forces a strict structure that machines can parse and validate.

Design 2: Goal‑Backward Verification – validates from the user’s goal perspective, exposing deeper failures.

Design 3: State‑Machine‑Driven Progress – STATE.md drives scheduling and enables resumable sessions.

Design 4: Discipline as Code – commands such as /gsd-clear-and-load, /gsd-verify-context, and /gsd-checkpoint encode workflow discipline.

Design 5: Automated Git Integration – each atomic task creates a commit with an auto‑generated message, turning Git history into the project’s execution log.

feat(M1.P1.T8): implement logout API
feat(M1.P1.T7): add JWT validation middleware
feat(M1.P1.T6): implement login API
feat(M1.P1.T5): implement register API
feat(M1.P1.T4): add JWT signing utility
feat(M1.P1.T3): create auth.service.ts skeleton
feat(M1.P1.T2): implement password hashing
feat(M1.P1.T1): create users table migration

09 | Limitations and Applicable Scenarios

Limitation 1: High Startup Cost – requires detailed Milestone → Phase → Task breakdown; start with a small Milestone.

Limitation 2: Strict Discipline Required – skipping Discuss or Verify degrades results; embed GSD commands into CI/CD.

Limitation 3: Heavy Dependence on Sub‑Agent Capability – choose AI tools that support sub‑agents (e.g., Claude Code).

Limitation 4: Unsuitable for Rapid Prototyping – use lighter frameworks for quick sketches, switch to GSD for formal development.

Limitation 5: No Built‑in Specification Management – combine with an SDD framework for long‑term contract governance.

Recommended Scenarios

Long‑duration projects (months to a year) – ★★★★★

Complex multi‑module feature development – ★★★★★

Projects demanding strict quality assurance – ★★★★★

Multi‑person collaboration needing shared state – ★★★★

Rapid prototyping – ★★

Simple single‑file edits – ★

Conclusion

GSD is not a toolbox but an "industrial pipeline" that makes AI programming observable, schedulable, and recoverable.

The .planning/ directory acts as the project’s operating system, a single source of truth for both AI and humans.

The three‑level decomposition (Milestone → Phase → Task) aligns business, technical, and execution concerns.

XML plan.xml sacrifices human readability for machine stability.

The five‑stage workflow enforces discipline at each step.

Wave execution turns serial work into parallel work, with speed‑up as a side effect.

Goal‑Backward verification checks user‑level outcomes rather than mere implementation details.

Limitations include high initial overhead, strict process adherence, reliance on capable sub‑agents, and lack of built‑in specification management.