Agents

OpenCorvus separates runtime identities from runtime templates. A caller always addresses an agent by its real identity; a template only supplies default prompt, model, tools, permissions, and session behavior.

Core identities

Core runtime identities are closed sets owned by the platform:

• Primary assistants are user-selectable top-level assistants such as coding, chat, control, and mission.
• Host agents are fixed platform coordinators. The task scheduler host is orchestrator.
• Helper agents are private platform services such as title or compaction helpers. They are not dispatch targets.

Unknown core identities fail immediately. OpenCorvus does not discover arbitrary local agent markdown files or create agents from inline config.

Goal is the user-facing name for a versioned Delivery Slice. It stores one delivery contract and acceptance surface; Task is the sole business-lifecycle owner.

Projected agents

Worker identities come from the active expert-squad package under:

.opencorvus/expert-squads/<namespace>/<squad-id>/

The manifest’s capability_projection.agents.<agent-id> key is a package worker’s exact identity. dispatch_agent.dispatch.target, the persisted WorkerTurnDescriptor, messages, tools, skills, Model Context Protocol providers, catalog rows, and skill mounts retain that ID. The sole platform worker is scheduler-only universal-build; it never appears in package agents, virtual workflows, catalog membership, or public projected_agent_ids.

Each projected worker declares a required base_role. The base role selects a core-owned Application Binary Interface (ABI) template seed for prompt, model, tools, permissions, session, and adapter behavior. It is not the running identity or an alias and cannot be used as a dispatch target unless the package explicitly declares the same string as an agent ID.

Manifest v2 gives every scheduler and worker one canonically sorted capability_refs array. Each entry is a typed capability:<kind>:<source>:<owner>:<local-ref> identity or a one-level CapabilitySet reference; package-owned sets are declared once under top-level capability_sets.

base_role sets an upper bound; it does not itself grant every base tool. An explicitly granted platform set such as build-base expands from the current platform registry, so its checklist member is now todo without editing each package. A direct checklist grant uses capability:tool:platform:tool-registry:todo. Keep direct refs, Skill required_tools, permission/tool switches and prompt examples aligned with the current tool contracts. Authorized general built-ins are directly callable; use discovery only for a needed specialist or extension that is not already callable. A package revision update does not rewrite an existing Task’s frozen package revision.

Identity and authorized capabilities are the primary Squad contract. virtual_workflows is optional reference guidance and may be omitted. The scheduler chooses actual dependencies, parallel work, local loops and conditional branches; several independent responsibilities may reuse one capability or suggested node:

"capability_projection": {
  "agents": {
    "security-reviewer": {
      "capability_refs": [
        "capability:capability_set:platform:tool-registry:integrity-base"
      ],
      "label": "Security reviewer",
      "base_role": "integrity",
      "execution_contract": "platform_integrity_review"
    }
  },
  "virtual_workflows": {
    "delivery-review": {
      "label": "Delivery review",
      "description": "Review completed delivery evidence.",
      "nodes": {
        "security-review": {
          "agent_id": "security-reviewer",
          "description": "Review the Task and cited Delivery Slice revisions.",
          "depends_on": []
        }
      }
    }
  }
}

This excerpt shows identity and planning fields; start from the generated portable expert-squad template for the complete strict manifest.

Develop an external squad

Omit virtual_workflows and use direct projected-Agent dispatch when no reference is useful. Requirements, Architect, Integrity, review, and Delivery Slice inputs are package-owned design choices justified by the domain responsibility graph. Registry and Software Development Kit (SDK) validate manifest shape, exact projected-agent/dependency references, canonical dependency order, and acyclicity only for explicit strategy: "dag"; they do not impose one role topology.

Use the Node-only authoring surface from the existing SDK to materialize a new source directory. The SDK’s runtime manifest v2 schema is the portable source consumed by both authoring and Registry. The writer validates completely, writes a same-parent staging directory, atomically renames it into place, and refuses an existing destination.

import { createOpenCorvusClient } from "@opencorvus-ai/sdk"
import {
  validateExpertSquadPackageDefinition,
  writeExpertSquadPackage,
  type ExpertSquadPackageDefinition,
} from "@opencorvus-ai/sdk/expert-squad-authoring"

const definition: ExpertSquadPackageDefinition = { manifest, files }
validateExpertSquadPackageDefinition(definition)
await writeExpertSquadPackage({ directory: sourceDirectory, definition })

const client = createOpenCorvusClient({ baseUrl, directory: projectDirectory })
await client.expertSquad.validateFolder({ sourceDirectory }, { throwOnError: true })
await client.expertSquad.importFolder(
  { sourceDirectory, replace: false, installationScope: "project" },
  { throwOnError: true },
)

