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

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.

After upgrading the plugin, rerun /gsd-lean:init to refresh seeded files (docs/adr/README.md, glossary grouping).

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

- Use `uv run python -c <command>` instead of `python3 -c <command>`
- [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.

Quick Executor

/gsd-lean:quick fix null check in parse_config

Lightweight, stateless execution for small, well-scoped tasks — bypasses the full cycle. Nothing is written to .planning/; traceability comes from git history alone. Requires a concrete task description (vague ones like "clean up code" are rejected).

Flow: explore in plan mode → quick-executor subagent implements → verification (lint, typecheck, tests) → one auto-debug round on failure → auto-commit on pass. If verification still fails after auto-debug, no commit is made.

Non-blocking advisories are printed when a full cycle is active, the working tree is dirty, or the task touches 4+ files (a hint to use /discuss instead).

Architecture Health

/gsd-lean:arch-health

Stateless, between-cycle architecture pass — no phase transition, no cycle-state writes. Accepts an optional scope argument (e.g. src/gsd_lean/cli).

Applies the deep/shallow module lens and the deletion test to find shallow modules — pass-throughs, thin wrappers, verbatim re-exports — worth deepening, inlining, or deleting. Analysis is grounded in CONTEXT.md, GLOSSARY.md, and docs/adr/ when present, and performed by a read-only arch-analyzer subagent.

Results append newest-first to .planning/ARCH_HEALTH.html as candidate cards, each with a confidence rating (Strong / Worth-exploring) and a verdict (deletion / deepening / cohesion).

Adapted from Matt Pocock's improve-codebase-architecture skill.

Caveats

• Run each GSD-Lean phase in a new Claude Code session. The /init, /discuss, /plan, and /quick 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.