--- name: sk-code-opencode description: "sk-code OPENCODE surface: system-code evidence (TypeScript/Python/shell/Rust/config standards, language-agnostic patterns, hooks, alignment verification, and skill/agent/command/MCP authoring checklists) plus shared implement/debug/verify workflow doctrine." allowed-tools: [Read, Bash, Grep, Glob] version: 1.2.4.0 metadata: author: OpenCode family: sk-code packetKind: surface --- > Canonical source: `.skilled/skills/sk-code/sk-code-opencode/`. This is a generated markdown-only copy so Hermes can load the > skill without scanning the canonical directory; read `references/`, `assets/` and `scripts/` > from the canonical path above. # opencode Surface — System-Code Evidence **Domain evidence** and shared workflow doctrine for OpenCode system code (the `.skilled/` tree: skills, agents, commands, plugins, MCP servers, config, changelogs, and runtime bridge wiring). This surface owns the implement -> debug -> verify phases through the workflow references below, then slices evidence by the detected language so a TypeScript task never pulls the Python/shell/config guides. Detection is two-step. First, the surface trigger is work under `.skilled/` (including `SKILL.md`, descriptors, commands, agents, plugins, MCP servers, assets, scripts, and changelogs). Second, once the OpenCode surface is selected, file extensions and local markers select the language trio: `.cjs`/`.mjs`/`.js` -> JavaScript, `.ts`/`.tsx`/`.mts`/`.d.ts` -> TypeScript, `.py` plus `argparse` -> Python, `.sh`/`.bash` -> shell, `.rs` -> Rust, `.json`/`.jsonc`/`.yaml`/`.yml` plus `graph-metadata` or `spec-folder` -> config. For Rust, when no `.rs` file is present, local `Cargo.toml`/`Cargo.lock` markers select it after the OpenCode surface is established; napi-rs and wasm-bindgen vocabulary are additional intent signals, not cross-project surface detectors. ## 1. WHEN THE HUB BUNDLES THIS - The task touches `.skilled/` system code — a skill, agent, command, plugin, MCP server, or descriptor/config. - The active workflow phase needs a language standard, a language-agnostic organization pattern, a hook contract, an alignment-verification procedure, or an authoring checklist. - This surface owns edits, tests, and verification through the workflow references; hand off formal findings-first review to `sk-code-review` and author-side quality gates to `sk-code-quality`. --- ## 2. REFERENCE MAP Language standards — after `.skilled/` selects this surface, load the exact split resources for the detected language: - TypeScript — `references/typescript/style-guide/overview-strict-and-naming.md`, `references/typescript/style-guide/formatting-imports-and-coexistence.md`, `references/typescript/quality-standards/overview-and-type-system.md`, `references/typescript/quality-standards/tsdoc-errors-and-async.md`, `references/typescript/quality-standards/tsconfig-and-modules.md`, `references/typescript/quick-reference/template-naming-and-types.md`, `references/typescript/quick-reference/imports-errors-and-tsconfig.md` - Python — `references/python/style-guide.md`, `references/python/quality-standards.md`, `references/python/quick-reference.md` - Shell — `references/shell/style-guide/overview-structure-and-naming.md`, `references/shell/style-guide/variables-functions-and-output.md`, `references/shell/quality-standards/overview-and-priority-blockers.md`, `references/shell/quality-standards/validation-security-and-shellcheck.md`, `references/shell/quick-reference/template-variables-and-loops.md`, `references/shell/quick-reference/functions-strings-and-checklist.md` - Rust — `references/rust/style-guide/overview-and-file-header.md`, `references/rust/style-guide/toolchain-and-project-structure.md`, `references/rust/style-guide/naming-conventions.md`, `references/rust/style-guide/formatting-and-imports.md`, `references/rust/style-guide/commenting-and-rustdoc.md`, `references/rust/style-guide/interop-model.md`, `references/rust/style-guide/interop-errors-and-parity.md`, `references/rust/quality-standards/overview-and-data-ownership.md`, `references/rust/quality-standards/modeling-collections-and-api.md`, `references/rust/quality-standards/docs-errors-and-async.md`, `references/rust/quality-standards/build-and-organization.md`, `references/rust/quality-standards/determinism-and-parity.md`, `references/rust/quick-reference/overview-and-boundary-template.md`, `references/rust/quick-reference/naming-ordering-and-signatures.md`, `references/rust/quick-reference/collections-imports-and-errors.md`, `references/rust/quick-reference/rustdoc-and-cargo.md`, `references/rust/quick-reference/determinism-parity-and-related.md` - Config (JSON/JSONC/YAML descriptors and route assets) — `references/config/style-guide.md`, `references/config/quality-standards.md`, `references/config/quick-reference.md`, `assets/checklists/config-checklist.md` - JavaScript (CommonJS/ESM plugins) — `references/javascript/style-guide.md`, `references/javascript/quality-standards/overview-modules-and-docs.md`, `references/javascript/quality-standards/security-testing-and-exemptions.md`, `references/javascript/quick-reference.md` Language-agnostic shared tier (`references/shared/`, always kept within OpenCode regardless of language): - `references/shared/universal-patterns/naming-and-commenting.md`, `references/shared/universal-patterns/organization-security-and-examples.md`, `references/shared/code-organization/overview-and-module-organization.md`, `references/shared/code-organization/imports-and-exports.md`, `references/shared/code-organization/directory-and-test-conventions.md` - `hooks.md` — runtime hook entrypoints, checked-in Claude wiring, OpenCode plugin-bridge delivery, and wrapper reachability; defer to that file for current hook infrastructure instead of duplicating it here - `alignment-verification-automation.md` — the alignment-drift verifier - `workflow-guardrails.md`: OpenCode-only implementation guardrails, the verification command chain and runtime build traps, applied on top of the shared implement and verify workflow Authoring and validation assets: `assets/checklists/agent-authoring.md`, `assets/checklists/command-authoring.md`, `assets/checklists/javascript-checklist.md`, `assets/checklists/mcp-server-authoring.md`, `assets/checklists/python-checklist.md`, `assets/checklists/rust-checklist/overview-and-p0-parity.md`, `assets/checklists/rust-checklist/p0-safety-and-boundary-discipline.md`, `assets/checklists/rust-checklist/p1-required.md`, `assets/checklists/rust-checklist/p2-evidence-validation-and-resources.md`, `assets/checklists/shell-checklist.md`, `assets/checklists/skill-authoring.md`, `assets/checklists/typescript-checklist.md`, `assets/checklists/universal-checklist.md`, `assets/scripts/README.md`, `references/shared/alignment-verification-automation.md`, `references/shared/hooks.md` Workflow: the implement -> debug -> verify phases use the split shared, language, hook, and alignment resources above; no root-level `workflow-*.md` trio is assumed. ## 2b. SMART ROUTING (machine-readable) This block is the deterministic projection of sk-code-opencode's own reference/asset routing; keep it in sync with the parent hub union. ```python # sk-code-opencode owns its intent -> reference/asset routing. Paths are relative to # this skill root. The parent sk-code hub RESOURCE_MAP is the union of this map # (re-prefixed with sk-code-opencode/) and the sibling sk-code-webflow map plus the # parent-owned universal/shared tier. The router-sync guard # (assets/scripts/verify-router-sync.cjs, leg 2) checks that equality. # verify_alignment_drift.py --check-router checks dead routes only, so it is not # the equality authority. Leg 1b of the same guard fails on any reference or asset doc that # no router names, so a new doc under references/ or assets/ needs a RESOURCE_MAP entry here. DEFAULT_RESOURCE = [ "references/shared/universal-patterns/naming-and-commenting.md", "references/shared/universal-patterns/organization-security-and-examples.md", "references/shared/code-organization/overview-and-module-organization.md", "references/shared/code-organization/imports-and-exports.md", "references/shared/code-organization/directory-and-test-conventions.md", "references/shared/workflow-guardrails.md", ] INTENT_SIGNALS = { "IMPLEMENTATION": {"weight": 1, "keywords": ["implement", "build", "create", "feature", "component", "module", "authoring"]}, "CODE_QUALITY": {"weight": 1, "keywords": ["lint", "format", "quality gate", "naming", "standards", "code smell"]}, "VERIFICATION": {"weight": 1, "keywords": ["verify", "passing", "type-check", "alignment drift", "completion claim"]}, "HOOKS": {"weight": 1, "keywords": ["session-prime", "user-prompt-submit", "pre-tool-use", "post-tool-use"]}, "CONFIG": {"weight": 1, "keywords": ["jsonc", ".json", ".jsonc", "descriptor", "config schema"]}, "JAVASCRIPT": {"weight": 1, "keywords": ["javascript", ".js", "commonjs", ".cjs", ".mjs"]}, "TYPESCRIPT": {"weight": 1, "keywords": ["typescript", ".ts", ".tsx"]}, "PYTHON": {"weight": 1, "keywords": ["python", ".py", "docstring"]}, "SHELL": {"weight": 1, "keywords": ["shell script", "bash", ".sh"]}, "RUST": {"weight": 1, "keywords": ["rust", ".rs", "cargo.toml", "cargo.lock", "napi-rs", "napi_rs", "#[napi]", "wasm-bindgen", "wasm_bindgen", "#[wasm_bindgen]", "wasi", "cdylib"]}, } RESOURCE_MAP = { "IMPLEMENTATION": [ "references/shared/universal-patterns/naming-and-commenting.md", "references/shared/universal-patterns/organization-security-and-examples.md", "references/shared/code-organization/overview-and-module-organization.md", "references/shared/code-organization/imports-and-exports.md", "references/shared/code-organization/directory-and-test-conventions.md", "assets/checklists/agent-authoring.md", "assets/checklists/command-authoring.md", "assets/checklists/skill-authoring.md", "assets/checklists/mcp-server-authoring.md", ], "CODE_QUALITY": [ "assets/checklists/universal-checklist.md", "assets/checklists/javascript-checklist.md", "assets/checklists/typescript-checklist.md", "assets/checklists/python-checklist.md", "assets/checklists/shell-checklist.md", "assets/checklists/rust-checklist/overview-and-p0-parity.md", "assets/checklists/rust-checklist/p0-safety-and-boundary-discipline.md", "assets/checklists/rust-checklist/p1-required.md", "assets/checklists/rust-checklist/p2-evidence-validation-and-resources.md", ], "VERIFICATION": [ "references/shared/alignment-verification-automation.md", "assets/scripts/README.md", ], "HOOKS": [ "references/shared/hooks.md", ], "CONFIG": [ "references/config/style-guide.md", "references/config/quality-standards.md", "references/config/quick-reference.md", "assets/checklists/config-checklist.md", ], "JAVASCRIPT": [ "references/javascript/style-guide.md", "references/javascript/quality-standards/overview-modules-and-docs.md", "references/javascript/quality-standards/security-testing-and-exemptions.md", "references/javascript/quick-reference.md", ], "TYPESCRIPT": [ "references/typescript/style-guide/overview-strict-and-naming.md", "references/typescript/style-guide/formatting-imports-and-coexistence.md", "references/typescript/quality-standards/overview-and-type-system.md", "references/typescript/quality-standards/tsdoc-errors-and-async.md", "references/typescript/quality-standards/tsconfig-and-modules.md", "references/typescript/quick-reference/template-naming-and-types.md", "references/typescript/quick-reference/imports-errors-and-tsconfig.md", ], "PYTHON": [ "references/python/style-guide.md", "references/python/quality-standards.md", "references/python/quick-reference.md", ], "SHELL": [ "references/shell/style-guide/overview-structure-and-naming.md", "references/shell/style-guide/variables-functions-and-output.md", "references/shell/quality-standards/overview-and-priority-blockers.md", "references/shell/quality-standards/validation-security-and-shellcheck.md", "references/shell/quick-reference/template-variables-and-loops.md", "references/shell/quick-reference/functions-strings-and-checklist.md", ], "RUST": [ "references/rust/style-guide/overview-and-file-header.md", "references/rust/style-guide/toolchain-and-project-structure.md", "references/rust/style-guide/naming-conventions.md", "references/rust/style-guide/formatting-and-imports.md", "references/rust/style-guide/commenting-and-rustdoc.md", "references/rust/style-guide/interop-model.md", "references/rust/style-guide/interop-errors-and-parity.md", "references/rust/quality-standards/overview-and-data-ownership.md", "references/rust/quality-standards/modeling-collections-and-api.md", "references/rust/quality-standards/docs-errors-and-async.md", "references/rust/quality-standards/build-and-organization.md", "references/rust/quality-standards/determinism-and-parity.md", "references/rust/quick-reference/overview-and-boundary-template.md", "references/rust/quick-reference/naming-ordering-and-signatures.md", "references/rust/quick-reference/collections-imports-and-errors.md", "references/rust/quick-reference/rustdoc-and-cargo.md", "references/rust/quick-reference/determinism-parity-and-related.md", ], } ``` --- ## 3. SURFACE STANDARDS (the non-negotiables) - **Plugins never write to the TUI.** OpenCode plugins must not print to the process stdout/stderr (no overlay on the chat input); user/agent-visible output goes through system-context injection, tools, or append-only log files; DEBUG-gated stderr is allowed only behind an env flag. See `references/javascript/quality-standards/overview-modules-and-docs.md` and the plugin exemption tier. - **Descriptors are load-bearing.** `graph-metadata.json` / `description.json` shape drives discovery; validate JSON/JSONC against `references/config/quality-standards.md`. - **Alignment drift is a verification gate.** System-code changes re-run the four live sk-code drift guards through the single entry point `scripts/run-all-drift-guards.sh` before any completion claim: `assets/scripts/verify_alignment_drift.py` (language integrity, plus dead RESOURCE_MAP routes with `--check-router`) and `assets/scripts/verify_stack_folders.py` (language reference folders resolve). The router-sync guard (`assets/scripts/verify-router-sync.cjs`) restores the four checks of the `sk-code-router-sync.vitest.ts` suite, which was deleted, and the wrapper runs every leg of it (1a, 1b, 2, 3 and 4): (1) router paths exist on disk, every routable doc is routed, and every full path the prose maps name is routed; (2) the parent RESOURCE_MAP equals the union of the surface children's maps plus the parent tier; (3) compiled route-gold destinations, `leaf-manifest.json` and this RESOURCE_MAP agree through `qualifiedIdToLeaf`; (4) every playbook routing scenario's `expected_resource` is emitted by the router. The dead-path part of (1) is also checked by `--check-router`. Leg 1b, the orphan-doc walk, fails on any reference or asset doc that no router names. It allowlists only the three shared workflow docs, which each surface reaches through a symlink. `.github/workflows/routing-registry-drift.yml` covers the compiled side of (3) and (4) in CI only, with the admission step warn-only. The documentation claim guard (`assets/scripts/verify-doc-claims.cjs`) reads the sk-code prose the other guards skip, from the hub folder on disk: path references resolve, no retired packet name remains, every surface count matches the surface modes in `mode-registry.json` and every file the `ROUTER.md` load-tier prose says loads on every route is in `DEFAULT_RESOURCE`. Lines that keep a legacy name on purpose sit in its allowlist with a reason. See `references/shared/alignment-verification-automation.md`. The wrapper scans repository content only: files git tracks, so ignored trees, sibling worktrees and vendored clones stay out of a gate they can never pass. It exits 0 on a clean tree, so a completion claim requires wrapper rc 0 rather than a delta against a backlog. - **Rust preserves the TypeScript contract.** Rust napi-rs, WASM/WASI, and sidecar modules are compatibility implementations, not independent behavior authorities. JS-visible bytes, six-decimal numeric behavior, comparator tie-breaks, deterministic IDs, collection order, DTOs, and error shapes must remain identical to the TypeScript oracle. - **Touched-language set, not one-per-task.** Most `.skilled/` tasks touch a single language — keep that slice tight and lean on the shared tier for cross-language rules. An interop task that spans a language pair (a napi-rs / WASM / sidecar Rust module held to its TypeScript oracle) legitimately touches both languages: the router slices to the set the task actually touches and loads both trios plus the shared tier, because you cannot hold Rust byte-identical to TypeScript without seeing both standards. --- ## 4. ASSETS AND OTHER SURFACE AREAS — ON-DEMAND Component authoring (`assets/checklists/`): `skill-authoring.md`, `agent-authoring.md`, `command-authoring.md`, `mcp-server-authoring.md` Language quality gates (`assets/checklists/`): `universal-checklist.md`, `typescript-checklist.md`, `python-checklist.md`, `shell-checklist.md`, `javascript-checklist.md`, `rust-checklist/` (split into topic parts), `config-checklist.md` Verifier assets (`assets/scripts/`): alignment-drift and stack-folder verifier scripts, the router-sync guard (`verify-router-sync.cjs`) with its replay library (`router-replay-lib.cjs`) and the documentation claim guard (`verify-doc-claims.cjs`), used by this surface. `scripts/run-all-drift-guards.sh` is the single entry point that runs all four as one gate (non-zero if any fails). Changelog directories (`changelog/`): real skill and packet changelog files are part of the OpenCode surface inventory, not out-of-scope documentation noise. Daemon IPC/socket wiring: daemon-backed CLIs and plugin bridges resolve runtime Unix socket paths such as `daemon-ipc.sock`; sockets are runtime artifacts, so checked-in evidence lives in launcher, bridge, and config files rather than in committed `.sock` files. Spec-folder authoring lives in system-spec-kit (`.skilled/skills/system-spec-kit/references/workflows/spec-folder-write-recipe.md` + `spec-folder-authoring-checklist.md`), not in this surface. Checklists are pulled on demand by the active workflow phase.