Start from templates/portable-expert-squad-template in the repository for a complete concrete definition. Validation is read-only and uses the real Registry; import is a separate explicit Manager operation and does not activate the package. Folder and ZIP imports require installationScope: "project" | "global"; both scopes use the same Registry and manifest identity rules. Select the installed manifest ID through prompt_profile.active only when the project should use it.

Package-local resource names follow one grammar. Shared Skills, tools, and Model Context Protocol (MCP) servers use <squad-id>/shared/<name>; agent-local resources use <squad-id>/<agent-id>/<name> and can be projected only by that agent. A Skill is a directory containing SKILL.md; a tool is tools/<name>.ts or the matching agent-local path; an MCP server is mcp/<name>.jsonc or the matching agent-local path. Encode those names in typed capability_refs with the package manifest ID as owner. An MCP server ref mounts every capability declared by that server; alternatively grant exact mcp_tool, mcp_prompt, or mcp_resource leaves, never both for the same capability. Default MCP leaves use source project and owner default-mcp-registry.

Without a manual Squad selection, the native creator first searches installed candidates with capability_search and reads their real identities and capability grants with the directly available panel_expert_squad_inspect. It uses a Squad when the complete outcome is very well matched; otherwise it selects embedded Dynamic to generate Task-local expert names, responsibilities and boundaries mapped to the real dynamic-generalist or dynamic-builder capability identities. Manual selection wins. Task creation freezes exact package identity and grants before execution.

Optional references may declare strategy: "adaptive" | "dag" | "loop" | "choice", guidance, and node when or repeat_until text. The scheduler uses that guidance with actual evidence; the Host does not evaluate conditions or execute graphs. turn.workflow_subject may be omitted or used as exact reference provenance. Different references, direct dispatch and multiple independent instances may coexist in one Task. A continuation preserves its original Session and occurrence; new independent work receives its own dispatch. Acceptance depends on actual user obligations and capability evidence contracts.

Compose independent squads

A multi-squad delivery keeps five identities separate:

• the Mission owns the final user outcome and the dependent stage-Task ledger;
• a Task is one fixed-profile squad stage and one visible root session;
• a Goal is a versioned Delivery Slice contract inside that Task;
• an Expert Squad is a self-contained capability package fixed for the Task lifetime;
• an Agent is a role inside the active squad, not an implicit cross-squad stage.

Use a user-invoked coordination Skill when several squads cooperate. Mission creates only the earliest ready stage Task and gives it an explicit selected promptProfile, predecessor Task ID, and terminal accepted evidence; workflow references are optional. The Task keeps that Squad for its complete lifetime, creates only local Delivery Slices, and schedules actual responsibilities from evidence. After terminal acceptance, Mission creates the next fixed-profile Task.

The authoring SDK can validate this static composition contract against the exact manifests:

import {
  validateExpertSquadCollaboration,
  type ExpertSquadCollaborationDefinition,
} from "@opencorvus-ai/sdk/expert-squad-authoring"

const collaboration: ExpertSquadCollaborationDefinition = {
  schema_version: 1,
  stage_execution: "mission_task",
  id: "research-to-delivery",
  label: "Research to delivery",
  inputs: ["task-brief"],
  outputs: ["accepted-delivery"],
  stages: [researchStage, deliveryStage],
}

validateExpertSquadCollaboration({ definition: collaboration, manifests })

Each stage names an exact squad_id, workflow_id, earlier depends_on stages, and visible consumes/produces evidence keys. stage_execution: "mission_task" makes the ownership boundary explicit: the fixed-profile Task and its complete selected binding workflow own the stage. A stage workflow contains Task-level nodes and can pass exact Slice revision subjects. The validator is authoring-time integrity only: it does not select a squad, create a Mission Task or Slice, dispatch an agent, persist stage state, or auto-advance. Runtime truth remains Mission-owned Tasks, Task-local Slice revisions, visible messages and tool calls, each Task’s prompt_profile.active, and PromptProfileResolver.

Global installation checks the target manifest ID against every project directory already registered with OpenCorvus before writing. A previously unknown directory is checked when it is first opened; OpenCorvus does not scan unrelated user directories or maintain a second package identity index.

Select one package through prompt_profile.active. The active package is resolved once into scheduler and worker capabilities. Inactive packages remain discoverable and selectable through catalog manifest and selector metadata, but they do not contribute active runtime prompts, tools, skills, providers, mounts, or runtime hashes.

Package tool trust

Installing an expert-squad package that contains executable tools is an explicit trust decision. Package tools are trusted executable extensions, in the same trust class as installed plugins, and run inside the OpenCorvus host process with the capabilities granted by the active projection.

OpenCorvus verifies the exact compiled bytes, declared dependency closure, package ownership boundaries, and SHA-256 digests before loading a package tool. Those checks provide deterministic and portable execution; they are not a security sandbox for hostile code. Do not install executable packages from an untrusted source. Supporting untrusted package code would require a separate process boundary and capability protocol rather than another in-process loader.

