Skip to main content
GSD Pi’s project bootstrapping flow takes you from a blank directory to a structured plan with milestones, slices, and tasks — all stored in a .gsd/ directory that acts as the living brain of your project. Whether you’re starting something greenfield or formalizing an existing codebase, /gsd new-project is the entry point.

​
Starting a New Project

1

Open a terminal in your project directory

Navigate to the root of the repository (or an empty folder for a greenfield project) and start a GSD session.
cd path/to/your-project
gsd
2

Run the new-project command

Inside the GSD session, run the bootstrapping command. Add --deep to trigger a staged discovery flow that gathers deeper context before planning.
/gsd new-project
Use --deep for complex projects, greenfield builds, or any time you want GSD to ask detailed questions about workflow preferences, requirements, and architecture before planning milestones.
3

Describe your project goals

GSD will prompt you for the information it needs. Be as specific as you like about:
  • What the project does and who it’s for
  • Your preferred tech stack and languages
  • Constraints, non-goals, and anti-patterns to avoid
  • Any existing code GSD should understand before planning
The more context you provide here, the better the generated plan will match your intentions.
4

Review the generated .gsd/ directory

After your conversation, GSD creates the .gsd/ directory with everything it needs to manage the project:
FilePurpose
STATE.mdCurrent project phase and active milestone
DECISIONS.mdArchitectural decisions and rationale
CODEBASE.mdAuto-generated codebase summary
M001-ROADMAP.mdThe first milestone’s slice-by-slice plan
M001-CONTEXT.mdMilestone-level context GSD injects into prompts
In deep mode, you’ll also see:
FilePurpose
PROJECT.mdVision, users, anti-goals, and constraints
REQUIREMENTS.mdCapability contract with R###-numbered requirements
research/STACK.mdStack and tooling research
research/ARCHITECTURE.mdArchitectural patterns and trade-offs
5

Adjust the roadmap if needed

Open M001-ROADMAP.md and review the generated milestones and slices. You can edit this file directly or use /gsd discuss to talk through any changes with GSD before committing to the plan.To reorganize or reorder milestones interactively, run:
/gsd rethink
6

Start autonomous implementation

When you’re happy with the plan, kick off auto mode:
/gsd auto
GSD will research, plan, execute, commit, and repeat — handling the full milestone lifecycle until it finishes or needs your input.

​
Starting a New Milestone on an Existing Project

Once your project is bootstrapped, use /gsd new-milestone to plan the next major chunk of work without losing any existing state. 
/gsd new-milestone
Add --deep to run the staged discovery flow for the new milestone, which is useful when the scope has shifted significantly or you’re entering a new domain. 
/gsd new-milestone --deep
/gsd new-milestone --deep writes planning_depth: deep to .gsd/PREFERENCES.md so that all future milestones on this project also use the deep planning flow by default. You can remove or override this setting at any time.

​
Managing Your Milestone Queue

After creating multiple milestones, use the queue commands to prioritize and reorder work: 
/gsd queue
This opens an interactive view of all pending milestones. You can change their order, park milestones you’re not ready for yet, or discard ones that are no longer relevant.

​
What Happens Under the Hood

When you run /gsd new-project --deep, GSD runs a multi-step discovery sequence before any milestone planning begins:
  1. Workflow preferences — captures how you like to work (test-first, documentation style, commit conventions)
  2. Project context — writes .gsd/PROJECT.md with vision, users, and anti-goals
  3. Requirements — writes .gsd/REQUIREMENTS.md with structured R###-numbered requirements
  4. Research decision — decides whether to do deep technical research or proceed directly to planning
  5. Optional project research — if research is warranted, generates STACK.md, FEATURES.md, ARCHITECTURE.md, and PITFALLS.md under .gsd/research/
  6. Milestone planning — generates the first milestone’s context and roadmap using all the above as input
GSD uses .gsd/ as the single source of truth for project state. The markdown files are human-readable projections you can review, edit, and commit alongside your code.You can commit .gsd/ files to git to share planning artifacts with your team. Set git.commit_docs: false in preferences if you want to keep them local-only.