Multi-Agent Pipeline
bohewu/agents_pipeline
Pipeline multi-agente configurável para automação de workflows em desenvolvimento.
Ver no GitHubPipeline instalável de múltiplos agentes para OpenCode, Codex, Claude Code e Copilot, com ferramentas de controle de uso/quota e plugins de interface textual. Orquestra fluxos de trabalho complexos com suporte a roteamento de modelos, validação de protocolos e geração de assets.
Instalação
npx convez-ai bohewu/agents_pipeline1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de implementação de features complexas (OAuth2, integrations)
- Orquestração de tarefas de design e frontend com direcionamento visual
- Controle de quota e roteamento inteligente de modelos por workspace
- Workflows de geração de conteúdo e assets com validação de protocolo
Veredito

Ferramenta robusta para quem precisa orquestrar múltiplos agentes em pipelines complexos, com forte suporte a configuração local e controle de recursos. Requer conhecimento técnico sólido e é mais adequada para times que trabalham com múltiplos provedores de IA simultaneamente.
README
A tradução para o português deste README ainda está na fila.
Multi-Agent Pipeline
Multi-agent workflows for OpenCode with companion agent docs for Claude Code, VS Code Copilot, and Codex.
This repository (bohewu/agents_pipeline) contains the workflow assets, protocols, tools, and plugins for Multi-Agent Pipeline, with opencode/agents/*.md as the single source of truth.
See the How To Use section below for usage instructions.
Contents
- TL;DR
- Project Docs
- Usage Prerequisites
- Install (Recommended)
- Developer Install (Clone Repo)
- How To Use
- Quick Start
- VS Code Copilot Agents
- Claude Code Subagents
- Codex Agent Roles
- Conceptual UI/UX Layer
- Frontend UI Implementation
- Workspace Agent Model Profiles
- Protocol Validation
- Config Example
- Flags
- Orchestrators
- Versioning
TL;DR
- Most users should use the published release bundle install commands in
Install (Recommended). - Fastest Ubuntu/macOS/Linux all-in-one path: paste the one-liner in
All local assets; no extrachmodstep is needed for that path. - If you are editing this repo or testing local changes from your working tree, use
Developer Install (Clone Repo). - Most common run:
/run-pipeline Implement OAuth2 login --effort=balanced - Optional workspace model routing: use
agent-profile.ps1oragent-profile.shto generate.opencode/agentsoverrides from tiered profiles and provider model sets.
Project Docs
CONTRIBUTING.mdfor repo layout, single-source-of-truth rules, local validation, and release expectations.SECURITY.mdfor private vulnerability reporting and token/supply-chain handling guidance.COMPATIBILITY.mdfor runtime and host-environment assumptions.docs/external-dependencies.mdfor network/auth/rate-limit/fallback/privacy notes onprovider-usage,skill-manager, and bootstrap installers.docs/art-generation-scaffold.mdfor the bounded 2D asset brief/prompt scaffold, standardized External Handoff Package, Direct Use Prompt, and optional/artgen --gen-provider=codexbridge used by the repo-managedartgen-scaffoldskill,art-director, and the normal/artgensurface.opencode/skills/codex-imagegen/SKILL.mdfor the Codex CLI$imagegenbridge used by/codex-imagegenwhen OpenCode should generate images through Codex quota without direct API or provider fallback.opencode/protocols/UI_UX_WORKFLOW.mdfor the thin conceptual UI/UX layer, non-expert design/interaction guidance, communication-first overlay, intake/review rubric, and theui-ux-bundleschema/example bundle used by/uiux,ui-ux-designer, and the repo-managedui-ux-workflowandui-communication-designerskills.opencode/skills/frontend-aesthetic-director/SKILL.mdfor frontend implementation and polish tasks that need visual direction, design-token alignment, responsive behavior, accessibility states, and rendered browser/Playwright QA.docs/agent-model-profiles.mdfor workspace-local OpenCode agent model profiles, provider model sets, and safe generated overrides under.opencode/agents.docs/runtime-agent-model-profiles.mdfor opt-in runtime agent model profile output behavior across OpenCode, Codex, Copilot, and Claude Code.
Usage Prerequisites
This repo assumes you have configured the required model providers in OpenCode.
If no model/provider is available in your OpenCode runtime config, update opencode.json (or your global OpenCode config) before running any commands.
Compatibility assumptions and optional dependencies are documented in COMPATIBILITY.md.
Required Tools
- OpenCode (with model providers configured)
- Claude Code (optional; default install target:
~/.claude/agents) - VS Code with GitHub Copilot (for Copilot custom-agent usage)
- Codex CLI (optional; for Codex multi-agent usage)
- Python 3.9+ (required for
opencode/tools/validate-schema.py,opencode/tools/agent-profile.sh,scripts/export-copilot-agents.py, andscripts/export-codex-agents.py) - PowerShell 7+ (for
scripts/install.ps1on Windows) or Bash (forscripts/install.shon macOS/Linux) curl+tar+sha256sum(orshasum) for release-bundle bootstrap install on macOS/Linux- GitHub CLI (
gh) is optional, but bootstrap installers use it to verify GitHub Artifact Attestations when available
Workspace Agent Model Profiles
OpenCode core installs include deterministic workspace profile installers for per-agent model routing. Profiles map agents to logical tiers (mini, standard, strong), and model sets map those tiers to concrete provider model IDs so provider changes or model version updates stay centralized.
Workspace-first installs write generated profile overrides under the selected workspace. Use -Workspace . / --workspace . for the current repo; when -Runtime / --runtime is omitted, OpenCode remains the default runtime.
PowerShell:
pwsh -NoProfile -File ~/.config/opencode/tools/agent-profile.ps1 install balanced -ModelSet openai -Workspace .
pwsh -NoProfile -File ~/.config/opencode/tools/agent-profile.ps1 install balanced -Runtime codex -ModelSet openai -Workspace .
pwsh -NoProfile -File ~/.config/opencode/tools/agent-profile.ps1 install balanced -Runtime copilot -ModelSet default -Workspace .
pwsh -NoProfile -File ~/.config/opencode/tools/agent-profile.ps1 install balanced -Runtime claude -ModelSet default -Workspace .
Bash/macOS/Linux:
bash ~/.config/opencode/tools/agent-profile.sh install balanced --model-set openai --workspace .
bash ~/.config/opencode/tools/agent-profile.sh install balanced --runtime codex --model-set openai --workspace .
bash ~/.config/opencode/tools/agent-profile.sh install balanced --runtime copilot --model-set default --workspace .
bash ~/.config/opencode/tools/agent-profile.sh install balanced --runtime claude --model-set default --workspace .
Generated overrides live in .opencode/agents; canonical opencode/agents/*.md remains unchanged. Restart OpenCode after changing profiles. See docs/agent-model-profiles.md.
The same wrapper can also dispatch opt-in Codex, Copilot, and Claude Code profile installs with --runtime / -Runtime; by default it derives workspace-local targets from --workspace / -Workspace (or the current directory): .opencode/agents, .claude/agents, .copilot/agents, or .codex. --target / -Target is not needed for workspace use; pass it only for an explicit override, such as an intentional global install. These runtime flags only select model names or aliases; Codex reasoning effort comes from the effective Codex runtime config, not these profiles. See docs/runtime-agent-model-profiles.md.
Maintainers can refresh bundled Anthropic and Google model-set catalogs with python3 scripts/update-agent-model-sets.py --dry-run.
Install (Recommended)
These commands install from the published release bundle and are the default path for most users.
Bootstrap installers download a release bundle, verify the archive checksum against the release SHA256SUMS asset, and, when gh is available, verify the GitHub Artifact Attestation before installing only the target you choose.
See docs/external-dependencies.md for external fetch, auth, and supply-chain notes for bootstrap/release installs.
Attestation details stay quiet by default. Use --verbose on Bash bootstrap scripts or -Verbose on PowerShell bootstrap scripts if you want to see the attestation verification steps.
Most common choices:
- Want everything in one step: start with
All local assets. - Already have OpenCode and only need the runtime status plugin: use
Status plugin only. - Only want
/usageplus the usage footer plugin: useUsage only. - Want OpenAI or GitHub Copilot GPT-5 reasoning floor controls in OpenCode: use
Effort-control plugin only. - Only need one editor/CLI integration: jump to
Copilot agents,Claude Code subagents, orCodex roles.
Pick the install target that matches what you want:
- OpenCode core: install the main OpenCode config only.
- Status plugin only: install just the OpenCode status runtime plugin.
- Usage only: install just the usage command/tool and the usage-status plugin.
- Effort-control plugin only: install just the OpenCode GPT-5 reasoning-effort controller for OpenAI and GitHub Copilot.
- All local assets: install OpenCode core + status/usage/effort plugins + Copilot + Claude + Codex in one step.
- Copilot agents: install only VS Code Copilot custom agents.
- Claude Code subagents: install only Claude Code agent markdown files.
- Codex roles: install only Codex role config.
PowerShell tips:
- Prefer pinned tags over
main. - Pass
-Targetexplicitly when you know the install location. - When combining PowerShell switch flags with other arguments, prefer
-Flag:$trueform for clarity. - Bootstrap installers create backups by default when they detect existing installed files.
OpenCode core
Copy-paste commands (recommended):
Existing OpenCode files are backed up by default. The installer refreshes the managed repo files, removes stale managed files that were deleted from this repo, and leaves unrelated user-created files in place.
Windows (PowerShell):
$tag = "v0.24.3"; Invoke-WebRequest "https://raw.githubusercontent.com/bohewu/agents_pipeline/$tag/scripts/bootstrap-install.ps1" -OutFile .\bootstrap-install.ps1; pwsh -NoProfile -File .\bootstrap-install.ps1 -Version $tag -Target "$HOME\.config\opencode"
macOS/Linux:
tag="v0.24.3" && curl -fsSL -o ./bootstrap-install.sh "https://raw.githubusercontent.com/bohewu/agents_pipeline/${tag}/scripts/bootstrap-install.sh" && bash ./bootstrap-install.sh --version "${tag}"
Quick one-liners (less auditable):
irm https://raw.githubusercontent.com/bohewu/agents_pipeline/main/scripts/bootstrap-install.ps1 | iex
curl -fsSL https://raw.githubusercontent.com/bohewu/agents_pipeline/main/scripts/bootstrap-install.sh | bash
Status plugin only
Install only the OpenCode status runtime plugin from the release bundle. The target must be the plugin entry file path, not a directory.
Copy-paste commands (recommended):
Windows (PowerShell):
$tag = "v0.24.3"; Invoke-WebRequest "https://raw.githubusercontent.com/bohewu/agents_pipeline/$tag/scripts/bootstrap-install-plugin-status-runtime.ps1" -OutFile .\bootstrap-install-plugin-status-runtime.ps1; pwsh -NoProfile -File .\bootstrap-install-plugin-status-runtime.ps1 -Version $tag -Target "$HOME\.config\opencode\plugins\status-runtime.js"
macOS/Linux:
tag="v0.24.3" && curl -fsSL -o ./bootstrap-install-plugin-status-runtime.sh "https://raw.githubusercontent.com/bohewu/agents_pipeline/${tag}/scripts/bootstrap-install-plugin-status-runtime.sh" && bash ./bootstrap-install-plugin-status-runtime.sh --version "${tag}" --target "$HOME/.config/opencode/plugins/status-runtime.js"
Dry-run preview (resolves release metadata only):
pwsh -NoProfile -File .\bootstrap-install-plugin-status-runtime.ps1 -Version $tag -Target "$HOME\.config\opencode\plugins\status-runtime.js" -DryRun
bash ./bootstrap-install-plugin-status-runtime.sh --version "${tag}" --target "$HOME/.config/opencode/plugins/status-runtime.js" --dry-run
Usage only
Install only the /usage command/tool and the toggleable OpenCode usage-status plugin from the release bundle.
The usage footer plugin defaults to off; enable it from OpenCode with /usage-status or /usage-status-on after install.
The installer registers the TUI plugin in ~/.config/opencode/tui.json, not in opencode.json.
Windows (PowerShell):
$tag = "v0.24.3"; Invoke-WebRequest "https://raw.githubusercontent.com/bohewu/agents_pipeline/$tag/scripts/bootstrap-install-usage-only.ps1" -OutFile .\bootstrap-install-usage-only.ps1; pwsh -NoProfile -File .\bootstrap-install-usage-only.ps1 -Version $tag -OpenCodeTarget "$HOME\.config\opencode" -UsagePluginTarget "$HOME\.config\opencode\plugins\usage-status.js"
macOS/Linux:
tag="v0.24.3" && curl -fsSL -o ./bootstrap-install-usage-only.sh "https://raw.githubusercontent.com/bohewu/agents_pipeline/${tag}/scripts/bootstrap-install-usage-only.sh" && bash ./bootstrap-install-usage-only.sh --version "${tag}" --opencode-target "$HOME/.config/opencode" --usage-plugin-target "$HOME/.config/opencode/plugins/usage-status.js"
Dry-run preview (resolves release metadata only):
pwsh -NoProfile -File .\bootstrap-install-usage-only.ps1 -Version $tag -OpenCodeTarget "$HOME\.config\opencode" -UsagePluginTarget "$HOME\.config\opencode\plugins\usage-status.js" -DryRun
bash ./bootstrap-install-usage-only.sh --version "${tag}" --opencode-target "$HOME/.config/opencode" --usage-plugin-target "$HOME/.config/opencode/plugins/usage-status.js" --dry-run
Behavior notes:
- When enabled, the footer refreshes immediately and then every
300seconds. - If you want the latest values on demand, use
/usage-status-refreshor run/usage. - Use
/usage-status-shortfor a compact one-line summary or/usage-status-detailfor the richer sidebar card view. - Use
/usage-status-codexto keep the footer scoped to Codex usage. - If a live lookup fails after a previous success, the footer reuses cached data and prefixes the summary with
~. - The footer is intentionally compact;
/usage --jsonremains the detailed/debug view.
Effort-control plugin only
Install only the OpenCode effort-control plugin from the release bundle.
Use this when you want the reasoning controller without installing the rest of the all-in bundle.
The installer registers the TUI plugin in ~/.config/opencode/tui.json, not in opencode.json.
Windows (PowerShell):
$tag = "v0.24.3"; Invoke-WebRequest "https://raw.githubusercontent.com/bohewu/agents_pipeline/$tag/scripts/bootstrap-install-plugin-effort-control.ps1" -OutFile .\bootstrap-install-plugin-effort-control.ps1; pwsh -NoProfile -File .\bootstrap-install-plugin-effort-control.ps1 -Version $tag -Target "$HOME\.config\opencode\plugins\effort-control.js"
macOS/Linux:
tag="v0.24.3" && curl -fsSL -o ./bootstrap-install-plugin-effort-control.sh "https://raw.githubusercontent.com/bohewu/agents_pipeline/${tag}/scripts/bootstrap-install-plugin-effort-control.sh" && bash ./bootstrap-install-plugin-effort-control.sh --version "${tag}" --target "$HOME/.config/opencode/plugins/effort-control.js"
Dry-run preview (resolves release metadata only):
pwsh -NoProfile -File .\bootstrap-install-plugin-effort-control.ps1 -Version $tag -Target "$HOME\.config\opencode\plugins\effort-control.js" -DryRun
bash ./bootstrap-install-plugin-effort-control.sh --version "${tag}" --target "$HOME/.config/opencode/plugins/effort-control.js" --dry-run
Behavior notes:
- For OpenAI and GitHub Copilot
gpt-5*, the plugin floors most execution/review-style agents to at leastmedium, but leaves structured low-reasoning roles such asspecifier,planner,router,repo-scout,flow-splitter,codex-account-manager, andtest-runnerexcluded. - Frontend UI work is not escalated to xhigh by default. For page, dashboard, or component polish, pair medium/high effort with
opencode/skills/frontend-aesthetic-director/SKILL.mdand rendered QA instead of relying on reasoning effort alone. /effort-medium,/effort-high, and/effort-maxset a reasoning floor. On the home screen they set a project default; inside a session they set a session override./effort-clearremoves the current session override or the project default.- Verification traces are written under the active project at
.opencode/effort-control.trace.jsonl.
All local assets
Install OpenCode core assets, the OpenCode-only status-runtime plugin, the OpenCode-only usage-status plugin, the OpenCode-only effort-control plugin, Copilot agents, Claude agents, and Codex config together from one release bundle.
Copy-paste commands (recommended):
Windows (PowerShell):
$tag = "v0.24.3"; Invoke-WebRequest "https://raw.githubusercontent.com/bohewu/agents_pipeline/$tag/scripts/bootstrap-install-all-local.ps1" -OutFile .\bootstrap-install-all-local.ps1; pwsh -NoProfile -File .\bootstrap-install-all-local.ps1 -Version $tag -OpenCodeTarget "$HOME\.config\opencode" -PluginTarget "$HOME\.config\opencode\plugins\status-runtime.js" -EffortPluginTarget "$HOME\.config\opencode\plugins\effort-control.js" -CopilotTarget "$HOME\.copilot\agents" -ClaudeTarget "$HOME\.claude\agents" -CodexTarget "$HOME\.codex"
macOS/Linux:
tag="v0.24.3" && tmp="$(mktemp)" && curl -fsSL -o "$tmp" "https://raw.githubusercontent.com/bohewu/agents_pipeline/${tag}/scripts/bootstrap-install-all-local.sh" && bash "$tmp" --version "${tag}" --opencode-target "$HOME/.config/opencode" --plugin-target "$HOME/.config/opencode/plugins/status-runtime.js" --effort-plugin-target "$HOME/.config/opencode/plugins/effort-control.js" --copilot-target "$HOME/.copilot/agents" --claude-target "$HOME/.claude/agents" --codex-target "$HOME/.codex" && rm -f "$tmp"
Ubuntu/macOS/Linux notes if you prefer downloading the script first:
- The easiest copy-paste path is to pipe the pinned bootstrap script into
bash; this avoids the downloaded-file executable-bit problem entirely. - If you download the bootstrap script first, run it as
bash ./bootstrap-install-all-local.sh .... - A script fetched with
curl -o ./bootstrap-install-all-local.sh ...usually does not have the executable bit on Ubuntu, so./bootstrap-install-all-local.sh ...can fail withpermission denied. - If you specifically want
./bootstrap-install-all-local.sh ..., runchmod +x ./bootstrap-install-all-local.shfirst.
Download-then-run version:
tag="v0.24.3"
curl -fsSL -o ./bootstrap-install-all-local.sh "https://raw.githubusercontent.com/bohewu/agents_pipeline/${tag}/scripts/bootstrap-install-all-local.sh"
bash ./bootstrap-install-all-local.sh --version "${tag}" --opencode-target "$HOME/.config/opencode" --plugin-target "$HOME/.config/opencode/plugins/status-runtime.js" --effort-plugin-target "$HOME/.config/opencode/plugins/effort-control.js" --copilot-target "$HOME/.copilot/agents" --claude-target "$HOME/.claude/agents" --codex-target "$HOME/.codex"
Dry-run preview (resolves release metadata only):
pwsh -NoProfile -File .\bootstrap-install-all-local.ps1 -Version $tag -OpenCodeTarget "$HOME\.config\opencode" -PluginTarget "$HOME\.config\opencode\plugins\status-runtime.js" -EffortPluginTarget "$HOME\.config\opencode\plugins\effort-control.js" -CopilotTarget "$HOME\.copilot\agents" -ClaudeTarget "$HOME\.claude\agents" -CodexTarget "$HOME\.codex" -DryRun
bash ./bootstrap-install-all-local.sh --version "${tag}" --opencode-target "$HOME/.config/opencode" --plugin-target "$HOME/.config/opencode/plugins/status-runtime.js" --effort-plugin-target "$HOME/.config/opencode/plugins/effort-control.js" --copilot-target "$HOME/.copilot/agents" --claude-target "$HOME/.claude/agents" --codex-target "$HOME/.codex" --dry-run
Copilot agents
Copy-paste commands (recommended):
Windows (PowerShell):
$tag = "v0.24.3"; Invoke-WebRequest "https://raw.githubusercontent.com/bohewu/agents_pipeline/$tag/scripts/bootstrap-install-copilot.ps1" -OutFile .\bootstrap-install-copilot.ps1; pwsh -NoProfile -File .\bootstrap-install-copilot.ps1 -Version $tag -Target "$HOME\.copilot\agents"
macOS/Linux:
tag="v0.24.3" && curl -fsSL -o ./bootstrap-install-copilot.sh "https://raw.githubusercontent.com/bohewu/agents_pipeline/${tag}/scripts/bootstrap-install-copilot.sh" && bash ./bootstrap-install-copilot.sh --version "${tag}"
Quick one-liners (less auditable):
irm https://raw.githubusercontent.com/bohewu/agents_pipeline/main/scripts/bootstrap-install-copilot.ps1 | iex
curl -fsSL https://raw.githubusercontent.com/bohewu/agents_pipeline/main/scripts/bootstrap-install-copilot.sh | bash
Opt-in runtime agent model profile when installing from a cloned repo:
pwsh -NoProfile -File .\scripts\install-copilot.ps1 -AgentProfile balanced -ModelSet default
scripts/install-copilot.sh --agent-profile balanced --model-set default
Claude Code subagents
Use a tagged release bundle to install Claude Code subagents.
Copy-paste commands (recommended):
Windows (PowerShell):
$release = "v0.24.3"; Invoke-WebRequest "https://raw.githubusercontent.com/bohewu/agents_pipeline/$release/scripts/bootstrap-install-claude.ps1" -OutFile .\bootstrap-install-claude.ps1; pwsh -NoProfile -File .\bootstrap-install-claude.ps1 -Version $release -Target "$HOME\.claude\agents"
macOS/Linux:
release="v0.24.3" && curl -fsSL -o ./bootstrap-install-claude.sh "https://raw.githubusercontent.com/bohewu/agents_pipeline/${release}/scripts/bootstrap-install-claude.sh" && bash ./bootstrap-install-claude.sh --version "${release}" --target "$HOME/.claude/agents"
Optional project-local override:
Invoke-WebRequest "https://raw.githubusercontent.com/bohewu/agents_pipeline/$release/scripts/bootstrap-install-claude.ps1" -OutFile .\bootstrap-install-claude.ps1
pwsh -NoProfile -File .\bootstrap-install-claude.ps1 -Version $release -Target "C:\path\to\your-project\.claude\agents"
curl -fsSL -o ./bootstrap-install-claude.sh "https://raw.githubusercontent.com/bohewu/agents_pipeline/${release}/scripts/bootstrap-install-claude.sh"
bash ./bootstrap-install-claude.sh --version "${release}" --target "/path/to/your-project/.claude/agents"
Opt-in runtime agent model profile when installing from a cloned repo:
pwsh -NoProfile -File .\scripts\install-claude.ps1 -AgentProfile balanced -ModelSet default
scripts/install-claude.sh --agent-profile balanced --model-set default
See docs/claude-mapping.md for tool mapping, $ARGUMENTS input adaptation, and the current orchestrator limitations.
Codex roles
Copy-paste commands (recommended):
Existing .codex files are backed up by default. The installer preserves non-agent Codex settings, replaces the managed agent definitions, and removes stale managed agent files.
Default/primary install path is global ~/.codex; target <workspace>/.codex only when you intentionally want a workspace override.
Global installs now also auto-manage the equivalent of the Codex mode-alias snippet in the active global AGENTS file inside that target: prefer AGENTS.override.md when it exists and is non-empty, otherwise use AGENTS.md. That managed note makes the authorization and definition-first workflow explicit for recognized mode aliases: a mode alias changes only the current/main agent's working style, does not automatically spawn subagents, and does not override higher-priority spawn_agent authorization. In a fresh/new session, first consult .codex/agents/orchestrator-<mode>.toml for the current workspace when present, otherwise ~/.codex/agents/orchestrator-<mode>.toml, then apply that definition. After applying it, the current/main agent must obey that definition's hard constraints and delegation rules as if it were that orchestrator, and if the applied definition forbids direct implementation or routes scouting/implementation to helper roles, the current/main agent must not bypass those helpers inline and should delegate those work items when separately authorized. In the same session, repeated use of the same mode does not need to reload that definition unless the mode changes, the workspace changes, the definition source changes between workspace .codex/agents/... and global ~/.codex/agents/..., the user explicitly asks to reload/refresh/re-read, or the agent is no longer confident it still has the relevant mode details. It also says that Codex mode simulation can ignore OpenCode-only plugin/command details that are not relevant in the current runtime. Manual snippet copy remains optional for users who are not using the installer.
Windows (PowerShell):
$tag = "v0.24.3"; Invoke-WebRequest "https://raw.githubusercontent.com/bohewu/agents_pipeline/$tag/scripts/bootstrap-install-codex.ps1" -OutFile .\bootstrap-install-codex.ps1; pwsh -NoProfile -File .\bootstrap-install-codex.ps1 -Version $tag -Target "$HOME\.codex"
macOS/Linux:
tag="v0.24.3" && curl -fsSL -o ./bootstrap-install-codex.sh "https://raw.githubusercontent.com/bohewu/agents_pipeline/${tag}/scripts/bootstrap-install-codex.sh" && bash ./bootstrap-install-codex.sh --version "${tag}"
Quick one-liners (less auditable):
irm https://raw.githubusercontent.com/bohewu/agents_pipeline/main/scripts/bootstrap-install-codex.ps1 | iex
curl -fsSL https://raw.githubusercontent.com/bohewu/agents_pipeline/main/scripts/bootstrap-install-codex.sh | bash
Opt-in runtime agent model profile when installing from a cloned repo:
pwsh -NoProfile -File .\scripts\install-codex.ps1 -AgentProfile balanced -ModelSet openai
scripts/install-codex.sh --agent-profile balanced --model-set openai
Use generated Codex roles either by direct role name in prompts (for example, Have orchestrator-pipeline ...) or by leading aliases such as use pipeline ... / 使用flow .... Those leading aliases change only the current/main agent's working style; they are not requests to first spawn the same-named orchestrator role just to enter the mode, they do not automatically spawn subagents, and they do not override higher-priority spawn_agent authorization. In a fresh/new session, the expected behavior for those explicit aliases is definition-first: first consult .codex/agents/orchestrator-<mode>.toml for the current workspace when present, otherwise ~/.codex/agents/orchestrator-<mode>.toml, then apply that definition. After the definition is applied, the current/main agent must obey that definition's hard constraints and delegation rules as if it were that orchestrator; if the definition forbids direct implementation or routes scouting/implementation to helper roles, the current/main agent must not bypass those helpers inline and should delegate those work items when separately authorized. In the same session, repeated use of the same mode does not need to reload that definition unless the mode changes, the workspace changes, the definition source changes between workspace .codex/agents/... and global ~/.codex/agents/..., the user explicitly asks to reload/refresh/re-read, or the agent is no longer confident it still has the relevant mode details. The managed note also says Codex mode simulation can ignore OpenCode-only plugin/command details that are not relevant in the current Codex runtime, focusing instead on mode behavior, task decomposition, delegation rules, and output style. Direct role-name prompts remain available when you explicitly want that. Global installer runs now manage that mode note automatically via the active global AGENTS file; the manual snippet remains available in docs/codex-mapping.md#global-custom-instructions-snippet.
Developer Install (Clone Repo)
If you are editing this repo or validating installers from your working tree, see docs/developer-install.md.
Most users should use the published release bundle commands in Install (Recommended) instead.
How To Use
- Agent definitions live in
opencode/agents/(one file per agent) - Global handoff rules are embedded in
opencode/agents/orchestrator-pipeline.mdfor portability. If you need to externalize them, you can extract the section into your own runtime path (e.g. under~/.config/opencode/agents/protocols). - Agent catalog lives in
AGENTS.md. - Default model selection is runtime-driven by OpenCode/provider configuration.
- Optional workspace model profiles can generate
.opencode/agentsoverrides fromopencode/tools/agent-profiles/*.jsonandopencode/tools/model-sets/*.json. - Optional runtime profiles for Codex, Copilot, and Claude Code are installer/exporter flags that reuse
opencode/tools/agent-profiles/*.jsonwith runtime-specific model sets; seedocs/runtime-agent-model-profiles.md. - Source agent frontmatter must not define
modelorprovider; use generated workspace overrides or runtime export profile flags when you intentionally want per-agent model routing. - VS Code Copilot
.agent.mdfiles are generated from OpenCode source byscripts/export-copilot-agents.py. - Copilot mapping details live in
docs/copilot-mapping.md. - Claude Code mapping details live in
docs/claude-mapping.md. - Codex install scripts live at
scripts/install-codex.ps1,scripts/install-codex.sh,scripts/bootstrap-install-codex.ps1, andscripts/bootstrap-install-codex.sh. - Codex role mapping details live in
docs/codex-mapping.md. - Protocol and JSON schemas live in
opencode/protocols/. Useopencode/protocols/PROTOCOL_SUMMARY.mdfor global instructions to reduce token usage. - Spec handoff SOP lives in
opencode/protocols/SPEC_TO_PIPELINE.md. - Spec end-to-end example lives in
opencode/protocols/SPEC_E2E_EXAMPLE.md. - Modernize handoff SOP lives in
opencode/protocols/MODERNIZE_TO_PIPELINE.md. - CI artifact templates live in
opencode/protocols/CI_TEMPLATES.md. - CI example for .NET + Vue lives in
opencode/protocols/CI_EXAMPLE_DOTNET_VUE.md. - CI generated output example lives in
opencode/protocols/CI_GENERATE_EXAMPLE.md. - Publish SOP lives in
opencode/protocols/PUBLISH_SOP.md. - Modernize templates live in
opencode/protocols/MODERNIZE_TEMPLATES.md. - Modernize example lives in
opencode/protocols/MODERNIZE_EXAMPLE.md. - Public checklist lives in
opencode/protocols/PUBLIC_CHECKLIST.md. - Root-tracked helper artifacts live in the project root:
session-guide.mdfor stable repo guidance only; keep it limited to non-ephemeral content such as architecture landmarks, conventions, recurring commands, and canonical artifact locationstodo-ledger.jsonas the canonical kanban / carryover data (schema inopencode/protocols/schemas/todo-ledger.schema.json)kanban.mdas the human-readable rendered board view derived fromtodo-ledger.json- A starter ledger template is provided in
todo-ledger.example.json. - A starter rendered board example is provided in
kanban.example.md. - A starter session guide skeleton is provided in
session-guide.example.md.
- Use
/run-ciinopencode/commands/run-ci.mdfor CI/CD planning (docs-first; optional generation). - Use
/run-modernizeinopencode/commands/run-modernize.mdfor modernization planning (experimental). - Use
/run-goalinopencode/commands/run-goal.mdfor resumable multi-batch goals that persist outer session state and default each batch to Flow. - Use
/run-pipelineinopencode/commands/run-pipeline.mdto execute the full pipeline end-to-end - Use
/run-committeeinopencode/commands/run-committee.mdfor a decision committee (experts + KISS soft-veto + judge) - Use
/run-simpleinopencode/commands/run-simple.mdfor build-agent-like subagent delegation without run artifacts - Use
/run-generalinopencode/commands/run-general.mdfor general-purpose mixed workflows (coding/debugging/maintenance/planning/writing/analysis/checklists) - Use
/run-uxinopencode/commands/run-ux.mdfor profile-aware UX audits and normal-user scorecards. - Use
/uiuxinopencode/commands/uiux.mdfor the thin conceptual UI/UX layer routed directly to the hidden subagentopencode/agents/ui-ux-designer.md. - Use
opencode/protocols/UI_UX_WORKFLOW.mdplusopencode/protocols/schemas/ui-ux-bundle.schema.jsonandopencode/protocols/examples/ui-ux-bundle.valid.jsonfor the conceptual UI/UX protocol and durable bundle contract. - Use the repo-managed
opencode/skills/ui-ux-workflow/SKILL.mdfor the same bounded conceptual workflow in skill form. - Use the repo-managed
opencode/skills/ui-communication-designer/SKILL.mdas the communication-first companion to/uiuxwhen the work is mainly about task clarity, copy, trust, and screen-level redesign. - Use the repo-managed
opencode/skills/frontend-aesthetic-director/SKILL.mdfor frontend UI implementation and polish. If/uiuxoutput or wireframes exist, treat them as the upstream source of truth and refine only visual direction, tokens, responsive behavior, component states, accessibility, and rendered defects. - Use
/codex-imagegenplus the repo-managedopencode/skills/codex-imagegen/SKILL.mdto delegate image generation to Codex CLI$imagegenwith per-runimage_generationfeature enablement and no API/provider fallback. - Use
/agent-profilefor deterministic workspace agent model profile installer examples. - Use the repo-managed
devtools-ux-auditskill for Chrome DevTools browser evidence collection. Installers mirror it into~/.agents/skillsas the global baseline and~/.claude/skillsas a compatibility mirror. - Use
/skill-listto inspect installed skills or browse curated catalogs. - Use
/skill-searchto search installed skills plus curated catalogs. - Use
/skill-installto install skills fromanthropicorawesome-copilot, or from a local skill folder. - Use
opencode/protocols/UX_DEVTOOLS_WORKFLOW.mdas the browser-evidence workflow source behind that skill. - Use
/session-guideto create or refresh the root-tracked repo guide. - Use
/kanbanto manage the root-tracked kanban / carryover ledger. - Use
/emit-handoffto create run-local handoff artifacts for a fresh session. - Use
/usageto inspect live Codex quota windows.
VS Code Copilot Agents
This repo can generate VS Code Copilot custom agents from opencode/agents/*.md with single-source maintenance.
- Generate agents directly:
python3 scripts/export-copilot-agents.py --source-agents opencode/agents --target-dir /path/to/copilot/agents --strict
-
Filename rule:
- Output filenames are generated as
<source-file-stem>.agent.md(for exampleorchestrator-pipeline.agent.md).
- Output filenames are generated as
-
Experimental subagent mode:
- Generated orchestrators include
agents:references for Copilot subagent routing (experimental behavior).
- Generated orchestrators include
-
Fallback mode:
- Generated
*-solo.agent.mdfiles run without subagents. - Example:
@orchestrator-pipeline-solo
- Generated
After install, add your generated directory to VS Code user settings:
{
"chat.agentFilesLocations": [
"/path/to/copilot/agents"
]
}
Claude Code Subagents
This repo also supports Claude Code with the same opencode/agents/*.md source files.
- Default install target:
~/.claude/agents. - Optional override target:
<project>/.claude/agentswhen you explicitly want repo-scoped Claude agents. - Source of truth stays in
opencode/agents/*.md; do not fork a separate long-lived Claude-only source set. - See
docs/claude-mapping.mdfor the frontmatter/tool mapping and$ARGUMENTSinput adaptation notes.
Two-Phase Dispatch Model
Claude Code subagents cannot nest Agent calls, so orchestrators use a two-phase dispatch model: the orchestrator plans, and the top-level Claude Code instance executes.
Phase 1 — Plan: Ask an orchestrator to produce a dispatch plan (it will NOT execute tasks itself):
@orchestrator-flow Create a REST endpoint for /api/health that returns {"status":"ok"}
The orchestrator returns a JSON dispatch plan:
{ "dispatch": [
{ "id": "T1", "agent": "executor", "prompt": "Create ...", "deps": [] },
{ "id": "T2", "agent": "orchestrator-pipeline", "prompt": "Implement phase P1 ...", "deps": ["T1"], "worktree": "../target-project" },
{ "id": "T3", "agent": "reviewer", "prompt": "Review ...", "deps": ["T2"] }
]}
Phase 2 — Execute: The top-level Claude Code instance runs the plan automatically:
- Tasks with empty
depsare spawned in parallel. - Tasks with
depswait for their dependencies to complete; results are forwarded in the prompt. - If a task includes
worktree, the runner should execute that subagent in the specified repo/worktree. If the runtime cannot honor it, stop and surface the blocker instead of silently using the current repo. - After all tasks finish, if the orchestrator needs post-dispatch work (e.g., synthesis), results are sent back via
SendMessage.
Which orchestrator to use:
| Scenario | Orchestrator | Notes |
|---|---|---|
| Daily engineering tasks | @orchestrator-flow | Max 5 atomic tasks, no reviewer |
| CI / PR / high-risk work | @orchestrator-pipeline | Full pipeline with review gates |
| Simple single-file change | @executor (directly) | Skip the orchestrator entirely |
Example session:
You: @orchestrator-flow Add input validation to src/api/users.ts
Claude: (orchestrator returns dispatch plan JSON)
Claude: (top-level spawns executor for T1, then reviewer for T2)
Claude: Done — here is the summary.
The dispatch protocol is also documented in CLAUDE.md under "Claude Code Pipeline Runner Protocol".
Codex Agent Roles
This repo can also generate Codex multi-agent role config from opencode/agents/*.md with single-source maintenance.
- Generate a
.codex-style config directory:
python3 scripts/export-codex-agents.py --source-agents opencode/agents --target-dir /path/to/.codex --strict
-
Output structure:
/path/to/.codex/config.toml/path/to/.codex/agents/*.toml
-
Safe overwrite behavior:
- Generation fails if the target contains non-generated files unless you pass
--force.
- Generation fails if the target contains non-generated files unless you pass
-
Codex docs / mapping notes:
- See
docs/codex-mapping.mdfor the exact field mapping, global-first install notes, and the reusable custom-instructions snippet.
- See
-
Invocation note:
- Ask Codex to use role names in prompts, or use the global custom-instructions snippet and leading aliases such as
use pipeline .../使用flow ...; those aliases only change the current agent's working style and do not auto-spawn subagents. - Do not expect
/agentto display generated custom roles fromconfig.toml. - Example:
Have reviewer inspect the patch and have generalist draft the migration notes.
- Ask Codex to use role names in prompts, or use the global custom-instructions snippet and leading aliases such as
Quick Start
- Load the orchestrator (handoff protocol is embedded for portability):
opencode/agents/orchestrator-pipeline.md
- Run
/run-pipelinewith an optional effort flag:
/run-pipeline Implement OAuth2 login --effort=balanced
- Optional smoke-check run:
/run-pipeline Run tests only --test-only
Common OpenCode commands
/run-pipeline ...Default end-to-end implementation flow./run-analysis ...Runs a bounded post-hoc analysis pipeline for correctness, complexity, robustness, and conditional numerics review./codex-imagegen ...Generates or edits images by delegating to Codex CLI$imagegenwith Codex quota, per-runimage_generationenablement, and no API/provider fallback./artgen ...Produces the normal bounded 2D asset brief/prompt package, and with--gen-provider=codexcan also hand the final prompt to Codex image generation usingdanger-full-accessfor that delegated imagegen step./usageShows live Codex quota windows./usage-status-onTurns on the usage footer plugin./usage-status-refreshForces a fresh usage refresh./effort-medium,/effort-high,/effort-maxSets a reasoning-effort floor for supported GPT-5 sessions./run-monetize ...Runs a monetization analysis flow with a dedicated market-research lane and monthly USD scenarios.
Local Codex account commands
These commands manage OpenCode's local openai-codex-accounts.json selection file when one exists.
/codex-accountLists discovered local Codex account-selection files, the active stored account, and the switchable choices./codex-account-switch --email=<address-or-label>Switches to a specific stored account./codex-account-switch --index=<n>Switches to the stored account entry that owns that index./next-codex-accountRotates to the next stored account in the selected file.
Behavior notes:
- If only one stored account is available,
/next-codex-accountis a no-op and returns a note explaining there is nothing to rotate. - If no local OpenCode account-selection file exists, these commands report that clearly instead of guessing.
- These commands only manage OpenCode's local stored account-selection file. They do not create new logins by themselves.
- If Codex usage is coming only from
~/.codex/auth.jsonand there is no OpenCode project account file,/usagecan still work while/next-codex-accounthas nothing to rotate.
Examples:
/codex-account
/codex-account --json
/codex-account-switch --email=bohewu@gmail.com
/codex-account-switch --index=2
/next-codex-account
CI Pipeline
Use /run-ci to create CI/CD plans and (optionally) generate workflows.
Examples:
/run-ci Plan CI/CD for .NET + Vue
/run-ci Plan CI/CD --generate --github
/run-ci Plan CI/CD --generate --github --docker --deploy
Modernize Pipeline (Experimental)
Use /run-modernize for legacy modernization planning. It produces:
modernize/modernize-current-state.mdmodernize/modernize-target-vision.mdmodernize/modernize-strategy.mdmodernize/modernize-roadmap.mdmodernize/modernize-risks.md
Modes:
-
/run-modernize --decision-only(current-state + target-vision + strategy only) -
/run-modernize --iterate(one revision round after initial docs) Recommended execution split: -
Start
/run-modernizein the source project. -
Keep modernization docs and handoff files under the source project's
.pipeline-output/modernize/. -
In same-session execution-enabled runs, target-local
.pipeline-output/should be created as soon as delegated implementation starts. -
Once implementation starts, switch to the target project for
/run-pipelineruns. -
Keep implementation/test/review artifacts under the target project's
.pipeline-output/pipeline/. -
Mirror the latest modernization handoff into the target project's
.pipeline-output/modernize/when the target directory exists. -
If the target project does not exist yet, create it manually before running execution modes.
General-Purpose Pipeline
Use /run-general for general-purpose mixed work such as:
- small or moderate coding/debugging tasks
- repo maintenance and validation fixes
- strategy/roadmap planning
- process/SOP design
- structured analysis and recommendation memos
- checklist/playbook drafting
Examples:
/run-general Draft a 90-day GTM roadmap
/run-general Fix the failing profile validation test --full-auto
/run-general Compare three vendor evaluation frameworks
/run-general Create an onboarding SOP for support team --confirm
General pipeline outputs are human-friendly by default:
- plain-language summary first
- clear Markdown sections
- actionable next steps
Simple Dispatcher
Use /run-simple when you want build-agent-like execution with automatic subagent delegation but no pipeline artifacts:
- no
.pipeline-output/run manifest, checkpoint, status, task-list, or dispatch-plan files - existing subagents are selected for implementation, docs, tests, review, or mechanical edits
- parallel subagent dispatch is capped by
--max-parallel=<n>
Examples:
/run-simple Fix the failing profile validation test
/run-simple Update docs and run focused validation --max-parallel=2
Workflow Guidance
New projects:
/run-ci→ CI/CD plans (docs)/run-pipeline(or/run-flowfor small, low-risk changes)/run-ci --generate --github --docker --deploywhen ready to publish
Iterative development:
/run-pipeline(or/run-flowfor small changes)/run-ciwhen CI/CD plan needs updates- Publish using
opencode/protocols/PUBLISH_SOP.md
Modernization work:
/run-modernizefrom the source project- If the target project does not exist, create it manually
- Review roadmap + handoff
/run-pipelinefrom the target project for actual implementation
Even if a runtime can do same-session cross-repo delegation, a fresh target-project session remains the recommended continuation path for modernization follow-up work.
Conceptual UI/UX Layer
Use this thin layer when you need conceptual UI/UX direction before implementation-ready spec work or after /run-ux findings need a bounded redesign pass.
- Entry command:
/uiuxinopencode/commands/uiux.md - Hidden subagent:
ui-ux-designerinopencode/agents/ui-ux-designer.md - Protocol, non-expert guidance, and intake/review rubric:
opencode/protocols/UI_UX_WORKFLOW.md - Contract bundle schema:
opencode/protocols/schemas/ui-ux-bundle.schema.json - Valid example bundle:
opencode/protocols/examples/ui-ux-bundle.valid.json - Repo-managed skill:
opencode/skills/ui-ux-workflow/SKILL.md - Repo-managed companion skill:
opencode/skills/ui-communication-designer/SKILL.md
Use /uiux for conceptual assessments, low-fi wireframes, mid-fi drafts, flows, communication-first rewrites, revised task flows, targeted microcopy rewrites, prompt export, and thin read-only preview handoffs. Use /run-ux for audits, /run-spec for implementation-ready specs, and /artgen for bounded 2D asset briefs plus optional Codex-backed generation via --gen-provider=codex.
If you want repo-owned export assets instead of inline-only output, pass --output-dir=<path>. Example:
/uiux Concept a privacy settings refactor for a desktop app --output-dir=output/uiux/
This writes a paired durable bundle under the selected repo path:
<output-dir>/<bundle-slug>.ui-ux-bundle.json<output-dir>/<bundle-slug>.ui-ux-bundle.md
Frontend UI Implementation
Use the repo-managed frontend-aesthetic-director skill when a task changes visible frontend UI and should produce implementation-quality polish rather than only a conceptual handoff. For screenshot, wireframe, or copy critique before implementation, use /uiux or ui-communication-designer first.
- Skill:
opencode/skills/frontend-aesthetic-director/SKILL.md - Upstream concept source:
/uiuxbundles, wireframes, screenshots, or Figma notes - Polish reference:
opencode/skills/frontend-aesthetic-director/references/polish-checklist.md - Verification pairing: browser tooling, Playwright, screenshots, or
opencode/skills/devtools-ux-audit/SKILL.mdwhen rendered evidence is needed
The intended handoff is /uiux -> frontend implementation -> rendered QA. If a /uiux bundle already exists, preserve its flow, surface structure, primary action, and copy intent. For existing UI cleanup, choose a preserve-vs-modernize level before choosing the concrete layout/style direction. The frontend skill should only refine visual hierarchy, tokens, spacing, responsive behavior, component states, accessibility, and defects found during rendered inspection unless the upstream handoff is impossible to implement.
For localized landing page edits, dashboard polish, component styling, forms, tables, and visual hierarchy improvements, prefer medium or high execution effort plus design-system scanning and visual QA. Do not treat xhigh reasoning as the default substitute for browser evidence, content realism, responsive checks, or accessibility states.
Example:
/run-flow Implement output/uiux/onboarding.ui-ux-bundle.md as the onboarding page. Preserve the /uiux wireframe and flow; use frontend-aesthetic-director for visual polish, design tokens, responsive behavior, and browser QA.
Protocol Validation
Validate a JSON output against the protocol schemas:
Python 3.9+ is required for this command.
python3 opencode/tools/validate-schema.py --schema opencode/protocols/schemas/task-list.schema.json --input path/to/task-list.json
Status contract fixtures follow the same validation pattern. To mirror the repository's status-layer CI checks locally, validate the positive fixtures and confirm the negative fixtures fail:
python3 opencode/tools/validate-schema.py --schema opencode/protocols/schemas/run-status.schema.json --input opencode/protocols/examples/status-layout.run-only.valid/run-status.json --require-jsonschema
python3 opencode/tools/validate-schema.py --schema opencode/protocols/schemas/run-status.schema.json --input opencode/protocols/examples/status-layout.expanded.valid/run-status.json --require-jsonschema
python3 opencode/tools/validate-schema.py --schema opencode/protocols/schemas/task-status.schema.json --input opencode/protocols/examples/status-layout.expanded.valid/tasks/task-doc-summary.json --require-jsonschema
python3 opencode/tools/validate-schema.py --schema opencode/protocols/schemas/task-status.schema.json --input opencode/protocols/examples/status-layout.expanded.valid/tasks/task-process-build.json --require-jsonschema
python3 opencode/tools/validate-schema.py --schema opencode/protocols/schemas/task-status.schema.json --input opencode/protocols/examples/status-layout.expanded.valid/tasks/task-local-server-smoke.json --require-jsonschema
python3 opencode/tools/validate-schema.py --schema opencode/protocols/schemas/task-status.schema.json --input opencode/protocols/examples/status-layout.expanded.valid/tasks/task-browser-resume.json --require-jsonschema
python3 opencode/tools/validate-schema.py --schema opencode/protocols/schemas/agent-status.schema.json --input opencode/protocols/examples/status-layout.expanded.valid/agents/agent-doc-01.json --require-jsonschema
python3 opencode/tools/validate-schema.py --schema opencode/protocols/schemas/agent-status.schema.json --input opencode/protocols/examples/status-layout.expanded.valid/agents/agent-process-01.json --require-jsonschema
python3 opencode/tools/validate-schema.py --schema opencode/protocols/schemas/agent-status.schema.json --input opencode/protocols/examples/status-layout.expanded.valid/agents/agent-server-01.json --require-jsonschema
python3 opencode/tools/validate-schema.py --schema opencode/protocols/schemas/agent-status.schema.json --input opencode/protocols/examples/status-layout.expanded.valid/agents/agent-browser-02.json --require-jsonschema
To replay the local-preview lifecycle boundary behind the devtools-ux-audit guidance, run:
node scripts/validate-local-preview-lifecycle-smoke.cjs
See opencode/protocols/SCHEMAS.md and opencode/protocols/VALIDATION.md for the status layout fixture set and the negative-fixture expectations enforced in CI.
For ownership boundaries and the follow-on roadmap, see opencode/protocols/STATUS_MVP_HANDOFF.md.
If you enable custom tools, you can call the validate-schema tool from OpenCode
instead of running the script manually (see opencode/tools/validate-schema.ts).
The /usage command relies on the custom tool provider-usage for live Codex quota
inspection (see opencode/tools/provider-usage.ts).
The /codex-imagegen command relies on the custom tool codex-imagegen to invoke
Codex CLI $imagegen with the local Codex login and per-run image_generation
feature enablement. It intentionally does not call direct image APIs or use provider
fallbacks (see opencode/tools/codex-imagegen.ts). If OpenCode cannot see codex
on PATH, pass codex_command or set CODEX_IMAGEGEN_CODEX_COMMAND; on Windows
the tool also checks common npm/fnm Codex CLI install paths before warning. Use
--output-path=path/to/file.png when the generated image needs a deterministic
file target; the command maps it to the tool's output_path argument.
The /skill-list, /skill-search, and /skill-install commands rely on the custom
tool skill-manager for local skill discovery plus curated catalog installs from
anthropics/skills and github/awesome-copilot (see opencode/tools/skill-manager.py
and opencode/tools/skill-manager.ts).
Use --ref=<tag|sha> for reproducible remote skill installs instead of mutable default-branch HEAD.
See docs/external-dependencies.md for auth requirements, rate limits, privacy boundaries, fallback behavior, and remote-install auditability notes.
Config Example
An example OpenCode config is provided at opencode.json.example.
Flags
Use flags after the main task prompt. Tokens starting with -- are treated as flags.
For resume-only flows, --resume can be used without a new prompt.
--dry- Stop after
atomizer + router - Output TaskList and DispatchPlan only
- Stop after
--no-test- Skip test-runner stage
- Reviewer must warn about missing verification
--test-only- Only run test-runner + reviewer
--loose-review- Reviewer does not require build/test evidence
- Reviewer must add a warning that results are unverified
--effort=low|balanced|high- low: Favor the smallest viable plan and fewer retries
- balanced: Practical default depth with standard validation
- high: Allow deeper analysis and higher execution rigor
--resume- Resume from the newest compatible
<run_output_dir>/checkpoint.jsonunder the selected output root - Can be used without a new prompt (reuses
checkpoint.user_promptwhen valid)
- Resume from the newest compatible
--commit=off|before|after- Optional git helper lane for pre-run or post-run commits
- Does not consume Flow's max-5 task budget or the pipeline
TaskListquota - Explicit
--commit=*wins over workflow-style commit wording in the prompt
--compress- Write reusable
context-pack.jsonat the end of the run - On clearly trivial successful runs, the pipeline writes a minimal valid pack inline instead of paying for a separate compressor subagent call
- Write reusable
--confirm- Pause after each stage for review
--verbose- Implies
--confirm, plus per-task pauses during execution
- Implies
--autopilot- Run non-interactively
- Overrides
--confirm/--verbosepauses - Continues other runnable work first, then attempts one bounded blocker-recovery pass for non-hard blockers
- Stops only on hard blockers (destructive/irreversible actions, security/billing impact, missing credentials)
--full-auto- Hands-off preset for stronger execution
- Implies
--autopilot - Disables interactive pauses
- For
/run-flow, defaults to--force-scoutunless you override scout mode - Defaults to
--effort=highand--max-retry=5unless you override them explicitly - Prefers the strongest safe bounded in-scope blocker recovery path before surfacing a non-hard blocker
- Still stops on hard blockers and does not permit scope expansion or leaving resources running
Flag precedence:
--dryoverrides--test-onlywhen both are present.--full-autoimplies--autopilot.--autopilotoverrides interactive pauses from--confirm/--verbose.--commit=*runs as a workflow helper, not a canonical task.
Examples:
/run-pipeline Refactor cache layer --no-test
/run-pipeline Improve search relevance --effort=balanced
/run-flow --resume
/run-pipeline --resume --autopilot
/run-pipeline Implement OAuth2 login --commit=before
/run-goal Ship onboarding cleanup --goal-id=goal-onboarding-cleanup --commit=after --kanban=auto
/run-flow Ship login improvements --full-auto
/run-flow Ship login improvements --commit=after
/run-goal --resume --goal-id=goal-onboarding-cleanup
/run-pipeline Ship migration end-to-end --full-auto
When to Use --autopilot vs --full-auto
| Scenario | Recommended flag | Why |
|---|---|---|
| Quick task, low risk, you just want no pauses | --autopilot | Runs non-interactively with default effort/retries; stops on hard blockers |
| You want to walk away and let the pipeline finish | --full-auto | Non-interactive preset with strongest safe bounded recovery before surfacing non-hard blockers |
| You want non-interactive but lower cost | --autopilot --effort=low | Autopilot suppresses pauses; effort=low keeps retries minimal |
| You want full-auto but cap retries | --full-auto --max-retry=2 | full-auto sets the baseline; explicit flags still override |
| Flow task, want forced repo scouting | --full-auto | Flow full-auto defaults to --force-scout |
| Modernize full-exec, no supervision | --full-auto | Defaults depth to deep, disables pauses, and forwards stronger full-auto behavior to delegated pipeline phases |
Rule of thumb:
--autopilot= "don't ask me questions, use safe defaults"--full-auto= "don't ask me questions, try your hardest to finish everything"
Both flags stop on hard blockers (destructive actions, security/billing impact, missing credentials). The difference is that --full-auto also raises preset defaults and prefers the strongest safe bounded in-scope recovery before giving up on non-hard blockers.
Explicit flags always win: --full-auto --effort=low --max-retry=1 gives you full-auto's recovery posture but with low effort and only 1 retry.
Execution Resource Control
- Dispatch plans annotate every batch with
resource_class,max_parallelism,teardown_required, and optional timeout hints. - Browser and local-server tasks are routed conservatively and should run one at a time by default.
- Process-class tasks stay conservative;
teardown_requiredis only set when explicit shutdown is still needed after the command. - Executors and test runners must tear down Node.js, Playwright, browser, and other background resources before reporting success.
- Missing teardown evidence for heavy tasks should be treated as incomplete execution, not a clean pass.
Session vs Checkpoint Behavior
- A new chat/session does not automatically inherit prior runtime state or stage progress.
- Cross-session continuation works through persisted files under the selected output root (default:
.pipeline-output/), with each run written to its own<run_output_dir> = <output_root>/<run_id>/directory. - To continue an interrupted Flow or Pipeline run, use
--resumefrom the same project and output root; resume-only flows should pick the newest compatible run directory unless you explicitly target a specific run directory. - If
--resumeis not provided, the orchestrator starts a fresh run even if older artifacts still exist. - Persisted artifacts may still be reused as inputs when the prompt explicitly references them or when the protocol treats them as optional context, but that is not the same as checkpoint resume.
Orchestrators
- Goal:
/run-goal(stateful outer goal session; ordered batches; resume by--goal-id; defaults each batch to Flow) - Full:
/run-pipeline(multi-stage pipeline with reviewer and retries) - Short:
/run-pipeline --decision-only(stops after planning/integration design; directional review only) - Spec:
/run-spec(review-ready development spec for humans first, pipeline-ready handoff second) - Flow:
/run-flow(max 5 atomic tasks; bounded parallel execution; no reviewer or retries) - Simple:
/run-simple(build-agent-like subagent dispatcher; no run artifacts) - Committee:
/run-committee(decision support; experts + KISS soft-veto + judge) - General:
/run-general(general dispatcher for coding, maintenance, planning, writing, and analysis) - UX:
/run-ux(normal-user experience audit with profile-aware viewport scoring) - CI:
/run-ci(docs-first CI/CD planning; optional generation) - Modernize:
/run-modernize(experimental modernization planning docs)
Choosing a Pipeline (Quick Guide)
- Use
/run-committeewhen:- you need a recommendation/decision (architecture, tradeoffs, approach selection)
- you want multiple perspectives + a final judge, with budget as an explicit criterion
- Use
/run-analysiswhen:- you want a post-hoc findings report instead of code changes
- you need severity-ranked correctness / complexity / robustness review grounded in code references
- Use
/run-flowwhen:- the change is small, low-risk, and you mainly want a fast execution plan (max 5 atomic tasks)
- Use
/run-simplewhen:- you want build-agent-like execution with automatic subagent delegation
- you do not want
.pipeline-output/, run manifests, checkpoint/status files, task lists, or dispatch plans - you want to cap parallel subagents with
--max-parallel=<n>
- Use
/run-specwhen:- you want to review a development spec before implementation starts
- you want a human-readable
DevSpecplus a machine-readable handoff for later/run-pipelineexecution
- Use
/run-generalwhen:- you want the default general dispatcher for mixed repository work
- the task may involve coding, debugging, maintenance, planning, analysis, writing, or operational documentation
- you want either direct completion or a concrete
/run-pipeline//run-flowhandoff recommendation, not a generic refusal
- Use
/run-uxwhen:- you want a bounded UX audit from a normal-user perspective
- you need profile-aware scoring across desktop/mobile viewports without assuming mobile-first behavior
- you want prioritized UX findings and a practical scorecard before implementation changes
- Use
/run-pipelinewhen:- the change is high-risk, multi-file/systemic, or needs reviewer gates + bounded retries
Naming Convention
- Repo name (
agents-pipeline) reflects the overall concept. - Full pipeline uses
*-pipelinenaming (e.g.orchestrator-pipeline.md,run-pipeline.md). - Flow pipeline uses
*-flownaming (e.g.orchestrator-flow.md,run-flow.md). - Simple dispatcher uses
*-simplenaming (e.g.orchestrator-simple.md,run-simple.md). - General-purpose pipeline uses
*-generalnaming (e.g.orchestrator-general.md,run-general.md). - Spec pipeline uses
*-specnaming (e.g.orchestrator-spec.md,run-spec.md). - CI pipeline uses
*-cinaming (e.g.orchestrator-ci.md,run-ci.md). - Modernize pipeline uses
*-modernizenaming (e.g.orchestrator-modernize.md,run-modernize.md). - Analysis pipeline uses
*-analysisnaming (e.g.orchestrator-analysis.md,run-analysis.md). - UX pipeline uses
*-uxnaming (e.g.orchestrator-ux.md,run-ux.md).
AGENT RESPONSIBILITY MATRIX
| Agent | Primary Responsibility | Forbidden Actions |
|---|---|---|
| orchestrator-ci | CI/CD planning pipeline | Implementing code |
| orchestrator-modernize | Modernization planning pipeline | Implementing code |
| orchestrator-pipeline | Flow control, routing, retries, synthesis | Implementing code |
| orchestrator-spec | Development spec orchestration | Implementing code |
| orchestrator-flow | Flow orchestration with max-5 tasks | Implementing code |
| orchestrator-simple | Build-style subagent dispatch without run artifacts | Implementing code |
| orchestrator-committee | Decision committee orchestration (experts + KISS soft-veto + judge) | Implementing code |
| orchestrator-general | General-purpose task routing and synthesis | Direct implementation instead of delegation |
| orchestrator-analysis | Post-hoc analysis orchestration | Implementing code |
| orchestrator-ux | UX audit orchestration with profile-aware scoring | Implementing code |
| specifier | ProblemSpec / DevSpec extraction | Proposing solutions |
| planner | High-level planning | Atomic task creation |
| repo-scout | Repo discovery | Design decisions |
| atomizer | Atomic task DAG | Implementation |
| flow-splitter | Max-5 Flow task decomposition | Implementation |
| router | Cost-aware assignment | Changing tasks |
| executor | Task execution | Scope expansion |
| test-runner | Tests & builds | Code modification |
| reviewer | Quality gate | Implementation |
| compressor | Context reduction | New decisions |
| handoff-writer | Cross-session handoff artifacts | Scope expansion |
| kanban-manager | Root-tracked kanban management | Scope expansion |
| session-guide-writer | Root-tracked session guide refresh | Scope expansion |
| summarizer | User summary | Technical decisions |
Versioning
- Single source of truth: root
VERSIONfile (SemVer withoutv, for example0.24.3). - Use SemVer tags with
vprefix (for example:v0.24.3). - Stay in
0.xwhile the pipeline and prompts evolve quickly. - In
0.x, treat minor bumps as potentially breaking (v0.5.0->v0.6.0). - Use patch bumps for docs/scripting fixes without intended behavior changes.
- Release CI checks
VERSIONand tag alignment (VERSION=0.24.3must release asv0.24.3). - After bumping
VERSION, runpython3 scripts/sync-readme-version.pyto refresh the pinned README release examples before commit. - README pinned examples that include explicit release versions must use the current
VERSIONvalue; CI validates those exact snippets. - Track release notes in
CHANGELOG.md.
Release CI
- Workflow:
.github/workflows/release.yml - Trigger: push tag
v*(for examplev0.24.3) or manualworkflow_dispatch - Output assets:
agents-pipeline-opencode-bundle-vX.Y.Z.tar.gzagents-pipeline-opencode-bundle-vX.Y.Z.zipagents-pipeline-opencode-bundle-vX.Y.Z.SHA256SUMS.txt
- Release workflow verifies downloaded artifact checksums before publishing release assets.
- Release workflow generates GitHub Artifact Attestations for the bundle artifacts and verifies them before publishing release assets.
CI Checks
- Workflow:
.github/workflows/ci.yml - Trigger:
pull_request, push tomain, manualworkflow_dispatch - Checks:
VERSIONformat check- README pinned version snippet validation against root
VERSION - schema validator script sanity check
- dispatch-plan resource schema/examples validation (positive + negative cases)
- status contract schema/examples validation (
run-status,task-status,agent-status; positive + negative fixtures) - modernize execution handoff schema/examples validation (positive + negative case)
- resource-control prompt coverage assertions for router/orchestrator/executor/reviewer docs
- Copilot export script strict dry run
- installer script syntax and dry-run validation
Example release:
git tag v0.24.3
git push origin v0.24.3
Public Release Checklist
- Confirm there are no secrets or private endpoints in the repo.
- Review git history for removed secrets if any (history still contains them).
- Ensure
opencode.json.examplecontains no real keys. - Verify
LICENSEexists and matches intended usage. - Verify README usage notes align with your public story.
Secret Scan (Optional)
If you already have a secret scanner installed, run one of:
gitleaks detect --source .
trufflehog filesystem .
Use whichever tool your team prefers.