opencode-codeops 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 1.7.0 — 2026-09-24
+
+### Fixes
+
+- installer: install _shared and references beside the skills
+
+### Features
+
+- installer: register the plugin automatically on install/update
+- installer: unify install/update into one command
+- installer: add npm-first install, agents installer, and release tooling
+
+## 1.6.0 — 2026-09-19
+
+### Features
+
+- installer: register the plugin automatically on install/update
+- installer: unify install/update into one command
+- installer: add npm-first install, agents installer, and release tooling
+
 ## 1.5.0 — 2026-09-19
 
 ### Features

package/README.md

@@ -27,29 +27,8 @@ Turn an idea or existing system into ambiguity-free requirements, grounded speci
 
 ## Installation
 
-CodeOps has two parts that OpenCode loads differently: the **plugin** (standards and hooks) is
-installed by OpenCode from npm, and the **skills** and **subagents** must be copied onto the
-filesystem because OpenCode only discovers those from disk.
-
-### 1. Add the plugin
-
-Add to your `opencode.json`:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-codeops"]
-}
-```
-
-OpenCode installs the plugin automatically via Bun on next startup. A global config
-(`~/.config/opencode/opencode.json`) is recommended so CodeOps is active in every project.
-
-### 2. Install the skills and subagents
-
-OpenCode discovers skills and subagents only from the filesystem; it never reads them from a plugin
-package. One command installs both. The installer is a thin `npx` wrapper around this package, so
-the installed files always match the published version:
+One command installs everything CodeOps owns: the skills, the subagents, and the OpenCode plugin
+entry in your config.
 
 ```bash
 # Global (recommended) — available in every OpenCode project
@@ -66,22 +45,39 @@ npx -y opencode-codeops@latest install
 npx -y opencode-codeops@latest update    # alias of install
 ```
 
+`install`/`update` writes the skills and subagents onto the filesystem (OpenCode discovers those
+only from disk), then registers the plugin in the OpenCode config by calling OpenCode's own
+`opencode plugin` command, so standards injection and `CODEOPS_PLUGIN_ROOT` are enabled. Restart
+OpenCode after installing for the plugin to load. Pass `--no-plugin` to manage the config yourself.
+
+The installer also places the shared `_shared/` and `references/` documents beside the installed
+`skills/` directory (for example `~/.config/opencode/_shared`), so the skills' relative links to
+them resolve at their installed location. An existing directory with either name is only replaced
+with `--force`.
+
 The scope is auto-detected: inside a CodeOps project (a git repo with `.opencode/` or
-`codeops/.codeops.yml`) it installs into `./.opencode/skills` and `./.opencode/agents`; anywhere
-else it installs globally into `~/.config/opencode/`. Pass `--project` or `--global` to force one.
+`codeops/.codeops.yml`) it installs into `./.opencode`, and registers the plugin in the project
+config; anywhere else it installs globally into `~/.config/opencode` and the global config. Pass
+`--project` or `--global` to force one.
 
-Pin a version with `CODEOPS_VERSION` (an npm dist-tag or exact version; defaults to `latest`):
+If you prefer to register the plugin manually instead, add it to your `opencode.json`:
 
-```bash
-CODEOPS_VERSION=1.5.0 curl -fsSL https://cdn.jsdelivr.net/npm/opencode-codeops@latest/install.sh | bash
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-codeops"]
+}
 ```
 
-Pin the plugin to the same version so the two cannot drift apart:
+Pin a version with `CODEOPS_VERSION` (an npm dist-tag or exact version; defaults to `latest`):
 
-```json
-{ "plugin": ["opencode-codeops@1.5.0"] }
+```bash
+CODEOPS_VERSION=1.6.0 curl -fsSL https://cdn.jsdelivr.net/npm/opencode-codeops@latest/install.sh | bash
 ```
 
+`install`/`update` pins the plugin in the OpenCode config to the installer's own version, so the
+plugin and the installed files cannot drift apart; run `update` to move both to a new version.
+
 Re-running the installer upgrades an existing install in place. It replaces only the files this
 package owns, recorded in `.opencode-codeops.json`. Files you author yourself, or install with
 another tool, are left untouched.
