npm package: @saikus08/opencode-workbench
Description: A portable team workflow kit for OpenCode: agents, commands, specs, skills, and guardrails for Node/TypeScript repos
Latest version: 0.1.9

# 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/<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:

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

```bash
npm login
npm publish
```

## Development

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