The tool({ args }) authoring API constructs one complete object input schema inside the package bundle’s own Zod runtime. OpenCorvus projects that schema directly for local validation and provider conversion; package tools must not export a second runtime schema authority.

Package tools that consume compiled webpage evidence must import CompiledWebpageStructureSchema and CompiledWebpageAssetGraphSchema from @opencorvus-ai/plugin. These schemas are the single compiled-webpage ABI; copying their shape into a squad creates a conflicting contract.

Built-in Base, Advanced, and Research Studio

For ordinary Base delivery, the accountable Task owner produces directly. The execution-verification graph contains one independent Tester; delegated Developer production belongs to the other graphs when their source-investigation or parallel-work boundaries are actually needed.

base is the default built-in expert-squad package and Advanced’s compact alternative. It offers three workflows: execution-verification for delivery without unresolved material source prerequisites, source-planned-execution-verification for irreversible actions requiring source-authority planning before execution, and planner-parallel-delivery for a useful independent research partition. The parallel workflow runs Delegated Worker base-planner first, then makes Explore base-researcher and Build base-developer dependency-ready together, and runs Delegated Worker base-tester after the implementation node settles so verification observes a result that has stopped changing. The workers own non-overlapping research, product/generated-output, and test/checker partitions; the Tester’s dependency is ordering only, so it takes its acceptance scope from the request and the plan rather than from the implementation’s report, and no worker manufactures a serial report handoff. UI acceptance remains implementation-owned real-page evidence, not a separate Visual Reviewer node. Base does not project Integrity or Visual Quality Assurance identities and does not create RequirementSet, ContractGraph, Goal, or Delivery Slice planning facts.

advanced is the independently selectable full built-in software-development team for request interpretation, requirements, architecture, workload review, source and external research, interface investigation and design, implementation, testing, visual review, system-integrity review, and claim verification. Every delivery graph retains Requirements → Architect traceability. Independent investigation starts together; after architecture, workload and delivery work share a frontier; after implementation, testing and independent review share a frontier whenever their Artifact inputs permit it. These are package-owned dynamic identities, not core roles.

research-studio is the independently selectable built-in research-delivery team. Its Planner, Deep Researcher, Evidence Analyst, Fact Checker, and Report Writer execute the exact direct-writing, evidence-synthesis, or full-research manifest workflow and produce a durable cited report. It is embedded directly and is not released through Market or project payload provisioning.

universal-build remains the platform implementation and repository-repair identity for work outside a narrower package-owned implementation contract. Advanced delivery workflows use their own Build implementation-engineer and Delegated Worker test-engineer; this does not remove the scheduler-only platform capability.

Selecting another expert-squad package replaces the current package’s complete projection. Packages do not inherit or combine Base, Advanced, Research Studio, or sibling agents, prompts, skills, tools, mounts, Model Context Protocol resources, or guidance graphs. Resolver-owned universal-build remains available only to the scheduler and consumes runtime-template/top-level configuration rather than package agent overrides.

Expert-squad manifest versions use YYYY.MM.DD.N, where N is that Squad’s positive revision ordinal for the date. The Registry rejects arbitrary SemVer, bare dates, timestamps, invalid calendar dates, and zero or leading-zero ordinals.

Dispatch

Only the Orchestrator dispatches projected workers. It calls dispatch_agent with an exact active agent ID. The runner resolves that projection, derives its runtime template from base_role, creates the worker session, persists an immutable WorkerTurnDescriptor, and installs a process-local runtime contract for that Turn. The process-local contract is execution machinery: its absence cannot erase the Session, durable facts, or visible messages, and it is not Task liveness.

virtual_workflows is a frozen, binding scheduler contract rather than an execution engine or state machine. The Orchestrator selects the matching graph through visible reasoning and must respect its complete node/dependency order. The graph cannot select itself, store step status, auto-advance, or dispatch agents; real scheduling and refusal remain visible Orchestrator tool calls.

Facts, Turns, and acceptance

Projected tools write durable domain facts; they are not terminal submit/finalizer calls. A normal model stream end is only a physical Turn observation. The visible final assistant message owns the worker’s narrative handoff, limitations, blockers, and stable references. Git changes, command/test exits, process facts, and attachment consumption are recorded independently as Host observations.

Dispatch lineage and execution attempts are immutable physical evidence identities, not business lifecycle. The Orchestrator evaluates persisted Sessions, real final message/error locators, domain artifacts, reviewer facts, and Host observations directly. Each Task completion appends a typed decision artifact citing accepted current Slice revisions, workflow selection, package revision, and exact evidence. The Goal panel derives progress from those facts and never writes Goal status, retry, attempt, result, or workspace state.

See Extensions for the expert-squad package boundary and Config for selecting an active package and configuring core runtime templates.