opencode-codeops 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 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
+
+- installer: unify install/update into one command
+- installer: add npm-first install, agents installer, and release tooling
+
 ## 1.4.0 — 2026-09-19
 
 ### Features

package/README.md

@@ -27,108 +27,97 @@ 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
-
-OpenCode discovers skills only from the filesystem (`.opencode/skills/` or
-`~/.config/opencode/skills/`); it never reads them from a plugin package. The installer is a thin
-`npx` wrapper around this package, so the skills 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
 curl -fsSL https://cdn.jsdelivr.net/npm/opencode-codeops@latest/install.sh | bash
 
-# Project-only — skills live in ./.opencode/skills and are committed with the repo
+# Project-only — files live in ./.opencode and are committed with the repo
 curl -fsSL https://cdn.jsdelivr.net/npm/opencode-codeops@latest/install.sh | bash -s -- --project
 ```
 
 The same installer runs directly through npm:
 
 ```bash
-npx -y opencode-codeops@latest install-skills
+npx -y opencode-codeops@latest install
+npx -y opencode-codeops@latest update    # alias of install
 ```
 
-Pin a version with `CODEOPS_VERSION` (an npm dist-tag or exact version; defaults to `latest`):
+`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.
 
-```bash
-CODEOPS_VERSION=1.4.0 curl -fsSL https://cdn.jsdelivr.net/npm/opencode-codeops@latest/install.sh | bash
-```
+The scope is auto-detected: inside a CodeOps project (a git repo with `.opencode/` or
+`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 the plugin to the same version so the two cannot drift apart:
+If you prefer to register the plugin manually instead, add it to your `opencode.json`:
 
 ```json
-{ "plugin": ["opencode-codeops@1.4.0"] }
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-codeops"]
+}
 ```
 
-Re-running the installer upgrades an existing install in place. It replaces only the files this
-package owns, recorded in `<skills-dir>/.opencode-codeops.json`. Skills you author yourself, or
-install with another tool, are left untouched.
-
-Check or remove an install:
+Pin a version with `CODEOPS_VERSION` (an npm dist-tag or exact version; defaults to `latest`):
 
 ```bash
-npx -y opencode-codeops@latest status
-npx -y opencode-codeops@latest uninstall
+CODEOPS_VERSION=1.6.0 curl -fsSL https://cdn.jsdelivr.net/npm/opencode-codeops@latest/install.sh | bash
 ```
 
-`status` reports the installed version next to the current package version, so a plugin/skills
-mismatch is visible. Use `--dry-run` to preview an install; a same-named directory the package
-does not own is skipped with a warning, and `--force` replaces it.
+`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.
 
-### 3. Install the subagents
+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.
 
-The 12 CodeOps subagents install into `.opencode/agents/` (project) or `~/.config/opencode/agents/`
-(global). The `/setup-codeops` skill does this for a project; do it manually with:
+Check or remove an install:
 
 ```bash
-npx -y opencode-codeops@latest install-agents --project
+npx -y opencode-codeops@latest status
+npx -y opencode-codeops@latest uninstall
 ```
 
+`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. `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 skills to a checkout, so edits
-are picked up without reinstalling:
+Symlink the plugin into your OpenCode plugin directory and link the installed files to a checkout,
+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-skills --link --global
-node /path/to/opencode-codeops/bin/index.mjs install-agents --link --global
+node /path/to/opencode-codeops/bin/index.mjs install --link --global --no-plugin
 ```
 
 ## Setup
 
-After installing the plugin and the skills, initialize CodeOps in your project:
+After installing the plugin and the files, initialize CodeOps in your project:
 
 ```
 /setup-codeops
 ```
 
-This creates the `codeops/` layout, scaffolds `codeops/codeops.json` and `codeops/.codeops.yml`, installs the 12 CodeOps subagent files into `.opencode/agents/`, and adds a managed section to `AGENTS.md`.
+This creates the `codeops/` layout, scaffolds `codeops/codeops.json` and `codeops/.codeops.yml`, installs the skills and the 12 CodeOps subagent files into `.opencode/`, and adds a managed section to `AGENTS.md`.
 
 Commit the result:
 
 ```bash
