Ralph PRD Starter

"Set up Ralph Orchestra for YOUR project - custom agents, skills, and configs in minutes."

Quick Start

Invoke this command to start the setup wizard:

/ralph-prd-starter

The wizard will guide you through configuring Ralph Orchestra for your project.

When to Use This Skill

Use

/ralph-prd-starter

• Setting up Ralph Orchestra for a new project
• Adding custom agents to your project
• Reconfiguring existing agents
• Generating initial PRD from feature ideas
• Updating orchestration mode or workflow patterns

Wizard Overview

Three Configuration Modes

┌─────────────────────────────────────────────────────────────┐
│                    WIZARD ENTRY POINTS                      │
├─────────────────────────────────────────────────────────────┤
│  ⚡ Quick Start   (5 min)   → Choose a preset template      │
│  🎯 Standard      (15 min)  → Guided with recommendations   │
│  🔧 Expert        (30+ min) → Full customization            │
└─────────────────────────────────────────────────────────────┘

Quick Start Flow (5 minutes)

1. Select project template (14 presets available)
2. Project name
3. Generate!

Standard Mode Flow (15 minutes)

1. Deep project understanding
2. Agent selection with recommendations
3. Skill/sub-agent confirmation
4. Generate!

Expert Mode Flow (30+ minutes)

1. Everything from Standard Mode
2. Per-agent skill configuration
3. Per-agent sub-agent selection
4. MCP server customization
5. Advanced settings

Phase 1: Entry Point Selection

Question: How would you like to configure Ralph Orchestra?

Flow Decision:

• Quick Start → Go to Phase 2 (Presets)
• Standard/Expert → Go to Phase 3 (Project Deep Dive)

Phase 2: Named Presets (Quick Start)

Question: Select a preset configuration for your project:

🎮 Game Development Presets

🌐 Web Application Presets

🏢 Business & Commerce Presets

🔧 Technical Presets

After Preset Selection:

1. Confirm project name
2. Review preset summary
3. Generate! (or customize further)

Phase 3: Project Deep Dive (Standard/Expert)

3.1 Project Identity

Question: What is your project's name and purpose?

Project Name: _______________

One-Line Summary: _________________________________

[Example: "A multiplayer space exploration game with base building"]

Question: Which category best describes your project?

Question: What is the primary technology stack?

3.2 Project Scope & Scale

Question: What is your team size?

Question: What is the project scale?

Question: What are your critical success factors? (Multi-select)

• Speed to market (fast iteration)
• Code quality (strict standards)
• Visual excellence (polish, effects)
• Multiplayer reliability (server-authoritative)
• Mobile performance (optimization)
• Accessibility (WCAG compliance)
• SEO optimization
• Real-time features
• Data processing (ML, analytics)

Phase 4: Agent Configuration (Standard/Expert)

4.1 Core Agent Selection

Question: Which agents do you need? (Multi-select)

Smart Recommendations:

Based on your project type (Game Development), I recommend:
  ✅ PM, Developer, QA (required)
  ✅ Tech Artist (3D graphics, shaders, effects)
  ✅ Game Designer (GDD, mechanics, balance)

4.2 Per-Agent Skill Configuration (Expert Only)

For each selected agent, ask about skill categories. See Skill Catalog below for complete list.

Developer Agent Skills

dev-r3f-r3f-fundamentals

dev-r3f-r3f-physics

dev-r3f-r3f-materials

dev-multiplayer-server-authoritative

dev-multiplayer-colyseus-server

dev-multiplayer-prediction-basics

dev-multiplayer-colyseus-client

dev-multiplayer-colyseus-state

dev-multiplayer-prediction-movement

dev-multiplayer-prediction-shooting

dev-multiplayer-anti-cheat-validation

dev-typescript-typescript-basics

dev-typescript-typescript-advanced

dev-patterns-*

dev-performance-*

dev-assets-*

dev-research-*

dev-validation-*

Tech Artist Skills

ta-r3f-fundamentals

ta-r3f-r3f-materials

ta-r3f-r3f-performance

ta-r3f-r3f-physics

ta-shader-development

ta-shader-sdf

ta-vfx-particles

ta-vfx-postfx

ta-camera-tps

ta-ui-polish

ta-ui-debug-helpers

ta-assets-*

ta-validation-typescript

ta-networking-visual-feedback

ta-input-validation

QA Skills

qa-browser-testing

qa-code-review

qa-gameplay-testing

qa-multiplayer-testing

qa-reporting-bug-reporting

qa-validation-asset

qa-validation-workflow

qa-visual-testing

qa-workflow

PM Skills

