v28.24 adds a semantic PR-readiness boundary so the final local diff is validated and reviewed before publication, while keeping existing gated-action semantics.

OpenCode Agent Pack v28.24

Model-agnostic agents · Startup blocks · OCR review · Clean PR branches · Persistent planning · Readable output

---

What's new in v28.24

• Added a semantic PR Readiness Gate before the first/next publication of task changes; it does not add a new approval gate or run before every local commit.
• Pre-publication review now has freshness semantics: when reviewer criteria apply, @reviewer must cover the current final local diff, and later code/history changes invalidate affected review evidence.
• Matching skills must be actually loaded/read via SKILL.md; merely naming a skill no longer counts as use. Installers now copy complete skill directories into OpenCode skill discovery roots so their references/support files remain available.
• Non-trivial multi-state/path bugfixes now require a compact case-to-verification check before editing, without forcing a matrix for simple local fixes.
• Existing v28.23 PR-body sync and 10-minute OCR timeout rules are retained.

v28.15 cleanup retained

• Permissions now follow default-allow style with only role-incompatible tools disabled.
• Commands stay minimal: description, agent, and subtask: false; no command-level permission sandbox.
• Built-in/base agents build, explore, general, and plan are preserved unchanged by name.
• Duplicate plan/review commands were folded into /plan and /review.
• Custom agent/command names were shortened and made consistent.
• The stale command JSONC snippet was removed; commands/*.md is the single command source of truth.

---

What this is

This is an opinionated OpenCode / OpenChamber agent configuration pack for real project work: bugfixing, UI work, PR follow-up, code review, release prep, project audits, long investigations, and multi-agent workflows.

Core rule:

Understand the request by meaning, preserve user/project contracts, keep long work in files, prove branch safety before publication, and write human-readable output.

---

Highlights

Area	What this pack enforces
Model agnostic	Agents do not contain provider-specific model: overrides. They use the active OpenCode/OpenChamber model.
Semantic routing	Route by normalized intent, scope, target, action level, confidence, and evidence — not magic trigger phrases.
Startup block	Before tools, emit a compact Markdown block with route, mode, summary, scope, gated status, and next action.
Behavioral contracts	Before user-facing changes, preserve the natural user action/value source instead of exposing raw internals.
Right-level fixes	Fix the shared helper/service/composable/API wrapper when the bug belongs there, not only the first call site.
Gated actions	Commits, pushes, PRs, releases, deps, secrets, destructive commands, runtime config, and broad product/architecture choices require approval.
Git sync before mutation	The active primary/orchestrator handles base-branch sync before mutation/publication work; leaf subagents are not forced to fetch before inspection.
PR branch provenance	Before commit/push/PR/update, agents prove the branch contains only intended commits/files.
PR body sync	Before marking PR work done, agents verify the PR title/body still match final commits, diff, scope, and validation.
PR readiness	Before publishing task changes, the primary/orchestrator proves the current final diff has fresh contract, validation, review, provenance, and PR metadata evidence.
OCR review	Alibaba open-code-review is the preferred backend for code/diff/PR review when installed and allowed.
Skills	Matching installed/project-listed skills are actually read from SKILL.md before implementation/review; referenced material is loaded only when relevant.
Persistent planning	Long-running/multi-agent work uses durable plans/<plan>/ artifacts.
Readable output	User replies, PR comments, issues, releases, changelogs, reviews, and handovers must be concise, skimmable Markdown/plain text.

---

Startup block before tools

Every multi-step, repository, issue/PR/release, external-URL, codebase, mutation-capable, publication-capable, or scope-expanding workflow must emit this visible Markdown block once, before the first tool call only:

### Startup
- Route: `<route>`
- Mode: `<read-only | options | edit-capable | gated>`
- Summary: <one sentence>
- Scope: <target + boundary>
- Gated: `<no | yes>` — <reason>
- Next: <next action/tool>

Rules:

• Use Markdown, not a prose paragraph.
• Keep field names in English.
• Keep it short: heading + six bullets.
• Emit it once per user-request workflow or agent invocation.
• Do not repeat it before every tool call or substep.
• For read-only work: Gated: no — read-only.
• Put the scope boundary in Scope before broad discovery.
• Do not use tools before this block except for a trivial single-step answer that needs no tools.
• If route, mode, or scope materially changes later, write a short ### Update block instead.

---

Git and PR safety

Pre-edit branch sync and clean-task gate

Before changing code/config/docs in a repository, the active primary/orchestrator must prove the branch is safe to edit.

Typical pre-edit checks:

git status -sb
git branch -vv
git remote -v
git fetch --prune <head_remote>
git fetch --prune <base_remote>
git log --oneline --decorate <base_ref>..HEAD
git diff --name-status <base_ref>...HEAD
git diff --stat <base_ref>...HEAD

If the current branch tracks upstream and is behind, update before editing only with safe git pull --ff-only.

For a new independent task, the branch must be clean relative to <base_ref> before edits. Do not fix on a branch already carrying unrelated commits/files. Use a clean branch from <base_ref> and re-apply only intended work.

PR branch provenance gate

A PR is the entire base-to-head comparison, not the last commit.

Before commit, push, PR creation, or PR update, fetch again and prove that the branch contains only intended commits/files. Stop if remote head changed unexpectedly, the branch diverged, or unrelated work appears.

Use explicit refs such as <base_remote>=origin, <base_branch>=main, <base_ref>=origin/main.

Useful file:

docs/git_branch_provenance_policy.md

Command:

/pr-provenance

PR readiness gate

Before the first push/PR publication of task changes, and before later pushes that change an existing PR diff, establish readiness for the current final local diff. This is separate from approval: the normal gated-action rule still controls whether publication is allowed.

Applicable readiness evidence covers repository/scoped guidance, selected skills, right-level/edge-path reasoning, actual validation results, reviewer freshness when reviewer criteria apply, branch provenance, and current PR metadata. External CI/bot review is additional post-publication evidence, not a substitute for required pre-publication review.

If code or history changes after validation/review, re-run only the affected evidence. Do not repeat the gate before every local edit or commit.

Useful file:

docs/pr_readiness.md

---

Installed skills

Installed skills are advisory guidance after Startup/normalization. When a matching skill is selected or required, read its SKILL.md before implementation/review; naming it is not enough. Load referenced skill material only when relevant. Skills do not override project rules, gates, existing tooling, minimal diff, OCR policy, PR readiness, or PR provenance.

Useful file:

docs/language_spec.md

Current mapping includes Python, TypeScript, Go, C++, Rust, React, Vue, security-sensitive code, Playwright/E2E, and API/OpenAPI work.

---

OCR / Open Code Review integration

Alibaba open-code-review is the preferred backend for code/diff/PR review when installed and allowed.

Policy:

OCR is the review engine. @reviewer is the policy and judgment layer.

The reviewer must:

• emit the Startup block before tools;
• normalize review target and scope;
• check privacy/gated status because OCR may send code/diffs/context to the configured LLM provider;
• run OCR with --audience agent, --timeout 10, and useful --background context when allowed;
• do not run OCR through a 120-second shell/tool timeout; use at least 10 minutes when supported;
• filter false positives and low-value nits;
• add right-level, behavioral-contract, tests, and risky API/schema/config judgment;
• never auto-apply fixes for review-only requests.

Useful files:

docs/ocr_review_policy.md
commands/review.md
agents/reviewer.md
snippet/open-code-review-usage.md

---

Core philosophy

Route by meaning, not words

Persistent Planning Mode activates when the normalized task is long-running, broad-scope, multi-agent, multi-session, likely to lose useful context, or likely to require phased execution, reviews, handoffs, or resumable state.

Phrases like full-project inspection, broad bug hunt, large refactor, or project-wide audit are examples/signals, not trigger phrases.

Preserve behavioral contracts

A schema type does not define the user experience.

Before changing user-facing behavior, agents must identify:

• what action the user naturally performs;
• who or what provides the value;
• what values are valid and where that domain comes from;
• which existing project pattern handles the same kind of action;
• whether the naive fix exposes raw/internal/manual values.

Files are memory for long work

For long-running tasks:

Chat history is not memory. Private reasoning is not memory. Canonical files are memory.

Use plans/<plan>/ so another model/provider/session can resume from durable artifacts.

Public output should be readable

No AI wall of text.

Default to target-aware Markdown/plain text:

• short summary first;
• headings only when useful;
• bullets for multiple reasons, risks, files, or checks;
• fenced code blocks for commands, logs, paths, config, or exact proposed text;
• compact tables only when the target renders them well;
• clear conclusion/next action.

For OpenCode CLI, Telegram, Hermes, terminals, and chat relays, prefer compact Markdown/plain text and avoid raw HTML, oversized tables, deeply nested lists, and GitHub-only formatting.

---

Directory layout

AGENTS.md
agents/
commands/
docs/
install/
snippet/

Persistent planning layout inside a target project:

plans/<plan>/
  plan.md
  phases/
    phase-N.md
  implementation/
    phase-N-impl.md
  reviews/
    plan-review.md
    impl-plan-review-phase-N.md
    impl-review-phase-N.md
  todo.md
  handovers/
    session-YYYY-MM-DD.md

docs/
  overview.md
  modules/
  features/
  handovers/
    session-YYYY-MM-DD.md

---

Workflow modes

Mode	Flow
Small/focused work	normalize -> inspect -> implement if allowed -> verify -> report
User-facing work	normalize -> inspect -> Behavioral Contract Check -> implement -> verify -> review/report
Long-running work	Discuss -> /plan -> /review when needed -> /execute-plan -> /review when needed -> /plan update/handover

Broad implementation uses:

Blueprint -> Gate -> Execute -> Digest

---

Commands included

Command	Purpose
/bugfix	Full bugfix workflow with investigation, fix, verification, and review.
/bug-issue	Verify a bug report and draft/open a factual issue when requested.
/code-explore	Explore code and return facts, paths, call paths, and patterns.
/debug	Reproduce/root-cause/fix a concrete failure or runtime error.
/devops-check	Inspect Docker/systemd/CI/runtime/deployment state.
/verify	Run tests, linters, builds, and smoke checks without editing.
/review	Unified review command for code, PRs, plans, implementation plans, results, and fix-level checks; prefers OCR when installed and allowed.
/pr-followup	Follow-up work on an existing PR with branch provenance checks.
/pr-provenance	Read-only proof that the current branch/PR contains only intended commits/files.
/audit	Broad repository/project audit with persistent planning when scope requires it.
/release-prep	Release notes and release checks from verified facts only.
/plan	Create/resume/update/handover persistent plan state and author implementation plans.
/execute-plan	Execute an approved plan/work package using Blueprint → Gate → Execute → Digest.
/ui-audit	UI/layout/UX audit.
/ui-options	UI redesign options without editing.
/ui-plan	Concrete UI redesign/theme plan.
/ui-redesign	Full UI redesign workflow.
/ui-implement	Implement an approved UI plan.
/ui-a11y-check	Accessibility/keyboard/focus/contrast/responsive check.
/ui-mcp-setup	UI MCP setup.
/ui-uupm-setup	UI UX Pro Max / UUPM setup.

---

Install

Global install

./install/install-global.sh

Installs to:

~/.config/opencode/AGENTS.md
~/.config/opencode/agents/
~/.config/opencode/commands/
~/.config/opencode/docs/
~/.config/opencode/skills/
~/.config/opencode/snippet/

Project-local install

Run from the repository root:

/path/to/opencode_model_agnostic_persistent_v28_24/install/install-project.sh

Installs to:

./AGENTS.md
./.opencode/agents/
./.opencode/commands/
./.opencode/docs/
./.opencode/skills/
./.opencode/snippet/

---

Validation checklist

This pack is expected to validate with:

• expected v28.15 compact baseline plus v28.24 PR-readiness/skill-freshness updates and retained v28.23 PR-body/OCR rules;
• YAML frontmatter parses for all agents and commands;
• no command has subtask: true;
• no command has a permission: block;
• no stale deleted command or renamed agent references remain;
• install scripts pass bash -n and copy complete skill directories to project/global OpenCode skill roots;
• no provider-specific model: overrides in agents;
• no stale provider-specific model IDs;
• no plural snippet-directory path references;
• root rules include semantic routing, startup blocks, behavioral contracts, skills, OCR review, branch provenance, persistent planning, and readable public output.

---

Recommended use

Use this pack when you want agents that can:

• inspect a project for a long time without losing context;
• hand off work between models/providers;
• avoid duplicate fixes across multiple agents;
• preserve UI/product behavior instead of only satisfying schema plumbing;
• use OCR for stronger code/diff/PR review when available;
• keep GitHub/PR/release work safe and evidence-based;
• format GitHub/Telegram/Hermes/OpenCode CLI output cleanly.

---

Upstream references

This pack references upstream tools/skills but does not vendor or overwrite them.

• Alibaba open-code-review: https://github.com/alibaba/open-code-review
• Jeffallan claude-skills: https://github.com/Jeffallan/claude-skills

---

OpenCode Agent Pack v28.24
Semantic routing · Skills · OCR review · Clean PR branches · Durable plans