# Development Guide
This document is for contributors working on OpenSymphony itself. For user
setup and operator flows, start with the [README](../README.md) and the docs
linked there.
If you are developing OpenSymphony itself, clone the repository and install from the checkout instead:
```bash
git clone https://github.com/kumanday/OpenSymphony.git && cd OpenSymphony
cargo install --path .
```
## Repository structure
```text
OpenSymphony/
├── Cargo.toml
├── crates/
│ ├── opensymphony-cli/
│ ├── opensymphony-control/
│ ├── opensymphony-domain/
│ ├── opensymphony-linear/
│ ├── opensymphony-openhands/
│ ├── opensymphony-orchestrator/
│ ├── opensymphony-testkit/
│ ├── opensymphony-tui/
│ ├── opensymphony-workflow/
│ └── opensymphony-workspace/
├── docs/
├── examples/
├── scripts/
├── tools/
│ └── openhands-server/
├── AGENTS.md
└── README.md
```
Only the repository-root `Cargo.toml` is a package manifest. The
`crates/opensymphony-*` directories are internal subsystem module trees that
compile into the one public `opensymphony` package.
## Design summary
OpenSymphony is the Rust implementation of the Symphony orchestration model.
Key choices:
- Rust owns orchestration, retries, workspace lifecycle, and tracker
reconciliation
- OpenHands is the execution substrate
- Linear reads happen through the internal `opensymphony_linear` module
- agent-side Linear writes use the repo-local GraphQL helper assets copied by
`opensymphony init`
- FrankenTUI is optional and must not affect correctness
## Milestones
### M1 Foundation and contracts
Workspace bootstrap, workflow/config loading, domain model, state machine.
### M2 OpenHands runtime adapter
Local server supervisor, REST client, WebSocket stream, session runner.
### M3 Symphony orchestration core
Workspace lifecycle, Linear adapter, scheduler, GraphQL-backed repo harness.
### M4 Operator UX and repo harness
Control plane, FrankenTUI, generated issue context artifacts.
### M5 Validation and local packaging
Fake server, live tests, doctor command, packaging.
## Required checks
```bash
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
```
## Useful commands
```bash
# Format and lint
cargo fmt --check
cargo clippy --all-targets -- -D warnings
# Full tests
cargo test
# CLI-focused checks
cargo test --test init
cargo test --test help
# Doctor
cargo run -- doctor --config examples/configs/local-dev.yaml
# Install and smoke-test
cargo install --path . --locked
./scripts/smoke_local.sh
```
## Template ownership
`opensymphony init` bootstraps target repositories from
`OpenSymphony-template`.
Important rule:
- copy `.agents/skills/` recursively, not file-by-file, so helper scripts,
query assets, and reference docs survive intact
- keep `opensymphony update` aligned with the same recursive copy rule so
existing target repos can refresh the template-managed skill tree without
rerunning the full bootstrap flow
When you change shared target-repo assets, update the template first and then
make sure the `init` and `update` flows still copy the full tree.
## Linear development rules
- keep orchestrator-side Linear logic inside the `opensymphony_linear` module tree
- keep agent-side Linear usage in the template-owned `.agents/skills/linear/`
tree
- prefer checked-in GraphQL query files over inline ad hoc mutations
- do not reintroduce a separate bridge layer for agent-side Linear writes
## Versioning
OpenSymphony `1.0.0` is the compatibility boundary for the GraphQL-only Linear
rewrite.
Breaking changes in this line include:
- removal of the old workflow-owned Linear bridge configuration
- removal of the bridge CLI entrypoint
- provider-agnostic AI review configuration via `AI_REVIEW_API_KEY`
## Document map
- `AGENTS.md`
- `docs/architecture.md`
- `docs/configuration.md`
- `docs/openhands-agent-server.md`
- `docs/linear-and-tools.md`
- `docs/operations.md`
- `docs/testing-and-operations.md`
- `docs/repository-layout.md`
- `docs/migration-1.0.0.md`
## Current model
- COE-280 contributed: PR #54: Support workflow-owned OpenHands runtime overrides (merge `5663898`)
- COE-281 contributed: PR #55: COE-281: support path-prefixed OpenHands URLs and MCP config (merge `a50e435`)
- COE-282 contributed: PR #52: Support workflow-owned OpenHands conversation reuse policy at runtime (merge `ad111a3`)
- COE-287 contributed: PR #48: Add opensymphony debug command for issue conversations (merge `021f5ad`)
- COE-294 contributed: PR #58: COE-294: detect LLM config drift and rehydrate conversations (merge `5ab7015`)
## Important invariants
- Preserve the behavior described in the recent captured changes unless current code and tests show it has changed.
- Use capsule source refs to inspect the original PR or Linear issue when context is ambiguous.
## Operational flow
```mermaid
flowchart TD
memory["Captured issue memory"] --> area["Development Guide"]
area --> docs["docs/DEVELOPMENT.md"]
```
## Known gotchas
- No area-specific gotchas were inferred from the selected memory.
## Recent changes
- COE-280: Support workflow-owned OpenHands auth, provider, and launcher overrides at runtime
- COE-281: Support path-bearing OpenHands base URLs and MCP config at runtime
- COE-282: Support workflow-owned OpenHands conversation reuse policy at runtime
- COE-287: Add opensymphony debug command for conversational session debugging
- COE-294: Detect LLM config changes and rehydrate conversations with updated env vars
## Source refs
- COE-280
- COE-281
- COE-282
- COE-287
- COE-294