Orca2 OpenCode Orchestration Plugin

NOTE

This is an early release under active development. I am working through validating existing workflows and tooling with it. Expect initial rapid changes in short order. I will remove this notice when I am satisfied the orca2 is fully tested and working. I am releasing working examples rpi, ocr and qrspi (planned) workflows with GAN validation loops with it. Stay tuned!

What Is This?

Orca2 is a plugin for OpenCode that orchestrates agentic workflows via YAML definitions. It uses file-based state management to track progress, making workflows transparent, auditable, and resilient to process restarts. It also manages task list completion on a per-task basis using generated artifacts to manage state across multi-step loops.

Why Use Orca2?

Orca2 simplifies the design of complex multi-step workflows with:

• State persists to disk - Workflow progress survives restarts
• Human-in-the-loop - You can intervene at any point
• Retry logic - Failed tasks can automatically retry
• Task iteration - Process multiple tasks in sequence
• Loop patterns - like Generate → Validate → Retry (GAN) cycles

Common use cases:

• Research → Plan → Implement RPI and QRSPI workflows
• Code generation with validation (GAN) loops
• Multi-phase project execution
• Batch processing of tasks

Quick Start

Installation

Add to your project's opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-plugin-orca2"]
}

OpenCode automatically installs dependencies and loads the plugin.

Invocation

Invoke workflows with the pattern:

#{<workflow> <arg1> <arg2> ...}

Example:

#{rpi 01-foundations}

This loads workflow/rpi.yaml and substitutes $1 with 01-foundation.

Workflows

Workflows let you orchestrate a sequence of steps with prompts where orchestration state is managed automatically by the generation and existence of the workflow output files -- artifacts created by each step.

#{my-workflow my-argument}

Create workflow files

Create yaml files in the workflow/ directory to define workflows in your current OpenCode development project.

Create workflow/rpi.yaml:

description: Simple research, plan and implement pipeline for quick features
prompt:
  - ./workflow/rpi.md
retry: 3
steps:
  - name: research
    description: Research the codebase
    prompt:
      - ./workflow/rpi-research.md
      - ## User Request
      - ./thoughts/$1/user-request.md
    output:
      - ./thoughts/$1/research.md

  - name: plan
    description: Create technical plan
    prompt:
      - ./workflow/rpi-plan.md
      - ## User Request
      - ./thoughts/$1/user-request.md
      - ./thoughts/$1/research.md
    output:
      - ./thoughts/$1/plan.md

  - name: implement
    description: Implement plan
    prompt:
      - ./workflow/rpi-implement.md
      - ./thoughts/$1/plan.md
      - ## User Request
      - ./thoughts/$1/user-request.md
      - ./thoughts/$1/research.md

Use the workflow by typing # followed by the workflow name and arguments inside curly brackets { }.

#{rpi 02-new-feature}

Create step prompts

Workflow steps comprise an array of text and/or file paths.

  - name: plan
    description: Create technical plan
    prompt:
      - ## Planning Agent
      - Write a comprehensive and detailed multi-phase plan in `thoughts/$1/plan.md`.
      - ## Current Task
      - $2
      - ./thoughts/$1/research.md

Path Resolution

• ./path - Relative to current working directory
• ~/path - Relative to home directory
• Absolute paths ~/../ outside home directory are rejected
• Use dual purpose OpenCode commands inside workflows:
  • ./.opencode/command/my-command.md for local commands
  • ~/.config/opencode/command/my-command.m for global commans

Arguments

Pass arguments to workflows step prompts and prompt files using the $ARGUMENTS placeholder.

Our objective is to $ARGUMENTS.

Work back and forth with the user, ask open questions about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

Ask the questions one at a time.

If a question can be answered by exploring the codebase, explore the codebase instead.

Run the command with arguments:

#{brief-alignment "Create a new OpenCode plugin for workflow orchestration"}

And $ARGUMENTS will be replaced with the objective text inside the prompt.

You can also access individual arguments using positional parameters:

• $1 - First argument
• $2 - Second argument
• $3 - Third argument

For example:

Create a file named $1 in the directory $2
with the following content: $3

Run the command:

#{create-file config.json src '{ "key": "value" }'}

This replaces:

• $1 with config.json
• $2 with src
• $3 with { "key": "value" }

Task Arguments

In addition to workflow arguments, task lists also provide $0 and $TASK placeholders.

• $0 - Current task number (1-indexed)
• $TASK - Current task description

Yaml Workflows

Orchestrations are comprised of yaml workflow files, and markdown step prompts. They expect the agent to generate output files, the existence of which provide a state mechanism for workflow orchestration.

