Workflow Guard

Deterministic policy and enforcement layer for OpenCode. Workflow Guard enforces safe engineering discipline through hard plugin hooks, not prompt instructions that LLMs can ignore, and pairs enforcement with a proactive workflow-tool surface for planning, review, worktree isolation, technical debt, and policy simulation.

Workflow Guard is deliberately not an agent harness: it can constrain actions, record and explain decisions, and supply bounded context, but it does not plan, prioritize, delegate, or autonomously sequence the agent's work. Bounded continuation may resume an existing session with unfinished owned todos; it never chooses the next task or creates new work.

---

Quick Start

1. Installation

Install the current published version globally:

VERSION=$(npm view opencode-workflow-guard version)
opencode plugin add "opencode-workflow-guard@$VERSION"   # OpenCode 2.x
opencode plugin "opencode-workflow-guard@$VERSION" --global --force   # OpenCode 1.x

Requires OpenCode >= 1.18. OpenCode detects the package's server and TUI targets and updates both global configs. Use the same command after a release to upgrade; the explicit version gives OpenCode a fresh package-cache key. Restart OpenCode after installation. See docs/installation.md for details and links to the OpenCode plugin documentation.

The plugin supports both generations from one package: OpenCode 1.x loads the server() entrypoint, and OpenCode 2.x loads the setup() entrypoint (@opencode/plugin). Policies, tools, and configuration behave the same on both; V2 load tests run against a real OpenCode 2 binary in npm run test:install.

For the optional TUI badge, configure "opencode-workflow-guard" in tui.json. OpenCode resolves the package's exported ./tui entrypoint automatically for TUI plugins. The companion keeps a static Workflow Guard shield in the prompt bar; warning toasts provide block details without changing agent behavior. Do not place the TUI module under the server plugins/ directory.

2. Verification

npm run typecheck    # Strict TypeScript check (0 errors)
npm test             # Run 1100+ unit and adversarial tests
npm run test:all     # Typecheck + unit + install/load checks
WORKFLOW_GUARD_LIVE_E2E=1 npm run test:install # Also run policy probes with OpenCode's most recently selected model

---

Core Guardrails Overview

The plugin enforces 24 deterministic policy rules across four main pillars:

• Branch & History Protection: Enforces feature-branch workflows (blocks edits/commits on main/master), hard-blocks direct or forced pushes to protected branches, enforces mergeability pre-flight checks, enforces secondary review approval (bound to the reviewed worktree content) before PR creation by default, and requires PR changelogs / changesets.
• Task & Verification Discipline: Gates file mutations on active todowrite tasks with subagent inheritance, blocks concurrent direct edits to the same canonical file across sessions, requires same-session fresh reads before edit/write can replace existing files, blocks silent task deletion, enforces fresh test verification evidence before task completion, and journals completion claims vs. verification mismatches.
• Secrets & Workspace Confinement: Confines edit tools and recognized shell/git mutations within the workspace root (including symlink and ../ escape checks), scrubs sensitive environment variables in agent subshells, and redacts .env reads with safe schema masks. Arbitrary executables are not OS-sandboxed; use containers or filesystem isolation when hard confinement is required.
• Destructive CLI & Environment Safety: Intercepts destructive cloud/database/infrastructure commands, stops script laundering and interpreter evasion, blocks TTY hangs (vim, nano, sudo), and guards against dangerous package manager flags.

For complete policy specifications and override rules, see docs/policies.md.

---

Proactive Workflow Tools

Enforcement is only half the surface. The plugin also registers first-class agent tools (same tool names on OpenCode 1.x and 2.x) so disciplined workflow is the path of least resistance:

• Task Planning: guard_next_tasks surfaces durable repository planning context (TODO.md, ROADMAP.md, PLAN.md, TASKS.md, BACKLOG.md, their docs/ counterparts, and plans under docs/plans/) at session start or during planning; guard_status reports active guardrails, branch protection, mutation counts, outstanding verification/review gates, a read-only git-hygiene snapshot, and the loaded pluginVersion.
• Review & Verification: before PR creation, a secondary reviewer subagent evaluates the diff against guard_review_rubric (five core axes: test integrity, task completeness, cleanliness, security, platform) and records its verdict with record_review; approvals are bound to the reviewed worktree content.
• Worktree Isolation: guard_worktree_create and guard_worktree_cleanup give parallel subagents isolated linked worktrees so concurrent mutations never collide.
• Technical Debt: guard_review_followups lists open P2/P3 durable review follow-ups; guard_review_followup_resolve closes them after the underlying issue is fixed and verified.
• Policy Simulation: guard_why returns the structured policy decision for a tool call or command without performing it; guard_audit shows recent audited policy entries.
• Project Memory (on by default): project_memory_search, project_memory_record, project_memory_export, and project_memory_import maintain durable facts, decisions, constraints, and lessons; secret content is rejected, and export promotes records to the repo-local .opencode/memory/project-memory.jsonl.
• Socratic Learning (off by default): learning_checkpoint, learning_profile, and learning_record maintain a global evidence-based learner profile with a per-session intervention budget.

The context modules — project memory, Socratic learning, and recovery checkpoints (guard_recovery_restore) — are independently gated and can be disabled without weakening policy enforcement; see docs/installation.md. Full tool specifications live in docs/policies.md.

---

Documentation Index

Guide	Description
Policy Reference	Comprehensive specification of all 24 enforced policies, invariants, and the proactive tool surface (guard_*, project_memory_*, learning_*)
Installation & Configuration	Setup options, global vs. local install, worktree isolation, and project configuration
Managed Deployment	Administrator-managed OpenCode policy, platform locations, and startup diagnostics
Troubleshooting	Diagnosing policy blocks, common false positives, and emergency override procedures
Testing Architecture	Test harness design, adversarial regression matrix, and CI verification
Contributing Guide	Development workflow, coding conventions, test requirements, and changeset PR rules
Security Policy	Vulnerability disclosure policy and threat model

---

License

MIT