-git add codeops/ .opencode/agents/ AGENTS.md
+git add codeops/ .opencode/ AGENTS.md
 git commit -m "chore: initialize CodeOps"
 ```
 
@@ -140,7 +129,7 @@ On every OpenCode session start and after every compaction, the plugin injects:
 
 These standards are active without any user action. They do not need to be copied into `AGENTS.md`.
 
-The plugin also warns (non-blocking) if any tool attempts to edit `codeops/.codeops.yml` directly — that file is managed exclusively by the `setup-codeops` skill.
+The plugin also warns (non-blocking) if any tool attempts to edit `codeops/.codeops.yml` directly — that file is managed exclusively by the `setup-codeops` skill — and if the installed skills version differs from the plugin version, so a stale install is visible.
 
 ## Agent model configuration
 

package/bin/index.mjs

@@ -2,92 +2,211 @@
 /**
  * The `opencode-codeops` command-line entry point.
  *
- * Routes each command to the skills installer (`install-skills.mjs`) or the
- * agent installer (`install-agents.mjs`), so one package binary exposes both.
- * `status` reports on both installs because the skills and the plugin can drift
- * in version and that is the check a user needs most.
+ * There is exactly one installation path: a command installs or updates the
+ * skills and the subagents together. The two filesystems installers
+ * (`install-skills.mjs` and `install-agents.mjs`) are implementation details
+ * this module orchestrates; they are never exposed as separate user commands.
+ *
+ * The scope is auto-detected. Inside a CodeOps project the files go to
+ * `.opencode/skills` and `.opencode/agents`; anywhere else they go to the
+ * global `~/.config/opencode/` directories. `--project` and `--global` override
+ * the detection.
  *
  * Usage:
- *   opencode-codeops install-skills [options]   Install or upgrade skills
- *   opencode-codeops install-agents [options]   Install or upgrade subagents
- *   opencode-codeops status [options]           Show installed skills and agents
- *   opencode-codeops uninstall [options]        Remove the managed skills
- *   opencode-codeops help                       Show this help
+ *   opencode-codeops install [options]     Install or upgrade skills and agents
+ *   opencode-codeops update [options]      Alias of install
+ *   opencode-codeops status [options]      Show installed versions
+ *   opencode-codeops uninstall [options]   Remove managed files
+ *   opencode-codeops help                  Show this help
  *
  * @module index
  */
 
-import { realpathSync } from "node:fs"
+import { execFileSync } from "node:child_process"
+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"])
+
 /** Prints command usage. */
 function printUsage() {
   console.log(`CodeOps installer for OpenCode.
 
 Usage:
