get-shit-done/commands/gsd/new-project.md

name, description, allowed-tools

name	description	allowed-tools
gsd:new-project	Initialize a new project with deep context gathering and PROJECT.md	Read Bash Write AskUserQuestion

Initialize a new project through comprehensive context gathering.

This is the most leveraged moment in any project. Deep questioning here means better plans, better execution, better outcomes. The quality of PROJECT.md determines the quality of everything downstream.

Creates .planning/ with PROJECT.md and config.json.

<execution_context>

@/.claude/get-shit-done/references/principles.md @/.claude/get-shit-done/references/questioning.md @/.claude/get-shit-done/templates/project.md @/.claude/get-shit-done/templates/config.json

</execution_context>

MANDATORY FIRST STEP — Execute these checks before ANY user interaction:

1. Abort if project exists:

   [ -f .planning/PROJECT.md ] && echo "ERROR: Project already initialized. Use /gsd:progress" && exit 1
   

2. Initialize git repo in THIS directory (required even if inside a parent repo):

   # Check if THIS directory is already a git repo root (handles .git file for worktrees too)
   if [ -d .git ] || [ -f .git ]; then
       echo "Git repo exists in current directory"
   else
       git init
       echo "Initialized new git repo"
   fi
   

3. Detect existing code (brownfield detection):

   # Check for existing code files
   CODE_FILES=$(find . -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.swift" -o -name "*.java" 2>/dev/null | grep -v node_modules | grep -v .git | head -20)
   HAS_PACKAGE=$([ -f package.json ] || [ -f requirements.txt ] || [ -f Cargo.toml ] || [ -f go.mod ] || [ -f Package.swift ] && echo "yes")
   HAS_CODEBASE_MAP=$([ -d .planning/codebase ] && echo "yes")
   

   You MUST run all bash commands above using the Bash tool before proceeding.

If existing code detected and .planning/codebase/ doesn't exist:

Check the results from setup step:

• If CODE_FILES is non-empty OR HAS_PACKAGE is "yes"
• AND HAS_CODEBASE_MAP is NOT "yes"

Use AskUserQuestion:

• header: "Existing Code"
• question: "I detected existing code in this directory. Would you like to map the codebase first?"
• options:
  • "Map codebase first" — Run /gsd:map-codebase to understand existing architecture (Recommended)
  • "Skip mapping" — Proceed with project initialization

If "Map codebase first":

Run `/gsd:map-codebase` first, then return to `/gsd:new-project`

Exit command.

If "Skip mapping": Continue to question step.

If no existing code detected OR codebase already mapped: Continue to question step.

Open the conversation:

Ask inline (freeform, NOT AskUserQuestion):

"What do you want to build?"

Wait for their response. This gives you the context needed to ask intelligent follow-up questions.

Follow the thread:

Based on what they said, ask follow-up questions that dig into their response. Use AskUserQuestion with options that probe what they mentioned — interpretations, clarifications, concrete examples.

Keep following threads. Each answer opens new threads to explore. Ask about:

• What excited them
• What problem sparked this
• What they mean by vague terms
• What it would actually look like
• What's already decided

Consult questioning.md for techniques:

• Challenge vagueness
• Make abstract concrete
• Surface assumptions
• Find edges
• Reveal motivation

Check context (background, not out loud):

As you go, mentally check the context checklist from questioning.md. If gaps remain, weave questions naturally. Don't suddenly switch to checklist mode.

Decision gate:

When you could write a clear PROJECT.md, use AskUserQuestion:

• header: "Ready?"
• question: "I think I understand what you're after. Ready to create PROJECT.md?"
• options:
  • "Create PROJECT.md" — Let's move forward
  • "Keep exploring" — I want to share more / ask me more

If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally.

Loop until "Create PROJECT.md" selected.

Synthesize all context into .planning/PROJECT.md using the template from templates/project.md.

For greenfield projects:

Initialize requirements as hypotheses:

## Requirements

### Validated

(None yet — ship to validate)

### Active

- [ ] [Requirement 1]
- [ ] [Requirement 2]
- [ ] [Requirement 3]

### Out of Scope

- [Exclusion 1] — [why]
- [Exclusion 2] — [why]

All Active requirements are hypotheses until shipped and validated.

For brownfield projects (codebase map exists):

Infer Validated requirements from existing code:

1. Read .planning/codebase/ARCHITECTURE.md and STACK.md
2. Identify what the codebase already does
3. These become the initial Validated set

## Requirements

### Validated

- ✓ [Existing capability 1] — existing
- ✓ [Existing capability 2] — existing
- ✓ [Existing capability 3] — existing

### Active

- [ ] [New requirement 1]
- [ ] [New requirement 2]

### Out of Scope

- [Exclusion 1] — [why]

Key Decisions:

Initialize with any decisions made during questioning:

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| [Choice from questioning] | [Why] | — Pending |

Last updated footer:

---
*Last updated: [date] after initialization*

Do not compress. Capture everything gathered.

Ask workflow mode preference:

Use AskUserQuestion:

• header: "Mode"
• question: "How do you want to work?"
• options:
  • "YOLO" — Auto-approve, just execute (Recommended)
  • "Interactive" — Confirm at each step

Ask planning depth preference:

Use AskUserQuestion:

• header: "Depth"
• question: "How thorough should planning be?"
• options:
  • "Quick" — Ship fast, minimal phases/plans (3-5 phases, 1-3 plans each)
  • "Standard" — Balanced scope and speed (5-8 phases, 3-5 plans each)
  • "Comprehensive" — Thorough coverage, more phases/plans (8-12 phases, 5-10 plans each)

Depth controls compression tolerance, not artificial inflation. All depths use 2-3 tasks per plan. Comprehensive means "don't compress complex work"—it doesn't mean "pad simple work to hit a number."

Ask parallel execution preference:

Use AskUserQuestion:

• header: "Parallelization"
• question: "Enable parallel phase execution?"
• options:
  • "Enabled" — Run independent plans in parallel (Recommended)
  • "Disabled" — Execute plans sequentially

Parallelization spawns multiple agents for independent plans within a phase. Wave-based execution handles dependencies automatically. Can be changed later in config.json.

Create .planning/config.json with chosen mode, depth, and parallelization using templates/config.json structure.

git add .planning/PROJECT.md .planning/config.json
git commit -m "$(cat <<'EOF'
docs: initialize [project-name]

[One-liner from PROJECT.md]

Creates PROJECT.md with requirements and constraints.
EOF
)"

Present completion with next steps (see ~/.claude/get-shit-done/references/continuation-format.md):

Project initialized:

- Project: .planning/PROJECT.md
- Config: .planning/config.json (mode: [chosen mode])
[If .planning/codebase/ exists:] - Codebase: .planning/codebase/ (7 documents)

---

## ▶ Next Up

Choose your path:

**Option A: Research first** (recommended for new domains)
Research the ecosystem before creating roadmap. Discovers standard stacks, expected features, architecture patterns, and common pitfalls.

`/gsd:research-project`

**Option B: Create roadmap directly** (for familiar domains)
Skip research if you know this domain well or have a clear spec.

`/gsd:create-roadmap`

<sub>`/clear` first → fresh context window</sub>

---

• .planning/PROJECT.md
• .planning/config.json

<success_criteria>

• Deep questioning completed (not rushed, threads followed)
• PROJECT.md captures full context with evolutionary structure
• Requirements initialized as hypotheses (greenfield) or with inferred Validated (brownfield)
• Key Decisions table initialized
• config.json has workflow mode, depth, and parallelization
• All committed to git

</success_criteria>