A portable team workflow kit for OpenCode: agents, commands, specs, skills, and guardrails for Node/TypeScript repos
npm install @saikus08/opencode-workbenchOpenCode 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.
From your target repo root:
``bash
npx @saikus08/opencode-workbench doctorfolder monorepos: run tasks per package
npx @saikus08/opencode-workbench run-task lint --preflight
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.mdWhy 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 configGitignore:
- 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 allCommands
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
- /statusFolder 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@).
- 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_*: falseThis 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.mdDetection 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 driftNon-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
``