# Configuration
This document covers target-repo bootstrap, generated files, and the runtime
configuration that `opensymphony run` expects.
## Bootstrap
Use `opensymphony init` from the target repository root:
```bash
cd /path/to/target-repo
opensymphony init
```
`opensymphony init` is the primary setup path for existing repositories. It:
- fetches the current starter files from the template repo's raw GitHub URLs
- copies missing files into the target repo
- merges an existing `AGENTS.md`
- prompts before overwriting other conflicting files
- fills the `WORKFLOW.md` clone hook from `git remote` when possible
- offers to fill the Linear project slug/key in `WORKFLOW.md`
- creates or updates `.gitignore` to ensure `.opensymphony*` stays untracked
- can optionally scaffold OpenHands AI PR review
- can configure the GitHub Actions variables, label, and optional review secret
automatically when `gh` is installed and can access the repository
For repositories that are already initialized, `opensymphony update` is the
maintenance path for template-owned skills:
```bash
cd /path/to/target-repo
opensymphony update
```
The command first checks whether the installed CLI is older than the newest
published `opensymphony` release and only runs `cargo install opensymphony`
when it actually needs to. If the current directory already looks like an
OpenSymphony target repo because it has both `WORKFLOW.md` and `config.yaml`,
the command then refreshes changed or new files under `.agents/skills/`.
The template repository is still the upstream source of those starter assets,
but it is an implementation detail of `opensymphony init`, not a required
manual setup step:
- [kumanday/OpenSymphony-template](https://github.com/kumanday/OpenSymphony-template)
- [Raw template base](https://raw.githubusercontent.com/kumanday/OpenSymphony-template/refs/heads/main/WORKFLOW.md)
## Files Added By `init`
Core bootstrap payload:
- `WORKFLOW.md`
- `AGENTS.md`
- `config.yaml`
- `.gitignore` created or updated to include `.opensymphony*`
- `.agents/skills/` copied recursively, including skill-local `references/`, `scripts/`, and similar helper files
- `.agents/skills/linear/references/`
- `.github/CODEOWNERS`
- `.github/pull_request_template.md`
## Refreshing Template Skills
`opensymphony update` only refreshes template-managed files under
`.agents/skills/`.
It does not:
- rerun the interactive `init` prompts
- modify `WORKFLOW.md`
- merge or rewrite `AGENTS.md`
- copy `.github/*` bootstrap files
- delete repo-local extra skills that are not in the template tree
Optional AI PR review scaffolding:
- `.github/workflows/ai-pr-review.yml`
- `.agents/skills/custom-codereview-guide.md`
## Labels
If you enable AI PR review and `gh` is available with repository access,
`opensymphony init` can create the `review-this` label for you. If automation is
skipped, create it once per repository:
```bash
gh label create "review-this" --description "Trigger AI PR review" --color "d73a4a" --force
```
## Review The Generated Workflow
After `init`, review `WORKFLOW.md` and `config.yaml`.
Important fields:
| `tracker.project_slug` | Linear `Project.slugId` from the project URL | - | `my-project-5250e49b61f4` |
| `workspace.root` | Where to store per-issue workspaces | - | `~/.opensymphony/workspaces` |
| `openhands.conversation.agent.llm.model` | LLM model to use | `LLM_MODEL` | `openai/accounts/fireworks/models/glm-5p1` |
For Linear trackers, `tracker.project_slug` should store the project's
`slugId`, not a `team/project` path.
## Environment Variables
OpenSymphony uses standard OpenHands environment variable names.
Fireworks example via the OpenAI-compatible provider adapter:
```bash
export LLM_MODEL="openai/accounts/fireworks/models/glm-5p1"
export LLM_API_KEY="fw-..."
export LLM_BASE_URL="https://api.fireworks.ai/inference/v1"
```
The workflow supports `${VAR}` syntax for environment variable substitution in
the front matter:
```yaml
openhands:
conversation:
agent:
llm:
model: ${LLM_MODEL}
```
## Conversation Condensation
Optional conversation condensation is enabled by default per workflow to reduce
long-history context pressure before the agent-server hits the model window:
```yaml
openhands:
conversation:
agent:
condenser:
max_size: 240
keep_first: 2
```
OpenSymphony forwards an OpenHands `LLMSummarizingCondenser` that reuses the
conversation agent's LLM settings. The condenser is enabled by default with
`max_size: 240` and `keep_first: 2`. To disable it, set `enabled: false`.
## Runtime Config
`opensymphony init` also copies a starter `config.yaml` next to the target
repository `WORKFLOW.md`.
Minimal local-supervised example:
```yaml
control_plane:
bind: 127.0.0.1:2468
openhands:
tool_dir: ~/.opensymphony/openhands-server
```
Provision that app-managed directory with:
```bash
opensymphony install openhands
```
When your workflow points at an external OpenHands agent-server with
`openhands.transport.session_api_key_env`, `config.yaml` can omit
`openhands.tool_dir`.
Use [examples/target-repo/config.yaml](../examples/target-repo/config.yaml) as
the starting template if you want to inspect the checked-in example.
[examples/configs/local-dev.yaml](../examples/configs/local-dev.yaml) is a
developer-facing doctor fixture for this repository. It is not the runtime
config that `opensymphony run` looks for in a target repo.
## OpenHands PR Review
If you opt into OpenHands PR review during `init`, the CLI will try to
configure the GitHub Actions variables, label, and optional review secret for
you when:
- `gh` is installed
- `gh` can access the target repository
- you approve the automation prompt
If any of those are missing, `init` falls back to a short checklist plus the
manual `gh` commands. The full verification and branch-protection guidance
lives in the OpenSymphony docs at
[ai-pr-review-human-setup.md](ai-pr-review-human-setup.md); `init` does not
copy that guide into the target repository.