How to use gsd-core: install, run the phase loop and ship

What GSD Core does and who it is for

GSD Core is a light-weight meta-prompting, context engineering and spec-driven development system. It drives AI coding agents through a disciplined phase loop rather than relying on one-off prompts. It is built to work with runtimes including Claude Code, OpenCode, Antigravity CLI, Kimi CLI, Kilo, Codex, Copilot, Cursor and Windsurf.

It fits developers who already use one of these tools, people running multi-step projects who want written plans and verification, and teams onboarding an existing codebase. It is not a good fit if you do not use a supported AI coding runtime, or if you want a simple one-shot code generator with no planning.

Install GSD Core with the npx installer

Node.js is a prerequisite. The README excerpt does not specify a minimum Node.js version. Run the installer from a terminal:

The installer prompts you to choose your runtime and whether to install globally or locally. The README says the installer is required for cross-runtime compatibility, so do not copy files from agents/ or commands/ by hand. If you are on another runtime or do not have Node.js, the project links a separate guide, Install on your runtime.

• Prerequisite: Node.js
• Installer prompts for runtime and install scope (global or local)
• Do not copy files from agents/ or commands/ manually

Start a new project or onboard an existing codebase

After installation, use one of two entry commands depending on your situation. Use the first for a greenfield project and the second for an existing repository.

If you are new, the project's tutorial Your first project walks from install to your first shipped phase. For existing code, the tutorial Onboarding an existing codebase covers brownfield setup.

• /gsd-new-project for a greenfield project
• /gsd-onboard for an existing codebase

Understand the five-step phase loop

Each milestone repeats the same loop, one phase at a time. Knowing the loop tells you what each command is for and where your attention should go.

Discuss captures implementation decisions before anything is planned. Plan researches, decomposes and checks that the plan fits a fresh context window. Execute runs plans in parallel waves, with each executor starting from a clean 200k-token context. Verify walks through what was built and diagnoses and fixes problems before a phase is declared done. Ship creates the PR, archives the phase and moves to the next one.

• Discuss: capture decisions before planning
• Plan: research, decompose, check fit to context window
• Execute: run plans in parallel waves
• Verify: walk through the build, diagnose and fix
• Ship: create the PR, archive the phase, repeat

How GSD Core keeps context and state between sessions

GSD Core runs heavy research and execution in fresh-context subagents so your main session stays lean. This addresses context rot, the quality degradation that builds up as an AI fills its context window.

Information moves between sessions through files such as STATE.md and CONTEXT.md. These structured artifacts are what let work survive session boundaries. For the reasoning behind this design, read the project's context engineering explanation.

• Heavy work runs in fresh subagents
• STATE.md and CONTEXT.md carry information between sessions

Find reference docs and troubleshooting help

The README points to separate documentation for commands, configuration and CLI tools, plus a how-to guide for recovery and troubleshooting. Use the full documentation index to find them. The project also has a Discord server for community support.

• Commands reference (docs/COMMANDS.md)
• Configuration reference (docs/CONFIGURATION.md)
• CLI tools reference (docs/CLI-TOOLS.md)
• Recover and troubleshoot guide (docs/how-to/recover-and-troubleshoot.md)