gsd-claude-teams

Multi-developer adaptation for Get Shit Done (GSD) — the AI-powered project execution framework for Claude Code.

GSD is designed for a single developer. This layer adds per-developer state isolation and team coordination commands so multiple engineers can work on different phases of the same project simultaneously.

Quick Start

Prerequisites

1. Claude Code installed and working
2. Vanilla GSD installed:

   npx get-shit-done-cc@latest
   # Interactive — choose global install, Claude Code

Install

git clone <this-repo-url>
cd gsd-claude-teams
node scripts/install.js

That's it. The script:

• Backs up your vanilla GSD install
• Copies vanilla as a base, then overlays the team-adapted patches on top
• Installs four team coordination commands
• Runs a smoke test to verify

To uninstall and restore vanilla GSD:

node scripts/install.js --uninstall

To update after someone pushes changes:

cd gsd-claude-teams
git pull
node scripts/install.js   # re-overlay the updated adapted files

What GSD Does (30-Second Version)

GSD turns a project idea into a structured execution plan and helps you build it phase by phase. The workflow:

1. /gsd:new-project — Describe what you're building. GSD creates PROJECT.md, REQUIREMENTS.md, and a phased ROADMAP.md
2. /gsd:plan-phase — For each phase, GSD researches the approach and writes detailed implementation plans
3. /gsd:execute-phase — GSD executes the plans: writes code, runs tests, commits. You review
4. /gsd:verify-work — Validate the built features work correctly

All artifacts live in .planning/ in your repo. Plans are committed so anyone can see what was built and why.

For the full guide: GSD User Guide

What This Layer Adds

Vanilla GSD uses a single STATE.md to track progress. If two developers both run GSD, they overwrite each other's state. This layer solves that.

Per-Developer State Isolation

Each developer gets their own state file (STATE_pat.md, STATE_dustin.md, etc.) while sharing the project's roadmap, requirements, and plans. When you run GSD commands, they read your state file — not a shared one.

Team Commands

Command	What It Does
/team:assign pat 3	Claim phase 3 as your own. Creates your state file, optionally creates a branch
/team:status	Show who's working on what across all developers
/team:handoff	Verify your work, normalize artifacts, create a PR to main
/team:pickup 3	Pick up a phase someone else started — get briefed on progress and what's next

Workflow for Engineers

First Time Setup

1. Install (see Quick Start above)
2. Clone the project repo your team is working on
3. In Claude Code, run: /team:assign <your-name>

Daily Workflow

Starting a new phase:

/team:assign <your-name> <phase-number>    # claim the phase
/gsd:plan-phase                            # plan it (or skip if already planned)
/gsd:execute-phase                         # build it
/gsd:verify-work                           # validate it works
/team:handoff                              # PR to main

Picking up someone else's work:

/team:pickup <phase-number>                # checks out branch, briefs you on status
/gsd:execute-phase                         # continue execution

Checking in on the team:

/team:status                               # who's on what, what's done, what's blocked

Parallel Work

Multiple developers can work on different phases at the same time:

• Pat plans and executes Phase 2
• Greg plans and executes Phase 3
• Dustin plans and executes Phase 4

This works because each phase has its own directory under .planning/phases/ and each developer has their own state file. No collisions.

The one rule: one developer per phase. Don't have two people executing the same phase simultaneously.

Session Management

GSD is context-aware across sessions. If you need to stop and come back later:

/gsd:pause-work         # saves your context for later
# ... next day ...
/gsd:resume-work        # picks up where you left off

Or just run /gsd:progress — it reads your state file and tells you what to do next.

How It Works Under the Hood

GSD hardcodes .planning/STATE.md in ~90 workflow files. Rather than forking GSD, we maintain a build-time transform (scripts/transform.js) that rewrites state file paths to support per-developer isolation while keeping shared artifacts (ROADMAP.md, PROJECT.md, REQUIREMENTS.md) in the common .planning/ root.

gsd-claude-teams/
├── original/get-shit-done/     # git submodule — upstream GSD (never modified)
├── adapted/                    # transformed workflows (generated by transform.js)
├── commands/team/              # team coordination commands
├── scripts/
│   ├── transform.js            # builds adapted/ from original/
│   └── install.js              # one-command setup
└── docs/
    └── install-strategy.md     # design decisions

Keeping Up With GSD Updates

GSD is actively maintained. When the upstream library gets a new release, there are two scenarios to handle: one for consumers (everyone on the team) and one for the maintainer (whoever manages gsd-claude-teams).

If You Run /gsd:update or npx get-shit-done-cc@latest

This will break your team setup. GSD's updater replaces ~/.claude/get-shit-done/ with fresh vanilla files, overwriting the merged team-adapted version.

How to tell it happened: GSD commands still work, but team features (/team:assign, /team:status, etc.) stop working and state isolation is gone — everyone shares a single STATE.md again.

How to fix it:

cd gsd-claude-teams
node scripts/install.js

That's it. The install script detects the vanilla directory, backs it up, copies it as a base, and re-overlays the adapted patches. Your state files and team commands are restored.

To avoid surprises: Don't run /gsd:update or npx get-shit-done-cc@latest without re-running the install script afterward. If you want to update vanilla GSD and keep the team layer, use the maintainer workflow below instead.

Maintainer Workflow: Pulling Upstream GSD Changes

When Lex pushes a new GSD release, one person on the team pulls the update, re-transforms, and pushes. Everyone else gets it on their next git pull.

cd gsd-claude-teams

# 1. Pull the latest upstream GSD into the submodule
git submodule update --remote

# 2. Re-run the transform to regenerate adapted/ with team patches
node scripts/transform.js

# 3. Verify the transform worked
node scripts/install.js          # re-overlay adapted patches
# Test a GSD command in a project repo to make sure nothing broke

# 4. Commit and push
git add original/ adapted/
git commit -m "chore: update GSD to $(cat original/get-shit-done/VERSION 2>/dev/null || echo 'latest')"
git push

Then tell the team: "GSD updated — pull gsd-claude-teams."

Everyone else:

cd gsd-claude-teams
git pull
node scripts/install.js   # re-overlay the updated adapted files

How often to do this: Check for updates every week or two while GSD is in active development. You can watch the GSD repo for releases or just pull the submodule periodically.

If the transform breaks: The transform script (scripts/transform.js) patches specific patterns in GSD's workflow files. If Lex significantly restructures those files, the transform may need updating. The script logs which patches succeeded and failed — if any fail, check what changed upstream and adjust the transform before committing.

Known Limitations

• After moving the gsd-claude-teams repo or pulling changes, re-run node scripts/install.js to re-overlay.
• /gsd:complete-milestone should be run by one person after all developers' phases are done — not while someone is still executing.