Multi-Project Setup

Symphony supports managing multiple projects simultaneously from a single instance. Each project gets its own issue board, agent profiles, and configuration.

How Project Detection Works

When Symphony starts, it scans the configured workspace directory for repositories. A directory is detected as a project if it contains recognizable project markers:

• package.json (Node.js/JavaScript)
• composer.json (PHP)
• Cargo.toml (Rust)
• go.mod (Go)
• pyproject.toml or setup.py (Python)

Each detected project is registered in the database with a unique identifier prefix (e.g., SYM, API, WEB).

Workspace Structure

Symphony expects projects to be siblings in a workspace directory:

~/workspace/
  project-a/      -> SYM-001, SYM-002, ...
  project-b/      -> API-001, API-002, ...
  project-c/      -> WEB-001, WEB-002, ...

Per-Project Configuration

Each project has independent settings accessible through the web UI:

• Agent toggles — Enable/disable worker, researcher, scanner, and planner agents per project
• Concurrency limits — Control how many agents can work on a project simultaneously
• Custom instructions — Project-specific guidance for all agents
• Pipeline configuration — Which phases to include (e.g., skip research for simple projects)

Configuring via the Web UI

1. Navigate to your project's board at /p/:slug
2. Click Settings in the project header
3. Adjust agent toggles, concurrency, and custom instructions
4. Click Save

Configuring via the CLI

npm run cli -- status          # See all projects and their status

Concurrency and Slot Management

Symphony allocates agent slots across projects:

• Global limit — Maximum total concurrent agents (configured in symphony.config.json)
• Per-project limit — Maximum concurrent agents per project
• Reserved worker slots — Ensures workers aren't starved by phase agents

The orchestrator dispatches work in priority order: judge (review) > phase agents > workers > scanners.

Testing

Worker slot reservation is tested in tests/integration/orchestrator/workerSlotStarvation.test.ts:

npx vitest run tests/integration/orchestrator/workerSlotStarvation.test.ts

The test suite verifies that phase agents cannot consume all concurrency slots when worker items are waiting.

Worktree Isolation

Each agent gets its own git worktree, regardless of which project it belongs to. Worktrees are created in .symphony-workspaces/<identifier> and cleaned up after the agent completes.

This means agents from different projects never interfere with each other, and multiple agents can work on the same project simultaneously without merge conflicts.