Custom Prompts

Symphony uses a layered prompt system that gives you full control over how agents behave. You can customize agent behavior at multiple levels without modifying core code.

Prompt Assembly

Every agent receives a prompt assembled from multiple layers:

Layers 1-4 define the workflow contract. Layers 5-7 provide local context but cannot weaken contract requirements.

Agent Profiles

Agent profiles live in prompts/profiles/ and define each agent type's identity:

Profile	File	Purpose
Worker	worker.md	Implements code changes
Judge	judge.md	Reviews PRs and phase artifacts
Planner	planner.md	Creates execution plans during grooming
Researcher	researcher.md	Deep analysis on assigned tickets
Scanner	scanner.md	Background codebase exploration

Each profile is stored per-project in the agent_profiles database table. You can edit profiles through the web UI at Settings > Agent Profiles.

Phase Contracts

Phase contracts in prompts/phases/ define what each pipeline phase requires:

• research.md — Research brief with YAML frontmatter
• architecture.md — Design document requirements
• grooming.md — Execution plan breakdown
• ready.md — Implementation requirements

Each contract includes YAML frontmatter specifying:

dispatch_profile: researcher    # Which agent type handles this phase
artifact_path: research.md      # Expected output file
required_sections:              # Sections that must be present
  - Problem Statement
  - Recommendation
validation: structural          # How completion is verified
next_phase: architecture        # Where to go next

Customizing Agent Behavior

Per-Project Instructions

The easiest way to customize agent behavior is through Project Settings in the web UI. Add custom instructions that apply to all agents working on that project:

Always use TypeScript strict mode.
Follow the repository's existing patterns for error handling.
Run tests with `npm test` before completing work.

CLAUDE.md

Add a CLAUDE.md file to your repository root with project conventions. All agents will receive this context:

# Project Conventions

- Use `pnpm` instead of `npm`
- All API routes must have input validation
- Database queries use Drizzle ORM, not raw SQL

Profile Overrides

For specific profile+phase combinations, create override files in prompts/overrides/:

prompts/overrides/researcher-architecture.md

This file contains small adjustments that apply only when a researcher agent is working on the architecture phase.

Token Budget System

Symphony automatically manages prompt size through a token budget system. Context sections are prioritized and trimmed when the total would exceed the model's context window:

1. Issue details — always included (highest priority)
2. Custom instructions — included up to budget
3. Learnings — scored and deduplicated, included up to budget
4. Dependencies — included if budget allows

The budget system ensures agents always receive the most relevant context without exceeding limits.