gsd-lean 0.9.0
Lightweight meta-prompting and spec-driven development plugin for Claude Code
Requires Python: <3.15,>=3.12
Keywords: claude-code, development, meta-prompting, plugin, spec-driven

# GSD-Lean

> A lightweight reimplementation of [Get-Shit-Done](https://github.com/glittercowboy/get-shit-done) — a complement to the original GSD system

## What is GSD?

[GSD](https://github.com/glittercowboy/get-shit-done) is a meta-prompting, context engineering, and spec-driven development system for Claude Code. It solves context rot by breaking projects into phases with fresh contexts per task, using a discuss → plan → execute → verify loop. Written in JavaScript.

## What is GSD-Lean?

A Python reimplementation of GSD's core ideas as a lightweight plugin. Rather than the full system, GSD-Lean focuses on being minimal and easy to extend.

**Status:** Early development.

## How It Works

GSD-Lean guides development through a 6-phase workflow:

```mermaid
stateDiagram-v2
    [*] --> init : gsd-lean init
    init --> discuss : project initialized

    discuss --> plan : requirements populated
    plan --> discuss : plan rejected
    plan --> execute : plan verified
    execute --> plan : revise plan
    execute --> verify
    verify --> execute : tasks remaining
    verify --> complete : all tasks done
    complete --> discuss : new cycle
    complete --> init : re-initialize
```

| Phase | What Happens |
|-------|-------------|
| **init** | Project scaffolded; tech stack auto-detected; PROJECT.md, CONTEXT.md, STATE.md created |
| **discuss** | Research subagent investigates codebase + web; user preferences probed; REQUIREMENTS.md and DECISIONS.md populated |
| **plan** | Requirements decomposed into tasks (T-NNN) in PLAN.md; plan-review subagent verifies completeness |
| **execute** | Tasks implemented one by one, status tracked in PLAN.md |
| **verify** | Lint, typecheck, tests run against task verification criteria |
| **complete** | Summary generated, cycle can restart |

Each phase is driven by a skill (`/init`, `/discuss`, `/plan`, `/execute`, `/verify`, `/complete`) that calls CLI commands (`gsd-lean init`, `gsd-lean transition`, `gsd-lean plan-status`) to manage state.

See [PROJECT_KNOWLEDGE.md](./PROJECT_KNOWLEDGE.md) for detailed architecture — transitions, preconditions, subagents, and CLI reference.

## Quick Start

**0. Install plugin**

Add the Bifurcate Loops marketplace, then install GSD-Lean:

```
/plugin marketplace add Bifurcate-Loops/bifurcate-plugins
/plugin install gsd-lean@bifurcate-plugins
```

**1. Initialize project**

```
/gsd-lean:init
```

Scaffolds the project. Claude asks clarifying questions, then writes PROJECT.md and CONTEXT.md.

Sections "Constraints" and "Notes" in PROJECT.md should be filled with useful information as you work through your development cycles. This will be picked up by GSD-Lean phases `/gsd-lean:discuss` and `/gsd-lean:plan`. Example:

````markdown
## Constraints

- (none yet)

## Notes

- Use skills `/ai-sdk` (.claude/skills/ai-sdk/SKILL.md) and `/mastra` (.claude/skills/mastra/SKILL.md) when working on agentic features
- Use skill `/vercel-react-best-practices` (.claude/skills/vercel-react-best-practices/SKILL.md) when working on React and Next.js applications
- If env variables are introduced in a development cycle, remember to include them in `.env.example`
````

**2. Discuss**

```
/gsd-lean:discuss Add user authentication with OAuth
```

Claude explores the codebase and web, probes for preferences, and populates REQUIREMENTS.md and DECISIONS.md.

**3. Plan**

```
/gsd-lean:plan
```

Decomposes requirements into structured tasks (T-NNN) in PLAN.md.

**4. Execute**

```
/gsd-lean:execute
```

Implements tasks sequentially — one per invocation. If requirements change mid-execution, re-invoke `/plan` to revise the plan while preserving task progress.

**5. Verify & Complete**

```
/gsd-lean:verify
/gsd-lean:complete
```

`/verify` runs verification against task criteria. `/complete` generates a summary and optionally starts a new cycle.

## Caveats

* Run each GSD-Lean phase in a **new Claude Code session**. The `/init`, `/discuss`, and `/plan` phases enter Plan Mode; when prompted to accept, select **Yes, auto-accept edits** — do **not** select "Yes, clear context and auto-accept edits (shift+tab)", as that erases internal context and causes GSD-Lean to lose track.
* If your project's `CLAUDE.md` contains development workflow instructions (e.g. branching strategy, commit conventions, test-before-push rules), these can conflict with GSD-Lean's phased development cycle. Remove or comment out such instructions before running GSD-Lean.