Skip to main content

​
Overview

The /gsd:new-project command initializes a new GSD project through a unified flow that captures your vision, researches the domain, and creates a structured roadmap. This is your entry point to the Get Shit Done workflow.

​
What It Does

The command guides you through four stages:
  1. Questioning - Deep conversation until the system understands your idea completely
  2. Research (optional) - Parallel agents investigate the domain
  3. Requirements - Extracts what’s v1, v2, and out of scope
  4. Roadmap - Creates phases mapped to requirements

​
Files Created

After running new-project, you’ll have:

PROJECT.md

Core project vision and context - always loaded by agents

config.json

Workflow preferences and model settings

REQUIREMENTS.md

Scoped v1/v2 requirements with phase traceability

ROADMAP.md

Phase structure showing what gets built when

STATE.md

Project memory tracking decisions and position

research/

Domain research from parallel investigation agents

​
Command Usage

/gsd:new-project
The system will:
  • Ask about your project goals and constraints
  • Clarify technical preferences and edge cases
  • Offer optional domain research (recommended)
  • Present requirements for approval
  • Generate roadmap for final approval

​
The Questioning Phase

GSD’s questioning system is designed to extract complete context before any code is written. The conversation continues until the system understands:
  • Goals - What you’re trying to build and why
  • Constraints - Technical requirements, limitations, preferences
  • Tech Stack - Frameworks, libraries, deployment targets
  • Edge Cases - Error scenarios, unusual inputs, boundary conditions
  • User Experience - Key workflows and interactions
The questioning is adaptive - it asks deeper questions about areas that need clarity and skips obvious details.
When you enable research, GSD spawns four parallel agents to investigate:
1

Stack Investigator

Researches your chosen frameworks, libraries, and tools. Finds best practices, common patterns, and known issues.
2

Feature Researcher

Investigates similar products and features. Identifies standard approaches and UI patterns.
3

Architecture Analyst

Examines architectural patterns for your use case. Recommends structure, data flow, and integration points.
4

Pitfall Detector

Identifies common mistakes, gotchas, and anti-patterns to avoid.
Research findings are saved to .planning/research/ and loaded during planning phases.

​
Requirements Extraction

The system analyzes your conversation and generates structured requirements:
  • v1 Requirements - Must-haves for initial release
  • v2 Requirements - Nice-to-haves for future iterations
  • Out of Scope - Explicitly deferred features
Each requirement is:
  • Testable (clear success criteria)
  • Traceable (linked to roadmap phases)
  • Prioritized (v1 vs v2)
Review requirements carefully before approval. These drive all planning and verification.

​
Roadmap Creation

The roadmap breaks your project into phases: 
### Phase 1: Database Schema and Auth
**Goal:** User accounts with secure authentication
**Requirements:** REQ-001, REQ-002, REQ-003

### Phase 2: Core API Endpoints
**Goal:** CRUD operations for main entities
**Requirements:** REQ-004, REQ-005, REQ-006

### Phase 3: Frontend Dashboard
**Goal:** User interface for managing data
**Requirements:** REQ-007, REQ-008, REQ-009
Each phase:
  • Has a clear goal
  • Maps to specific requirements
  • Is small enough to complete in 2-3 hours
  • Builds on previous phases

​
Configuration

During initialization, you’ll configure:

​
Execution Mode

Pauses for confirmation at each stage:
  • Approve requirements before roadmap
  • Approve roadmap before planning
  • Confirm each phase execution

​
Granularity

Controls how work is broken down:
  • Coarse - Fewer, larger phases. Faster but more context per phase.
  • Standard (default) - Balanced approach, 5-10 phases per milestone.
  • Fine - More, smaller phases. Slower but keeps context ultra-fresh.

​
Model Profile

Balance quality vs token spend:
ProfilePlanningExecutionBest For
qualityOpusOpusComplex projects, critical code
balancedOpusSonnetMost projects (default)
budgetSonnetSonnetPrototypes, simple projects

​
Brownfield Projects

Already have code? Run /gsd:map-codebase first before new-project.
The codebase mapper spawns parallel agents to analyze:
  • Stack and frameworks
  • Architecture and patterns
  • Conventions and style
  • Current concerns and tech debt
Then when you run new-project, the questioning focuses on what you’re adding rather than re-discovering what exists.

​
Example Flow

1

Start the command

/gsd:new-project
2

Answer questions

Describe what you’re building. The system asks follow-ups until it has complete context.Example questions:
  • “What problem does this solve?”
  • “Who are the users?”
  • “Any specific tech stack requirements?”
  • “What happens if a user tries X?”
3

Enable research (optional)

Would you like domain research? (yes/no)
Recommended for unfamiliar domains or complex features.
4

Review requirements

The system presents extracted requirements:
## v1 Requirements
- [ ] REQ-001: Users can create accounts with email
- [ ] REQ-002: Users can log in with password
- [ ] REQ-003: Sessions persist across page reloads

## v2 Requirements
- [ ] REQ-004: OAuth login with Google
- [ ] REQ-005: Password reset via email
Approve, request changes, or add missing requirements.
5

Approve roadmap

The system presents the phase breakdown:
### Phase 1: Database and Auth Core
Goal: User accounts with secure authentication
Requirements: REQ-001, REQ-002, REQ-003

### Phase 2: Session Management
Goal: Persistent sessions and security
Requirements: REQ-003, REQ-006
Approve to finalize initialization.
6

Start building

/gsd:discuss-phase 1
Begin the build workflow with phase 1.

​
Next Steps

After new-project completes:

Discuss Phase

Capture implementation preferences before planning

Plan Phase

Research and create detailed execution plans

​
Tips

Be specific in questioning. “E-commerce site” is vague. “Shopify-style store with product variants, cart, and Stripe checkout” is clear.
Use research for new domains. If you’re building something unfamiliar, let the parallel investigators find best practices.
Keep v1 scope tight. You can always add phases or start v2 after shipping. Smaller scope = faster first release.
Don’t skip requirements approval. Once the roadmap is created, changing scope requires manual edits or starting over.