opencode-toolkit/AGENTS.md

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.