Skip to content
Orcho Docs

Workspace model

An Orcho workspace is the operating folder for a project group. It is not the project repository itself. It holds run state, local Orcho settings, generated worktrees, prompt override rails, task-file conventions, and MCP setup hints.

Start by creating the workspace beside the repositories you want Orcho to work with:

Terminal window
orcho workspace init ~/www/my-org
source ~/www/my-org/workspace-orchestrator/orcho-env.sh

The init command is the birth event for the operating surface. It creates the workspace-orchestrator/ folder, records local config, prepares runspace/, prints the environment setup line, detects projects when it can, and exposes safe extension points. Use --dry-run to inspect what would be created. Use --no-scaffold only when you intentionally want the bare runtime folders without the extension-point templates.

my-org/
├── api/
│   └── .orcho/
│       └── multiagent/
│           └── plugin.py        optional project tuning
├── web/
└── workspace-orchestrator/
    ├── orcho-env.sh
    ├── .orcho/
    │   ├── config.local.json
    │   ├── .task-files/
    │   └── multiagent/
    │       ├── plugin.py        template, copy into a project to tune it
    │       └── prompts/
    │           ├── roles/
    │           ├── tasks/
    │           └── formats/
    ├── .agents/
    │   └── skills/              optional shared skill packages
    └── runspace/
        └── runs/

Why keep it separate?

Section titled “Why keep it separate?”

The workspace is operational state. Your project repository is product code.

Keeping them separate makes it easier to:

  • inspect run artifacts without committing them;
  • run Orcho against several sibling repositories;
  • preserve delivery diffs;
  • recover from interrupted runs;
  • share a project group without mixing run state into source history;
  • keep local MCP and runtime setup out of product source.

What workspace init gives you

Section titled “What workspace init gives you”

orcho workspace init gives Orcho a home for work that should not live inside one application repo.

SurfacePurpose
workspace-orchestrator/The local operating root for this project group.
runspace/runs/Recorded run state, output logs, events, receipts, and generated worktrees.
orcho-env.shShell setup so orcho status, orcho evidence, and follow-up commands resolve the same workspace.
.orcho/config.local.jsonWorkspace-local project registration and local settings.
.orcho/multiagent/plugin.pyA visible plugin template. Copy it into a project when that project needs tuning.
.orcho/multiagent/prompts/Workspace-level prompt override rails for roles, tasks, and formats.
.agents/skills/Optional shared skill packages for repeatable specialist procedures.
.orcho/.task-files/Convention point for reusable task files before they are copied into a project.

This is why workspace setup belongs early in the docs. It is not only filesystem hygiene. It is the place where Orcho separates project code, delivery state, project tuning, and operator control.

Checkout isolation policy

Section titled “Checkout isolation policy”

Orcho distinguishes the canonical project repository from the checkout used by a specific run.

ConceptWhat it means
{project}The target repository: the durable source tree the run is about.
{checkout}The current Orcho-provided checkout: either a run-owned worktree or the project checkout itself.

With per-run worktree isolation, agents and verification run in {checkout}, while {project} stays untouched until the delivery boundary. The run records the worktree path, base ref, diff, and receipts, so review and repair can keep talking about the same subject.

With isolation off, {checkout} and {project} are the same folder. That mode is simpler and useful for read-only inspection, current-diff review, or small intentional edits, but it also means the worker is operating directly in the target repository.

The full policy — per_run vs off, per-profile defaults, and the dirty-checkout intake (include / exclude / commit / halt) when the project has uncommitted changes — lives in Profile and gate policy. This page only fixes the {project} vs {checkout} vocabulary those rules use.

Project tuning lives in the plugin

Section titled “Project tuning lives in the plugin”

Without a plugin, Orcho runs in generic mode — fine for a first mono-run, but a real repository usually needs a little project knowledge. That knowledge lives in one file per project, plugin.py: project identity and architecture, file hints, allowed companion modifications, quality_gates, extra plan/implementation/review instructions, and project skill trust.

In the workspace layout, the plugin and its prompt overrides sit next to the project it tunes:

project/.orcho/multiagent/plugin.py
project/.orcho/multiagent/prompts/tasks/build.md
project/.orcho/multiagent/prompts/roles/code_reviewer.md
workspace-orchestrator/.orcho/multiagent/prompts/formats/review_json.md

This page is about where that tuning lives. For the plugin’s fields, real PLUGIN = {…} examples, and how minimal identity grows into a policy contract, read Project tuning and plugins.

Read the layers as a ladder:

  1. No plugin: generic Orcho behavior.
  2. Minimal plugin: project identity, stack, paths, and test hints.
  3. Policy plugin: gates, allowed modifications, review focus, and local trust.
  4. Skill registry: shared domain procedures routed to phases or subtasks.
  5. Prompt overrides: targeted changes to role, task, or output-format behavior.
  6. Profiles, runtime adapters, and MCP control: expert surfaces for changing run shape, worker routing, and external control.

First-run rule

Section titled “First-run rule”

For the first run, choose one project and one task. Add tuning only when the basic lifecycle is clear.

The healthy path is:

  1. Run orcho workspace init.
  2. Run one mono task in generic mode.
  3. Add a minimal project plugin.
  4. Add shared skills only when the same specialist procedure repeats.
  5. Move into profile and gate policy only when the task class justifies it.
  6. Use workspace-level prompt overrides only when generic prompts repeatedly miss a project-specific pattern.

Next

Section titled “Next”