pm-workflow

pm-organization-task-selection

pm-organization-task-research

pm-organization-scale-adaptive

pm-organization-prd-reorganization

pm-improvement-self-improvement

pm-improvement-skill-research

pm-planning-test-planning

pm-retrospective-facilitation

pm-retrospective-playtest-session

pm-validation-architecture

pm-configuration-vite-assets

pm-configuration-asset-coordination

Game Designer Skills

gd-gdd-creation

gd-design-character

gd-design-game-loop

gd-design-level

gd-design-mechanic

gd-design-weapon

gd-assets-impact-analysis

gd-thermite-integration

gd-validation-playtest

4.3 Per-Agent Sub-Agent Configuration (Expert Only)

Developer Sub-Agents

code-research

implementation

validation

commit

Tech Artist Sub-Agents

asset-researcher

asset-creator

shader-compiler

particle-system-designer

visual-validator

visual-tester

performance-profiler

code-quality

QA Sub-Agents

browser-validator

multiplayer-validator

visual-regression-tester

gameplay-tester

code-review

PM Sub-Agents

task-researcher

retrospective-facilitator

skill-researcher

prd-organizer

test-planner

architecture-validator

Game Designer Sub-Agents

asset-analyst

visual-reference-researcher

reference-game-researcher

thermite-facilitator

gdd-documenter

playtest-evidence-collector

Phase 5: Orchestration Configuration (Standard/Expert)

Question: Which orchestration mode matches your needs?

Question: Max iterations before automatic stop?

[ 200 ] ← Default safe limit

Tip: Set higher for large projects, lower for testing

Question: Context reset behavior?

Phase 6: MCP Server Configuration (Expert Only)

Question: Which MCP servers does each agent need?

PM Agent MCP Servers

github

filesystem

web-search

brave-search

Developer Agent MCP Servers

github

filesystem

web-search

brave-search

Tech Artist MCP Servers

playwright

vision

blender

shadertoy

image-process

filesystem

github

QA Agent MCP Servers

playwright

vision

filesystem

github

Game Designer MCP Servers

playwright

vision

filesystem

github

web-search

Phase 7: Quality Standards (Standard/Expert)

Question: What are your quality standards?

Question: Additional quality gates? (Multi-select)

• No

  any

  types (strict enforcement)
• No

  @ts-ignore

  (zero tolerance)
• All feedback loops must pass
• Visual regression testing
• Server-authoritative validation
• Mobile performance checks
• Accessibility auditing
• Security scanning

Phase 8: Initial Features (All Modes)

Question: Describe your initial features in natural language

Example input:
"I need a player character that can move around with WASD, jump with spacebar,
and has a health system. There should be enemies that chase the player and
deal damage on contact. When health reaches zero, respawn at the start."

AI Processing:

• Parse into structured PRD items
• Categorize by type (architectural, feature, bug, chore)
• Assign priority (high/medium/low)
• Suggest acceptance criteria
• Map to appropriate agent

Phase 8b: Deep Research (All Modes)

After collecting initial features, launch the

pm-research-specialist

Research Specialist Invocation

Launch the pm-research-specialist sub-agent:

Task("pm-research-specialist", {
  prompt: """
  Research this project idea deeply:

  Project: {project.name}
  Description: {project.description}
  Category: {project.category}
  Tech Stack: {project.techStack}
  Initial Features: {features}

  Research:
  1. Similar projects and their architectures (use WebSearch, GitHub repo search)
  2. Best practices for this tech stack
  3. Common pitfalls and challenges
  4. Questions we should ask the user (5-10 targeted questions)

  Return structured output with:
  1. Research summary (3-5 key insights)
  2. List of clarifying questions with context and impact
  3. Recommended feature refinements
  4. References to useful resources
  """
})

User Questions Phase

Present research findings and ask clarifying questions:

═══════════════════════════════════════════════════════════════
                    RESEARCH FINDINGS
═══════════════════════════════════════════════════════════════

{research_findings_summary}

Similar Projects Found:
- [{Project 1}]({url}) - {relevance}
- [{Project 2}]({url}) - {relevance}

Best Practices:
- {practice 1} - {reason}
- {practice 2} - {reason}

═══════════════════════════════════════════════════════════════
                    CLARIFYING QUESTIONS
═══════════════════════════════════════════════════════════════

{generated_questions}

Please answer each question to help tailor your project setup.
[You can also request more research or modify questions]

Store answers in state file under

researchData.questionsAnswered

Research Data Storage

Update state file with research results:

