Practical workflows for repository management and pull request collaboration. This guide assumes you’ve linked your GitHub account (top-right menu) for private repository access. For command details, see Commands Reference.

​
Clone Repositories

​
Clone Your Repositories

Use natural language or the /clone command: 
"Clone my backend-api repository, develop branch"

"Clone the repo at github.com/myorg/myproject, main branch"
Or use /clone which guides you through:
  • Selecting private (authenticated) or public repository
  • Choosing from your repositories or entering a URL
  • Selecting a branch or entering a specific commit
After cloning, files are immediately available to Maestro and synced to the sandbox.

​
Clone Pull Requests

Clone PRs directly by URL: 
"Clone https://github.com/org/repo/pull/123"

"Clone PR #456 from the backend repository"
Maestro automatically:
  • Fetches PR metadata
  • Determines the source branch
  • Handles forked PRs
  • Shows PR context (number, state, branches)
Use cases:
  • Review a teammate’s PR
  • Test proposed changes
  • Collaborate on a feature branch
  • Understand implementation before merging

​
Pull Remote Changes

Pull changes from the remote by cloning again: 
"Clone the backend-api repository, feature-branch again to pull latest changes"
When you clone a repository that’s already cloned:
  • Maestro detects changed files
  • Creates new iterations for changed files
  • Adds any new files
  • Preserves your iteration history
  • Informs you what changed
Catchup workflow after pulling: 
"I need to understand what changed in my branch.

Steps:
1. Show me which files changed
2. Display diffs for the most important changes
3. Explain what was accomplished
4. Identify any conflicts with my local changes"

​
Create Repositories

​
Create via Natural Language

"Create a new GitHub repository called my-project with MIT license and Python gitignore"

​
Create via Command

/create
Opens an interactive flow for:
  • Repository name (required)
  • Description (optional)
  • Visibility (public or private, defaults to private)
  • GitIgnore template (Python, Node, Go, etc.)
  • License template (MIT, Apache-2.0, GPL, etc.)
  • Organization (personal or org account)
  • Auto-clone (enabled by default)
With auto-clone enabled (default):
  • Repository created on GitHub
  • Immediately cloned to session
  • Ready to start working
  • Files synced to sandbox

​
Push Existing Session Files

If you have files in your session: 
"Create a repository called my-project and push my existing session files as the initial commit"
Maestro will:
  • Create empty remote repository
  • Push your session files as initial commit
  • Respect .gitignore patterns
  • Make you ready to work

​
Create Pull Requests

​
Understanding the Workspace

Critical: Maestro’s workspace is separate from git. Your work stays in the session until you explicitly create or update a PR:
  • Files exist in Maestro’s storage
  • Changes tracked via iterations
  • Full history preserved
  • Nothing pushed to git until you create/update PR
This means you can work as long as needed before sharing changes with your team.

​
Create a PR

Via natural language: 
"Create a pull request for my authentication changes. Title: Add JWT auth. Base: main."
Via command: 
/pr
The PR creation flow: Step 1: Branch Configuration
  • Review repository URL
  • Set base branch (target, usually main/develop)
  • Set feature branch name
  • Confirm or modify
Step 2: File Selection
  • Interactive UI shows all modified/new files
  • Select which files to include
  • Can deselect files you don’t want in this PR
  • Shows diff statistics (lines added/removed)
Step 3: Confirmation
  • Provide/edit PR title and description
  • Review file selection
  • See complete diff of changes
  • Confirm or cancel
Step 4: Push and Create
  • Commits selected files
  • Pushes to GitHub
  • Opens pull request
  • Ready for team review

​
Update Existing PR

To update a PR, use /pr again with the same repository and branch: 
"Update my PR on the feature-branch with the latest changes"
The update flow:
  1. Shows currently included files
  2. Let you add/remove files
  3. Computes diff against current PR state
  4. Pushes updates to feature branch
  5. PR automatically updates on GitHub
Important: Updating is a full sync. If you deselect a file that was previously included, it reverts to the base branch state on the remote. Use case for deselecting: 
Previously included: auth.py, config.py, tests.py
You deselect: config.py

