gsd-lean 1.2.0

Lightweight meta-prompting and spec-driven development plugin for Claude Code

GSD-Lean

A lightweight reimplementation of Get-Shit-Done — a complement to the original GSD system

What is GSD?

GSD 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:

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.html and DECISIONS.html populated; hard-to-reverse decisions offered as ADRs in docs/adr/
plan	Requirements decomposed into tasks (T-NNN) in PLAN.html; plan-review subagent verifies completeness
execute	Tasks implemented one by one, status tracked in PLAN.html
verify	Lint, typecheck, tests run against task verification criteria
complete	Summary generated, cycle can restart; hard-to-reverse decisions offered as ADRs in docs/adr/
quick (utility)	Ad-hoc task executed, verified, and committed — bypasses the full cycle

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. For lightweight ad-hoc work outside the cycle, /quick runs execution + verification + commit without touching cycle state.

See 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 are read by GSD-Lean phases and injected into subagent prompts.

Constraints are mandatory rules. Prefix with [phase] to target specific phases. Untagged constraints apply to all phases.

## Constraints

- [execute] After writing `.luau` files, run `rojo sourcemap default.project.json -o sourcemap.json`
- [plan] For each development cycle, always include a last task running the `code-simplifier` subagent
- [execute][verify] If env variables are introduced, update `.env.example`
- When writing `.luau` files, run `rojo sourcemap ...`

Valid tags: [discuss], [plan], [execute], [verify]. Multiple tags allowed (e.g., [execute][verify]).

Notes are informational context injected into all phases. No phase tags needed.

## Notes

- We're migrating from REST to GraphQL next quarter — prefer GraphQL patterns where possible
- The auth module is owned by team-security; changes there need extra review
- Performance budget: no endpoint should exceed 200ms p95

2. Discuss

/gsd-lean:discuss Add user authentication with OAuth

Claude explores the codebase and web, probes for preferences, and populates REQUIREMENTS.html and DECISIONS.html. Hard-to-reverse architectural decisions can also be recorded as durable ADRs in docs/adr/ (git-tracked, permanent — distinct from the ephemeral DECISIONS.html).

3. Plan

/gsd-lean:plan

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

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, offers to record hard-to-reverse decisions as durable ADRs in docs/adr/, 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.