Add guidance for cloning multiple repositories

[jpelletier1]

• I have read and reviewed the documentation changes to the best of my ability.
• If the change is significant, I have run the documentation site locally and confirmed it renders as expected.

Summary of changes

Added comprehensive guidance for working with multiple repositories in the prompting best practices documentation. This addresses a common real-world scenario where users start in one repository (e.g., backend) but need OpenHands to access related code from other repositories (e.g., frontend).

Changes Made

• New Section: Added "Working with Multiple Repositories" to openhands/usage/tips/prompting-best-practices.mdx
• Common Scenarios: Documents typical use cases including frontend/backend splits, microservices, and shared libraries
• Two Methods:
  1. Repository configuration files (repo.md, agents.md)
  2. Ad-hoc prompting during conversations
• Best Practices: Guidelines for clone locations, providing context, and leveraging Git tokens
• Practical Examples: Multiple example prompts and a comprehensive multi-repo workflow example

Benefits

• Helps users understand how to give OpenHands access to their complete project ecosystem
• Provides clear, actionable guidance for both planned and spontaneous multi-repo workflows
• Addresses authentication concerns by explaining Git token usage
• Includes concrete examples that users can adapt to their specific scenarios

The new content maintains consistency with the existing documentation style and integrates seamlessly with the current structure.

@jpelletier1 can click here to continue refining the PR

[jpelletier1]

@OpenHands Let's actually move this text into it's own document. The document should be "Working with multiple repos" and fall under the same "Tips and tricks" section.

[openhands-ai]

I'm on it! jpelletier1 can track my progress at all-hands.dev

[openhands-ai]

Summary of Changes

I have successfully completed your request to move the multi-repo content into its own document. Here's what was accomplished:

✅ Request Fulfillment Checklist:

• Created a new document titled "Working with Multiple Repos"
• Moved all multi-repo content from prompting-best-practices.mdx to the new document
• Placed the new document under the "Tips and Tricks" section in the navigation
• Removed the multi-repo section from the original prompting document
• Maintained proper document structure and formatting

Changes Made:

1. Created: openhands/usage/tips/working-with-multiple-repos.mdx - A standalone document focused entirely on multi-repository workflows
2. Updated: docs.json - Added the new document to the "Tips and Tricks" navigation section
3. Modified: prompting-best-practices.mdx - Removed the 54-line multi-repo section while preserving the reference to First Projects

Result:

The documentation is now better organized with:

• Prompting Best Practices: Focused on general prompting techniques and best practices
• Working with Multiple Repos: Dedicated guide for multi-repository workflows and cloning strategies

The changes have been committed and pushed to the add-multi-repo-cloning-guidance branch, updating the existing PR #153. The new document maintains all the original content while providing better discoverability and organization within the documentation structure.

_{View full conversation}