Markdown edition

# Take a software milestone through GSD Core phases and acceptance

> Use current GSD Core commands to carry an owned software milestone from requirements and phase plans through fresh-context execution, handoff, project tests and human acceptance.

By BIGCHANGE.AI Editorial

Published: 2026-10-25T14:44:39.092Z
Updated: 2026-10-25T14:44:39.092Z
Canonical: https://bigchange.ai/blog/gsd-core-software-milestone-phases-acceptance-guide

![Conceptual charcoal illustration of a developer viewing a generic project file tree on a laptop at a worktable.](https://bigchange.ai/api/media/file/gsd-core-milestone-review-hero-v3.png)
AI-generated conceptual illustration by BIG CHANGE.

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](https://github.com/open-gsd/gsd-core/releases/tag/v1.18.0); we did not install the package or run a reader's project.

## The big change

- **What changed:** The [archived Get Shit Done repository](https://github.com/gsd-build/get-shit-done) 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](https://registry.npmjs.org/@opengsd/gsd-core/latest) and [v1.18.0 release](https://github.com/open-gsd/gsd-core/releases/tag/v1.18.0), 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:

```sh
node --version
npm --version
```

Stop 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:

```sh
npx @opengsd/gsd-core@1.18.0 --claude --local --profile=full --relative-includes --no-legacy-cleanup
```

The [pinned installer](https://github.com/open-gsd/gsd-core/blob/v1.18.0/bin/install.js) 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:

```text
/gsd-settings
```

The [current configuration reference](https://github.com/open-gsd/gsd-core/blob/v1.18.0/docs/CONFIGURATION.md) 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:

```text
/gsd-onboard
```

The [onboarding tutorial](https://github.com/open-gsd/gsd-core/blob/v1.18.0/docs/tutorials/onboarding-an-existing-codebase.md) routes codebase mapping, possible existing specification intake and project setup. If it asks for mapping, run:

```text
/gsd-map-codebase
```

Inspect the resulting `.planning/codebase/` descriptions against the actual architecture, conventions, tests and concerns, then rerun `/gsd-onboard`. Follow its project-setup handoff with:

```text
/gsd-new-project
```

Review 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:

```text
/gsd-resume-work
```

Compare 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:

```text
/gsd-new-milestone
```

Check 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](https://bigchange.ai/blog/superpowers-claude-code-plan-test-review-change-guide) 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 `CONTEXT.md` decision | `PLAN.md` check | Commit and observed project test | `VERIFICATION.md` and `UAT.md` | Owner disposition |
| --- | --- | --- | --- | --- | --- |
| Copy an actual ID from `REQUIREMENTS.md` | 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:

1. Run the discussion command:

```text
   /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.

2. Run the planning command:

```text
   /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.

3. After plan and permission approval, run the execution command:

```text
   /gsd-execute-phase N
```

   The [phase-loop documentation](https://github.com/open-gsd/gsd-core/blob/v1.18.0/docs/explanation/the-phase-loop.md) 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.

4. Run the verification command for human user acceptance:

```text
   /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:

```text
/gsd-execute-phase N --gaps-only
```

Recheck 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](https://github.com/open-gsd/gsd-core/blob/v1.18.0/docs/how-to/verify-and-ship.md) has a separate command that pushes a branch and creates a PR:

```text
/gsd-ship N
```

Use 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:

```text
/gsd-audit-milestone
```

Completion or tagging is a further reviewed owner decision, using:

```text
/gsd-complete-milestone
```

Do 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:

```text
/gsd-pause-work
```

The [pause workflow](https://github.com/open-gsd/gsd-core/blob/v1.18.0/gsd-core/workflows/pause-work.md) 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](https://github.com/open-gsd/gsd-core/blob/v1.18.0/docs/how-to/recover-and-troubleshoot.md) from the state that exists. For established but inconsistent state, inspect:

```text
/gsd-health
```

Approve a repair only after reading that diagnosis. The repair command is:

```text
/gsd-health --repair
```

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

## Sources

- [Archived Get Shit Done maintainer repository](https://github.com/gsd-build/get-shit-done) — The maintainer notice directs current development to GSD Core. The archived predecessor package remains a separate historical version line.
- [GSD Core v1.18.0 release](https://github.com/open-gsd/gsd-core/releases/tag/v1.18.0) — Establishes the pinned release dated October 19, 2026; the package and installer sources supply executable requirements. Checked October 25, 2026.
- [GSD Core npm package metadata](https://registry.npmjs.org/@opengsd/gsd-core/latest) — Confirms package version, Node.js and npm engines and artifact identity at check time. Readers must verify the current registry and their PATH before installation.
- [GSD Core v1.18.0 installer](https://github.com/open-gsd/gsd-core/blob/v1.18.0/bin/install.js) — Documents the pinned Claude/local/full/relative-includes/no-legacy-cleanup flags, project writes and legacy cleanup boundary. No installation was run for this guide.
- [Onboarding an existing codebase](https://github.com/open-gsd/gsd-core/blob/v1.18.0/docs/tutorials/onboarding-an-existing-codebase.md) — Shows brownfield onboarding, mapping and project setup handoffs; check the generated descriptions against the actual repository.
- [GSD Core configuration](https://github.com/open-gsd/gsd-core/blob/v1.18.0/docs/CONFIGURATION.md) — Documents current interactive workflow and gate keys; verify effective local settings and Claude permissions.
- [GSD Core phase loop](https://github.com/open-gsd/gsd-core/blob/v1.18.0/docs/explanation/the-phase-loop.md) — Explains phase discussion, plans and fresh-context execution; generated records still need real project checks.
- [GSD Core planning artifacts](https://github.com/open-gsd/gsd-core/blob/v1.18.0/docs/reference/planning-artifacts.md) — Explains project and phase records used in the requirement trail; the article's blank matrix is an editorial aid, not a framework output.
- [Verify and ship](https://github.com/open-gsd/gsd-core/blob/v1.18.0/docs/how-to/verify-and-ship.md) — Documents UAT, gap recovery and separate branch/PR ship action; this guide does not claim a completed project.
- [Pause-work workflow](https://github.com/open-gsd/gsd-core/blob/v1.18.0/gsd-core/workflows/pause-work.md) — Documents HANDOFF.json and context-specific continuation record; check live jobs and commits before context reset.
- [Recovery and troubleshooting](https://github.com/open-gsd/gsd-core/blob/v1.18.0/docs/how-to/recover-and-troubleshoot.md) — Documents health diagnosis and repair route; inspect actual state before any authorized repair.