Setup Project - Interactive Configuration

Initialize any project directory for Claude Code with intelligent analysis and RALPH support.

Triggers

• /setup-project - Start interactive setup
• "set up this project for Claude"
• "initialize project"
• "configure RALPH"

Process

Step 1: Detect Project State

First, check if this is a new or existing project by looking for common project indicators:

# Check for project files
ls -la 2>/dev/null | head -20

# Check for package managers
ls package.json requirements.txt go.mod Cargo.toml pyproject.toml 2>/dev/null

Indicators of existing project:

• package.json - Node.js/JavaScript project
• requirements.txt or pyproject.toml - Python project
• go.mod - Go project
• Cargo.toml - Rust project
• README.md with content
• src/, lib/, or app/ directories

Step 2: Gather Information with AskUserQuestion

CRITICAL: Always use AskUserQuestion to gather project information.

For New/Empty Directory

Ask these 6-7 questions:

1. Project Type

   Copy

   ? What type of project is this?
     ○ Web application (frontend)
     ○ REST API / Backend service
     ○ Full-stack application
     ○ CLI tool
     ○ Library / Package
   

2. Primary Language

   Copy

   ? What language will you use?
     ○ TypeScript (Recommended)
     ○ JavaScript
     ○ Python
     ○ Go
     ○ Rust
   

3. Framework

   Copy

   ? Framework?
     ○ None
     ○ React
     ○ Next.js
     ○ Express
     ○ FastAPI
     ○ Django
   

4. Test Framework

   Copy

   ? Test framework?
     ○ Vitest (Recommended for TS/JS)
     ○ Jest
     ○ Pytest
     ○ Go test
     ○ None / Decide later
   

5. Linting and Formatting

   Copy

   ? Linting and formatting?
     ○ ESLint + Prettier (Recommended)
     ○ ESLint only
     ○ Biome
     ○ Ruff (Python)
     ○ None
   

6. Git Initialization

   Copy

   ? Initialize git repository?
     ○ Yes (Recommended)
     ○ No
   

7. First Feature (free text)

   Copy

   ? Describe the first feature to build (or leave empty to skip PRD):
   > [user input]
   

For Existing Project

Ask these questions after detection:

1. Confirm Detection

   Copy

   ? I detected a [TypeScript/JavaScript/Python/Go] project using [framework]. Is this correct?
     ○ Yes, that's correct
     ○ No, let me specify
   

2. Analyze Codebase

   Copy

   ? Should I analyze the codebase for patterns and conventions?
     ○ Yes, analyze existing code (Recommended)
     ○ No, I'll provide the details
   

3. Test Framework (if not auto-detected)

   Copy

   ? Test framework?
     ○ [Auto-detected option]
     ○ Other options...
   

4. Lint/Format Tools (if not auto-detected)

   Copy

   ? Linting and formatting?
     ○ [Auto-detected option]
     ○ Other options...
   

5. Rules and Boundaries

   Copy

   ? Any directories that should NEVER be modified?
     ○ None
     ○ Let me specify: [user input]
   

6. Next Feature (free text)

   Copy

   ? What feature would you like to build next (or leave empty to skip PRD):
   > [user input]
   

Step 3: Create Configuration Files

Based on the answers, create these files:

1. PROJECT_SPEC.md

# Project Specification: {{projectName}}

Generated: {{date}}
Type: {{projectType}}

## Overview

{{description}}

## Tech Stack

| Component | Value |
|-----------|-------|
| Language | {{language}} |
| Framework | {{framework}} |
| Test Framework | {{testFramework}} |
| Linter | {{linter}} |

## Quality Commands

| Command | Purpose |
|---------|---------|
| `{{testCommand}}` | Run tests |
| `{{lintCommand}}` | Run linter |
| `{{typecheckCommand}}` | Type checking |
| `{{buildCommand}}` | Build project |

## Patterns to Follow

- {{namingConvention}}
- {{moduleSystem}}
- {{importOrder}}

## Boundaries

