opencode-codeops 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 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

@@ -45,41 +45,46 @@ Add to your `opencode.json`:
 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
+### 2. Install the skills and subagents
 
-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:
+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:
 
 ```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
 ```
 
+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.
+
 Pin a version with `CODEOPS_VERSION` (an npm dist-tag or exact version; defaults to `latest`):
 
 ```bash
-CODEOPS_VERSION=1.4.0 curl -fsSL https://cdn.jsdelivr.net/npm/opencode-codeops@latest/install.sh | bash
+CODEOPS_VERSION=1.5.0 curl -fsSL https://cdn.jsdelivr.net/npm/opencode-codeops@latest/install.sh | bash
 ```
 
 Pin the plugin to the same version so the two cannot drift apart:
 
 ```json
-{ "plugin": ["opencode-codeops@1.4.0"] }
+{ "plugin": ["opencode-codeops@1.5.0"] }
 ```
 
 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.
+package owns, recorded in `.opencode-codeops.json`. Files you author yourself, or install with
+another tool, are left untouched.
 
 Check or remove an install:
 
@@ -88,47 +93,37 @@ 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/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.
-
-### 3. Install the subagents
-
-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:
-
-```bash
-npx -y opencode-codeops@latest install-agents --project
-```
+`status` reports the installed version next to the current package version, so a plugin/files
+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.
 
 ### 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:
 
 ```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
 ```
 
 ## 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 +135,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,174 @@
 /**
  * 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"
 
+/** 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)
+  -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/.`)
 }
 
 /**
- * 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
   }
-  return "skills"
 }
 
 /**
- * Runs the requested command.
+ * Resolves whether files install into the project or globally.
  *
- * The modules are imported lazily so a skills-only invocation never loads the
- * agent installer, and vice versa.
+ * 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"`
  */
-async function run() {
-  const args = process.argv.slice(2)
-  const first = args[0]
+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 "global"
+}
+
+/**
+ * Runs one command against both installers.
+ *
+ * @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 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 scope = resolveScope(
+    { project: rest.includes("--project"), global: rest.includes("--global") },
+    cwd
+  )
+  const passed = rest.filter((arg) => arg !== "--project" && arg !== "--global")
+  const scoped = [scope === "project" ? "--project" : "--global", ...passed]
+
+  const skillsCode = skills.main([command, ...scoped], io)
+  const agentsCode = agents.main([command, ...scoped], io)
+  return skillsCode || agentsCode
+}
+
+/**
+ * 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/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.5.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.