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
  → policy plugin
  → 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": "Run pytest tests/unit -q after Python changes.",
    "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;
  • commands or test gates 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.

Plugin as policy

Section titled “Plugin as policy”

When the repository is important enough, the plugin becomes a project policy surface. It can declare test gates 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",
    ],
    "quality_gates": {
        "tests": {
            "run_command": "pytest tests/unit -q",
            "fail_keyword": "FAILED",
            "timeout": 120,
        },
    },
    "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.”

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 template. Copy it into a project when that project needs tuning. Workspace prompt overrides are useful when several repositories in the same project group share the same operating language.

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.

Next

Section titled “Next”