{
  "researchData": {
    "similarProjects": [...],
    "bestPractices": [...],
    "commonPitfalls": [...],
    "techStackInsights": {...},
    "questionsAsked": [...],
    "questionsAnswered": [...],
    "recommendedRefinements": [...],
    "references": [...]
  }
}

User Review Gate 1: After Research

User reviews:

• Research findings
• Generated questions
• Can request more research or modify questions

Options: [Continue to Next Phase] [Request More Research] [Modify Questions]

Phase 8c: GDD Creation (Game Projects Only)

Condition: Only runs if

project.category === "game-development"

Thermite Session

Launch thermite facilitator for game design:

Task("gamedesigner-thermite-facilitator", {
  prompt: """
  Run a Thermite Design Session for this game:

  Project: {project.name}
  Description: {project.description}
  Features: {features}
  Research Findings: {researchData}
  User Answers: {researchData.questionsAnswered}

  Session Type: Boardroom Retreat (4 personas)

  Run the session to:
  1. Establish core design pillars
  2. Define key mechanics
  3. Identify design tensions
  4. Create initial design decisions (DEC-NNN format)
  5. Document open questions (OQ-NNN format)

  Output structured GDD data including:
  - Design decisions with rationale
  - Open questions with priority
  - Design pillars
  - Core mechanics
  """
})

GDD Output

Save to

docs/design/

• decision_log.md

  - All design decisions

• open_questions.md

  - Unresolved design questions

• gdd.md

  - Game Design Document summary

GDD Data Storage

Update state file with GDD results:

{
  "gddData": {
    "designDecisions": [
      {
        "id": "DEC-001",
        "title": "Player Movement Model",
        "decision": "Use player-relative WASD controls...",
        "rationale": "Accessibility design pillar requires..."
      }
    ],
    "openQuestions": [...],
    "designPillars": [...],
    "coreMechanics": [...],
    "thermiteSessionType": "boardroom-retreat",
    "participants": [...]
  }
}

User Review Gate 2: After GDD (Games Only)

User reviews:

• Design decisions
• Open questions
• Design pillar compliance
• Can request additional thermite sessions

Options: [Continue to PRD Creation] [Request Additional Thermite Session] [Modify GDD]

Phase 8d: PRD Creation (All Modes)

PM Agent Handoff

CRITICAL: The final PRD.json must be created by a PM agent, not the generator script.

Task("pm-prd-creator", {
  prompt: """
  Create the final prd.json using your PM expertise:

  Project Specification:
  - Name: {project.name}
  - Description: {project.description}
  - Category: {project.category}
  - Tech Stack: {project.techStack}
  - Agents: {configured_agents}

  Research Data:
  {researchData}

  GDD Data (if game project):
  {gddData}

  User Answers:
  {researchData.questionsAnswered}

  Initial Features:
  {features}

  Create prd.json with:
  1. Properly structured PRD items based on research
  2. Acceptance criteria derived from user input + research
  3. Correct agent assignments (considering skills)
  4. Dependency mapping between items
  5. Priority assignment based on user goals
  6. Feedback loops configured for tech stack
  7. Quality standards from Phase 7

  For game projects, include GDD references in PRD item descriptions.

  Write the file to: prd.json
  """
})

PRD Review

Display generated PRD for user review:

═══════════════════════════════════════════════════════════════
                    PRD REVIEW
═══════════════════════════════════════════════════════════════

Project: {project.name}

Summary:
{brief_project_overview}

Items ({count}):
───────────────────────────────────────────────────────────────
| ID    | Title                    | Category | Priority | Agent |
───────────────────────────────────────────────────────────────
{prd_items_table}
───────────────────────────────────────────────────────────────

Agent Assignment:
- Developer: {n} tasks
- Tech Artist: {n} tasks
- QA: {n} tasks
- Game Designer: {n} tasks

Feedback Loops:
{feedback_loops}

Quality Standards:
- TypeScript: {mode}
- Test Coverage: {target}%
- Linting: {tools}

═══════════════════════════════════════════════════════════════

Approve this PRD? [Yes/No/Modify]

User Review Gate 3: After PRD

User reviews:

• Complete prd.json content
• All PRD items
• Agent assignments
• Can request modifications before final approval

Options: [Approve and Continue] [Modify PRD] [Request New Research]

PRD Specification Storage

Update state file with PRD specification:

{
  "prdSpecification": {
    "refinedFeatures": [...],
    "dependencies": [...],
    "priorities": {...},
    "technicalRecommendations": [...]
  }
}

Phase 9: Review and Generate (All Modes)

Summary Display

═══════════════════════════════════════════════════════════════
                    RALPH ORCHESTRA SETUP
═══════════════════════════════════════════════════════════════

