feat(mcp): Add support for working on non-default branches during sprints

[Helmi]

Description

Simone needs to support workflows where teams work on feature branches for extended periods (e.g., during sprints) rather than always branching from and merging to master/main. Currently, the system assumes work is always done against the default branch, which doesn't align with many real-world branching strategies like GitFlow or feature branch workflows.

Context

• Project area: MCP Server - Configuration, Constitution, and Prompts
• Complexity: 7/10 - Architectural enhancement affecting multiple components
• Related: Branching strategies, sprint-based development, GitFlow support

Many projects require developers to:

• Work on a sprint branch for the duration of a sprint
• Create feature branches from the sprint branch (not master)
• Create pull requests targeting the sprint branch (not master)
• Only merge the sprint branch to master at sprint completion

Technical Details

Current Limitations

1. Prompts assume default branch: work_issue.yaml, create_pr.yaml, and refine_pr.yaml all assume working against master/main
2. No branch configuration: Project configuration doesn't support specifying a working branch
3. Constitution lacks branch awareness: Generated constitution doesn't include branch strategy information
4. No sprint/temporary branch support: No way to temporarily override the target branch for a period

Affected Files

• /mcp-server/src/config/types.ts - Add branch configuration types
• /mcp-server/src/templates/prompts/work_issue.yaml - Add branch awareness
• /mcp-server/src/templates/prompts/create_pr.yaml - Support custom target branch
• /mcp-server/src/templates/prompts/refine_pr.yaml - Handle non-default branch PRs
• /mcp-server/src/templates/prompts/init_simone.yaml - Include branch info in constitution
• /mcp-server/src/templates/prompts/partials/github.hbs - Add branch context
• Project configuration schema documentation

Requirements

Configuration Support

1. Add branch configuration to project settings:

   • defaultBranch: The main branch (master/main)
   • workingBranch: Current working branch (can be temporary)
   • branchStrategy: Type of branching strategy (gitflow, github-flow, custom)
   • sprintBranch: Optional sprint-specific branch

2. Support temporary branch overrides:

   • Allow setting a working branch for a sprint duration
   • Automatically detect and suggest branch based on current context
   • Provide prompts to switch working branch context

Prompt Updates

1. Update issue/PR prompts to:

   • Check configuration for target branch
   • Create branches from the working branch (not always master)
   • Target PRs to the working branch
   • Include branch context in PR descriptions

2. Add branch awareness prompts:

   • set_working_branch: Set temporary working branch
   • show_branch_context: Display current branch configuration
   • sync_branch: Sync working branch with upstream

Constitution Integration

1. Include in project constitution:
   • Current branch strategy
   • Default and working branches
   • Sprint branch if applicable
   • Branch naming conventions

Implementation Steps

Phase 1: Configuration Foundation

• Define branch configuration interfaces in types.ts
• Add branch settings to project configuration schema
• Create configuration helpers for branch management
• Update configuration loader to handle branch settings

Phase 2: Prompt Updates

• Update work_issue.yaml to branch from working branch
• Modify create_pr.yaml to target working branch
• Update refine_pr.yaml for non-default branch awareness
• Create new branch management prompts
• Update GitHub partial with branch context

Phase 3: Constitution Integration

• Update init_simone.yaml to include branch information
• Add branch strategy to constitution template
• Include branch naming conventions in constitution

Phase 4: Documentation

• Document branch configuration options
• Create examples for different branching strategies
• Add migration guide for existing projects
• Update README with branching workflow examples

Acceptance Criteria

• Users can configure a working branch different from master/main
• All issue and PR prompts respect the configured working branch
• Constitution includes branch strategy and current working branch
• Users can temporarily set a sprint branch without modifying config
• Branch context is visible in relevant prompts
• PRs are created against the correct target branch
• Documentation clearly explains branching workflow support
• Existing projects continue to work without configuration changes (backward compatible)

Additional Considerations

• Should support common branching strategies out of the box (GitFlow, GitHub Flow)
• Consider integration with GitHub Projects for sprint management
• May need to detect branch from current git context
• Should provide clear feedback about which branch is being used
• Consider adding branch validation to prevent mistakes

Research Links

• GitFlow Workflow
• GitHub Flow
• Trunk-Based Development

[Helmi]

We might also consider automatically adding text to a PR on a non-main branch situation to trigger code reviews. But this is a consideration as it would need to be configured and might complicate/blow up our configuration.

Example: Claude code actions are by default only auto triggered on the defined main branch. They can manually be commited to a certain other branch but that needs to be done - otherwise adding "@\claude please review this PR" (escpaing to not trigger claude here) can trigger it "manually".

But both, the fact that this should be added to non default branch PRs as well as what the command is (might not be claude code but other reviewers) would need to be configured and might complicate our configuration/init process.

Debatable if that helps or if it would better just be added to the constitution by the user.