These files/directories should NOT be modified by RALPH:
{{#each boundaries}}
- `{{this}}`
{{/each}}

---

*Generated by /setup-project*

2. .ralph/config.yaml

# RALPH Configuration
# Generated by /setup-project

# Rules - AI MUST follow these
rules:
  - "Follow patterns in PROJECT_SPEC.md"
  - "Write tests for new functionality"
  - "Keep code DRY - don't repeat patterns"

# Boundaries - Files/directories to never modify
boundaries:
  never_touch:
    - "*.lock"
    - "node_modules/**"
    - ".git/**"
{{#each customBoundaries}}
    - "{{this}}"
{{/each}}

# Quality gate commands
commands:
  test: "{{testCommand}}"
  lint: "{{lintCommand}}"
  typecheck: "{{typecheckCommand}}"
  build: "{{buildCommand}}"

# Settings
settings:
  max_retries: 3
  auto_commit: true

3. .ralph/progress.txt

# RALPH Progress Log

Started: {{date}}
Project: {{projectName}}
Type: {{projectType}}

## Discovered Patterns
(Patterns will be logged here as they are discovered during iterations)

## Learnings
(Key learnings from each task will be recorded here)

---

4. .claude/settings.json (Yolo Mode)

Create project-level Claude Code settings with bypass permissions:

{
  "permissions": {
    "allow": [
      "Bash",
      "Read",
      "Write",
      "Edit",
      "mcp__*"
    ],
    "deny": [],
    "defaultMode": "bypassPermissions"
  }
}

This enables "yolo mode" - no permission prompts during development for this project.

5. prd.json (if feature provided)

Generate intelligent user stories based on:

• The feature description
• The tech stack
• The framework patterns

Example for "User authentication":

{
  "project": "User Authentication",
  "branchName": "ralph/user-authentication",
  "description": "Implement user authentication with email/password",
  "userStories": [
    {
      "id": "US-001",
      "title": "Create User model and types",
      "description": "Define data structures for User",
      "acceptanceCriteria": [
        "User type/interface defined",
        "Types exported properly",
        "Type checking passes"
      ],
      "priority": 1,
      "passes": false
    },
    // ... more stories based on tech stack
  ]
}

Step 4: Display Summary

After creating files, show a summary:

╔════════════════════════════════════════════════════════════════╗
║                    Setup Complete!                              ║
╚════════════════════════════════════════════════════════════════╝

Created:
  ✓ PROJECT_SPEC.md - Project specification
  ✓ .ralph/config.yaml - RALPH configuration
  ✓ .ralph/progress.txt - Progress log
  ✓ .claude/settings.json - Yolo mode enabled (no permission prompts)
{{#if hasPrd}}
  ✓ prd.json - {{storyCount}} user stories for "{{feature}}"
{{/if}}

Project: {{projectName}}
Type: {{projectType}}
Language: {{language}}
Framework: {{framework}}

Next Steps:
  1. Review PROJECT_SPEC.md and adjust if needed
{{#if hasPrd}}
  2. Review prd.json and customize acceptance criteria
  3. Run /ralph-run to start autonomous development
{{else}}
  2. Run /prd [feature description] to create a PRD
  3. Run /ralph-run to start autonomous development
{{/if}}

Important Guidelines

1. ALWAYS use AskUserQuestion - Never assume project details
2. Analyze before writing - For existing projects, read code first
3. Match existing patterns - PRD stories should follow project conventions
4. Be specific in acceptance criteria - Include actual commands, paths, patterns
5. Respect user choices - If they say "None", don't add defaults

Example Interaction

User: /setup-project

Claude: Let me check if this is a new or existing project...

I see this is an empty directory. Let me ask some questions to set up your project.

[AskUserQuestion: Project type, Language, Framework, etc.]

Based on your answers, I'll create the configuration files...

[Creates PROJECT_SPEC.md, .ralph/config.yaml, .ralph/progress.txt]

Setup complete! Here's what I created:

• PROJECT_SPEC.md with your project specification
• .ralph/config.yaml with quality commands
• .ralph/progress.txt for tracking progress

Since you want to build "User authentication", I also created prd.json with 6 user stories.

Run /ralph-run when you're ready to start autonomous development!