feat: scaffold OpenCode V2 toolkit with safe project installer

README.md

@@ -0,0 +1,82 @@
+# 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. Live plugin activation is still under validation (see `FIXME.md`).
+- 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:
+
+```sh
+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/`, adds the
+package plugin to the applicable project config, and writes an ownership
+manifest. 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:
+
+```sh
+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. Configure and authenticate your
+provider normally in OpenCode.
+
+## Development
+
+```sh
+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. Provider-backed workflow validation
+is not yet complete; see [`FIXME.md`](FIXME.md) and [`TODO.md`](TODO.md).
+
+## Project documentation
+
+- [`AGENTS.md`](AGENTS.md): verified development commands and conventions.
+- [`docs/IMPLEMENTATION-PLAN.md`](docs/IMPLEMENTATION-PLAN.md): accepted plan,
+  phases, scope, and acceptance criteria.
+- [`docs/PROVENANCE.md`](docs/PROVENANCE.md): ECC source revision, attribution,
+  adaptations, and content hashes.
+- [`CHANGELOG.md`](CHANGELOG.md): user-visible changes.
+- [`TODO.md`](TODO.md) and [`FIXME.md`](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`](NOTICE.md).