Skip to content
Orcho Docs

Project Tuning and Plugins

Project tuning is how Orcho stops treating a repository as an anonymous folder of files. Start with the smallest useful tuning, then add stronger policy only when the project needs it.

generic mode
  → minimal plugin
  → scheduled verification
  → prompt overrides
  → profiles, gates, runtime adapters

Minimal tuning

Section titled “Minimal tuning”

A minimal plugin gives Orcho the project facts a human reviewer would normally say out loud before starting work.

project/
└── .orcho/
    └── multiagent/
        └── plugin.py
PLUGIN = {
    "name": "Checkout API",
    "language": "Python",
    "architecture": "FastAPI. Routes in app/routes/, services in app/services/.",
    "file_hints": ["app/routes/", "app/services/", "tests/"],
    "build_prompt_extra": "Keep route handlers thin and validate at boundaries.",
    "review_focus_extra": "Check auth, validation, migrations, and API compatibility.",
}

This layer is not about clever customization. It is about giving Orcho enough project context to choose better files, better checks, and better review questions.

What belongs in a plugin

Section titled “What belongs in a plugin”

Good plugin data is operational:

  • project name and stack;
  • architecture boundaries;
  • important directories;
  • generated or companion files that may change with source edits;
  • environments and native commands that prove the change;
  • project-specific review concerns;
  • trust policy for local skills when a repository intentionally uses them.

Avoid vague preference dumps. A plugin field should help a phase choose a file, command, gate, or review lens.

Existing CI is evidence, not a substitute

Section titled “Existing CI is evidence, not a substitute”

Projects with established tests, linting, builds, static analysis, and CI have the strongest starting evidence for a plugin. Reuse those project-native commands. Do not create a parallel Orcho-specific quality suite and do not remove the independent CI gate.

CI and the Orcho contract operate at different boundaries:

Existing CIConfigured Orcho contract
Independently protects the repository after push.Selects relevant existing proof inside the task lifecycle.
Reports a job result to the source host.Records immutable command receipts against the run’s verification subject.
Usually waits until delivery has reached the remote branch.Can route a fixable failure to repair before delivery.
Treats infrastructure according to CI job policy.Can separate repairable code failure from an operator handoff for environment, service, or credential failure.

The plugin also establishes verification ownership. A recurring broad command belongs to the engine schedule once, not in every task’s prose and not as a planner-created implementation criterion. Implementation agents may still run focused tests or lint changed files for fast feedback; the engine owns the official broad proof and durable receipt.

Plugin as policy

Section titled “Plugin as policy”

When the repository is important enough, the plugin becomes a project policy surface. It can declare scheduled verification and allowed companion modifications so the run can separate real scope drift from expected generated changes.

PLUGIN = {
    "name": "Checkout API",
    "language": "Python",
    "allowed_modifications": [
        "poetry.lock — derived from pyproject.toml",
        "tests/golden/*.json — regenerated snapshots",
    ],
    "verification_envs": {
        "project": {"python": "python"},
    },
    "work_mode": "pro",
    "verification": {
        "default_env": "project",
        "commands": {
            "lint": {
                "run": ["python", "-m", "ruff", "check", "."],
                "cost": "fast",
            },
        },
        "gate_sets": {
            "hygiene": {
                "commands": ["lint"],
                "default_policy": "require",
            },
        },
        "selection": [{"always": ["hygiene"]}],
        "schedule": [{
            "after_phase": "implement",
            "gate_sets": ["hygiene"],
            "action": "repair_loop",
        }],
    },
    "review_focus_extra": "Reject missing negative-path tests for API validation.",
}

This is the difference between “agent, please be careful” and “this repository has an explicit operating contract.”

The verification contract declares native commands once, selects them for a run, schedules their engine-owned execution, and records immutable receipts. Cost is an independent four-value axis: fast, moderate, slow, or unknown. It never changes selection, policy, or failure consequence automatically, but it should shape the contract you author: fast repairable proof usually belongs after implementation; moderate and slow proof should be narrowed by semantic selection; final integration proof belongs at delivery; unknown or operational checks stay operator-owned until measured.

