setup

name	setup
description	Interactive project onboarding - creates project-goals.md and project-map.md
allowed-tools	["Read","Write","Glob","Grep","Bash","AskUserQuestion"]

Setup Command - Interactive Project Onboarding

Initialize a project for use with Sprint by creating the two "Second Brain" documents that guide all sprint work.

Overview

This command interactively creates:

1. .claude/project-goals.md - Business vision and objectives (user-maintained)
2. .claude/project-map.md - Technical architecture (architect-maintained)

Workflow

Step 1: Check Existing Files

Check if either file already exists:

test -f .claude/project-goals.md && echo "GOALS_EXISTS" || echo "NO_GOALS"
test -f .claude/project-map.md && echo "MAP_EXISTS" || echo "NO_MAP"

If files exist, ask the user:

• Overwrite existing files?
• Skip existing and create only missing?
• Abort setup?

Step 2: Create .claude Directory

Ensure the directory exists:

mkdir -p .claude

Step 3: Gather Project Goals (Interactive)

Use AskUserQuestion to gather business context:

Question 1: Product Vision

• "What is this project? Describe it in 1-2 sentences."

Question 2: Target Users

• "Who are the target users?"
• Options: "Developers", "End consumers", "Internal team", "Other"

Question 3: Key Features

• "What are the 3-5 most important features or capabilities?"

Question 4: Success Metrics

• "How will you measure success?"
• Options: "User adoption", "Revenue", "Performance metrics", "Other"

Question 5: Constraints

• "Any important constraints or requirements?"
• Examples: compliance, performance, technology restrictions

Step 4: Generate project-goals.md

Write the gathered information to .claude/project-goals.md:

# Project Goals

## Vision
[User's product vision]

## Target Users
[Target audience description]

## Key Features
- [Feature 1]
- [Feature 2]
- [Feature 3]

## Success Metrics
[How success is measured]

## Constraints
[Important constraints and requirements]

---
*This file is maintained by the user. Update it when business objectives change.*

Step 5: Scan Codebase

Analyze the project structure:

# List top-level structure
ls -la

# Find key configuration files
find . -maxdepth 2 -name "package.json" -o -name "pyproject.toml" -o -name "Cargo.toml" -o -name "go.mod" -o -name "*.csproj" 2>/dev/null

# Check for common frameworks
test -f next.config.js -o -f next.config.ts && echo "NEXTJS"
test -f nuxt.config.ts && echo "NUXT"
test -f angular.json && echo "ANGULAR"
test -f vite.config.ts && echo "VITE"
test -d backend -o -f requirements.txt -o -f pyproject.toml && echo "PYTHON"
test -f go.mod && echo "GO"
test -f Cargo.toml && echo "RUST"

Read key files to understand the project:

• README.md (if exists)
• package.json / pyproject.toml / etc.
• Docker configuration
• CI/CD files

Step 6: Gather Technical Context (Interactive)

Ask clarifying questions based on scan results:

Question: Tech Stack Confirmation

• "I detected [frameworks]. Is this correct?"
• Allow corrections

Question: Architecture Style

• Options: "Monolith", "Microservices", "Serverless", "Monorepo", "Other"

Question: Database

• Options: "PostgreSQL", "MySQL", "MongoDB", "SQLite", "None/Other"

Question: Deployment

• Options: "Docker", "Kubernetes", "Serverless", "Traditional hosting", "Not yet decided"

Step 7: Generate project-map.md

Create .claude/project-map.md with discovered and confirmed information:

# Project Map

## Tech Stack

### Backend
- Language: [detected/confirmed]
- Framework: [detected/confirmed]
- Database: [confirmed]

### Frontend
- Framework: [detected/confirmed]
- Styling: [detected]

### Infrastructure
- Deployment: [confirmed]
- CI/CD: [detected]

## Project Structure

[directory tree of main folders]

## Key Components

### [Component 1]
- Location: [path]
- Purpose: [description]

### [Component 2]
- Location: [path]
- Purpose: [description]

## Development Workflow

### Running Locally
[commands to start the project]

### Running Tests
[test commands]

## Current Features
- [Feature 1]
- [Feature 2]

## Known Limitations
- [Any detected issues or TODOs]

---
*This file is maintained by the project-architect agent. Updated during sprints.*

Step 8: Offer First Sprint

Ask the user:

• "Would you like to create your first sprint now?"

If yes, prompt for sprint goal and run /sprint:new logic.

If no, provide next steps:

Setup complete!

Next steps:
1. Review .claude/project-goals.md and adjust as needed
2. Review .claude/project-map.md for accuracy
3. Run /sprint:new to start your first sprint

Error Handling

No Codebase Detected

If the directory appears empty or has no recognizable project structure:

• Ask if this is a new project
• Offer to create a minimal project-map.md for greenfield development
• Suggest running setup again after initial code is written

Permission Issues

If unable to write to .claude/:

• Report the error clearly
• Suggest checking directory permissions

Output

On completion, display:

✓ Created .claude/project-goals.md
✓ Created .claude/project-map.md

Your project is ready for Sprint!
Run /sprint:new to begin.