@@ -93,21 +89,24 @@ npx -y opencode-codeops@latest status
 npx -y opencode-codeops@latest uninstall
 ```
 
-`status` reports the installed version next to the current package version, so a plugin/files
+`status` reports the installed skills and agents versions and the configured plugin entry, so a
 mismatch is visible. Use `--dry-run` to preview an install; a same-named file the package does not
-own is skipped with a warning, and `--force` replaces it.
+own is skipped with a warning, and `--force` replaces it. `uninstall` removes the skills and
+subagents but leaves the plugin entry in your config; remove `opencode-codeops` from the `plugin`
+array by hand to fully disable it.
 
 ### Local development
 
 Symlink the plugin into your OpenCode plugin directory and link the installed files to a checkout,
-so edits are picked up without reinstalling:
+so edits are picked up without reinstalling. Pass `--no-plugin` so the checkout is not overwritten
+by a registered npm plugin:
 
 ```bash
 # Plugin (project or global plugin directory)
 ln -s /path/to/opencode-codeops/plugin/index.ts ~/.config/opencode/plugins/codeops.ts
 
 # Skills and agents — link instead of copy
-node /path/to/opencode-codeops/bin/index.mjs install --link --global
+node /path/to/opencode-codeops/bin/index.mjs install --link --global --no-plugin
 ```
 
 ## Setup

package/bin/index.mjs

@@ -27,6 +27,8 @@ import { existsSync, realpathSync } from "node:fs"
 import { join } from "node:path"
 import { fileURLToPath } from "node:url"
 
+import { PLUGIN_NAME, readConfiguredPlugin, registerPlugin } from "./lib/opencode-plugin.mjs"
+
 /** Commands this CLI understands. */
 const COMMANDS = new Set(["install", "update", "status", "uninstall", "help"])
 
@@ -47,10 +49,15 @@ Options:
   --dry-run          Show what would happen without writing files
   --force            Replace same-named files this package does not own
   --link             Symlink to the source instead of copying (development)
+  --no-plugin        Do not register the plugin in the OpenCode config
   -h, --help         Show this help
 
 Scope is auto-detected: inside a CodeOps project (a git repo with .opencode/ or
-codeops/.codeops.yml) the files go to .opencode/; otherwise to ~/.config/opencode/.`)
+codeops/.codeops.yml) the files go to .opencode/; otherwise to ~/.config/opencode/.
+
+install/update also register the CodeOps plugin in the OpenCode config (unless
+--no-plugin), so standards injection and CODEOPS_PLUGIN_ROOT are enabled. Restart
+OpenCode after installing for the plugin to load.`)
 }
 
 /**
@@ -108,16 +115,46 @@ async function runCombined(command, rest, io) {
   const agents = await import("./install-agents.mjs")
 
   const cwd = io.cwd ?? process.cwd()
+  const noPlugin = rest.includes("--no-plugin")
+  const dryRun = rest.includes("--dry-run")
   const scope = resolveScope(
     { project: rest.includes("--project"), global: rest.includes("--global") },
     cwd
   )
-  const passed = rest.filter((arg) => arg !== "--project" && arg !== "--global")
+  const passed = rest.filter(
+    (arg) => arg !== "--project" && arg !== "--global" && arg !== "--no-plugin"
+  )
   const scoped = [scope === "project" ? "--project" : "--global", ...passed]
 
   const skillsCode = skills.main([command, ...scoped], io)
   const agentsCode = agents.main([command, ...scoped], io)
-  return skillsCode || agentsCode
+  const code = skillsCode || agentsCode
+
+  if (command === "install" && code === 0 && !noPlugin && !dryRun) {
+    const version = io.version ?? skills.readPackageVersion()
+    const result = registerPlugin({ scope, version, cwd, run: io.run })
+    if (result.ok) {
+      console.log(`Plugin: registered ${result.spec} in the ${scope} OpenCode config.`)
+      console.log("Restart OpenCode to load the plugin.")
+    } else {
+      console.log(
+        `Plugin: not registered (${result.reason}). ` +
+          `Add "${PLUGIN_NAME}" to the "plugin" array in your opencode.json.`
+      )
+    }
+  }
+
+  if (command === "status") {
+    const plugins = readConfiguredPlugin({ cwd, run: io.run })
+    if (plugins === undefined) {
+      console.log("plugin: opencode CLI unavailable; cannot read the config")
+    } else {
+      const entry = plugins.find((item) => String(item).startsWith(PLUGIN_NAME))
+      console.log(entry ? `plugin: configured (${entry})` : "plugin: not configured")
+    }
+  }
+
+  return code
 }
 
 /**

package/bin/install-skills.mjs

@@ -46,6 +46,18 @@ import {
 // package root that contains skills/ and package.json.
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
 
+/**
+ * Package-root sibling directories that the installed skills reference with
+ * `../../<name>/...` links.
+ *
+ * The skills live in `skills/<skill>/`, so `../../_shared/...` and
+ * `../../references/...` only resolve when these directories sit beside the
+ * installed `skills` directory. The installer copies them from the parent of
+ * the source skills directory into the parent of the install target, and
+ * records them in the marker so `uninstall` can remove them.
+ */
+export const SHARED_DIRS = ["_shared", "references"]
+
 export { MARKER_FILE, readMarker }
 
 /**
@@ -120,14 +132,17 @@ export function listSkills(sourceDir) {
  * @param details - Marker contents
  * @param details.version - Installed package version
  * @param details.skills - Skill directory names the package owns
+ * @param details.shared - Shared directory names the package owns, installed
+ *   beside the skills directory; defaults to an empty list for older callers
  */
-export function writeMarker(targetDir, { version, skills }) {
+export function writeMarker(targetDir, { version, skills, shared = [] }) {
   writeMarkerFile(targetDir, {
     schema: 1,
     source: "opencode-codeops",
     version,
     installedAt: new Date().toISOString(),
     skills,
+    shared,
   })
 }
 
@@ -159,12 +174,97 @@ function installOneSkill({ sourceDir, targetDir, name, dryRun, link }) {
   return atomicReplace({ from, targetDir, name, recursive: true })
 }
 
+/**
+ * Installs the package-root sibling directories the skills link to.
+ *
+ * Both the source and the destination are the parents of the skills
+ * directories, so `../../_shared/...` and `../../references/...` links resolve
+ * from every installed skill. A sibling the marker does not own is left
+ * untouched unless `force` is set. A sibling missing from the source is skipped
+ * with a warning, which is normal when a custom `--source` points at a bare
+ * skills directory.
+ *
+ * @param details - Shared-directory install inputs
+ * @param details.sourceDir - Skills source directory (siblings live beside it)
+ * @param details.targetDir - Skills install directory (siblings install beside it)
+ * @param details.ownedShared - Shared directory names the marker already owns
+ * @param details.force - Replace unowned same-named directories
+ * @param details.dryRun - Report only, write nothing
+ * @param details.link - Symlink to the source instead of copying
+ * @returns The installed shared directory names and the skipped count
+ */
+function installSharedDirs({ sourceDir, targetDir, ownedShared, force, dryRun, link }) {
+  const sourceRoot = dirname(sourceDir)
+  const installRoot = dirname(targetDir)
+  const shared = []
+  let skipped = 0
+
+  for (const name of SHARED_DIRS) {
+    const from = join(sourceRoot, name)
+    const dest = join(installRoot, name)
+
+    if (!existsSync(from)) {
+      // The marker may already own this directory from an earlier install even
+      // though the current source no longer ships it. Keep the recorded
+      // ownership so `uninstall` can still remove it, and leave the copy alone.
+      if (ownedShared.has(name) && entryExists(dest)) {
+        console.log(`shared directory not found in source; keeping managed copy: ${dest}`)
+        shared.push(name)
+      } else {
+        console.log(`shared directory not found in source, skipped: ${from}`)
+      }
+      continue
+    }
+
+    if (entryExists(dest) && !ownedShared.has(name) && !force) {
+      console.log(`conflict, skipped (not managed by opencode-codeops; use --force): ${dest}`)
+      skipped += 1
+      continue
+    }
+
+    const existed = entryExists(dest)
+    if (!dryRun) {
+      if (link) linkEntry({ from, dest, type: "dir" })
+      else atomicReplace({ from, targetDir: installRoot, name, recursive: true })
+    }
+    shared.push(name)
+    console.log(`${dryRun ? "[dry-run] would " : ""}${existed ? "replace" : "install"}: ${dest}`)
+  }
+
+  return { shared, skipped }
+}
+
+/**
+ * Reports that shared directories are skipped when the target is a symlink.
+ *
+ * The skills are written through a symlinked target into the real directory,
+ * but the shared directories would land beside the link. Their `../../` links
+ * then resolve beside the real skills directory, so installing beside the link
+ * puts them in the wrong place; copying into the link target could overwrite
+ * the package checkout the link often points at. Skipping leaves the escape
+ * hatch safe and lets the user place the shared directories beside the real
+ * skills directory if the link target does not already contain them.
+ *
+ * @param targetDir - Symlinked skills install directory
+ * @returns Empty install result
+ */
+function skipSharedDirs(targetDir) {
+  console.log(
+    `warning: ${targetDir} is a symlink; skipping shared directories. ` +
+      "_shared/ and references/ must exist beside the real skills directory " +
+      "for the skills' relative links to resolve."
+  )
+  return { shared: [], skipped: 0 }
+}
+
 /**
  * Installs or upgrades every packaged skill into a target directory.
  *
  * Skills named by an existing marker, plus every packaged skill on a first run,
  * are replaced. A same-named directory that the marker does not own is skipped
  * unless `force` is set, so an unrelated skill is never overwritten by accident.
+ * The shared directories the skills link to are installed beside the target
+ * through {@link installSharedDirs}.
  *
  * @param details - Install inputs
  * @param details.sourceDir - Skills directory holding the packaged skills
@@ -173,7 +273,7 @@ function installOneSkill({ sourceDir, targetDir, name, dryRun, link }) {
  * @param details.force - Replace same-named directories the marker does not own
  * @param details.dryRun - Report only, write nothing
  * @param details.link - Symlink to the source instead of copying
- * @returns Counts plus the skill names recorded in the marker
+ * @returns Counts plus the skill and shared names recorded in the marker
  */
 export function installSkills({
   sourceDir,
@@ -186,13 +286,15 @@ export function installSkills({
   const names = listSkills(sourceDir)
   const marker = readSkillsMarker(targetDir)
   const managed = marker ? new Set(marker.skills ?? []) : null
-  const counts = { skills: names.length, installed: 0, replaced: 0, skipped: 0 }
+  const ownedShared = new Set(marker?.shared ?? [])
+  const counts = { skills: names.length, installed: 0, replaced: 0, skipped: 0, shared: 0 }
   const owned = []
   const prefix = dryRun ? "[dry-run] would " : ""
 
   if (!dryRun) {
     ensureDir(targetDir)
     cleanStaleArtifacts(targetDir)
+    cleanStaleArtifacts(dirname(targetDir))
   }
 
   for (const name of names) {
@@ -211,9 +313,15 @@ export function installSkills({
     console.log(`${prefix}${existed ? "replace" : "install"}: ${dest}`)
   }
 
-  if (!dryRun) writeMarker(targetDir, { version, skills: owned })
+  const installedShared = isSymlink(targetDir)
+    ? skipSharedDirs(targetDir)
+    : installSharedDirs({ sourceDir, targetDir, ownedShared, force, dryRun, link })
+  counts.shared = installedShared.shared.length
+  counts.skipped += installedShared.skipped
 
-  return { ...counts, owned }
+  if (!dryRun) writeMarker(targetDir, { version, skills: owned, shared: installedShared.shared })
+
+  return { ...counts, owned, shared: installedShared.shared }
 }
 
 /**
@@ -222,16 +330,19 @@ export function installSkills({
  * The marker is the ownership record, so an unmanaged install is left intact.
  * Without a marker the function reports an error instead of guessing.
  *
+ * Removes both the owned skills and the shared directories the installer placed
+ * beside them, so an uninstall leaves no package-owned files behind.
+ *
  * @param details - Uninstall inputs
  * @param details.targetDir - Skills directory to clean
  * @param details.dryRun - Report only, write nothing
- * @returns Removed skill names plus the marker outcome, or a reason it refused
+ * @returns Removed skill and shared names plus the marker outcome, or a reason it refused
  */
 export function uninstallSkills({ targetDir, dryRun = false }) {
   const marker = readSkillsMarker(targetDir)
 
   if (!marker) {
-    return { removed: [], markerRemoved: false, error: "no opencode-codeops marker found" }
+    return { removed: [], shared: [], markerRemoved: false, error: "no opencode-codeops marker found" }
   }
 
   const removed = []
@@ -245,9 +356,21 @@ export function uninstallSkills({ targetDir, dryRun = false }) {
     console.log(`${dryRun ? "would remove" : "removed"}: ${dest}`)
   }
 
+  const shared = []
+  const installRoot = dirname(targetDir)
+
+  for (const name of marker.shared ?? []) {
+    const dest = join(installRoot, name)
+    if (!entryExists(dest)) continue
+
+    if (!dryRun) rmSync(dest, { recursive: true, force: true })
+    shared.push(name)
+    console.log(`${dryRun ? "would remove" : "removed"}: ${dest}`)
+  }
+
   if (!dryRun) rmSync(join(targetDir, MARKER_FILE), { force: true })
 
-  return { removed, markerRemoved: true }
+  return { removed, shared, markerRemoved: true }
 }
 
 /** Prints command usage. */
@@ -341,6 +464,11 @@ function printStatus({ targetDir, sourceDir, sourceVersion }) {
     if (missing.length > 0) {
       console.log(`warning: missing managed skills: ${missing.join(", ")}`)
     }
+    const installRoot = dirname(targetDir)
+    const missingShared = (marker.shared ?? []).filter((name) => !entryExists(join(installRoot, name)))
+    if (missingShared.length > 0) {
+      console.log(`warning: missing managed shared directories: ${missingShared.join(", ")}`)
+    }
     return
   }
 
@@ -415,8 +543,8 @@ export function main(argv, io = {}) {
       return 0
     }
     console.log(
-      `${options.dryRun ? "would remove" : "removed"} ${result.removed.length} skill(s); ` +
-        `marker ${options.dryRun ? "would be removed" : "removed"}`
+      `${options.dryRun ? "would remove" : "removed"} ${result.removed.length} skill(s) and ` +
+        `${result.shared.length} shared dir(s); marker ${options.dryRun ? "would be removed" : "removed"}`
     )
     return 0
   }
@@ -432,7 +560,8 @@ export function main(argv, io = {}) {
   const mode = options.dryRun ? " (dry-run, nothing written)" : ""
   console.log(
     `Done${mode}: ${counts.skills} skills | ` +
-      `installed ${counts.installed}, replaced ${counts.replaced}, ${counts.skipped} skipped`
+      `installed ${counts.installed}, replaced ${counts.replaced}, ${counts.skipped} skipped | ` +
+      `shared ${counts.shared}/${SHARED_DIRS.length}`
   )
   if (counts.skipped > 0) {
     console.log("Re-run with --force to replace skipped directories.")

package/bin/lib/opencode-plugin.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * Registers (or inspects) the CodeOps plugin in OpenCode's own config.
+ *
+ * OpenCode ships a command that installs a plugin and updates the config
+ * safely, including JSON/JSONC formatting and version replacement:
+ *
+ *   opencode plugin <module> [--global] [--force]
+ *
+ * The installer delegates to that command instead of editing `opencode.json`
+ * itself, so it never has to parse JSONC or risk clobbering a user's config.
+ * All calls are best-effort: if the `opencode` executable is missing or the
+ * command fails, the caller still completes the file install and tells the user
+ * how to register the plugin manually.
+ *
+ * @module lib/opencode-plugin
+ */
+
+import { spawnSync } from "node:child_process"
+
+/** The npm package name of the plugin. */
+export const PLUGIN_NAME = "opencode-codeops"
+
+/**
+ * Runs a command and normalizes the result.
+ *
+ * @param command - Executable to run
+ * @param args - Argument list
+ * @param options - Spawn options (for example `cwd`)
+ * @returns The exit status, stdout, stderr, and any spawn error
+ */
+export function defaultRun(command, args, options = {}) {
+  const result = spawnSync(command, args, { encoding: "utf-8", ...options })
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    error: result.error,
+  }
+}
+
+/**
+ * Builds the arguments for `opencode plugin`.
+ *
+ * @param details - Plugin registration inputs
+ * @param details.scope - `"global"` adds `--global`; `"project"` omits it
+ * @param details.version - Exact version to pin, or `undefined` for the bare name
+ * @returns Arguments after the `opencode` executable
+ * @example
+ * buildPluginArgs({ scope: "global", version: "1.0.0" })
+ * // ["plugin", "opencode-codeops@1.0.0", "--global", "--force"]
+ */
+export function buildPluginArgs({ scope, version }) {
+  const module = version ? `${PLUGIN_NAME}@${version}` : PLUGIN_NAME
+  const args = ["plugin", module]
+  if (scope === "global") args.push("--global")
+  args.push("--force")
+  return args
+}
+
+/**
+ * Registers the plugin in the OpenCode config.
+ *
+ * Tries the exact version first so plugin and files stay in sync; if the CLI
+ * rejects the versioned spec, falls back to the bare package name. Never throws.
+ *
+ * @param details - Registration inputs
+ * @param details.scope - `"global"` or `"project"`
+ * @param details.version - Version to pin
+ * @param details.cwd - Working directory (used for project scope)
+ * @param details.run - Command runner, injectable for tests
+ * @returns Whether registration succeeded, the spec used, and a reason on failure
+ */
+export function registerPlugin({ scope, version, cwd, run = defaultRun }) {
+  try {
+    const probe = run("opencode", ["--version"], { cwd })
+    if (probe.error || probe.status !== 0) {
+      return { ok: false, spec: null, reason: "opencode CLI not found on PATH" }
+    }
+
+    const pinned = run("opencode", buildPluginArgs({ scope, version }), { cwd })
+    if (!pinned.error && pinned.status === 0) {
+      return { ok: true, spec: `${PLUGIN_NAME}@${version}` }
+    }
+
+    const bare = run("opencode", buildPluginArgs({ scope, version: null }), { cwd })
+    if (!bare.error && bare.status === 0) {
+      return { ok: true, spec: PLUGIN_NAME }
+    }
+
+    const message = (bare.stderr || bare.stdout || pinned.stderr || pinned.stdout || "").trim()
+    return { ok: false, spec: null, reason: message.split("\n").pop() || "opencode plugin failed" }
+  } catch (caught) {
+    return { ok: false, spec: null, reason: caught.message }
+  }
+}
+
+/**
+ * Reads the resolved `plugin` list from OpenCode's effective config.
+ *
+ * @param details - Inspection inputs
+ * @param details.cwd - Working directory
+ * @param details.run - Command runner, injectable for tests
+ * @returns The plugin entries, or `undefined` when the config cannot be read
+ */
+export function readConfiguredPlugin({ cwd, run = defaultRun } = {}) {
+  try {
+    const result = run("opencode", ["debug", "config"], { cwd })
+    if (result.error || result.status !== 0) return undefined
+
+    const config = JSON.parse(result.stdout)
+    return Array.isArray(config.plugin) ? config.plugin : []
+  } catch {
+    return undefined
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codeops",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Specification-first engineering for complex systems — CodeOps plugin for OpenCode",
   "type": "module",
   "engines": {