# OpenCode Toolkit — Agent Instructions

## Stack

- TypeScript ESM package targeting Node.js 20+; initial runtime target is
  OpenCode 2.0.24 and `@opencode/plugin` 2.0.24.
- Tests use Node.js built-in `node:test`; coverage uses `c8`.
- `jsonc-parser` edits project configuration while preserving comments.

## Verified commands

- Install dependencies: `npm install`
- Compile: `npm run build`
- Type check: `npm run typecheck`
- Tests: `npm test` (builds first)
- Coverage: `npm run test:coverage` (builds first; enforces 80% lines/functions)
- Inspect package contents: `npm pack --dry-run`

## Layout

- `src/`: OpenCode V2 plugin, CLI, and project installer.
- `content/`: curated skills and subagents copied into consuming projects.
- `test/`: plugin contract and installer tests.
- `docs/`: implementation plan and provenance records.

## Conventions and gotchas

- Use the V2 `@opencode/plugin` API; do not transplant ECC's V1 hook function.
- Keep project installation conservative: never overwrite unmanaged or locally
  modified files; preserve JSONC comments and unrelated configuration.
- Keep state scoped by project/session. Do not introduce a mutable module-level
  store for user session data.
- Every imported ECC file must have source, revision, attribution, and hash
  recorded in `docs/PROVENANCE.md`.
- Tests do not prove provider-backed agent behavior; report that separately.
- `npm test` compiles into ignored `dist/`; `npm pack --dry-run` runs the
  `prepack` build hook and therefore writes generated output.

See `docs/IMPLEMENTATION-PLAN.md`, `TODO.md`, and `FIXME.md` for scope and
remaining work.