OpenCode Workbench

OpenCode Workbench is an installable kit for teams (and solo devs) using OpenCode on Node/TypeScript repositories.

It bootstraps a consistent, safety-first workflow across projects:

• .opencode/ agents + commands + context (plan-first, reviewable, safe)
• openspec/ folder conventions for spec-driven development
• .agent/skills/ small, reusable playbooks (SKILL.md)
• cc-safety-net integration + repo rules (.safety-net.json)
• Built-in context drift warnings (opencode-workbench audit) to keep docs aligned with reality
• Monorepo-aware task runner (opencode-workbench run-task) so /lint, /typecheck, /test can run per package
• Repo doctor (opencode-workbench doctor) to catch common local blockers (Node version, broken installs)

Not affiliated with OpenCode, Anthropic, or Sentry.

Quick start

From your target repo root:

npx @saikus08/opencode-workbench doctor
# folder monorepos: run tasks per package
npx @saikus08/opencode-workbench run-task lint --preflight

# install the OpenCode kit (agents/commands/specs)
npx @saikus08/opencode-workbench init

Default install is portable: no scripts/ or docs/ are added to the repo. Use --include-scripts/--include-docs if you want those extra files.

Optional profiles:

npx @saikus08/opencode-workbench add nx
npx @saikus08/opencode-workbench add turbo
npx @saikus08/opencode-workbench add angular
npx @saikus08/opencode-workbench add react
npx @saikus08/opencode-workbench add nest

Run drift warnings (no auto-edits):

npx @saikus08/opencode-workbench audit

Docs:

• docs/workbench.md
• TEST_PLAN.md

Why this exists

AI coding agents are powerful, but teams drift quickly (especially in monorepos):

• conventions live in chat history instead of the repo
• new tooling appears without updating the workflow docs
• agent behavior differs per developer due to local config differences
• destructive git/fs commands happen in the worst moments

Workbench puts the workflow in the repo: versioned, reviewable, and portable.

How it works

Workbench is a small CLI that:

• installs a curated template tree into the target repo
• merges directories (so profiles do not nuke existing .opencode/)
• optionally backs up colliding files to .opencode-workbench-backup/<timestamp>/...
• creates or updates opencode.jsonc (JSONC-safe) to add a sane baseline config

Gitignore:

• If a .gitignore file already exists, init will add a small ignore block for Workbench internal state (manifest + backups).
• If you want to ignore all installed workflow files (not recommended for team repos), run:
  • npx @saikus08/opencode-workbench init --gitignore all

Commands

CLI:

• init installs the core template
• add <profile> applies optional profiles (nx, turbo, angular, react, nest)
• audit runs drift checks (warnings only)
• run-task <task> runs lint/typecheck/test/build per package
• configure updates repo context files from discovery (manifest + project context)
• doctor prints basic environment info (or runs repo-local doctor when installed)
• uninstall removes internal state and removes unchanged installed files (safe by default)

After install, your repo also gets OpenCode commands under .opencode/commands/:

• /context-audit
• /lint
• /typecheck
• /test
• /status

Folder monorepo (backend/frontend)

Workbench supports repos with multiple independent Node packages without Nx/Turbo/workspaces (example: backend/ + frontend/).

• Commands like /lint and /typecheck are monorepo-aware via opencode-workbench run-task (invoked through npx from the installed OpenCode commands).
• Drift detection aggregates deps across all discovered package.json files.

Suggested flow:

npx @saikus08/opencode-workbench init
npx @saikus08/opencode-workbench configure
npx @saikus08/opencode-workbench audit

Team adoption guide

Minimal rollout:

• Install + configure Workbench, then commit the kit.
• Use the same commands in CI that developers run locally (npx @saikus08/opencode-workbench@<version> run-task ...).
• Keep openspec/project.md as the human source of truth; let configure fill the machine-readable parts.

What it installs

• .opencode/
  • agents/ (openagent, reviewer, tester, librarian, build)
  • commands/ (context-audit, lint, typecheck, test, status)
  • context/ (baseline standards + project rules)
• openspec/ (project.md, specs/, changes/)
• .agent/skills/ (initial skills)
• .safety-net.json (team guardrails for cc-safety-net)
• (portable by default) does not install repo-local scripts or docs
• Optional: init --include-scripts installs scripts/ai/* for offline/local execution
• Optional: init --include-docs installs docs/*

OpenCode config + MCPs

If opencode.json/opencode.jsonc is missing, Workbench creates opencode.jsonc. If it exists, Workbench updates it (JSONC-safe) to add:

• plugin: ["cc-safety-net"]
• MCP servers:
  • context7 enabled by default (official docs)
  • sentry disabled by default
  • gh_grep disabled by default
• Tools:
  • sentry_*: false
  • gh_grep_*: false

This keeps token usage under control. Enable Sentry/Grep only when you need them.

Profiles

Profiles are small, additive context snippets (not full frameworks). Use them when the repo actually uses the tool/framework:

• nx: adds .opencode/context/project/nx.md
• turbo: adds .opencode/context/project/turbo.md
• angular: adds .opencode/context/project/angular.md
• react: adds .opencode/context/project/react.md
• nest: adds .opencode/context/project/nest.md

Detection is intentionally lightweight and may require --force.

Safety model

Workbench improves safety via:

• cc-safety-net hard guardrails (blocks destructive git/fs commands)
• repo-level .safety-net.json rules (team policy)
• drift checker warnings to reduce documentation/config drift

Non-goals:

• not a sandbox (does not restrict all network access)
• not a replacement for code review
• not a guarantee of perfect code; it enforces structure and repeatable defaults

Limits / best fit

Best fit:

• teams and solo devs working across multiple Node/TS repos
• monorepos with multiple apps/packages
• projects that want consistent agent behavior and safe defaults

Current limits (by design):

• drift checker is warnings-only (no auto-sync)
• drift checker is heuristic-based (good defaults, but not perfect)
• no CI templates included yet

Philosophy

• Prefer small changes, explicit scope, and fast feedback (lint/typecheck/tests).
• Use spec-driven workflow (openspec/changes/) for non-trivial work.
• Use Context7 for up-to-date official docs.
• Use hard guardrails (cc-safety-net) for destructive commands.

Publishing

This package is meant to be published as a scoped npm package.

npm login
npm publish

Development

npm install
npm run typecheck
npm run build
node dist/cli.js doctor