33ffc647e2
* test(117): add failing tests for env validator (check-env.sh)
RED phase. Six tests for scripts/check-env.sh — none pass because the
script does not exist yet. Fixtures:
good/ — engines.node >=22, .nvmrc 26, synced lockfile
bad-node-version/ — engines.node <14.0.0 (current Node v26 fails)
missing-lockfile/ — no package-lock.json
bad-nvmrc/ — .nvmrc says 22, current Node is v26
Tests cover:
1. Happy path exits 0
2. engines.node constraint failure exits 1
3. Missing lockfile exits 1
4. .nvmrc major mismatch exits 1
5. --json flag emits {pass: boolean, checks: array}
6. Integration smoke: exits 0 on live worktree root
Sources:
npm engines: https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines
npm ci docs: https://docs.npmjs.com/cli/v10/commands/npm-ci
Closes #117
* feat(117): add scripts/check-env.sh with Node/npm/lockfile/version-manager checks
GREEN phase. Implements the five-check environment validator:
1. Node version vs engines.node (semver constraint — >=, >, <=, <, =)
2. npm version vs engines.npm (skipped if field absent)
3. package-lock.json presence
4. Lockfile sync via `npm ci --dry-run` (exits non-zero when drift detected)
5. Version-manager pin (.nvmrc / .node-version / .tool-versions) vs active Node major
Exit codes: 0 = all green; 1 = at least one failure; 2 = tool error.
Flags: --json (structured report), --help.
All 7 tests pass. shellcheck clean. bash -n syntax check clean.
Sources:
npm engines: https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines
Reproducible builds: https://reproducible-builds.org/docs/source-tree/
npm ci docs: https://docs.npmjs.com/cli/v10/commands/npm-ci
Closes #117
* chore(117): pin Node engines + .nvmrc; add check:env npm script
- Add engines.npm: ">=10.0.0" (npm 10 ships with Node 22, the CI floor).
Source: https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines
- Add .nvmrc pinning Node 22 (lowest supported version per CI matrix in
.github/workflows/test.yml; node-version: [22, 24]).
- Add "check:env": "./scripts/check-env.sh" script to package.json.
No generator is involved (not a .generated. file). The test update in this
commit adjusts the integration smoke: it now asserts on --json structured
output rather than raw text, and accepts exit 0 or 1 (version-manager pin
mismatch is expected when developer runs Node 26 against a .nvmrc of 22).
Closes #117
* ci(117): wire environment check into test workflow
Add "Environment check" step to .github/workflows/test.yml in the `test`
job. Positioned AFTER actions/setup-node and BEFORE npm ci so that env
mismatches (wrong Node version, missing npm version, absent lockfile) are
caught before the install step obscures the root cause.
Runs `npm run check:env` (./scripts/check-env.sh) on every matrix lane
(ubuntu, macos, windows) × (Node 22, 24).
Source: https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines
Closes #117
* docs(117): publish docs/contributing/bootstrap.md + link from CONTRIBUTING.md
Adds docs/contributing/bootstrap.md with:
1. Prerequisites (nvm, fnm, asdf, mise; gh CLI)
2. One-time setup (clone, nvm use, check:env, npm ci)
3. Daily commands table
4. Validation guide (check table, exit codes, --json usage)
5. Troubleshooting (node-version, npm-version, lockfile-present,
lockfile-sync, version-manager-pin, missing modules, locale errors)
6. Alternative: Docker via gsd-test-runner
(https://github.com/open-gsd/gsd-test-runner)
Adds "Bootstrap your environment" section to CONTRIBUTING.md pointing to
the new doc. No content duplication — CONTRIBUTING.md links only.
Adds .changeset/117-npm-bootstrap.md (type: Added) for changelog.
Sources:
npm engines: https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines
Reproducible builds: https://reproducible-builds.org/docs/source-tree/
npm ci docs: https://docs.npmjs.com/cli/v10/commands/npm-ci
gsd-test-runner: https://github.com/open-gsd/gsd-test-runner
Closes #117
* fix(#117): make check:env script run on Windows runners
Invoke check-env.sh via `bash` instead of a bare POSIX path so
Windows CI runners (which have Git Bash on PATH) execute the script
without requiring a POSIX shell shebang dispatcher.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test(117): make check-env.sh fixture .nvmrc adapt to active Node major (cross-platform fix)
Before() hook writes good/.nvmrc = activeNodeMajor and bad-nvmrc/.nvmrc = activeNodeMajor+99
at test-run time. Hardcoded .nvmrc=26 failed on every CI matrix row except Node 26.
After() restores originals so the checked-in files stay stable.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(117): exempt gsd-test-runner URL path from slash-command registry check
docs/contributing/bootstrap.md links to https://github.com/open-gsd/gsd-test-runner.
The parity-test regex captures /gsd-test-runner from the URL path component and
flags it as an unregistered slash command. Add 'test-runner' to INTERNAL_COMPONENT_SLUGS
(mirrors the existing 'build' entry for GitHub org URLs) with an explanatory comment.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(117): fix Node-24 and Windows-22 CI failures in check-env
Two root causes:
1. version-manager-pin on Node 24 (mac/ubuntu/win):
The project root .nvmrc pins major 22 for local dev. When the CI
matrix runs Node 24, check-env.sh fails the version-manager-pin
check and exits 1, blocking the entire test job before any test
runs. Fix: skip the pin check when CI=true (GitHub Actions always
sets this). The pin is a local dev guard, not a gate for multi-
version matrix CI.
2. engines.node appears missing on Windows-22 (pkg_field backslash):
pkg_field() embedded PACKAGE_JSON directly into a node -e string
literal using require(). On Windows, the path uses backslashes
(D:\a\...) which are silently interpreted as JS escape sequences
inside the string, causing require() to fail silently (2>/dev/null
|| true). engines.node returns empty, triggering a spurious FAIL.
Fix: switch to fs.readFileSync + JSON.parse and normalise
backslashes to forward-slashes before embedding in the JS literal.
Also pass { CI: '' } from the bad-nvmrc unit test so the
version-manager-pin fixture test still exercises the mismatch path
even when running inside CI runners.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(117): use relative ./package.json path in pkg_field to fix Windows CI
On Windows, Git Bash exposes \$PWD as a POSIX path (/d/a/…) which
node.exe cannot resolve via fs.readFileSync. The previous fix embedded
the absolute PACKAGE_JSON path in the node -e string after converting
backslashes to forward-slashes, but the POSIX form produced by Git Bash
(/d/a/…) has no backslashes — so the conversion was a no-op and node
received an unresolvable path. The silent catch(e) { process.exit(0) }
swallowed the ENOENT, returning empty string for every engines.* field.
Fix: use './package.json' (relative to CWD). pkg_field() is always
called before any cd in the script so CWD === PROJECT_ROOT at call time.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
⚠️ This is the active fork
📢 Read the announcement: why the fork, what changed, what's next →
The original repo at gsd-build/get-shit-done appears compromised or abandoned. The maintainer (TÂCHES) has not been reachable since 2026-04-01. TÂCHES social accounts appear deleted, and a
$GSDtoken associated with the project has been linked publicly to a rug-pull.I have no inside information beyond what is publicly visible. I am stating absence-of-information deliberately — absence of news is not the same as evidence.
What I can confirm
- No contact with the original maintainer since 2026-04-01.
- TÂCHES social accounts appear deleted or unreachable.
- The
$GSDtoken has been linked publicly to a rug-pull.- The repo at
gsd-build/get-shit-donecontinues to exist but I cannot vouch for any changes pushed there from this point forward.What changed
Before After GitHub gsd-build/get-shit-doneopen-gsd/get-shit-done-reduxnpm (main) get-shit-done-cc→get-shit-done-redux@opengsd/get-shit-done-reduxnpm (sdk) @gsd-build/sdk→@gsd-redux/sdk@opengsd/gsd-sdkIssue numbers per source renumbered; original is in body as [from gsd-build/get-shit-done#N]If you can reach the original maintainer, please open an issue here and CC them. If you have technical evidence that materially changes the picture above, please share it in an issue.
— trek-e, fork maintainer
GET SHIT DONE
English · Português · 简体中文 · 日本語 · 한국어
A light-weight meta-prompting, context engineering, and spec-driven development system for Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, and more.
Solves context rot — the quality degradation that happens as your AI fills its context window.
npx @opengsd/get-shit-done-redux@latest
Works on Mac, Windows, and Linux.
"If you know clearly what you want, this WILL build it for you. No bs."
"I've done SpecKit, OpenSpec and Taskmaster — this has produced the best results for me."
"By far the most powerful addition to my Claude Code. Nothing over-engineered. Literally just gets shit done."
Trusted by engineers at Amazon, Google, Shopify, and Webflow.
Important
Returning to GSD?
Run
/gsd-map-codebaseto re-index your codebase, then/gsd-new-projectto rebuild GSD's planning context. Your code is fine — GSD just needs its context rebuilt. See the CHANGELOG for what's new.
Why I Built This
I'm a solo developer. I don't write code — Claude Code does.
Other spec-driven tools exist, but they're all built for 50-person engineering orgs — sprint ceremonies, story points, stakeholder syncs, Jira workflows. I'm not that. I'm a creative person trying to build great things consistently.
So I built GSD. The complexity is in the system, not in your workflow. Behind the scenes: context engineering, XML prompt formatting, subagent orchestration, state management. What you see: a few commands that just work.
The system gives Claude everything it needs to do the work and verify it. I trust the workflow. It just does a good job.
— TÂCHES
How It Works
The loop is six commands. Each one does exactly one thing.
1. Initialize
/gsd-new-project
Questions → research → requirements → roadmap. You approve it, then you're ready to build.
Already have code? Run
/gsd-map-codebasefirst. It analyzes your stack, architecture, and conventions so/gsd-new-projectasks the right questions.
2. Discuss
/gsd-discuss-phase 1
Your roadmap has a sentence per phase. That's not enough to build it the way you imagine it. Discuss captures your decisions before anything gets planned: layouts, API shapes, error handling, data structures — whatever gray areas exist for this specific phase.
The output feeds directly into research and planning. Skip it, get reasonable defaults. Use it, get your vision.
3. Plan
/gsd-plan-phase 1
Research → plan → verify, in a loop until the plans pass. Each plan is small enough to execute in a fresh context window.
4. Execute
/gsd-execute-phase 1
Plans run in parallel waves. Each executor gets a fresh 200k-token context. Each task gets its own atomic commit. Walk away, come back to completed work with a clean git history.
Your main context window stays at 30–40%. The work happens in the subagents.
5. Verify
/gsd-verify-work 1
Walk through what was built. Anything broken gets a diagnosed fix plan — ready for immediate re-execution. You don't debug manually; you just run execute again.
6. Repeat → Ship
/gsd-ship 1
/gsd-complete-milestone
/gsd-new-milestone
Loop discuss → plan → execute → verify → ship until the milestone is done. Then archive, tag, and start the next one fresh.
Getting Started
npx @opengsd/get-shit-done-redux@latest
The installer prompts for your runtime (Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, and more) and whether to install globally or locally.
claude --dangerously-skip-permissions
GSD is built for frictionless automation. Skip-permissions is how it's intended to run.
Install only the skills you need with --profile=core (six core-loop skills), --profile=standard (core + phase management), or the default full install. Profiles compose: --profile=core,audit. --minimal is an alias for --profile=core. See docs/USER-GUIDE.md for the full walkthrough, non-interactive install flags for all 15 runtimes, and permissions configuration. See ADR-0011 for the profile model and runtime surface control.
Current release highlights are in docs/RELEASE-v1.42.1.md: package legitimacy checks, safer installer migrations, runtime surface control, custom ship PR sections, reviewer defaults, fallow structural review, and quota-aware execution recovery.
Cross-runtime compatibility: installer required
The agents/ and commands/ directories in this repository are Claude Code-format source files. The installer (npx @opengsd/get-shit-done-redux@latest) transforms them per target runtime — stripping or converting frontmatter fields that Claude Code uses but other runtimes reject. For example, OpenCode requires color as a hex or semantic value from a fixed set, and does not accept a tools: frontmatter field; the installer function convertClaudeToOpencodeFrontmatter (bin/install.js) handles this automatically.
Manually copying files from agents/ or commands/ directly into a non-Claude-Code runtime config directory (e.g., ~/.config/opencode/agents) skips the conversion step and will produce schema validation errors in that runtime.
If you are on a system without Node.js or npm (Windows + OpenCode is the most common case), see docs/USER-GUIDE.md — Manual install / no-Node.js setup for the per-runtime conversion summary and alternative install paths.
Commands
The main loop:
| Command | What it does |
|---|---|
/gsd-new-project |
Questions → research → requirements → roadmap |
/gsd-discuss-phase [N] |
Capture implementation decisions before planning |
/gsd-plan-phase [N] |
Research + plan + verify |
/gsd-execute-phase <N> |
Execute plans in parallel waves |
/gsd-verify-work [N] |
Manual acceptance testing |
/gsd-ship [N] |
Create PR from verified phase work |
/gsd-progress --next |
Auto-detect and run the next step |
/gsd-complete-milestone |
Archive milestone and tag release |
/gsd-new-milestone |
Start next version |
/gsd:surface |
Enable/disable skill clusters at runtime without reinstall |
For ad-hoc tasks, autonomous mode, codebase analysis, forensics, and the full command surface — see docs/COMMANDS.md.
Why It Works
Three things most AI-coding setups get wrong:
1. Context bloat. As a session grows, quality degrades. GSD keeps your main context clean by doing the heavy work in fresh subagent contexts. Researchers, planners, and executors each start fresh with exactly what they need.
2. No shared memory. GSD maintains structured artifacts that survive session boundaries: PROJECT.md (vision), REQUIREMENTS.md (scope), ROADMAP.md (where you're going), STATE.md (current position and decisions), CONTEXT.md (per-phase implementation decisions). Every new session loads these and knows exactly where things stand.
3. No verification. Code that "runs" isn't code that "works." GSD's verify step walks you through what was built, diagnoses failures with dedicated debug agents, and generates fix plans before you declare a phase done.
See docs/ARCHITECTURE.md for how the multi-agent orchestration and context engineering work in detail.
Configuration
Settings live in .planning/config.json. Configure during /gsd-new-project or update with /gsd-settings.
Key dials:
| Setting | What it controls |
|---|---|
mode |
interactive (confirm each step) or yolo (auto-approve) |
| Model profiles | quality / balanced / budget — controls which model each agent uses |
workflow.research / plan_check / verifier |
Toggle the quality agents that add tokens and time |
parallelization.enabled |
Run independent plans simultaneously |
Optional structural review: set code_quality.fallow.enabled to true to add a fallow pre-pass to /gsd-code-review. GSD writes .planning/phases/<phase>/FALLOW.json and surfaces a Structural Findings (fallow) section in REVIEW.md. Install with npm install -D fallow@^2.70.0 (or system-wide via cargo install fallow; note that the Rust binary's JSON schema must match the documented v2.70+ contract — older versions may produce silent zero-finding output).
Package legitimacy checks are built into the research, planning, and execution path: recommended dependencies get audited, unverified packages require a human checkpoint, and failed installs stop instead of trying similarly named alternatives.
For the full configuration reference — all settings, git branching strategies, per-runtime model overrides, workstream config inheritance, agent skills injection — see docs/CONFIGURATION.md.
Documentation
| Doc | What's in it |
|---|---|
| User Guide | End-to-end walkthrough, install options, all runtime flags, configuration reference |
| Commands | Every command with flags and examples |
| Configuration | Full config schema, model profiles, git branching |
| Architecture | How the multi-agent orchestration works |
| CLI Tools | gsd-sdk query and programmatic SDK dispatch seams |
| Features | Complete feature index |
| Changelog | What changed in each release |
Troubleshooting
Commands not showing up? Restart your runtime after install. GSD installs to ~/.claude/skills/gsd-*/ (Claude Code), ~/.codex/skills/gsd-*/ (Codex), or the equivalent for your runtime.
Codex users — minimum supported CLI version is 0.130.0. Codex CLI 0.130.0 (release notes) removed extra-skill-roots discovery via openai/codex#21485; from that version onward Codex discovers skills from standard roots (including ~/.codex/skills/<name>/SKILL.md). GSD installs there directly. Earlier Codex CLI versions may still discover additional roots, which can surface duplicate gsd-* entries (one from extra-roots discovery, one from ~/.codex/skills/); restart Codex after install and either upgrade or accept the duplicate listing.
Something broken? Re-run the installer — it's idempotent:
npx @opengsd/get-shit-done-redux@latest
Containers or Docker? Set CLAUDE_CONFIG_DIR before installing to avoid tilde-expansion issues:
CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @opengsd/get-shit-done-redux --global
Full troubleshooting and uninstall instructions in docs/USER-GUIDE.md.
Community
| Project | Platform |
|---|---|
| gsd-opencode | Original OpenCode port |
| Discord | Community support |
Star History
License
MIT License. See LICENSE for details.
Claude Code is powerful. GSD makes it reliable.