-  opencode-codeops install-skills [options]   Install or upgrade skills (default)
-  opencode-codeops install-agents [options]   Install or upgrade subagents
-  opencode-codeops status [options]           Show installed skills and agents
-  opencode-codeops uninstall [options]        Remove the managed skills
-  opencode-codeops help                       Show this help
-
-Run \`opencode-codeops install-skills --help\` or
-\`opencode-codeops install-agents --help\` for the option list.`)
+  opencode-codeops install [options]     Install or upgrade skills and agents (default)
+  opencode-codeops update [options]      Alias of install
+  opencode-codeops status [options]      Show installed skills and agents
+  opencode-codeops uninstall [options]   Remove managed skills and agents
+  opencode-codeops help                  Show this help
+
+Options:
+  --project          Force the project scope (./.opencode)
+  --global           Force the global scope (~/.config/opencode)
+  --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/.
+
+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.`)
 }
 
 /**
- * Chooses the installer module for a command line.
+ * Finds the git top-level directory for a working directory.
  *
- * @param argv - Arguments after the executable
- * @returns `"agents"` for agent commands, otherwise `"skills"`
+ * @param cwd - Directory to start from
+ * @returns The repository root, or `cwd` when it is not a git checkout
  */
-export function route(argv) {
-  const first = argv[0]
-  if (first === "install-agents" || first === "agents-status" || first === "agents-uninstall") {
-    return "agents"
+function findProjectRoot(cwd) {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim()
+  } catch {
+    return cwd
+  }
+}
+
+/**
+ * Resolves whether files install into the project or globally.
+ *
+ * Explicit flags win. Otherwise a git repository is a CodeOps project when it
+ * already contains `.opencode/` or `codeops/.codeops.yml`; anything else uses
+ * the global scope.
+ *
+ * @param options - Scope flags from the command line
+ * @param options.project - Force the project scope
+ * @param options.global - Force the global scope
+ * @param cwd - Directory the command ran from
+ * @returns `"project"` or `"global"`
+ */
+export function resolveScope(options, cwd) {
+  if (options.project) return "project"
+  if (options.global) return "global"
+
+  const root = findProjectRoot(cwd)
+  if (existsSync(join(root, ".opencode")) || existsSync(join(root, "codeops", ".codeops.yml"))) {
+    return "project"
   }
-  return "skills"
+  return "global"
 }
 
 /**
- * Runs the requested command.
+ * Runs one command against both installers.
  *
- * The modules are imported lazily so a skills-only invocation never loads the
- * agent installer, and vice versa.
+ * @param command - `install`, `status`, or `uninstall`
+ * @param rest - Options to forward, without the scope flags (re-added below)
+ * @param io - Injectable environment (`cwd`, `home`) for tests
+ * @returns The combined process exit code
  */
-async function run() {
-  const args = process.argv.slice(2)
-  const first = args[0]
+async function runCombined(command, rest, io) {
+  const skills = await import("./install-skills.mjs")
+  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" && arg !== "--no-plugin"
+  )
+  const scoped = [scope === "project" ? "--project" : "--global", ...passed]
+
+  const skillsCode = skills.main([command, ...scoped], io)
+  const agentsCode = agents.main([command, ...scoped], io)
+  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
+}
+
+/**
+ * Dispatches a command line.
+ *
+ * Bare options (for example `opencode-codeops --project`) mean `install`, so the
+ * common case needs no subcommand.
+ *
+ * @param argv - Arguments after the executable
+ * @param io - Injectable environment (`cwd`, `home`) for tests
+ * @returns The process exit code
+ */
+export async function dispatch(argv, io = {}) {
+  const first = argv[0]
+  const rest = argv.slice(1)
 
   if (!first || first === "help" || first === "-h" || first === "--help") {
     printUsage()
-    return
+    return 0
   }
 
-  if (first === "status") {
-    const skills = await import("./install-skills.mjs")
-    const agents = await import("./install-agents.mjs")
-    const skillsCode = skills.main(["status", ...args.slice(1)])
-    const agentsCode = agents.main(["agents-status", ...args.slice(1)])
-    process.exitCode = skillsCode || agentsCode
-    return
+  // Keep the unified help; the internal installers still document the old
+  // component commands in their own usage text.
+  if (rest.includes("--help") || rest.includes("-h")) {
+    printUsage()
+    return 0
   }
 
-  if (route(args) === "agents") {
-    const { main } = await import("./install-agents.mjs")
-    process.exitCode = main(args)
-    return
+  if (first.startsWith("-")) return runCombined("install", argv, io)
+
+  if (!COMMANDS.has(first)) {
+    console.error(`error: unknown command '${first}'`)
+    printUsage()
+    return 2
   }
 
-  const { main } = await import("./install-skills.mjs")
-  process.exitCode = main(args)
+  const command = first === "update" ? "install" : first
+  return runCombined(command, rest, io)
 }
 
 /**
- * True when this module is the process entry point.
+ * Runs the CLI when this module is the process entry point.
  *
  * The comparison resolves symlinks because npm installs the bin as a symlink in
  * `node_modules/.bin`, so `process.argv[1]` is the link path, not the real path.
+ */
+async function run() {
+  process.exitCode = await dispatch(process.argv.slice(2))
+}
+
+/**
+ * True when this module is the process entry point.
  *
  * @returns True when this file is the entry point
  */

package/bin/install-agents.mjs

@@ -81,20 +81,17 @@ export function readPackageVersion() {
 /**
  * Resolves the directory that holds the packaged agent definitions.
  *
- * The `CODEOPS_PLUGIN_ROOT` environment variable overrides the default, which
- * lets a checkout run the installer before the package is published.
+ * The package's own `agents/` directory is always the source, so the installed
+ * agents match the package that was invoked. The `CODEOPS_PLUGIN_ROOT`
+ * environment variable is deliberately ignored: the plugin exports it into
+ * every shell, and honouring it would install a different checkout's agents.
+ * Pass `--source` to override for development.
  *
  * @param override - Optional explicit agents directory
  * @returns Absolute path to the agents directory
  */
 export function resolveSourceDir(override) {
   if (override) return resolve(override)
-
-  const envRoot = process.env.CODEOPS_PLUGIN_ROOT
-  if (envRoot && existsSync(join(envRoot, "agents"))) {
-    return join(envRoot, "agents")
-  }
-
   return join(PACKAGE_ROOT, "agents")
 }
 
@@ -375,7 +372,7 @@ export function main(argv, io = {}) {
   const cwd = io.cwd ?? process.cwd()
   const version = io.version ?? readPackageVersion()
   const sourceDir = io.source ?? resolveSourceDir(options.source)
-  const targetDir = resolveTarget(options, cwd, "agents")
+  const targetDir = resolveTarget(options, cwd, "agents", io.home)
 
   if (!existsSync(sourceDir)) {
     console.error(`error: agents directory not found: ${sourceDir}`)
@@ -404,8 +401,8 @@ export function main(argv, io = {}) {
   if (command === "uninstall") {
     const result = uninstallAgents({ targetDir, dryRun: options.dryRun })
     if (result.error) {
-      console.error(`error: ${result.error} at ${targetDir}`)
-      return 1
+      console.log(`nothing to remove at ${targetDir} (${result.error})`)
+      return 0
     }
     console.log(
       `${options.dryRun ? "would remove" : "removed"} ${result.removed.length} agent(s); ` +

package/bin/install-skills.mjs

@@ -81,20 +81,17 @@ export function readPackageVersion() {
 /**
  * Resolves the directory that holds the shipped skills.
  *
- * The `CODEOPS_PLUGIN_ROOT` environment variable overrides the default. That
- * lets a checkout run the installer before the package is published.
+ * The package's own `skills/` directory is always the source, so the installed
+ * skills match the package that was invoked. The `CODEOPS_PLUGIN_ROOT`
+ * environment variable is deliberately ignored: the plugin exports it into
+ * every shell, and honouring it would install a different checkout's skills.
+ * Pass `--source` to override for development.
  *
  * @param override - Optional explicit skills directory
  * @returns Absolute path to the skills directory
  */
 export function resolveSourceDir(override) {
   if (override) return resolve(override)
-
-  const envRoot = process.env.CODEOPS_PLUGIN_ROOT
-  if (envRoot && existsSync(join(envRoot, "skills"))) {
-    return join(envRoot, "skills")
-  }
-
   return join(PACKAGE_ROOT, "skills")
 }
 
@@ -385,7 +382,7 @@ export function main(argv, io = {}) {
   const cwd = io.cwd ?? process.cwd()
   const version = io.version ?? readPackageVersion()
   const sourceDir = io.source ?? resolveSourceDir(options.source)
-  const targetDir = resolveTarget(options, cwd, "skills")
+  const targetDir = resolveTarget(options, cwd, "skills", io.home)
 
   if (!existsSync(sourceDir)) {
     console.error(`error: skills directory not found: ${sourceDir}`)
@@ -414,8 +411,8 @@ export function main(argv, io = {}) {
   if (command === "uninstall") {
     const result = uninstallSkills({ targetDir, dryRun: options.dryRun })
     if (result.error) {
-      console.error(`error: ${result.error} at ${targetDir}`)
-      return 1
+      console.log(`nothing to remove at ${targetDir} (${result.error})`)
+      return 0
     }
     console.log(
       `${options.dryRun ? "would remove" : "removed"} ${result.removed.length} skill(s); ` +

package/bin/lib/opencode-install.mjs

@@ -167,12 +167,13 @@ export function linkEntry({ from, dest, type = "dir" }) {
  * @param options.project - Use a project-relative directory instead of global
  * @param cwd - Project root used for `--project`
  * @param kind - Subdirectory name under `.opencode` (for example `skills`)
+ * @param home - Home directory used for the global default (injectable for tests)
  * @returns Absolute path to the target directory
  */
-export function resolveTarget(options, cwd, kind) {
+export function resolveTarget(options, cwd, kind, home = homedir()) {
   if (options.target) return resolve(options.target)
   if (options.project) return resolve(cwd, ".opencode", kind)
-  return join(homedir(), ".config", "opencode", kind)
+  return join(home, ".config", "opencode", kind)
 }
 
 /**

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/install.sh

@@ -17,11 +17,11 @@
 # defaults to "latest").
 #
 # Subcommands (see `npx opencode-codeops help` for the full option list):
-#   install-skills   Install or upgrade the skills      (default)
-#   install-agents   Install or upgrade the subagents
-#   status           Show the installed skills and agents version
-#   uninstall        Remove the managed skills
-#   help             Show installer help
+#   install     Install or upgrade skills and subagents   (default)
+#   update      Alias of install
+#   status      Show the installed versions
+#   uninstall   Remove the managed files
+#   help        Show installer help
 
 set -euo pipefail
 
@@ -40,12 +40,12 @@ if ! command -v npx >/dev/null 2>&1; then
   exit 1
 fi
 
-# The subcommand is optional and defaults to install-skills. Any remaining
-# arguments are passed through to the installer unchanged.
-subcommand="install-skills"
+# The subcommand is optional and defaults to install. Any remaining arguments
+# are passed through to the installer unchanged.
+subcommand="install"
 if (( $# > 0 )); then
   case "$1" in
-    install | install-skills | install-agents | status | uninstall | help)
+    install | update | status | uninstall | help)
       subcommand="$1"
       shift
       ;;

package/package.json

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

package/plugin/index.ts

@@ -79,9 +79,9 @@ function installedSkillsVersion(skillsDir: string): string | undefined {
 
 // ---------------------------------------------------------------------------
 // Helper — warn (non-blocking) when the installed skills were written by a
-// different CodeOps version than this plugin. The plugin and the skills are
+// different CodeOps version than this plugin. The plugin and the files are
 // installed by separate commands, so their versions can drift; a mismatch
-// usually means the skills need `npx opencode-codeops install-skills` again.
+// usually means the skills need `npx opencode-codeops update` again.
 // ---------------------------------------------------------------------------
 async function warnOnVersionSkew(
   client: Parameters<Plugin>[0]["client"],
@@ -103,7 +103,7 @@ async function warnOnVersionSkew(
         message:
           `CodeOps skills at ${skillsDir} are version ${installed}, ` +
           `but the plugin is version ${packageVersion}. ` +
-          `Run \`npx opencode-codeops@${packageVersion} install-skills\` to match them.`,
+          `Run \`npx opencode-codeops@${packageVersion} update\` to match them.`,
       },
     })
   }