Follow Set up scheduled verification for the complete cost-to-selection-to-schedule matrix and authoring path. The older quality_gates registry is an extension surface for custom post-phase handlers; it is not the primary way to declare project-native lint, test, build, or analysis commands.

Prompt overrides

Section titled “Prompt overrides”

Plugin fields tune facts and policy. Prompt overrides tune a composable prompt part when the default behavior repeatedly misses a project-specific pattern.

project/.orcho/multiagent/prompts/tasks/build.md
project/.orcho/multiagent/prompts/roles/code_reviewer.md
project/.orcho/multiagent/prompts/formats/review_json.md

Use them sparingly. Prefer plugin.py for project facts and verification policy. Use prompt overrides when you need to change how a role, task, or format behaves.

Skills

Section titled “Skills”

Skills are the next customization layer after project facts.

A project plugin can say “this repository is a FastAPI service; routes live here; run these checks.” A skill can say “when a subtask is about API contract compatibility, use this repeatable review procedure and these reference files.”

project/.agents/skills/api-contract-review/SKILL.md
workspace-orchestrator/.agents/skills/pytest-fixtures/SKILL.md
~/.agents/skills/security-audit/SKILL.md

Orcho discovers skills into a registry, exposes a compact roster to planning, and injects the full skill only when a phase or subtask binds it. Project-local skills are trust-gated; do not treat copied repository instructions as trusted without an operator or project policy decision.

Use Skill registry when project tuning is no longer enough and you need repeatable specialist procedures.

Workspace-level defaults

Section titled “Workspace-level defaults”

orcho workspace init creates workspace-visible extension rails under:

workspace-orchestrator/.orcho/multiagent/
├── plugin.py
└── prompts/
    ├── roles/
    ├── tasks/
    └── formats/

The workspace plugin.py is a language-neutral template. Copy it into a project, inspect that repository, and replace the empty verification skeleton with real project-native commands. The adjacent agent guidance explains verification ownership and task authoring; merge it into the project’s root AGENTS.md and keep CLAUDE.md as a shim rather than maintaining two policies. Workspace prompt overrides are useful when several repositories in the same project group share the same operating language.

Let an agent accelerate discovery

Section titled “Let an agent accelerate discovery”

Two setup aids reduce the mechanical work without delegating policy.

First, ask Orcho for a read-only candidate from repository markers:

Terminal window
cd /path/to/project
orcho workspace fine-tune --dry-run

Fine-tune proposes initial environments and commands. It writes nothing and does not infer a complete selection, schedule, or failure policy.

Second, merge the generated agent rules into the project’s existing root AGENTS.md, preserve the existing instructions, and keep the root CLAUDE.md shim. Then ask the coding agent to inspect manifests, package scripts, CI workflows, developer documentation, required services, and worktree constraints before drafting the plugin:

Inspect this repository and configure the generated Orcho plugin from
repository evidence. Reuse project-native commands, classify their cost,
propose selection, schedule, policy, and failure routing, and report every
unresolved assumption. Do not invent commands or silently weaken failures.

The agent may prepare the diff and execute bounded candidate checks. The engineer remains the authority: review exact commands and environments, decide which checks are load-bearing, approve selection, schedule, policy, and failure consequences, then inspect the normalized contract:

Terminal window
orcho quality-gates

Do not rely on the configured gates until that review is complete. Agent assistance shortens discovery and drafting; it does not decide what is authoritative or release-blocking.

What not to put here

Section titled “What not to put here”

Do not use project tuning to hide task requirements. A task file should still state the actual work, acceptance criteria, and verification expectation.

Do not use prompt overrides for facts that belong in code or configuration: runtime routing, parser contracts, and public protocol behavior should remain owned by Orcho’s code-level contracts and profile/runtime configuration.

Deep reference

Section titled “Deep reference”

The canonical engineering doc lives with the code:

Next

Section titled “Next”