fix: branch creation defaults to current HEAD instead of main

[chaitanyakumar-d]

Summary

This PR fixes the branch creation behavior to use the current HEAD or an optional baseBranch instead of always defaulting to main.

Problem

When the PRD's branchName doesn't exist, the agent instructions say to "create from main". This causes issues when using a development branch (e.g., stage) as the integration point, leading to:

• New work based on stale code
• Massive merge conflicts due to diverged architectures

Solution

• Updated prompt.md and CLAUDE.md to create branches from baseBranch (if specified in PRD) or from the current HEAD
• Added optional baseBranch field to prd.json.example
• Updated README.md to document the new option

Changes

• prompt.md: Updated step 3 to use baseBranch or current HEAD
• CLAUDE.md: Updated step 3 to use baseBranch or current HEAD
• prd.json.example: Added baseBranch field example
• README.md: Documented the new baseBranch option

Fixes #40

[chaitanyakumar-d]

Hi! 👋 This is my first contribution to this project.

A few notes on this implementation:

1. Backward compatible - If baseBranch is not specified in prd.json, the agent will use the current HEAD, which is more intuitive than defaulting to main.

2. Flexible - Users can still explicitly set baseBranch: "main" in their PRD if they want the old behavior.

3. Example scenario from the issue:

   • User is on stage branch
   • PRD specifies a new branchName: "ralph/feature-x"
   • Before: Branch created from main (stale code)
   • After: Branch created from stage (current work)

Happy to make any changes if you'd like a different approach!

[greptile-apps]

Greptile Summary

• Fixes branch creation behavior to use current HEAD or optional baseBranch instead of always defaulting to main branch
• Adds optional baseBranch field to PRD schema (prd.json.example) for specifying which branch to create feature branches from
• Updates agent instructions in both prompt.md and CLAUDE.md to support flexible base branch creation for modern Git workflows

Important Files Changed

Filename	Overview
prompt.md	Updated step 3to create branches from baseBranch or current HEAD instead of hardcoded main
CLAUDE.md	Updated step 3 to create branches from baseBranch or current HEAD instead of hardcoded main
prd.json.example	Added optional baseBranch field to demonstrate the new schema option

Confidence score: 5/5

• This PR is extremely safe to merge with no risk of breaking existing functionality
• Score reflects simple, well-targeted changes that maintain backward compatibility while solving a real workflow problem
• No files require special attention as changes are straightforward and consistent across all modified files

Sequence Diagram

sequenceDiagram
    participant User
    participant Ralph as ralph.sh
    participant AI as "AI Tool (Amp/Claude)"
    participant Git
    participant Files as "PRD & Progress Files"

    User->>Ralph: "Execute ./ralph.sh [--tool] [iterations]"
    Ralph->>Files: "Read prd.json"
    Ralph->>Git: "Check/create branch from baseBranch or HEAD"
    loop Until all stories pass or max iterations
        Ralph->>AI: "Spawn fresh AI instance with prompt"
        AI->>Files: "Read prd.json and progress.txt"
        AI->>AI: "Pick highest priority story with passes: false"
        AI->>AI: "Implement single user story"
        AI->>AI: "Run quality checks (typecheck, lint, test)"
        alt Quality checks pass
            AI->>Git: "Commit changes with feat: [Story ID] - [Title]"
            AI->>Files: "Update prd.json: set passes: true"
            AI->>Files: "Append progress to progress.txt"
        else Quality checks fail
            AI->>AI: "Fix issues and retry"
        end
        AI->>Ralph: "Return completion status"
        Ralph->>Files: "Check if all stories have passes: true"
        alt All complete
            Ralph->>User: "Output <promise>COMPLETE</promise>"
        else More work needed
            Ralph->>Ralph: "Continue to next iteration"
        end
    end

Loading

[greptile-apps]

Greptile found no issues!

From now on, if a review finishes and we haven't found any issues, we will not post anything, but you can confirm that we reviewed your changes in the status check section.

_{This feature can be toggled off in your Code Review Settings by deselecting "Create a status check for each PR".}