GSD Core can keep a complex software milestone's requirements, phase decisions and execution records in a project's .planning/ directory. That structure is useful only if the person responsible for the release checks the generated plans against the real repository and tests the result. This guide uses the current @opengsd/gsd-core 1.18.0 commands for Claude Code. It covers first setup in an existing codebase, continuation of an unfinished milestone, and the next milestone after a completed one. BIG CHANGE reviewed the pinned documentation and package metadata; we did not install the package or run a reader's project.
The big change
- What changed: The archived Get Shit Done repository points to GSD Core as its active successor. The current package has its own version line and requires Node.js 24 or newer and npm 10 or newer.
- Why it matters: A milestone can carry numbered requirements through phase context, plans, execution summaries, verification and human acceptance across fresh Claude Code sessions, giving the owner concrete records to inspect.
- What to watch: Generated PASS reports do not establish that your actual software works. Check project tests and user acceptance yourself, and keep pushing, PR creation and milestone completion behind separate owner decisions.
Prepare the repository and the installer
Use a repository you own or are authorized to change. Record its URL, starting commit, working branch or worktree, active jobs, and the existing .claude/ and .planning/ contents. Write down the milestone goal, real users, constraints, numbered acceptance requirements, the person who approves scope, the project's build and test commands, and a budget for Claude Code and model use. Preserve or commit existing work before installation. If an executor or external job is still running, settle its state before changing the installation or resetting context.
The npm package and v1.18.0 release, checked October 25, 2026, identify @opengsd/gsd-core@1.18.0, tag commit 35f5a452239b897b8d6352c973e1e4efd683370f, and package engines of Node.js >=24.0.0 and npm >=10.0.0. Check both executables on the PATH in the terminal you will use:
node --version
npm --versionStop if either version is below its minimum. Some older tutorial prose lists an earlier Node minimum; the pinned package engines govern this install. The predecessor get-shit-done-cc@1.42.3 is an archived, separate package line, so its larger version number does not make it the current release. Check the package identity before running this project-local installation from the authorized repository:
npx @opengsd/gsd-core@1.18.0 --claude --local --profile=full --relative-includes --no-legacy-cleanupThe pinned installer targets the project's .claude/ with --local. The full profile supplies the phase and milestone commands; relative includes keep local workflow references with the checkout. Inspect the install report and compare the actual before and after state. The installer may write GSD-managed commands, agents, skills, runtime files, hooks, settings merges, manifests and backups in the project, while npx uses the user's npm cache. Its usual legacy cleanup can scan user configuration and cache, so this command explicitly skips that cleanup. It does not migrate an old installation. If a global predecessor command shadows the local one, inspect the warning and /gsd-health rather than deleting global files. Resolve any predecessor .planning/ state through an approved transition before starting new work over it.
Restart Claude Code and inspect the available /gsd-* commands and effective permissions. Keep GSD's interactive approval and Claude Code's normal permission checks. When GSD has created .planning/config.json, inspect its actual values and use this command for changes:
/gsd-settingsThe current configuration reference describes mode: interactive, workflow.auto_advance: false, workflow.skip_discuss: false, workflow research and verification controls, and the current gates.execute_next_plan, gates.confirm_transition and gates.confirm_milestone_scope keys. A missing or malformed config can fall back to defaults with a warning; confirm the effective settings before execution. This owner-reviewed route does not use automatic advance, skipped verification or bypassed permission gates.
Enter at the state your project actually has
For an existing codebase without an initialized GSD Core project, start with:
/gsd-onboardThe onboarding tutorial routes codebase mapping, possible existing specification intake and project setup. If it asks for mapping, run:
/gsd-map-codebaseInspect the resulting .planning/codebase/ descriptions against the actual architecture, conventions, tests and concerns, then rerun /gsd-onboard. Follow its project-setup handoff with:
/gsd-new-projectReview the generated PROJECT.md, numbered REQUIREMENTS.md, ROADMAP.md, STATE.md and configuration, and approve the milestone scope and phase breakdown only when they fit the real change. Rerun onboarding to check its summary. A genuinely empty new repository may start with /gsd-new-project directly.
For an unfinished GSD Core milestone, inspect those project records, phase files, Git commits, current worktree and any .planning/HANDOFF.json. In a new session run:
/gsd-resume-workCompare its proposed next action with the repository and any live jobs. Continue the unfinished milestone; do not initialize another project to clear an uncertain status. If the owner's goal has changed, revise requirements and phases through a reviewed project flow.
For a new milestone after the prior one is complete, use:
/gsd-new-milestoneCheck that the previous state really is complete, then review the new goal, requirement IDs, roadmap and approvals. Hold if the previous milestone or repository state conflicts with that route. These are different entry points into the same requirement trail, not interchangeable reset commands.
Our Superpowers guide for one bounded code change covers a smaller task in Claude Code. The process here follows one approved software milestone through multiple GSD Core phases and a final acceptance decision.
Trace requirements through each phase
Before the first phase, make a compact matrix from your actual requirement IDs. Give each row its approved roadmap phase, a decision to settle in phase context, the planned check, and a place to record implementation commit, observed test result, GSD verification, user acceptance and owner disposition. This matrix is your audit aid; GSD does not promise to generate it. Leave cells blank until evidence exists. A requirement that has no check or approver needs work before execution.
Requirement ID | Phase and | | Commit and observed project test | | Owner disposition |
|---|---|---|---|---|---|
Copy an actual ID from | Fill from the approved roadmap and phase context | Add the exact plan and expected check | Record a real commit, command and result | Record the observed status or blocker | Record approval, gap or hold |
For each approved roadmap phase, replace N with its actual number. Run each command at its step, stopping at the review and permission checkpoints:
- Run the discussion command:
/gsd-discuss-phase N Answer the actual interface, integration, data, security, error-handling and acceptance questions. Read the phase CONTEXT.md and discussion record. Correct invented repository details and resolve decisions that require the owner before moving on.
- Run the planning command:
/gsd-plan-phase N Read its RESEARCH.md, numbered PLAN.md files, coverage or validation material and plan-check result. Put each original requirement ID beside a plan and a concrete check. Confirm dependencies, files, permissions, irreversible choices and your project's real build/test commands. Replan missing coverage rather than accepting a generated green status.
- After plan and permission approval, run the execution command:
/gsd-execute-phase N The phase-loop documentation describes fresh executor contexts and dependency-aware work. Inspect the diffs, commits, each plan's SUMMARY.md and phase VERIFICATION.md. Run the project's actual tests and build yourself, record commands and observed outputs, and review changed behavior. A generated PASS is a report to check, not user acceptance.
- Run the verification command for human user acceptance:
/gsd-verify-work N Compare the actual result against each requirement and inspect the persistent UAT.md. If UAT finds a defect, inspect the diagnosis and reviewed gap plans, then use the gap-only command for that bounded fix:
/gsd-execute-phase N --gaps-onlyRecheck the diff, rerun relevant real tests and repeat /gsd-verify-work N. Mark inaccessible or untested requirements blocked rather than complete.
The verify and ship guide has a separate command that pushes a branch and creates a PR:
/gsd-ship NUse it only after the owner authorizes that external action and you verify the remote and gh account. A milestone can reach local acceptance with ship held. Repeat the phase sequence for every approved phase, then check all original requirement IDs with:
/gsd-audit-milestoneCompletion or tagging is a further reviewed owner decision, using:
/gsd-complete-milestoneDo not convert a tool's completion label into release authority.
Pause and recover without losing the trail
At a safe phase or plan boundary, check that no executor or outside job is live. Run:
/gsd-pause-workThe pause workflow writes .planning/HANDOFF.json, a context-specific .continue-here.md, and a handoff commit. Inspect those files alongside STATE.md, phase artifacts, git status, commits and job manifests. Only then use Claude Code /clear or close the session. In the next context, run /gsd-resume-work; reconcile its restored action with the saved handoff and completed work. The handoff is consumed after successful resumption. Do not replay an already finished plan or resubmit a job simply because its summary is delayed.
For partial initialization, follow the documented recovery path from the state that exists. For established but inconsistent state, inspect:
/gsd-healthApprove a repair only after reading that diagnosis. The repair command is:
/gsd-health --repairReview the proposed diff and preserve prior evidence. Stop on permission denial, unexpected installer changes, source mismatch, ambiguous phase state or the usage budget. A repair or rollback still needs a checked diff and renewed acceptance; editing a status file to say PASS does not repair the software.
GSD Core's package is MIT licensed without a separate package fee. npm access and Claude Code/model use remain separate; mapping, planning and execution can use multiple agent turns. The exact cost, compatibility and outcome depend on the reader's account and project. This guide reports documented commands and inspectable checkpoints, not a measured speed or quality gain.
