Metadata-Version: 2.4
Name: gsd-lean
Version: 1.3.2
Summary: Lightweight meta-prompting and spec-driven development plugin for Claude Code
Project-URL: Homepage, https://github.com/Bifurcate-Loops/gsd-lean
Project-URL: Repository, https://github.com/Bifurcate-Loops/gsd-lean
Project-URL: Issues, https://github.com/Bifurcate-Loops/gsd-lean/issues
Project-URL: Changelog, https://github.com/Bifurcate-Loops/gsd-lean/blob/main/CHANGELOG.md
Author: Bifurcate-Loops
License-Expression: MIT
License-File: LICENSE
Keywords: claude-code,development,meta-prompting,plugin,spec-driven
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.12
Requires-Dist: click>=8.3.1
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# 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, `docs/adr/README.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](./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.

````markdown
## 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.

````markdown
## 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.
