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 shows registered open source projects in a tiled grid:

• Category filters — Filter by AI/ML, Developer Tools, etc.
• Search — Find projects by name or description
• Project tiles — Click to view available issues

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 (expandable)

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}/
2. Create a new branch for your contribution
3. Open a draft PR (claims the issue so others know it's in progress)
4. Copy the Auto Run documents to your session
5. Begin processing tasks automatically

Tracking Contributions

Active Tab

View your in-progress Symphony sessions:

• Links to jump to the agent session
• Progress indicators for current document
• Links to draft PRs
• Cancel/abort controls

History Tab

Review completed contributions:

• PR links with merge status
• Per-contribution statistics
• Time and tokens spent

Stats Tab

Track your overall impact:

• Total contributions and merged PRs
• Tokens donated and estimated cost
• Issues resolved and repositories contributed to
• Streak tracking and achievement badges

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

When you click Start Symphony, Maestro immediately creates a draft PR. This claims the task so other contributors know it's being worked on:

• No draft PR → Task is available
• Draft PR exists → Task is in progress

First to create a draft PR wins — this prevents duplicate work.

Registering Your Project

To add your open source project to Symphony:

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

Your project entry should include:

{
  "slug": "owner/repo",
  "name": "Project Name",
  "description": "Brief description",
  "url": "https://github.com/owner/repo",
  "category": "developer-tools",
  "tags": ["tag1", "tag2"],
  "maintainer": {
    "name": "Your Name",
    "url": "https://github.com/yourusername"
  },
  "isActive": true
}

---

Maestro Symphony — Advancing open source, together.