package/skills/setup-codeops/scaffold.md

@@ -76,24 +76,24 @@ default when it is absent — so this line is a convenience/pin, not a requireme
 - Scaffolding is intentionally simple, so it lives in skill prose; only the *migration* path
   needs the deterministic engine. For migration, see [migration.md](migration.md).
 
-## Agent file installation
+## Project file installation
 
-After scaffolding, install the CodeOps OpenCode agent definitions into the project. Prefer the
-installer bundled with the running plugin, so the agent version always matches the plugin version:
+After scaffolding, install the CodeOps skills and subagents into the project. Prefer the installer
+bundled with the running plugin, so the installed files always match the plugin version:
 
 ```bash
-node "${CODEOPS_PLUGIN_ROOT}/bin/install-agents.mjs" --project
+node "${CODEOPS_PLUGIN_ROOT}/bin/index.mjs" install --project
 ```
 
 When the plugin is not active, the published installer does the same thing:
 
 ```bash
-npx -y opencode-codeops@latest install-agents --project
+npx -y opencode-codeops@latest install --project
 ```
 
-This installs the 12 CodeOps subagent definitions (`executor`, `explorer`, `correctness-reviewer`,
-etc.) into `.opencode/agents/` where OpenCode will discover and load them automatically. These files
-are safe to commit to git. Files the installer owns are replaced on upgrade; same-named files it
-does not own are left untouched (pass `--force` to replace them). Users can override individual
-agent models in `opencode.json` under the `agent` key.
+This installs the skills into `.opencode/skills/` and the 12 subagent definitions (`executor`,
+`explorer`, `correctness-reviewer`, etc.) into `.opencode/agents/`, where OpenCode discovers and
+loads them automatically. These files are safe to commit to git. Files the installer owns are
+replaced on upgrade; same-named files it does not own are left untouched (pass `--force` to replace
+them). Users can override individual agent models in `opencode.json` under the `agent` key.