symphonize

symphonize

Plan-to-implementation execution engine for Claude Code.

Symphonize turns plain-language requirements into auditable specs into shipped PRs with minimal user interaction. You describe the problem (/discover), make technical decisions (/plan), roadmap the work (/roadmap), and execute (/next or /orchestrate). Agents handle implementation autonomously — branching, coding, testing, and opening PRs. You review the results.

The governance files constrain agent behavior at each stage, making output loosely deterministic: predictable enough to review confidently, flexible enough to handle real codebases.

Design principles

The goals that shape every decision in symphonize.

• Acceptance before exploration — define "done" before exploring "how," at every layer. Success criteria before features, observable behavior before design, failing tests before code. TDD applied recursively from requirements through implementation.
• Thin vertical slices — every PR delivers a complete path from internal logic through to a user-facing surface. Horizontal layers (plumbing without a user-visible path) ship inventory, not value.
• Single-responsibility commands — each command reads upstream deliverables but writes exactly one. /discover → REQUIREMENTS.md, /plan → SPEC.md, /roadmap → ROADMAP.md. Upstream backpressure fills gaps without blocking progress.
• Depth-first by section — context coherence, testable PRs, early bug detection
• Boy Scout Rule — leave the code better than you found it. Agents clean up orphaned horizontal layers in files they touch.
• Worktree isolation — never touches the user's main checkout
• Single PR per batch — one CI run, one review surface
• Fail fast — CI after each cherry-pick, not just at the end

Opinions

How the design principles are implemented in practice. Symphonize expects these conventions and won't work well without them.

• Conventional Commits — every commit follows <type>(<scope>): <description>. Feeds release-please and changelog generation.
• Release Please (or melos for monorepos) — turns conventional commits into semver releases and CHANGELOG.md entries.
• Branch protection — work never lands on main directly. Every change flows through a feature branch and a PR with CI.
• Keep a Changelog — CHANGELOG.md format. [Unreleased] section always present.
• Feature branches per unit of work — /next creates worktree branches, /clean prunes them. No long-lived branches.
• gh CLI as the Git-ops interface — authenticated gh handles push and PR creation.
• Governance files as source of truth — REQUIREMENTS.md drives SPEC.md drives ROADMAP.md drives work, not the other way around. See Governance files.

Governance files

Symphonize assumes — and enforces — a four-file governance loop at the repo root:

File	Role
REQUIREMENTS.md	Problem-space requirements. What users need and why.
SPEC.md	Declarative target state. What the system does and why.
ROADMAP.md	Imperative work queue. What remains to close the gap.
CHANGELOG.md	Release history. What shipped, in Keep a Changelog format.

The loop: /symphonize:discover interviews the user and produces REQUIREMENTS.md. /symphonize:plan explores technical decisions and produces SPEC.md sections. /symphonize:roadmap breaks spec sections into ROADMAP.md workstreams as thin vertical slices. Each /next batch advances the roadmap, produces conventional commits, and opens a PR. A downstream release-please workflow (or melos for monorepos) consumes those commits to cut versioned releases and update CHANGELOG.md automatically.

Each command reads upstream deliverables but writes exactly one. When upstream documents are absent or thin, commands apply backpressure — filling small gaps inline, recommending the upstream command for large ones. Technical users can enter the pipeline at any point; the commands will pull them back as far as needed.

Cross-document traceability

Governance files use namespaced slug prefixes (§req:, §spec:, §road:) for grep-friendly cross-document references. Every spec section traces to a requirement; every roadmap workstream traces to a spec section. See CONVENTIONS.md for the full traceability chain.

Why in-repo?