Metadata-Version: 2.5
Name: gsd-lean
Version: 1.13.0
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
Classifier: Programming Language :: Python :: 3.15
Requires-Python: <3.16,>=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/`; on the default branch, a feature git branch is suggested (created only on confirmation) |
| **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. Subagents read compact Markdown context slices via `gsd-lean slice` instead of full HTML artifacts.

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.

After upgrading the plugin, rerun `/gsd-lean:init` to refresh seeded files (`docs/adr/README.md`, glossary grouping). The rerun also runs a drift check that updates stale CONTEXT.md entries and PROJECT.md Stack fields after a single confirmation, and surfaces Constraints/Notes inconsistencies one question at a time (see [ADR-0014](docs/adr/0014-content-level-drift-check-is-a-gated-rewrite.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.

<!-- keep in sync: constraint tags — planning.py PROJECT.md template / README Constraints / PROJECT_KNOWLEDGE routing matrix / quick SKILL.md Step 5+10 / quick-executor / auto-debug -->
````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`
- [quick] Skip the CHANGELOG entry for quick fixes
- When writing `.luau` files, run `rojo sourcemap ...`
````

Valid tags: `[discuss]`, `[plan]`, `[execute]`, `[verify]`, `[quick]`. Multiple tags allowed (e.g., `[execute][verify]`); tags are additive — there is no override — and `/quick` applies `[execute]` + `[verify]` + `[quick]` + untagged.

**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). When you are on the default branch, it also suggests a feature git branch, created only if you confirm.

**3. Plan**

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

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

**TDD flagging is request-only.** The planner adds `[tdd]` to a task title only when you ask for it (a `[plan]`-tagged or untagged constraint in PROJECT.md, or the `/plan` arguments); it never flags tasks on its own. Every `[tdd]` task gets a **Seams** field: the public interfaces its tests may touch, each with a one-line catches/misses note and the system boundaries to mock. Plan-review checks that `[tdd]` tasks have Seams and that non-`[tdd]` tasks do not.

**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.

**TDD mode.** A task titled `[tdd]` runs the executor in TDD mode: per listed seam, one vertical slice of failing test (red) then minimal code (green), no refactor inside the loop. The executor reports evidence per slice (seam, test command, trimmed failing and passing excerpts). Reviewers act as a backstop: spec-review checks the evidence and that tests sit only at listed seams; code-quality-review flags mocks of internal collaborators, implementation-coupled or tautological tests, and side-channel verification; cleanup belongs to code-quality-review, not the loop. Auto-debug places regression tests only at listed test seams. A `[tdd]` task with no Seams stops before the executor runs and asks you to fix the plan. Unflagged tasks execute exactly as before.

> Adapted from Matt Pocock's `tdd` skill.

> The `- Seams:` line in `gsd-lean slice plan` output needs the CLI release that ships it; with an older CLI, Seams are folded into Files and plan-review cannot see them separately.

**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.

## Glossary Hygiene

```
/gsd-lean:glossary
/gsd-lean:glossary lean
/gsd-lean:glossary lean "### Group"
```

`.planning/GLOSSARY.md` is a shared vocabulary for code-writing agents, so each `## Language` entry follows an **entry rule**: one or two sentences saying what the term is, with no file paths, storage detail, citations or behaviour narratives, and at most one code name. `/discuss` admits only terms that pass the entry rule and an admission test, and prints a one-line size hint when `## Language` grows past 40KB.

`/glossary` is stateless — no phase transition, no cycle-state writes. With no argument it assesses the glossary (section sizes, term and violation counts, via `uvx gsd-lean glossary stats`) and writes nothing. `/glossary lean` works per `###` group: it proposes in plan mode, asks once, and applies through `uvx gsd-lean glossary lean --apply` — never by hand-editing the glossary. The quoted `"### Group"` form runs a single group. Deletion is limited to code-artifact terms with no `_Avoid_` ban.

### Multiple glossary contexts (opt-in)

A single `.planning/GLOSSARY.md` is the default and stays that way unless you opt in. A project with distinct sub-domains can instead keep a **glossary map**, `.planning/GLOSSARY-MAP.md`, that lists **glossary contexts** (`- **slug** — [text](glossary/slug.md): scope`, plus a `## Relationships` section). Each context lives in `.planning/glossary/<slug>.md` in the same three-section format as `GLOSSARY.md`; `GLOSSARY.md` remains the **shared glossary**. With no map, everything behaves as before.

`/gsd-lean:glossary split` creates the map. It proposes a term-to-context assignment in plan mode behind two approval gates, warns when the file is bloated (splitting a bloated file gives you several bloated files), and applies the approved assignment through `uvx gsd-lean glossary split --assign` — never by moving bullets by hand. The command moves bullets byte-for-byte, routes Relationships and Flagged ambiguities lines by the terms they name, and is idempotent. A homonym (a term heading that occurs more than once) needs one target per occurrence, in source order.

**Migration: lean first, then split.** Run `/gsd-lean:glossary lean` to bring the existing glossary to the entry rule, then `/gsd-lean:glossary split`. `/gsd-lean:glossary lean <glossary-context>` and `uvx gsd-lean glossary lean --apply FILE --context SLUG` lean a single context afterwards (default target: the shared glossary).

With a map, `/discuss` and `/plan` record which glossary contexts a cycle touches (a `glossary-contexts` requirements section and a per-task `Contexts` field), and `/execute`, `/quick` and `/arch-health` hand their subagents only those glossary contexts via `uvx gsd-lean slice glossary --context SLUG` (repeatable; `--context shared` for the shared glossary only). Without `--context`, a mapped project slices every glossary context; `--context` without a map is an error. `uvx gsd-lean glossary stats` reports the shared glossary and each context separately.

## 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 instruction files (`CLAUDE.md` and/or `AGENTS.md`) contain 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.
* GSD-Lean reads both `CLAUDE.md` and `AGENTS.md` itself. Claude Code (v2.1.277+) reads `AGENTS.md` natively only when no `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` exists; otherwise `AGENTS.md` is shadowed and Claude Code's own sessions ignore it. Fix: add an `@AGENTS.md` import at the top of `CLAUDE.md` — `/init` offers this.
