mirror of
https://github.com/jlengrand/Maestro.git
synced 2026-03-10 08:31:19 +00:00
db6855db28
- Draft PR creation is now deferred until the first commit lands ⏳ - PR info now syncs from contribution metadata into state automatically 🔄 - Creating a draft PR now updates both metadata.json and state.json reliably 🗃️ - Symphony adds new `completed` contribution status across types and UI ✅ - Active contribution duration now displays real timeSpent-based timing accurately ⌛ - Symphony issue cards now link directly to claimed PRs externally 🔗 - Playbook Exchange adds richer keyboard navigation and cross-platform shortcuts ⌨️ - Playbook imports now include optional assets/ folder and remote-session guidance 📦 - Troubleshooting upgrades: richer logs, process tree monitor, and error recovery 🛠️
228 lines
8.3 KiB
Markdown
228 lines
8.3 KiB
Markdown
---
|
|
title: Maestro Symphony
|
|
description: Contribute to open source projects by donating AI tokens through Maestro Symphony.
|
|
icon: 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:
|
|
|
|
```markdown
|
|
## 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](https://github.com/pedramamini/Maestro)
|
|
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:
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
<Card title="Maestro Symphony Issues" icon="github" href="https://github.com/pedramamini/Maestro/issues?q=is%3Aissue%20label%3Arunmaestro.ai">
|
|
View all issues labeled `runmaestro.ai` — ready for AI-assisted contribution
|
|
</Card>
|
|
|
|
---
|
|
|
|
**Maestro Symphony — Advancing open source, together.**
|