📁 PROJECT: My Awesome Game
📋 TYPE: Game Development (React Three Fiber)
👥 TEAM: Solo Developer
🎯 MODE: Sequential (Token-Efficient)

───────────────────────────────────────────────────────────────
AGENTS (5)
───────────────────────────────────────────────────────────────
  ✅ PM          • 12 skills • 6 sub-agents
  ✅ Developer   • 28 skills • 4 sub-agents
  ✅ Tech Artist • 12 skills • 8 sub-agents
  ✅ QA          • 9 skills  • 5 sub-agents
  ✅ Game Designer • 9 skills • 6 sub-agents

───────────────────────────────────────────────────────────────
FEATURES (8)
───────────────────────────────────────────────────────────────
  feat-001  [high]   Player movement system     → Developer
  feat-002  [high]   Player health system       → Developer
  feat-003  [medium] Enemy AI                    → Developer
  feat-004  [medium] Combat system               → Developer
  feat-005  [low]    Respawn mechanic            → Developer
  feat-006  [high]   Visual effects              → Tech Artist
  feat-007  [medium] UI HUD                      → Tech Artist
  feat-008  [low]    GDD documentation           → Game Designer

───────────────────────────────────────────────────────────────
GENERATION
───────────────────────────────────────────────────────────────
  📄 agents/pm/AGENT.md
  📄 agents/developer/AGENT.md
  📄 agents/techartist/AGENT.md
  📄 agents/qa/AGENT.md
  📄 agents/gamedesigner/AGENT.md
  📁 .claude/agents/*.agent.md (31 sub-agents)
  📁 .claude/skills/*/SKILL.md (70 skills)
  ⚙️  .claude/settings.*.json (5 configs)
  📋 prd.json (8 features)

═══════════════════════════════════════════════════════════════

[Generate Setup]  [Back]  [Save Configuration]

Phase 10: Project Initialization (All Modes)

Question: How would you like to handle project dependencies?

If Auto-Initialize or Ask Me Later is selected:

Question: What is your primary runtime environment?

npm init -y

npm install

npm run dev

python -m venv venv

pip install -r requirements.txt

python main.py

cargo init

cargo build

cargo run

go mod init

go mod tidy

go run main.go

mvn archetype:generate

mvn install

mvn spring-boot:run

dotnet new console

dotnet restore

dotnet run

Question: What are your feedback loop commands? (Auto-populated based on runtime)

npm run type-check

mypy --strict .

cargo clippy

npm run lint

ruff check .

golangci-lint run

npm run test

pytest

cargo test

npm run build

python -m build

cargo build

Customization:

• Users can customize any command based on their project setup
• Commands will be written to

  prd.json.feedbackLoops

  for agent use
• Initialization script will be generated as

  .claude/scripts/init-project.sh

  and

  .ps1

Initialization Flow:

1. Wizard collects runtime, package manager, and commands
2. Generator creates

   init-project.sh

   and

   init-project.ps1

   scripts
3. Scripts check for package manager availability
4. Scripts run init, install, and verify commands
5. Coordinator checks

   prd.json.projectInitialization.status

   on startup
6. If "pending", coordinator runs init script before task coordination
7. Status updated to "completed" on success, "failed" on error (with retry)

If Manual Setup selected:

• projectInitialization.status

  set to "skipped"
• Coordinator skips auto-init and proceeds directly to task coordination
• User is responsible for running setup before starting Ralph

Phase 11: Workflow Documentation Generation (All Modes)

After all files are generated, create comprehensive workflow documentation for all agents.

Summary

Generate workflow documentation that describes:

• How each agent operates (startup, decision framework, exit conditions)
• The complete task lifecycle across all agents
• Communication protocols and handoff mechanisms
• File permissions and commit standards

Process

1. Create workflows directory (if not exists):

mkdir -p docs/workflows

2. Launch parallel sub-agents using the Task tool in a single message:

Task("workflow-generator", {
  agent_name: "pm",
  output_file: "pm-coordinator.md",
  source_file: "agents/pm/AGENT.md"
})

Task("workflow-generator", {
  agent_name: "developer",
  output_file: "developer.md",
  source_file: "agents/developer/AGENT.md"
})

Task("workflow-generator", {
  agent_name: "techartist",
  output_file: "techartist.md",
  source_file: "agents/techartist/AGENT.md"
})

Task("workflow-generator", {
  agent_name: "qa",
  output_file: "qa.md",
  source_file: "agents/qa/AGENT.md"
})

Task("workflow-generator", {
  agent_name: "gamedesigner",
  output_file: "gamedesigner.md",
  source_file: "agents/gamedesigner/AGENT.md"
})