Task lists are also supported. These provide for per-task outputs, where each task correlates to an output file defined by the task_list template. In this mode the orchestrator manages the task list itself, marking task as they are completed and halting when repeated failures exceed the retry count.

Workflow Format

| Field | Type | Required | Description | |-------|------|----------|-------------| | description | string | Yes | Human-readable workflow description | | prompt | array | Yes | Prompt elements (text or file paths) | | retry | number | No | Default max retries per step (default: 3) | | debug | boolean | No | Enable verbose logging (default: false) | | steps | array | Yes | Array of step definitions |

Step Definition SyntaFormatx

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Unique step identifier | | description | string | Yes | Human-readable step description | | prompt | array | Yes | Prompt elements (text or file paths) | | prompt_optional | array | No | Optional prompt file paths | | task_list | string | No | Path to task list file | | loop | string | No | Name of step to loop back for each task | | retry | number | No | Max retries for this step (overrides default retry) | | output | array | No | Required output file paths | | output_list | array | No | Template for task-specific output paths |

Task list Format

Tasks list files are the simple markdown-like todo lists familiar to agents.

- [ ] Process user data
- [ ] Generate reports
- [ ] Create documentation

Task Status Syntax

Task lists managed by the orchestrator use the following syntax.

- [ ] Pending task
- [x] Completed task
- [3] Task with 3 failed attempts

Task List Semantics

• Tasks are 1-indexed (first $0 task is task 1)
• The current task is the first task that is not marked complete
• If all tasks are complete, the current step is complete
• Task lists are strict: if the current task's output is missing, the workflow retries or halts

Task List Lifecycle

When a step with a task_list is entered:

1. When entering the step, the task list is read as-is
2. If the step or loop step is completed, and the step has a task_list, all tasks are reset to pending state (- [ ])
3. The reset happens exactly once when transitioning to the next step

This enables workflows like:

plan(5 tasks, reset) 
  → acceptance-criteria(5 tasks, reset)
  → loop { implement(current task) → validate(5 tasks, reset) }
  → Done

Error Handling

Orca2 enforces strict mode - if expected output is missing after max retries, the workflow halts. This requires human intervention.

To recover:

1. Check the error log
2. Manually create missing output files OR
3. Fix the issue and re-invoke the workflow

Examples

Copy workflow directory into you project.

Research Plan Implement (rpi)

See workflow/rpi.yaml for a complete example of three sequential steps.

Prerequisites:

1. Create a thoughts directory for you next feature request in thoughts/NN-feature.
2. Write a prompt in thoughts/NN-feature/user-request.md outlining the work you want performed and and research references in the codebase the agent should read.

Run the rpi workflow:

#{rpi NN-funtion}

Optical Character Recognition (ocr)

See workflow/ocr.yaml for a complete example of a task list.

Prerequisites:

1. A multi-modal model like Qwen 3.x
2. My OpenCode tool pdf2img installed
3. Create a per-document directory for the document you want to analyze task-N/.
4. Add additional steps with custom prompts for the data you wan to extract.

Run the ocr workflow:

#{ocr task-N}

Questions Research Structure Plan Implement (qrspi) -- crispy

Coming Soon:

See workflow/qrspi.yaml for a task list and generate-validate loop pattern.

Troubleshooting

Workflow Not Starting

Symptom: Invocation has no effect

Check:

1. Workflow file exists at workflow/<name>.yaml
2. Plugin is in opencode.json
3. Step prompt files exist at ./<path>/<step-name>.md

Output Files Not Detected

Symptom: Workflow stuck waiting for output

Check:

1. Output file paths match exactly (case-sensitive)
2. Files are created in the correct directory
3. No typos in output array

Max Retries Exceeded

Symptom: Workflow halts with error

Check:

1. Review error log for missing outputs
2. Manually create missing files OR
3. Investigate why step cannot complete

References

The examples draw on knowledge and techniques shared by Dex Horthy and Matt Pocock

• 12-Factor Agents: Patterns of reliable LLM applications — Dex Horthy, HumanLayer
• No Vibes Allowed: Solving Hard Problems in Complex Codebases — Dex Horthy, HumanLayer
• It Ain't Broke: Why Software Fundamentals Matter More Than Ever — Matt Pocock, AI Hero
• Everything We Got Wrong About Research-Plan-Implement — Dex Horthy, HumanLayer

License

MIT

Authors

• @whpthomas - Concept, logic and troubleshooting
• Qwen3.5 122B A10B int4 AutoRound ~ DGX Spark - Research and coding