OpenCode Toolkit

A small, OpenCode V2-native package containing a curated set of engineering workflows adapted from ECC, plus a read-only project-status tool and a conservative project installer.

This is an early development release. It currently targets OpenCode 2.0.24 and Node.js 20 or newer. It is not yet published to npm.

Included

Skills: coding standards, security review, and test-driven development.
Subagents: planner, code reviewer, and security reviewer.
Plugin tool: toolkit_project_status, implemented against OpenCode's V2 VCS API and exposed in the toolkit Code Mode namespace.
Project installer with JSONC-preserving plugin registration, file ownership hashes, collision checks, and protection for locally modified files.

Provider/model selection remains the user's OpenCode configuration. The package does not enable hooks through a global install or configure credentials.

Install from a local checkout

Until a release is published, install the package from its checkout in the project where it will be used:

npm install --save-dev /path/to/opencode-toolkit
npx opencode-toolkit install .

Replace /path/to/opencode-toolkit with the checkout path on your machine.

The installer copies the selected skills and agents into .opencode/, registers the local package directory from node_modules in the applicable project config, and writes an ownership manifest. This avoids asking OpenCode to fetch the provisional, unpublished package name from npm. It does not overwrite unmanaged files. If a managed file has been edited since installation, updates stop rather than replacing it. If both opencode.json and .opencode/opencode.json exist, installation stops until the project consolidates them; this avoids ambiguous V2 config precedence.

To remove managed content and the plugin entry when the installer added it:

npx opencode-toolkit uninstall .

Modified managed files are preserved and reported. The installer does not yet remove the npm dependency from the consuming project's package.json; remove that dependency separately if desired.

To update, install the newer checkout or tarball into the consuming project, then rerun the installer. It updates files that still match their recorded hashes and refuses to overwrite a locally modified current file:

npm install --save-dev /path/to/new-opencode-toolkit.tgz
npx opencode-toolkit install .

Verify a package tarball

For a release candidate, build the package and create a tarball from the checkout:

npm pack

This creates sargatxet-opencode-toolkit-0.1.0.tgz for the current provisional package identity and version. In a disposable project, install that tarball rather than linking the checkout:

npm install --save-dev /path/to/sargatxet-opencode-toolkit-0.1.0.tgz
npx opencode-toolkit install .
npx opencode-toolkit install .

The second install should make no content changes. Check that the expected toolkit-* agents and skills are present under .opencode/, and that the project config contains the local package plugin path. To verify removal, first edit one installed toolkit file, then run:

npx opencode-toolkit uninstall .

The edited file should be reported as preserved; unmodified managed files and the toolkit plugin entry should be removed. These install/uninstall checks need no model credentials. Plugin activation and tool execution were separately smoke-tested with OpenCode 2.0.24 and a local mock OpenAI-compatible endpoint. Provider-backed agent delegation and skill behavior remain unverified.

Safety boundaries

The installer rejects unmanaged-file collisions, symlinked install paths, and managed files changed since installation. Its ownership manifest is local bookkeeping, not a signed security boundary. Path checks do not protect against another process changing the project tree concurrently; use it on a project directory whose filesystem is trusted. Uninstall removes files incrementally, so resolve any reported I/O error and rerun it rather than deleting the manifest manually. See docs/SECURITY-REVIEW.md for the review scope and limitations.

After installation, restart or reload OpenCode and select the installed toolkit-* skills or subagents as needed. The plugin exposes its namespaced tool through Code Mode. Configure and authenticate your provider normally in OpenCode.

Development

npm install
npm run typecheck
npm test
npm run test:coverage
npm pack --dry-run

The package is tested against OpenCode 2.0.24 and Node.js 20+. The unit and installer tests are deterministic and do not call an LLM. Plugin activation and tool execution were smoke-tested with a local mock OpenAI-compatible endpoint; provider-backed agent delegation and skill behavior remain unverified.

Provenance and security

docs/PROVENANCE.md: ECC source revision, attribution, adaptations, and content hashes.
docs/SECURITY-REVIEW.md: review scope, result, and operational limitations.

License

The new implementation is MIT licensed. Adapted ECC material remains subject to the preserved MIT notice and attribution described in NOTICE.md.

5.2 KiB Raw Blame History