Maestro/docs/SYMPHONY_ISSUES.md

Creating Symphony Issues

Maintainers create GitHub Issues to define contribution opportunities for the Symphony community.

Overview

Symphony issues are standard GitHub issues with the runmaestro.ai label. The issue body contains paths to Auto Run documents that define the work to be done. When a contributor starts working on an issue, a draft PR is automatically created to claim it.

Issue Requirements

1. Label: Add the runmaestro.ai label to the issue
2. Title: Clear description of the contribution (e.g., "Add unit tests for user module")
3. Body: List the Auto Run document paths (one per line)

Issue Body Format

Simply list the paths to your Auto Run documents:

.maestro/autorun/add-user-tests.md
.maestro/autorun/add-user-tests-2.md

That's it! No special formatting required. The system will:

• Parse the .md file paths from the issue body
• Clone your repository when a contributor starts
• Run each document in sequence via Auto Run
• Create a PR with all changes

Supported Path Formats

The following formats are recognized:

# Bare paths (recommended)
.maestro/autorun/task-1.md
.maestro/autorun/task-2.md

# Markdown list items
- .maestro/autorun/task-1.md
- `.maestro/autorun/task-2.md`

# Numbered lists
1. .maestro/autorun/task-1.md
2. .maestro/autorun/task-2.md

Example Issue

Title: Add comprehensive tests for the authentication module

Labels: runmaestro.ai

Body:

Add test coverage for the authentication module.

Documents to process:
.maestro/autorun/auth-unit-tests.md
.maestro/autorun/auth-integration-tests.md
.maestro/autorun/auth-e2e-tests.md

## Context

The `src/auth/` module currently has low test coverage. These documents will guide the AI to add comprehensive tests following our existing patterns.

## Expected Outcome

- Unit tests for all public functions
- Integration tests for auth flow
- E2E tests for login/logout

Estimated time: ~45 minutes of AI agent time.

Auto Run Document Format

Each .md file should be a complete Auto Run document:

# Task: Add Unit Tests for Auth Module

## Context
The authentication module at `src/auth/` needs test coverage.

## Objectives
- [ ] Create `src/__tests__/auth.test.ts`
- [ ] Add tests for `login()` function
- [ ] Add tests for `logout()` function
- [ ] Add tests for `refreshToken()` function
- [ ] Ensure `npm test` passes
- [ ] Verify coverage > 80%

## Constraints
- Use Jest testing framework
- Follow existing test patterns in the codebase
- Do not modify production code

Document Best Practices

1. Small, focused tasks: Each document should be ~30-60 minutes of AI time
2. Clear objectives: Use checkboxes (- [ ]) for verification steps
3. Provide context: Include file paths, existing patterns, constraints
4. Verification steps: Include test commands, linting checks
5. Independence: Each document should be self-contained

Issue Availability

An issue is available for contribution when:

• It has the runmaestro.ai label
• It is open (not closed)
• There is no open PR with "Closes #N" in the body

When a contributor starts working on an issue, a draft PR is immediately created with "Closes #N" in the body. This claims the issue and prevents duplicate work.

Claim Flow

1. Contributor clicks "Start Symphony" on an issue
2. Repository is cloned locally
3. A new branch is created (symphony/issue-{number}-{timestamp})
4. An empty commit is made
5. The branch is pushed to origin
6. A draft PR is created with "Closes #{issue}" in the body
7. Auto Run begins processing documents
8. When complete, contributor clicks "Finalize PR"
9. Draft PR is converted to "Ready for Review"

Creating Good Issues

Do

• ✅ Break large tasks into multiple smaller issues
• ✅ Include all necessary context in the documents
• ✅ Provide clear acceptance criteria
• ✅ Estimate the expected time/complexity
• ✅ Link to relevant documentation or examples

Don't

• ❌ Create issues that require human judgment calls
• ❌ Include tasks that need external credentials/access
• ❌ Bundle unrelated tasks in a single issue
• ❌ Assume contributors know your codebase intimately
• ❌ Create documents with ambiguous requirements

Example Document Structure

For complex tasks, organize your documents like this:

.maestro/autorun/
├── feature-1-setup.md      # First: Set up files/structure
├── feature-1-implement.md  # Second: Implement the feature
├── feature-1-tests.md      # Third: Add tests
└── feature-1-docs.md       # Fourth: Update documentation

Each document builds on the previous one, and contributors can see the full scope in the issue body.

Monitoring Contributions

As a maintainer:

1. You'll receive a GitHub notification when a draft PR is created
2. Watch the PR for progress as the contributor works
3. Review and provide feedback once the PR is ready
4. Merge when satisfied

Questions?

• See SYMPHONY_REGISTRY.md for registry information
• Check the Maestro documentation for Auto Run guides
• Open an issue on the Maestro repository for support