[Feature] Add ralph-init command for existing projects

[paulodearaujo]

Summary

Add a new ralph-init command (or extend ralph-setup) to initialize Ralph in an existing project directory without creating a new folder or running git init.

Problem Statement

Currently, both ralph-setup and ralph-import always create a new project directory:

# ralph-setup always creates new folder
mkdir -p "$PROJECT_NAME"
cd "$PROJECT_NAME"
git init  # Dangerous for existing repos!

# ralph-import does the same
ralph-setup "$project_name"
cd "$project_name"

Users with existing projects have no native way to add Ralph. The current workaround is cumbersome:

# Workaround: create temp project and copy .ralph/ folder
ralph-import my-project/prd.md temp-ralph
cp -r temp-ralph/.ralph my-project/
rm -rf temp-ralph

This is a highly requested feature - see issue #85 with 8+ users asking for this capability.

Proposed CLI Interface

# Initialize Ralph in current directory (no new folder, no git init)
cd my-existing-project
ralph-init

# Initialize with PRD conversion
ralph-init --from prd.md

# Initialize in specific directory
ralph-init --dir /path/to/existing/project

# Force overwrite existing .ralph/ folder
ralph-init --force

Expected Behavior

Command	Creates folder?	Runs git init?	Converts PRD?
ralph-setup project	Yes	Yes	No
ralph-import prd.md project	Yes	Yes	Yes
ralph-init	No	No	No
ralph-init --from prd.md	No	No	Yes

Implementation Approach

1. Create new ralph_init.sh script
2. Add safety checks:
   • Warn if .ralph/ already exists (require --force to overwrite)
   • Detect if directory is a git repo (skip git init)
   • Verify templates directory exists
3. Create only .ralph/ structure without touching project root
4. Optionally run PRD conversion with --from flag
5. Add ralph-init to install.sh for global availability
6. Update documentation

Proposed Implementation

#!/bin/bash
# ralph_init.sh - Initialize Ralph in existing project

set -e

TARGET_DIR="${1:-.}"
PRD_FILE=""
FORCE=false

# Parse arguments
while [[ $# -gt 0 ]]; do
    case $1 in
        --from) PRD_FILE="$2"; shift 2 ;;
        --dir) TARGET_DIR="$2"; shift 2 ;;
        --force) FORCE=true; shift ;;
        *) shift ;;
    esac
done

cd "$TARGET_DIR"

# Safety check
if [[ -d ".ralph" && "$FORCE" != "true" ]]; then
    echo "Error: .ralph/ already exists. Use --force to overwrite."
    exit 1
fi

# Create .ralph structure (no git init!)
mkdir -p .ralph/{specs/stdlib,examples,logs,docs/generated}

# Copy templates
cp "$TEMPLATES_DIR/PROMPT.md" .ralph/
cp "$TEMPLATES_DIR/fix_plan.md" .ralph/@fix_plan.md
cp "$TEMPLATES_DIR/AGENT.md" .ralph/@AGENT.md

# Optional PRD conversion
if [[ -n "$PRD_FILE" ]]; then
    # Run conversion logic from ralph_import.sh
    convert_prd "$PRD_FILE"
fi

echo "✅ Ralph initialized in $(pwd)"

Acceptance Criteria

• ralph-init creates .ralph/ structure in current directory
• Does NOT create new project folder
• Does NOT run git init (respects existing repos)
• --from prd.md converts PRD using Claude Code
• --dir path allows specifying target directory
• --force overwrites existing .ralph/ folder
• Warns if .ralph/ already exists without --force
• Added to install.sh for global installation
• Documentation updated in README.md
• Tests added for new command

Related Issues

• Best way to drop into a existing project? #85 - Best way to drop into an existing project? (user request)
• Ralph not starting on existing project #97 - Ralph not starting on existing project
• Feature Proposal: Monorepo Support & .ralphrc Configuration File #64 - Feature Proposal: Monorepo Support & .ralphrc Configuration File

Notes

This would significantly improve Ralph's adoption for users with existing codebases, which is likely the majority of real-world use cases.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#45 - feat: add dedicated uninstall.sh script [merged]
#59 - test(install): add comprehensive installation tests [merged]
#60 - test(setup): add 36 comprehensive tests for setup.sh [merged]
#61 - test(import): add 22 comprehensive tests for ralph_import.sh [merged]
#109 - feat(structure): migrate Ralph files to .ralph/ subfolder [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[frankbria]

This is the implementation proposal for the highly-requested feature in #85 (8+ users asking for existing project support).

Priority: High - this is blocking adoption for users with existing codebases, which is likely the majority of real-world use cases.