Subtask2 Plugin Brings Structured Orchestration to opencode Commands

The spoons-and-mirrors/subtask2 plugin extends opencode’s /command handler into a more structured orchestration layer that queues prompts and subtasks, passes session context to subagents, and lets the main session steer multi-step flows.

What it enables

• Queueing of prompts, /commands, and subagents with argument passing.
• Chaining and steering via return so the main session can receive structured follow-ups or trigger additional commands when a subtask completes.
• Parallel execution of subtasks (feature depends on a pending upstream PR).
• Session-context piping using the $TURN[n] syntax to inject previous conversation turns into subtasks or arguments.

These capabilities aim to reduce agentic entropy by making multi-step, multi-agent workflows explicit and controllable while keeping command templates familiar to existing opencode users.

Key features (technical)

• return: Replaces opencode’s default post-subtask summary with a developer-defined prompt. The first return substitutes the injected message; additional entries run sequentially. Slash commands inside return are supported, enabling chained commands and subtasks.
• Inline model override ({model:provider/model-id}): Attach a model override directly to a command name (no space) to reuse a template with different models. This behavior is noted as pending a PR.
• parallel: Declare subtasks to run concurrently; the parent’s return fires after all parallel subtasks finish. The feature requires this PR to be merged for full functionality and correct model/agent inheritance.
• Argument piping (||): Pass custom arguments to main, parallel, and return commands using chronological pipe segments. Priority rules: pipe args > frontmatter args > inherited main args.
• $TURN[n]: Injects recent conversation turns (user + assistant) into command templates, arguments, or piped inputs. Supports ranges, specific indices, and wildcard.
• Configurable defaults: If a subtask lacks a return, config at ~/.config/opencode/subtask2.jsonc can supply a generic_return. Priority for fallback is: explicit return > config generic_return > built-in default > opencode original.

Workflow examples

The repository includes demo command files that illustrate:

• Multi-model A/B/C plan comparisons via parallel subtasks.
• Isolated “plan-only” modes that separate research from implementation.
• Nested parallel subtasks (flattened to a maximum depth of 5) with per-command argument overrides.

A short demo command in the repo shows how parallel, subtask: true, and return can coordinate a multi-step sequence while piping arguments across stages.

Installation

Add the plugin to opencode’s plugin array in the config, for example: { "plugins": [" @openspoon/subtask2@latest " ] }

The package is also listed on npm: https://www.npmjs.com/package/@openspoon/subtask2.

Repository and source material: https://github.com/spoons-and-mirrors/subtask2