Result: config.py changes removed from PR, reverts to base branch state
Use when: Splitting features across multiple PRs

​
Collaboration Workflows

​
Review a Teammate’s PR

"Clone https://github.com/org/repo/pull/456"
Then review: 
"Review this PR for:
- Code quality issues
- Test coverage gaps
- Performance concerns
- Security vulnerabilities

Provide detailed feedback on each issue found."

​
Work on Shared Branch

When collaborating on the same branch: 
1. "Clone the repository, feature-branch to pull teammate's changes"

2. "Show me what changed since I last worked on this"

3. Make your changes

4. "Update the PR with my additions"

​
Sequential Collaboration

Developer A (first session): 
- Creates feature branch
- Implements partial feature
- Creates PR (draft mode)
Developer B (new session): 
- "Clone PR #123 from Developer A"
- Continues implementation
- "Update the same PR with my additions"
- Marks PR as ready for review

​
Advanced Workflows

​
Multi-Repository Features

Work across repositories: 
"Clone the frontend repository"
"Clone the backend repository"
"Clone the shared library repository"

Now implement changes across all three.
Create separate PRs for each repository.
Link PRs in descriptions for coordinated review."

​
Hotfix Workflow

"Clone the repository, production branch"

"Implement minimal fix for \{critical bug\}"

"Create PR directly to production branch with title: hotfix/\{issue\}"
Keep the change surgical and focused for fast review and merge.

​
Release Preparation

"Clone from main branch"

"Review all changes since v1.5 tag:
- Identify what changed
- Create comprehensive changelog
- Document breaking changes
- Validate backward compatibility"

"Create PR with all release documentation"

​
Stacked PRs

Building features incrementally: 
Base: main

PR #1: feature/core → main
  (Core infrastructure)

PR #2: feature/api → feature/core
  (API layer, depends on core)

PR #3: feature/ui → feature/api
  (UI, depends on API)
Each PR is reviewable independently. Merge order: #1, then #2, then #3.

​
Best Practices

​
Before Creating PR

Run this checklist: 
"Before I create the PR, verify:
1. Run full test suite - show me all tests passing
2. Check code follows project conventions
3. Update documentation affected by changes
4. Remove any TODO comments or debug code
5. Verify no sensitive data in files"

​
PR Quality Standards

For good PR descriptions, include: 
## Changes
\{What was implemented\}

## Testing
\{How it was validated\}

## Performance
\{Benchmark results if relevant\}

## Breaking Changes
\{None or list them\}

## Notes
\{Additional context for reviewers\}

​
Incremental PRs

Create small, focused PRs instead of large ones: 
Instead of giant PR with:
- authentication + caching + monitoring + logging

Create sequential PRs:
1. "Add authentication system" (merged)
2. "Add caching layer" (builds on #1, merged)
3. "Add monitoring" (builds on #2, merged)
4. "Add logging" (builds on #3)
Small PRs are easier to review, less likely to have conflicts, and faster to merge.

​
CI/CD Integration

Validate before pushing: 
"Before creating the PR:
1. Run the full test suite locally
2. Run linters and formatters
3. Check code coverage meets threshold
4. Run any CI scripts locally if possible
5. Verify build succeeds

Show me evidence that all validations pass."

​
Troubleshoot Common Issues

​
Clone Failed

Repository too large (limit ~10GB): 
Contact support for special cases or clone specific subdirectories if possible
Authentication failed: 
Verify GitHub account is linked in top-right menu
Check you have access to the repository
Branch not found: 
Verify branch name (case-sensitive)
Try default branch if unsure

​
PR Creation Failed

No changes detected: 
Verify files were actually modified
Ensure Apply Changes ran before creating PR
Check file selection in PR UI
Branch already exists: 
Choose different branch name, or
Update existing PR instead, or
Delete remote branch first (if safe)

​
PR Not Showing Changes

Check: 
"Did Apply Changes run before I created the PR?"
"Show me which files are modified in the session"
"Let me see the diff for \{file\} to verify changes exist"
Verify: 
Use "Compute diffs between the base and my changes"
Ensure files were selected in PR creation flow
Check that changes were actually applied to files

​
Next Steps

Master source control workflows, then explore: