mirror of
https://github.com/jlengrand/Maestro.git
synced 2026-03-10 08:31:19 +00:00
0b1e387287
Key fixes:
- Corrected PR creation flow: uses deferred PR creation (on first commit), not immediate
- Rewrote Task Claiming section to explain deferred flow: start → first commit creates PR → subsequent commits push
- Added four modal tabs documentation (Projects, Active, History, Stats)
- Added keyboard navigation: arrows, Enter, / for search, Cmd+Shift+[/] for documents
- Expanded Active tab: status indicators, progress bar, token usage, controls, Check PR Status button
- Expanded History tab: PR status, completion date, documents, cost, summary stats
- Expanded Stats tab: overview metrics, repos contributed, streak tracking, achievements
- Fixed branch naming to `symphony/{issue-number}-{short-id}`
- Added `featured` and `addedAt` fields to JSON example
- Added complete categories table with all 9 categories, labels, and emojis
- Added cache TTL info (registry: 2hr, issues: 5min)
193 lines
6.8 KiB
Markdown
193 lines
6.8 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:
|
|
- 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:
|
|
|
|
```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).
|
|
|
|
---
|
|
|
|
**Maestro Symphony — Advancing open source, together.**
|