Maestro/docs/symphony.md

title, description, icon

title	description	icon
Maestro Symphony	Contribute to open source projects by donating AI tokens through Maestro Symphony.	music

Maestro Symphony is a community-driven program that connects Maestro users with open source repository maintainers seeking contributions. Think of it like distributed computing for AI-assisted development — instead of donating CPU cycles, users donate LLM tokens to advance open source.

How It Works

For Contributors

1. Browse available projects directly within Maestro
2. Select a GitHub issue that matches your interests
3. Create a dedicated agent session — choose your AI provider and model
4. Single-click contribution — Maestro clones the repo, runs Auto Run docs, and creates a PR

For Repository Owners

1. Define contribution opportunities as Auto Run documents in your repository
2. Open a GitHub issue listing the document paths
3. Add the runmaestro.ai label to make it visible to the Maestro community
4. Receive quality pull requests generated by AI-assisted workflows

Opening Symphony

Method	Description
Cmd+Shift+Y / Ctrl+Shift+Y	Keyboard shortcut
Quick Actions → "Maestro Symphony"	Command palette (Cmd+K)
Hamburger Menu → "Maestro Symphony"	Menu item

Browsing Projects

The Symphony modal has four tabs: Projects, Active, History, and Stats.

Projects Tab

The Projects tab shows registered open source projects in a tiled grid:

• Category filters — Filter by AI/ML, Developer Tools, etc.
• Search — Find projects by name, description, or tags
• Project tiles — Click to view available issues
• Keyboard navigation — Use arrow keys to navigate, Enter to select, / to focus search

Select a repository to see its available GitHub issues. Each issue shows:

• Issue title and number
• Number of Auto Run documents to process
• Document previews with a dropdown selector (use Cmd+Shift+[ / Cmd+Shift+] to cycle documents)
• Status indicator (available or in-progress with PR link)

Starting a Contribution

Click Start Symphony on an available issue to open the agent creation dialog:

Configure your contribution:

• AI Provider — Choose Claude Code, Codex, OpenCode, etc.
• Session Name — Pre-filled as "Symphony: owner/repo #123"
• Working Directory — Where the repository will be cloned

Click Create Agent and Maestro will:

1. Clone the repository to ~/Maestro-Symphony/{owner}-{repo}/ (default location, customizable)
2. Create a new branch (symphony/{issue-number}-{short-id})
3. Set up Auto Run documents (external attachments downloaded to cache, repo docs referenced in place)
4. Begin processing tasks automatically
5. Create a draft PR on first commit (claims the issue so others know it's in progress)

Tracking Contributions

Active Tab

View your in-progress Symphony sessions:

Each active contribution shows:

• Issue title and repository — The GitHub issue being worked on
• Status badge — Running, Paused, Creating PR, etc.
• Progress bar — Documents completed vs. total
• Current document — The document being processed
• Time elapsed — How long the contribution has been running
• Token usage — Input/output tokens and estimated cost
• Draft PR link — Once created on first commit
• Controls — Pause/Resume, Cancel, Finalize PR

Click Check PR Status to verify your draft PR on GitHub and detect merged/closed PRs.

History Tab

Review completed contributions with aggregate stats at a glance:

The header shows your totals: PRs created, merged count, tasks completed, tokens used, and dollar value donated. Each contribution card displays:

• Issue and repository — What you worked on
• Merge status — Whether the PR was merged
• Completion date — When you finished
• PR link — Direct link to the pull request
• Detailed metrics — Documents processed, tasks completed, tokens used, and cost

Stats Tab

Track your overall impact and unlock achievements:

Summary cards show your cumulative contributions:

• Tokens Donated — Total tokens contributed with dollar value
• Time Contributed — Hours spent and repositories helped
• Streak — Current and best contribution streaks

Achievements reward milestones in your Symphony journey:

Achievement	Requirement
First Steps	Complete your first Symphony contribution
Merged Melody	Have a contribution merged
Weekly Rhythm	Maintain a 7-day contribution streak
Harmony Seeker	Complete 10 contributions
Ensemble Player	Contribute to 5 different repositories
Virtuoso	Complete 1000 tasks across all contributions
Token Millionaire	Donate over 10 million tokens
Early Adopter	Join Symphony in its first month

Session Integration

Symphony sessions appear in the Left Bar like any other session:

• Named "Symphony: owner/repo #123"
• Optionally grouped under a "Symphony" group
• Full access to AI Terminal, Command Terminal, and Auto Run controls

You can interact with Symphony sessions just like regular sessions — pause Auto Run, make manual edits, or switch to the Command Terminal for custom commands.

Creating Symphony-Ready Issues

Repository owners create issues with the runmaestro.ai label:

## Add unit tests for auth module

We need comprehensive test coverage for the authentication module.

### Auto Run Documents
- `docs/symphony/auth-tests-1.md`
- `docs/symphony/auth-tests-2.md`
- `docs/symphony/auth-tests-3.md`

### Context
The auth module is at `src/auth/index.ts`. Tests should use Jest.

Each document path should point to an Auto Run-compatible markdown file with task checkboxes.

Task Claiming

Symphony uses deferred PR creation to avoid GitHub's "no commits between branches" error. When you start a contribution, Maestro sets up the branch and documents but waits until the first commit to create the draft PR:

1. Start contribution → Branch created locally, Auto Run begins processing
2. First commit → Draft PR automatically created, claims the issue
3. Subsequent commits → Push to the same PR

This means issues show as "in progress" once the first commit lands. The claiming mechanism:

• No draft PR → Task is available
• Draft PR exists → Task is in progress (first to commit wins)

Registering Your Project

To add your open source project to Symphony:

1. Fork the Maestro repository
2. Add your project to symphony-registry.json in the root directory
3. Submit a pull request to the main Maestro repository

Your project entry should include:

{
  "slug": "owner/repo",
  "name": "Project Name",
  "description": "Brief description",
  "url": "https://github.com/owner/repo",
  "category": "ai-ml",
  "tags": ["tag1", "tag2"],
  "maintainer": {
    "name": "Your Name",
    "url": "https://github.com/yourusername"
  },
  "isActive": true,
  "featured": false,
  "addedAt": "2025-01-01"
}

Available Categories

Category	Label	Emoji
ai-ml	AI & ML	🤖
developer-tools	Developer Tools	🛠️
infrastructure	Infrastructure	🏗️
documentation	Documentation	📚
web	Web	🌐
mobile	Mobile	📱
data	Data	📊
security	Security	🔒
other	Other	📦

Once merged, your project will appear in the Symphony Projects tab (registry cached for 2 hours, issues cached for 5 minutes).

Available Issues

Browse Symphony-ready issues on Maestro itself:

View all issues labeled `runmaestro.ai` — ready for AI-assisted contribution

---

Maestro Symphony — Advancing open source, together.