Best Practices
Effective workflows
Single session vs Orchestration vs Arena, prompt reuse, review, memory, and sync levels.
Operon does not force one way of working. The same project can be driven by a single focused session, a multi-step Orchestration plan, or an Arena where several agents compete for the same goal. Picking the right shape for the task — and reviewing the result before it ships — is most of what makes an AI-assisted workflow feel calm instead of chaotic.
Choosing an execution shape
Match the shape to the task. A well-scoped change is a single session. A larger goal that breaks into ordered steps is Orchestration. A goal where you want to compare approaches — or you are not sure which agent will do best — is Arena.
| Approach | Best for | How it runs |
|---|---|---|
| Single session | One focused change with a clear goal and scope. | You drive one agent directly; simplest and most common. |
| Orchestration | A larger goal that decomposes into ordered subtasks. | A sequential plan advances one subtask at a time as each completes. |
| Arena | Comparing approaches, or picking the strongest agent for the job. | Two to four agents run the same goal in isolated worktrees; you judge the results and pick the winner. |
- Reach for a single session first — most work does not need more than one agent.
- Use Orchestration when the goal has natural stages, so each subtask is a smaller, reviewable unit.
- Use Arena when the value is in the comparison: each agent works in its own worktree, so you can judge them side by side on real signals — cost, files touched, and diff quality — before picking a winner. The losing worktrees are reclaimed, and uncommitted work is preserved.
Note
In Arena, the human always picks the winner. Operon can surface an advisory judge recommendation, but the final call — and merging the winning branch — is yours.
Reuse prompts with the Prompt Library
The prompts that work well are worth keeping. The Prompt Library stores reusable prompts you can search, tag, and drop into a session or straight into the running terminal. Open it with the Cmd+L shortcut, pick a prompt, and send it — no re-typing your best instructions every time. Curated built-in prompts ship alongside the ones you save.
- Save prompts that produced good results so they become a repeatable playbook.
- Tag them so you can find the right one fast when you are mid-session.
- Send a saved prompt to the running agent, copy it into a new goal, or edit it before use.
Review before you ship
When the agent finishes, do the review inside Operon rather than jumping to a separate tool. The Changes workbench walks the whole finishing arc without leaving the app: read the diff, stage files (or individual hunks), commit, push, and open a pull request. You can also annotate lines and send those comments back to the agent as a single grouped prompt for another pass.
- 1
Read the diff
Open the Changes tab and click a file to see exactly what changed against your working tree.
- 2
Stage what you want
Stage whole files or individual hunks so a commit contains only the changes you have actually reviewed.
- 3
Commit and push
Write a message, commit, and push — with an ahead/behind indicator so you know where your branch stands.
- 4
Open a pull request
Generate a PR draft from the session and open it, all from inside Operon.
Tip
Always read the diff before committing. The agent’s guardrails keep it honest during the run, but a human review is the last gate before code ships — and staging by hunk lets you keep the good changes and drop the rest.
Let project knowledge accumulate
Decisions, plans, and context persist across sessions, and Operon can distill project knowledge into memory that gets injected into future sessions and written to an AGENTS.md file in the repo. The practice here is simple: let it build. The more sessions you run, the better the memory that primes the next agent — so a new session starts already aware of prior decisions instead of relearning them.
- Prior decisions are surfaced back to new sessions, so the agent inherits context instead of guessing.
- The generated AGENTS.md keeps a durable, in-repo record of how the project is meant to be worked on.
- Because decisions sync to the cloud, that knowledge can span your machines and, on a team, your teammates.
For teams: choose sync levels
On a team, decide how much leaves each machine. Sync is opt-in, and by default includes prompt text, tool inputs/outputs, and code diffs alongside events, tasks, decisions, and session information — the per-project code-content toggle narrows that to metadata only. Choosing a sync level lets you share exactly the outcomes a team needs (shared decisions, progress, analytics) without over-sharing. The web dashboard then reads that synced data so the team can review and collaborate without touching anyone’s source — your repository itself is never uploaded as files.
Note
Your repository is never uploaded as files at any level. The per-project code-content toggle controls whether prompt/response text, tool I/O, and diffs sync alongside metadata — pick the level and toggle that gives your team the visibility it needs and no more.