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:

``bash
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:

`bash
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):

`bash
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//...
- 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 applies optional profiles (nx, turbo, angular, react, nest)
- audit runs drift checks (warnings only)
- run-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:

`bash
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@ 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.

`bash
npm login
npm publish
`

Development

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