Symphony

Appearance

First Agent Run ​

This walkthrough takes you through a complete agent lifecycle: from creating an issue to merging the resulting pull request.

The Full Cycle ​

Here's what happens at each stage:

1. Create and Queue the Issue ​

Create an issue with a clear, implementable task. For your first run, try something simple:

Title: Add health check endpoint

Description: Create a GET /api/health endpoint that returns { status: "ok", timestamp: Date.now() }. Include a test.

Move the issue to Todo.

2. Agent Dispatch (todo → in_progress) ​

The orchestrator's tick loop (every 5 seconds) checks for dispatchable issues. When your issue is picked up:

  1. A git worktree is created at .symphony-workspaces/<identifier>
  2. A worker agent is spawned with the Claude CLI
  3. The issue status changes to In Progress

You'll see in the orchestrator logs:

[dispatch] Dispatching worker for SYM-001: Add health check endpoint
[worktree] Created worktree at .symphony-workspaces/SYM-001

3. Agent Implementation ​

The worker agent:

  • Reads the issue description and project context
  • Plans the implementation approach
  • Writes code in the isolated worktree
  • Runs tests to verify the implementation
  • Commits changes to the worktree branch
  • Calls complete_phase via MCP to signal completion

During this phase, the agent records:

  • Findings — Technical observations and decisions made
  • Learnings — Reusable knowledge for future agents

4. PR Creation (automatic) ​

When the worker completes, the orchestrator:

  1. Detects committed changes in the worktree
  2. Auto-creates a pull request with the diff
  3. Moves the issue to Review

The PR appears on the issue detail page with a full diff viewer.

5. Judge Review (in_progress → review) ​

A judge agent is dispatched to review the PR:

  • Checks code quality, test coverage, and adherence to requirements
  • Reviews the diff for potential issues
  • Calls approve_pr or reject_pr via MCP

If approved: The PR is marked as approved, ready for human merge.

If rejected: The issue returns to todo with feedback, and a new worker attempt is dispatched.

6. Human Merge (review → done) ​

You have final say. On the issue detail page:

  1. Review the PR diff and agent findings
  2. Check that CI passes (if configured)
  3. Click Merge to merge the PR and close the issue
  4. The issue moves to Done

Troubleshooting Your First Run ​

Agent doesn't start ​

  • Check the orchestrator is running (npm run orchestrator)
  • Verify the issue is in todo status
  • Check agent slots aren't full (see orchestrator logs)
  • Ensure Claude CLI is installed and authenticated

Agent fails ​

  • Check the orchestrator logs for error messages
  • The issue returns to todo automatically for retry
  • Review findings on the issue detail page for context
  • Maximum retries are configured in symphony.config.json

PR not created ​

  • The agent may not have committed changes — check the worktree
  • The orchestrator auto-commits uncommitted changes on agent exit
  • Check orchestrator logs for PR creation errors

Next Steps ​