https://github.com/bohewu/agents_pipeline
Installable multi-agent pipeline for OpenCode, Codex, Claude Code, and Copilot, with usage/quota tooling and TUI plugins.
https://github.com/bohewu/agents_pipeline
agentic-workflow ai-agents claude-code codex github-copilot multi-agent opencode orchestrator tui-plugin
Last synced: 9 days ago
JSON representation
Installable multi-agent pipeline for OpenCode, Codex, Claude Code, and Copilot, with usage/quota tooling and TUI plugins.
- Host: GitHub
- URL: https://github.com/bohewu/agents_pipeline
- Owner: bohewu
- License: mit
- Created: 2026-02-03T00:05:45.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-05-28T01:30:48.000Z (27 days ago)
- Last Synced: 2026-05-28T03:17:41.381Z (27 days ago)
- Topics: agentic-workflow, ai-agents, claude-code, codex, github-copilot, multi-agent, opencode, orchestrator, tui-plugin
- Language: Python
- Homepage:
- Size: 3.24 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 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](#tldr)
- [Project Docs](#project-docs)
- [Usage Prerequisites](#usage-prerequisites)
- [Install (Recommended)](#install-recommended)
- [Developer Install (Clone Repo)](#developer-install-clone-repo)
- [How To Use](#how-to-use)
- [Quick Start](#quick-start)
- [VS Code Copilot Agents](#vs-code-copilot-agents)
- [Claude Code Subagents](#claude-code-subagents)
- [Codex Agent Roles](#codex-agent-roles)
- [Conceptual UI/UX Layer](#conceptual-uiux-layer)
- [Frontend UI Implementation](#frontend-ui-implementation)
- [Workspace Agent Model Profiles](#workspace-agent-model-profiles)
- [Protocol Validation](#protocol-validation)
- [Config Example](#config-example)
- [Flags](#flags)
- [Orchestrators](#orchestrators)
- [Versioning](#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 extra `chmod` step 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.ps1` or `agent-profile.sh` to generate `.opencode/agents` overrides from tiered profiles and provider model sets.
## Project Docs
- `CONTRIBUTING.md` for repo layout, single-source-of-truth rules, local validation, and release expectations.
- `SECURITY.md` for private vulnerability reporting and token/supply-chain handling guidance.
- `COMPATIBILITY.md` for runtime and host-environment assumptions.
- `docs/external-dependencies.md` for network/auth/rate-limit/fallback/privacy notes on `provider-usage`, `skill-manager`, and bootstrap installers.
- `docs/art-generation-scaffold.md` for the bounded 2D asset brief/prompt scaffold, standardized External Handoff Package, Direct Use Prompt, and optional `/artgen --gen-provider=codex` bridge used by the repo-managed `artgen-scaffold` skill, `art-director`, and the normal `/artgen` surface.
- `opencode/skills/codex-imagegen/SKILL.md` for the Codex CLI `$imagegen` bridge used by `/codex-imagegen` when OpenCode should generate images through Codex quota without direct API or provider fallback.
- `opencode/protocols/UI_UX_WORKFLOW.md` for the thin conceptual UI/UX layer, non-expert design/interaction guidance, communication-first overlay, intake/review rubric, and the `ui-ux-bundle` schema/example bundle used by `/uiux`, `ui-ux-designer`, and the repo-managed `ui-ux-workflow` and `ui-communication-designer` skills.
- `opencode/skills/frontend-aesthetic-director/SKILL.md` for 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.md` for workspace-local OpenCode agent model profiles, provider model sets, and safe generated overrides under `.opencode/agents`.
- `docs/runtime-agent-model-profiles.md` for 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`, and `scripts/export-codex-agents.py`)
- PowerShell 7+ (for `scripts/install.ps1` on Windows) or Bash (for `scripts/install.sh` on macOS/Linux)
- `curl` + `tar` + `sha256sum` (or `shasum`) 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:
```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
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](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](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 `/usage` plus the usage footer plugin: use `Usage 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`, or `Codex roles`.
Pick the install target that matches what you want:
- [OpenCode core](#opencode-core): install the main OpenCode config only.
- [Status plugin only](#status-plugin-only): install just the OpenCode status runtime plugin.
- [Usage only](#usage-only): install just the usage command/tool and the usage-status plugin.
- [Effort-control plugin only](#effort-control-plugin-only): install just the OpenCode GPT-5 reasoning-effort controller for OpenAI and GitHub Copilot.
- [All local assets](#all-local-assets): install OpenCode core + status/usage/effort plugins + Copilot + Claude + Codex in one step.
- [Copilot agents](#copilot-agents): install only VS Code Copilot custom agents.
- [Claude Code subagents](#claude-code-subagents): install only Claude Code agent markdown files.
- [Codex roles](#codex-roles): install only Codex role config.
PowerShell tips:
- Prefer pinned tags over `main`.
- Pass `-Target` explicitly when you know the install location.
- When combining PowerShell switch flags with other arguments, prefer `-Flag:$true` form 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):
```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:
```bash
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):
```powershell
irm https://raw.githubusercontent.com/bohewu/agents_pipeline/main/scripts/bootstrap-install.ps1 | iex
```
```bash
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):
```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:
```bash
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):
```powershell
pwsh -NoProfile -File .\bootstrap-install-plugin-status-runtime.ps1 -Version $tag -Target "$HOME\.config\opencode\plugins\status-runtime.js" -DryRun
```
```bash
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):
```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:
```bash
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):
```powershell
pwsh -NoProfile -File .\bootstrap-install-usage-only.ps1 -Version $tag -OpenCodeTarget "$HOME\.config\opencode" -UsagePluginTarget "$HOME\.config\opencode\plugins\usage-status.js" -DryRun
```
```bash
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 `300` seconds.
- If you want the latest values on demand, use `/usage-status-refresh` or run `/usage`.
- Use `/usage-status-short` for a compact one-line summary or `/usage-status-detail` for the richer sidebar card view.
- Use `/usage-status-codex` to 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 --json` remains 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):
```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:
```bash
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):
```powershell
pwsh -NoProfile -File .\bootstrap-install-plugin-effort-control.ps1 -Version $tag -Target "$HOME\.config\opencode\plugins\effort-control.js" -DryRun
```
```bash
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 least `medium`, but leaves structured low-reasoning roles such as `specifier`, `planner`, `router`, `repo-scout`, `flow-splitter`, `codex-account-manager`, and `test-runner` excluded.
- 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.md` and rendered QA instead of relying on reasoning effort alone.
- `/effort-medium`, `/effort-high`, and `/effort-max` set a reasoning floor. On the home screen they set a project default; inside a session they set a session override.
- `/effort-clear` removes 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):
```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:
```bash
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 with `permission denied`.
- If you specifically want `./bootstrap-install-all-local.sh ...`, run `chmod +x ./bootstrap-install-all-local.sh` first.
Download-then-run version:
```bash
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):
```powershell
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
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):
```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:
```bash
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):
```powershell
irm https://raw.githubusercontent.com/bohewu/agents_pipeline/main/scripts/bootstrap-install-copilot.ps1 | iex
```
```bash
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:
```powershell
pwsh -NoProfile -File .\scripts\install-copilot.ps1 -AgentProfile balanced -ModelSet default
```
```bash
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):
```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:
```bash
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:
```powershell
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"
```
```bash
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:
```powershell
pwsh -NoProfile -File .\scripts\install-claude.ps1 -AgentProfile balanced -ModelSet default
```
```bash
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 `/.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-.toml` for the current workspace when present, otherwise `~/.codex/agents/orchestrator-.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):
```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:
```bash
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):
```powershell
irm https://raw.githubusercontent.com/bohewu/agents_pipeline/main/scripts/bootstrap-install-codex.ps1 | iex
```
```bash
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:
```powershell
pwsh -NoProfile -File .\scripts\install-codex.ps1 -AgentProfile balanced -ModelSet openai
```
```bash
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-.toml` for the current workspace when present, otherwise `~/.codex/agents/orchestrator-.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`](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](docs/developer-install.md).
Most users should use the published release bundle commands in `Install (Recommended)` instead.
## How To Use
Repo map and platform export notes
- Agent definitions live in `opencode/agents/` (one file per agent)
- Global handoff rules are embedded in `opencode/agents/orchestrator-pipeline.md` for 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/agents` overrides from `opencode/tools/agent-profiles/*.json` and `opencode/tools/model-sets/*.json`.
- Optional runtime profiles for Codex, Copilot, and Claude Code are installer/exporter flags that reuse `opencode/tools/agent-profiles/*.json` with runtime-specific model sets; see `docs/runtime-agent-model-profiles.md`.
- Source agent frontmatter must not define `model` or `provider`; use generated workspace overrides or runtime export profile flags when you intentionally want per-agent model routing.
- VS Code Copilot `.agent.md` files are generated from OpenCode source by `scripts/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`, and `scripts/bootstrap-install-codex.sh`.
- Codex role mapping details live in `docs/codex-mapping.md`.
- Protocol and JSON schemas live in `opencode/protocols/`.
Use `opencode/protocols/PROTOCOL_SUMMARY.md` for 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.md` for stable repo guidance only; keep it limited to non-ephemeral content such as architecture landmarks, conventions, recurring commands, and canonical artifact locations
- `todo-ledger.json` as the canonical kanban / carryover data (schema in `opencode/protocols/schemas/todo-ledger.schema.json`)
- `kanban.md` as the human-readable rendered board view derived from `todo-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-ci` in `opencode/commands/run-ci.md` for CI/CD planning (docs-first; optional generation).
- Use `/run-modernize` in `opencode/commands/run-modernize.md` for modernization planning (experimental).
- Use `/run-goal` in `opencode/commands/run-goal.md` for resumable multi-batch goals that persist outer session state and default each batch to Flow.
- Use `/run-pipeline` in `opencode/commands/run-pipeline.md` to execute the full pipeline end-to-end
- Use `/run-committee` in `opencode/commands/run-committee.md` for a decision committee (experts + KISS soft-veto + judge)
- Use `/run-simple` in `opencode/commands/run-simple.md` for build-agent-like subagent delegation without run artifacts
- Use `/run-general` in `opencode/commands/run-general.md` for general-purpose mixed workflows (coding/debugging/maintenance/planning/writing/analysis/checklists)
- Use `/run-ux` in `opencode/commands/run-ux.md` for profile-aware UX audits and normal-user scorecards.
- Use `/uiux` in `opencode/commands/uiux.md` for the thin conceptual UI/UX layer routed directly to the hidden subagent `opencode/agents/ui-ux-designer.md`.
- Use `opencode/protocols/UI_UX_WORKFLOW.md` plus `opencode/protocols/schemas/ui-ux-bundle.schema.json` and `opencode/protocols/examples/ui-ux-bundle.valid.json` for the conceptual UI/UX protocol and durable bundle contract.
- Use the repo-managed `opencode/skills/ui-ux-workflow/SKILL.md` for the same bounded conceptual workflow in skill form.
- Use the repo-managed `opencode/skills/ui-communication-designer/SKILL.md` as the communication-first companion to `/uiux` when the work is mainly about task clarity, copy, trust, and screen-level redesign.
- Use the repo-managed `opencode/skills/frontend-aesthetic-director/SKILL.md` for frontend UI implementation and polish. If `/uiux` output 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-imagegen` plus the repo-managed `opencode/skills/codex-imagegen/SKILL.md` to delegate image generation to Codex CLI `$imagegen` with per-run `image_generation` feature enablement and no API/provider fallback.
- Use `/agent-profile` for deterministic workspace agent model profile installer examples.
- Use the repo-managed `devtools-ux-audit` skill for Chrome DevTools browser evidence collection. Installers mirror it into `~/.agents/skills` as the global baseline and `~/.claude/skills` as a compatibility mirror.
- Use `/skill-list` to inspect installed skills or browse curated catalogs.
- Use `/skill-search` to search installed skills plus curated catalogs.
- Use `/skill-install` to install skills from `anthropic` or `awesome-copilot`, or from a local skill folder.
- Use `opencode/protocols/UX_DEVTOOLS_WORKFLOW.md` as the browser-evidence workflow source behind that skill.
- Use `/session-guide` to create or refresh the root-tracked repo guide.
- Use `/kanban` to manage the root-tracked kanban / carryover ledger.
- Use `/emit-handoff` to create run-local handoff artifacts for a fresh session.
- Use `/usage` to inspect live Codex quota windows.
## VS Code Copilot Agents
Copilot / Claude / Codex reference
This repo can generate VS Code Copilot custom agents from `opencode/agents/*.md` with single-source maintenance.
- Generate agents directly:
```text
python3 scripts/export-copilot-agents.py --source-agents opencode/agents --target-dir /path/to/copilot/agents --strict
```
- Filename rule:
- Output filenames are generated as `.agent.md` (for example `orchestrator-pipeline.agent.md`).
- Experimental subagent mode:
- Generated orchestrators include `agents:` references for Copilot subagent routing (experimental behavior).
- Fallback mode:
- Generated `*-solo.agent.md` files run without subagents.
- Example: `@orchestrator-pipeline-solo`
After install, add your generated directory to VS Code user settings:
```json
{
"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: `/.claude/agents` when 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.md` for the frontmatter/tool mapping and `$ARGUMENTS` input 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):
```text
@orchestrator-flow Create a REST endpoint for /api/health that returns {"status":"ok"}
```
The orchestrator returns a JSON dispatch plan:
```json
{ "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:
1. Tasks with empty `deps` are spawned in parallel.
2. Tasks with `deps` wait for their dependencies to complete; results are forwarded in the prompt.
3. 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.
4. 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:**
```text
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:
```text
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`.
- Codex docs / mapping notes:
- See `docs/codex-mapping.md` for the exact field mapping, global-first install notes, and the reusable custom-instructions snippet.
- 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 `/agent` to display generated custom roles from `config.toml`.
- Example: `Have reviewer inspect the patch and have generalist draft the migration notes.`
## Quick Start
1) Load the orchestrator (handoff protocol is embedded for portability):
- `opencode/agents/orchestrator-pipeline.md`
2) Run `/run-pipeline` with an optional effort flag:
```text
/run-pipeline Implement OAuth2 login --effort=balanced
```
3) Optional smoke-check run:
```text
/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 `$imagegen` with Codex quota, per-run `image_generation` enablement, and no API/provider fallback.
- `/artgen ...`
Produces the normal bounded 2D asset brief/prompt package, and with `--gen-provider=codex` can also hand the final prompt to Codex image generation using `danger-full-access` for that delegated imagegen step.
- `/usage`
Shows live Codex quota windows.
- `/usage-status-on`
Turns on the usage footer plugin.
- `/usage-status-refresh`
Forces a fresh usage refresh.
- `/effort-medium`, `/effort-high`, `/effort-max`
Sets 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-account`
Lists discovered local Codex account-selection files, the active stored account, and the switchable choices.
- `/codex-account-switch --email=`
Switches to a specific stored account.
- `/codex-account-switch --index=`
Switches to the stored account entry that owns that index.
- `/next-codex-account`
Rotates to the next stored account in the selected file.
Behavior notes:
- If only one stored account is available, `/next-codex-account` is 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.json` and there is no OpenCode project account file, `/usage` can still work while `/next-codex-account` has nothing to rotate.
Examples:
```text
/codex-account
/codex-account --json
/codex-account-switch --email=bohewu@gmail.com
/codex-account-switch --index=2
/next-codex-account
```
More command references
## 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.md`
- `modernize/modernize-target-vision.md`
- `modernize/modernize-strategy.md`
- `modernize/modernize-roadmap.md`
- `modernize/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-modernize` in 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-pipeline` runs.
- 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:
```text
/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=`
Examples:
```text
/run-simple Fix the failing profile validation test
/run-simple Update docs and run focused validation --max-parallel=2
```
## Workflow Guidance
New projects:
1. `/run-ci` → CI/CD plans (docs)
2. `/run-pipeline` (or `/run-flow` for small, low-risk changes)
3. `/run-ci --generate --github --docker --deploy` when ready to publish
Iterative development:
1. `/run-pipeline` (or `/run-flow` for small changes)
2. `/run-ci` when CI/CD plan needs updates
3. Publish using `opencode/protocols/PUBLISH_SOP.md`
Modernization work:
1. `/run-modernize` from the source project
2. If the target project does not exist, create it manually
3. Review roadmap + handoff
4. `/run-pipeline` from 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: `/uiux` in `opencode/commands/uiux.md`
- Hidden subagent: `ui-ux-designer` in `opencode/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=`. Example:
```text
/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:
- `/.ui-ux-bundle.json`
- `/.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: `/uiux` bundles, 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.md` when 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:
```text
/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.
```text
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:
```text
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:
```text
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=` 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 and execution behavior
## 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
- `--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 `/checkpoint.json` under the selected output root
- Can be used without a new prompt (reuses `checkpoint.user_prompt` when valid)
- `--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 `TaskList` quota
- Explicit `--commit=*` wins over workflow-style commit wording in the prompt
- `--compress`
- Write reusable `context-pack.json` at 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
- `--confirm`
- Pause after each stage for review
- `--verbose`
- Implies `--confirm`, plus per-task pauses during execution
- `--autopilot`
- Run non-interactively
- Overrides `--confirm` / `--verbose` pauses
- 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-scout` unless you override scout mode
- Defaults to `--effort=high` and `--max-retry=5` unless 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:
- `--dry` overrides `--test-only` when both are present.
- `--full-auto` implies `--autopilot`.
- `--autopilot` overrides 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_required` is 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 ` = //` directory.
- To continue an interrupted Flow or Pipeline run, use `--resume` from 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 `--resume` is 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.
Agent catalog quick reference
## 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-committee` when:
- you need a recommendation/decision (architecture, tradeoffs, approach selection)
- you want multiple perspectives + a final judge, with budget as an explicit criterion
- Use `/run-analysis` when:
- 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-flow` when:
- the change is small, low-risk, and you mainly want a fast execution plan (max 5 atomic tasks)
- Use `/run-simple` when:
- 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=`
- Use `/run-spec` when:
- you want to review a development spec before implementation starts
- you want a human-readable `DevSpec` plus a machine-readable handoff for later `/run-pipeline` execution
- Use `/run-general` when:
- 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-flow` handoff recommendation, not a generic refusal
- Use `/run-ux` when:
- 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-pipeline` when:
- 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 `*-pipeline` naming (e.g. `orchestrator-pipeline.md`, `run-pipeline.md`).
- Flow pipeline uses `*-flow` naming (e.g. `orchestrator-flow.md`, `run-flow.md`).
- Simple dispatcher uses `*-simple` naming (e.g. `orchestrator-simple.md`, `run-simple.md`).
- General-purpose pipeline uses `*-general` naming (e.g. `orchestrator-general.md`, `run-general.md`).
- Spec pipeline uses `*-spec` naming (e.g. `orchestrator-spec.md`, `run-spec.md`).
- CI pipeline uses `*-ci` naming (e.g. `orchestrator-ci.md`, `run-ci.md`).
- Modernize pipeline uses `*-modernize` naming (e.g. `orchestrator-modernize.md`, `run-modernize.md`).
- Analysis pipeline uses `*-analysis` naming (e.g. `orchestrator-analysis.md`, `run-analysis.md`).
- UX pipeline uses `*-ux` naming (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
Maintainer release notes
- Single source of truth: root `VERSION` file (SemVer without `v`, for example `0.24.3`).
- Use SemVer tags with `v` prefix (for example: `v0.24.3`).
- Stay in `0.x` while 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 `VERSION` and tag alignment (`VERSION=0.24.3` must release as `v0.24.3`).
- After bumping `VERSION`, run `python3 scripts/sync-readme-version.py` to refresh the pinned README release examples before commit.
- README pinned examples that include explicit release versions must use the current `VERSION` value; CI validates those exact snippets.
- Track release notes in `CHANGELOG.md`.
## Release CI
- Workflow: `.github/workflows/release.yml`
- Trigger: push tag `v*` (for example `v0.24.3`) or manual `workflow_dispatch`
- Output assets:
- `agents-pipeline-opencode-bundle-vX.Y.Z.tar.gz`
- `agents-pipeline-opencode-bundle-vX.Y.Z.zip`
- `agents-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 to `main`, manual `workflow_dispatch`
- Checks:
- `VERSION` format 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:
```bash
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.example` contains no real keys.
- Verify `LICENSE` exists 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:
```text
gitleaks detect --source .
```
```text
trufflehog filesystem .
```
Use whichever tool your team prefers.
Generated with this repo's own /artgen --gen-provider=codex flow.