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:

• Status indicators (Running, Paused, Creating PR, etc.)
• Progress bar showing documents completed vs. total
• Current document being processed
• Token usage (input/output tokens, estimated cost)
• Draft PR link (once created on first commit)
• Controls: Pause/Resume, Cancel, Finalize PR
• Check PR Status button to detect merged/closed PRs

History Tab

Review completed contributions:

• PR links with merge status (Open or Merged)
• Completion date
• Documents processed count
• Total cost for the contribution
• Summary statistics at the top (total PRs, merged count, tokens, cost)

Stats Tab

Track your overall impact:

• Overview metrics: Total contributions, merged PRs, tokens donated, estimated cost
• Repositories contributed to: Unique project count
• Streak tracking: Current and longest contribution streaks
• Achievement badges: Unlock achievements like "First Contribution", "Week Warrior", "Token Titan"

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).

---

Maestro Symphony — Advancing open source, together.