Maestro Symphony

​

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

​

Browsing Projects

​

Projects Tab

• 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

• 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

• 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

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

• 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

• 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

• 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

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

​

Creating Symphony-Ready Issues

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

​

Task Claiming

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

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

​

Registering Your Project

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

{
  "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