# Setup Project

> Initialize any project with Claude Code best practices and RALPH autonomous development

- Skill: `majiayu000/setup-project` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/setup-project`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/setup-project/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/setup-project

---


# 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:

```bash
# 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**
   ```
   ? What type of project is this?
     ○ Web application (frontend)
     ○ REST API / Backend service
     ○ Full-stack application
     ○ CLI tool
     ○ Library / Package
   ```

2. **Primary Language**
   ```
   ? What language will you use?
     ○ TypeScript (Recommended)
     ○ JavaScript
     ○ Python
     ○ Go
     ○ Rust
   ```

3. **Framework**
   ```
   ? Framework?
     ○ None
     ○ React
     ○ Next.js
     ○ Express
     ○ FastAPI
     ○ Django
   ```

4. **Test Framework**
   ```
   ? Test framework?
     ○ Vitest (Recommended for TS/JS)
     ○ Jest
     ○ Pytest
     ○ Go test
     ○ None / Decide later
   ```

5. **Linting and Formatting**
   ```
   ? Linting and formatting?
     ○ ESLint + Prettier (Recommended)
     ○ ESLint only
     ○ Biome
     ○ Ruff (Python)
     ○ None
   ```

6. **Git Initialization**
   ```
   ? Initialize git repository?
     ○ Yes (Recommended)
     ○ No
   ```

7. **First Feature** (free text)
   ```
   ? 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**
   ```
   ? I detected a [TypeScript/JavaScript/Python/Go] project using [framework]. Is this correct?
     ○ Yes, that's correct
     ○ No, let me specify
   ```

2. **Analyze Codebase**
   ```
   ? 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)
   ```
   ? Test framework?
     ○ [Auto-detected option]
     ○ Other options...
   ```

4. **Lint/Format Tools** (if not auto-detected)
   ```
   ? Linting and formatting?
     ○ [Auto-detected option]
     ○ Other options...
   ```

5. **Rules and Boundaries**
   ```
   ? Any directories that should NEVER be modified?
     ○ None
     ○ Let me specify: [user input]
   ```

6. **Next Feature** (free text)
   ```
   ? 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

```markdown
# 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

```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

```markdown
# 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:

```json
{
  "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":
```json
{
  "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!