Skip to content
Orcho Docs

Workspace Model for Orcho

An Orcho workspace is the operating folder behind one project or a related 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.

The normal adoption path starts inside an existing repository:

Terminal window
cd ~/www/my-project
orcho workspace init

Orcho registers the repository in place and creates a deterministic managed workspace under the platform’s user-data directory. Nothing is moved into an Orcho-specific parent. CLI commands launched from the project resolve that workspace automatically.

For a product already organized as several related repositories, initialize their common root instead:

Terminal window
orcho workspace init ~/work/my-product

A non-project root keeps the explicit shared topology:

my-product/
├── api/
│   └── .orcho/
│       └── multiagent/
│           └── plugin.py        configured project contract
├── web/
└── workspace-orchestrator/
    ├── orcho-env.sh
    ├── .orcho/
    │   ├── config.local.json
    │   ├── .task-files/
    │   └── multiagent/
    │       ├── plugin.py        template, copy into a project to tune it
    │       ├── AGENTS.md        agent rules for configuring that plugin
    │       ├── CLAUDE.md        shim to the same rules
    │       └── prompts/
    │           ├── roles/
    │           ├── tasks/
    │           └── formats/
    ├── .agents/
    │   └── skills/              optional shared skill packages
    └── runspace/
        └── runs/

The init command creates the operating surface, records local config, prepares runspace/, prints shell and MCP setup, registers projects, 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 plugin and agent-guidance templates.

These topologies serve different moments:

TopologyUse it when
Managed single-project workspaceYou found Orcho and want to connect one repository without reorganizing it.
Shared product workspaceRelated repositories already share, or can deliberately adopt, one product root for aliases and cross-project work.

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 application source, whether that home is managed automatically or placed under an explicit product root.

SurfacePurpose
workspace-orchestrator/The operating root for one project or 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 language-neutral plugin template. Copy it into a project, then configure it from repository evidence.
.orcho/multiagent/AGENTS.mdAgent guidance for discovering native checks, classifying cost, choosing policy, and preserving verification ownership.
.orcho/multiagent/CLAUDE.mdA shim to the same guidance, so the policy has one maintained source.
.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 a demand to reorganize source. It is the control boundary 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 configured project plugin, Orcho runs in generic mode — fine for a first mono-run, but insufficient for durable repository-specific readiness. workspace init already creates the safe scaffold. Adapt it into one file per project, plugin.py: project identity and architecture, file hints, allowed companion modifications, scheduled verification, 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. Generated scaffold only: generic Orcho behavior.
  2. Minimal plugin: project identity, stack, paths, and test hints.
  3. Policy plugin: scheduled 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. Copy the plugin template, merge its agent guidance into the project root, and add a minimal project plugin from observed repository facts.
  4. Review the configured commands and gate consequences as an engineer, then inspect the resolved contract with orcho quality-gates.
  5. Add shared skills only when the same specialist procedure repeats.
  6. Move into profile and gate policy only when the task class justifies it.
  7. Use workspace-level prompt overrides only when generic prompts repeatedly miss a project-specific pattern.

Deep reference

Section titled “Deep reference”

The canonical engineering doc lives with the code:

Next

Section titled “Next”