opencode-toolkit/README.md

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.

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. 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 and skill workflows are not yet complete. See FIXME.md and TODO.md.

Project documentation

• AGENTS.md: verified development commands and conventions.
• docs/IMPLEMENTATION-PLAN.md: accepted plan, phases, scope, and acceptance criteria.
• docs/PROVENANCE.md: ECC source revision, attribution, adaptations, and content hashes.
• CHANGELOG.md: user-visible changes.
• TODO.md and FIXME.md: remaining work and known gaps.

License

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