Task("devcycle-generator", {
  output_file: "development-cycle.md"
})

3. Wait for all to complete - Each sub-agent reports when done

4. Verify outputs - Check all expected files exist:

ls docs/workflows/
# Expected: pm-coordinator.md, developer.md, techartist.md, qa.md, gamedesigner.md, development-cycle.md

5. Create index file - Generate

docs/workflows/index.md

Success Criteria

• All enabled agent workflow files created

• development-cycle.md

  created
• All files follow template structure (

  docs/workflows/_template.md

  )
• YAML frontmatter present and valid
• ASCII diagrams render correctly
• Index file created with proper cross-references

Output Files Generated

docs/workflows/pm-coordinator.md

docs/workflows/developer.md

docs/workflows/techartist.md

docs/workflows/qa.md

docs/workflows/gamedesigner.md

docs/workflows/development-cycle.md

docs/workflows/index.md

Skip Condition

If the user is in a hurry or wants to generate workflows later, they can choose to skip this phase. Workflows can be generated later by invoking the

shared-workflow-generation

Implementation Steps

1. Initialize State Management

On first invocation, create the state file:

# Read or create state file
$statePath = ".claude/session/prd-starter-state.json"
if (-not (Test-Path $statePath)) {
    $state = @{
        version = "4.0.0"
        startedAt = (Get-Date).ToUniversalTime().ToString("o")
        completedAt = $null
        wizardMode = $null
        currentPhase = "entry_point_selection"
        currentSubPhase = $null
        phases = @{}
        researchData = @{}
        gddData = @{}
        prdSpecification = @{}
    } | ConvertTo-Json -Depth 20
    $state | Out-File -FilePath $statePath -Encoding utf8
}

2. Run Phase Questions

Use

AskUserQuestion

3. Update State File

After each phase completion, update the state with collected data.

4. Load Preset (Quick Start Mode)

For Quick Start mode, load the preset from

.claude/presets/{preset-name}.json

$presetPath = ".claude/presets/$selectedPreset.json"
$preset = Get-Content $presetPath | ConvertFrom-Json
# Merge preset into state configuration

5. Generate Files

After Phase 9 (Review and Confirm), invoke the generator:

Windows:

.\.claude\scripts\prd-starter\prd-starter-generator.ps1 -Action generate -StateFile .claude\session\prd-starter-state.json

Mac/Linux:

python3 .claude/scripts/prd-starter/prd-starter-generator.py --action generate --state .claude/session/prd-starter-state.json

6. Verify Generation

After generation completes, verify:

1. Check all agent directories exist
2. Verify AGENT.md files have correct frontmatter
3. Confirm MCP settings are valid
4. Validate prd.json format
5. Check scripts were updated

State Persistence

The state file persists across invocations:

• Location:

  .claude/session/prd-starter-state.json

• Resumable from any phase
• Tracks wizard mode (quick-start/standard/expert)
• Records preset selection (if Quick Start)
• Stores per-agent skill/sub-agent selections (if Expert)
• Records quality standards and orchestration settings

Output Files

agents/{name}/AGENT.md

.claude/agents/{subagent-name}.agent.md

.claude/skills/{skill-name}/SKILL.md

.claude/settings.{name}.json

prd.json

Architecture Notes:

• Agents: Single

  AGENT.md

  file per agent (no subdirectories)
• Sub-agents: Flat

  .claude/agents/*.agent.md

  with YAML frontmatter
• Skills: Folder-based

  .claude/skills/{name}/SKILL.md

  with naming prefixes (dev-, ta-, qa-, pm-, gd-, shared-)

Anti-Patterns

• Don't skip questions: All phases are required for complete setup
• Don't skip research: Research provides context for better decisions
• Don't hardcode values: Always gather from user or research
• Don't bypass validation: Use schemas before generating files
• Don't forget "Other" option: Allow free-form for every question

Cross-Platform Support

The generator works on all platforms:

• Windows: Use

  .prd-starter-generator.ps1

• Mac/Linux: Use

  .prd-starter-generator.sh

  or call Python directly
• Python 3.8+ required with jinja2, pyyaml, jsonschema

See Also

• shared-ralph-core.md - Core Ralph Orchestra concepts
• shared-worker-protocol.md - Agent lifecycle
• shared-ralph-event-protocol.md - Event-driven messaging

• .claude/schemas/prd-starter-state.schema.json

  - Configuration validation

• .claude/scripts/prd-starter/prd-starter-generator.py

  - Generator implementation

• .claude/presets/

  - Preset configuration files