opencode-codeops 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 2.5.0 — 2026-10-29
+
+### Features
+
+- setup-codeops: add Discovery enable and disable toggles
+
 ## 2.4.0 — 2026-10-29
 
 ### Features

package/README.md

@@ -191,8 +191,16 @@ The shared header carries a real breadcrumb and a **System / Light / Dark** them
 follows the operating-system setting; an explicit choice is remembered in the browser. If storage
 is unavailable, the choice still applies for the current tab.
 
-New projects created with `setup-codeops` start with Discovery enabled. For an existing project,
-run `analyze-project --with-discovery`, or add the setting to `codeops/codeops.json`:
+New projects created with `setup-codeops` start with Discovery enabled. Existing projects can
+toggle it without re-scaffolding:
+
+```text
+/setup-codeops --enable-discovery
+/setup-codeops --disable-discovery
+```
+
+`analyze-project --with-discovery` remains available for the same config change. The setting lives
+in `codeops/codeops.json`:
 
 ```json
 {

package/_shared/discovery.md

@@ -4,7 +4,8 @@
 
 Discovery moves large question rounds out of the chat scroll and into a local
 browser page. New projects created with `setup-codeops` enable it by default;
-existing projects opt in. It never replaces the Ambiguity Register. Use it only
+existing projects toggle it with `setup-codeops --enable-discovery` or
+`--disable-discovery`. It never replaces the Ambiguity Register. Use it only
 when this file's conditions hold; otherwise ask in chat exactly as before.
 
 ## When it applies

package/package.json

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

package/scripts/discovery-toggle.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/**
+ * Enable or disable Discovery in an existing CodeOps project.
+ *
+ * The toggle is deliberately small and deterministic: it edits only
+ * `codeops/codeops.json` and, when the managed block exists, the Discovery
+ * line in `AGENTS.md`. It refuses symlinks and malformed configuration, and
+ * preserves every unrelated key.
+ *
+ * @module discovery-toggle
+ */
+
+import { existsSync, lstatSync, readFileSync, writeFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+/** The managed AGENTS.md line for an enabled Discovery page. */
+export const DISCOVERY_LINE =
+  "- Discovery: enabled — question rounds open in the local Discovery page"
+
+const START_MARKER = "<!-- CODEOPS-PROJECT:START -->"
+const END_MARKER = "<!-- CODEOPS-PROJECT:END -->"
+
+/** A user-facing toggle failure. */
+export class DiscoveryToggleError extends Error {}
+
+/** True for a non-null, non-array object. */
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+/** Refuse a symlink or a missing regular file. */
+function assertRegularFile(path, label) {
+  if (!existsSync(path)) {
+    throw new DiscoveryToggleError(`${label} does not exist.`)
+  }
+  const stats = lstatSync(path)
+  if (stats.isSymbolicLink()) {
+    throw new DiscoveryToggleError(`${label} is a symlink; refusing to write through it.`)
+  }
+  if (!stats.isFile()) {
+    throw new DiscoveryToggleError(`${label} is not a regular file.`)
+  }
+}
+
+/** Refuse a symlinked codeops directory. */
+function assertDirectory(path, label) {
+  if (!existsSync(path)) {
+    throw new DiscoveryToggleError(`${label} does not exist; run setup-codeops first.`)
+  }
+  const stats = lstatSync(path)
+  if (stats.isSymbolicLink()) {
+    throw new DiscoveryToggleError(`${label} is a symlink; refusing to write through it.`)
+  }
+  if (!stats.isDirectory()) {
+    throw new DiscoveryToggleError(`${label} is not a directory.`)
+  }
+}
+
+/** Normalize a config's discovery object without discarding known keys. */
+function nextDiscovery(existing, enable) {
+  if (existing !== undefined && !isPlainObject(existing)) {
+    throw new DiscoveryToggleError("codeops/codeops.json has a malformed discovery object.")
+  }
+  const discovery = { ...(existing ?? {}) }
+  discovery.enabled = enable
+  if (enable && discovery.chatMaxQuestions === undefined) {
+    discovery.chatMaxQuestions = 3
+  }
+  if (
+    discovery.chatMaxQuestions !== undefined &&
+    (!Number.isInteger(discovery.chatMaxQuestions) || discovery.chatMaxQuestions < 0)
+  ) {
+    throw new DiscoveryToggleError("discovery.chatMaxQuestions must be a non-negative integer.")
+  }
+  return discovery
+}
+
+/** Add or remove the managed Discovery line inside an AGENTS.md managed block. */
+function updateAgents(text, enable) {
+  const eol = text.includes("\r\n") ? "\r\n" : "\n"
+  const lines = text.split(/\r?\n/)
+  const starts = lines
+    .map((line, index) => (line.trim() === START_MARKER ? index : -1))
+    .filter((index) => index >= 0)
+  const ends = lines
+    .map((line, index) => (line.trim() === END_MARKER ? index : -1))
+    .filter((index) => index >= 0)
+  if (starts.length !== 1 || ends.length !== 1 || starts[0] > ends[0]) {
+    return { status: "block-missing", changed: false, text }
+  }
+  const start = starts[0]
+  const end = ends[0]
+  const block = lines.slice(start, end + 1)
+  const existing = block.findIndex((line) => line.trim() === DISCOVERY_LINE)
+  if (enable) {
+    if (existing >= 0) return { status: "already-enabled", changed: false, text }
+    const anchor = block.findIndex((line) => line.trim().startsWith("- Specialist coverage:"))
+    if (anchor === -1) {
+      return { status: "anchor-missing", changed: false, text }
+    }
+    block.splice(anchor + 1, 0, DISCOVERY_LINE)
+  } else {
+    if (existing === -1) return { status: "already-disabled", changed: false, text }
+    block.splice(existing, 1)
+  }
+  lines.splice(start, end - start + 1, ...block)
+  return { status: enable ? "enabled" : "disabled", changed: true, text: lines.join(eol) }
+}
+
+/**
+ * Toggle Discovery for one project.
+ *
+ * @param {{ root?: string, enable: boolean, dryRun?: boolean }} options
+ * @returns {{ configPath: string, discovery: object, changed: boolean,
+ *   agents: string, dryRun: boolean }}
+ */
+export function toggleDiscovery(options) {
+  if (typeof options.enable !== "boolean") {
+    throw new DiscoveryToggleError("enable must be true or false.")
+  }
+  const root = resolve(options.root ?? process.cwd())
+  const dryRun = options.dryRun === true
+  const codeopsDir = join(root, "codeops")
+  assertDirectory(codeopsDir, "codeops/")
+  const configPath = join(codeopsDir, "codeops.json")
+  assertRegularFile(configPath, "codeops/codeops.json")
+
+  const original = readFileSync(configPath, "utf8")
+  let config
+  try {
+    config = JSON.parse(original)
+  } catch {
+    throw new DiscoveryToggleError("codeops/codeops.json is not valid JSON.")
+  }
+  if (!isPlainObject(config)) {
+    throw new DiscoveryToggleError("codeops/codeops.json must contain a JSON object.")
+  }
+  const discovery = nextDiscovery(config.discovery, options.enable)
+  const nextConfig = { ...config, discovery }
+  const nextText = JSON.stringify(nextConfig, null, 2) + "\n"
+  const configChanged = nextText !== original
+
+  const agentsPath = join(root, "AGENTS.md")
+  let agents = "missing"
+  let agentsText = null
+  let agentsChanged = false
+  if (existsSync(agentsPath)) {
+    const stats = lstatSync(agentsPath)
+    if (stats.isSymbolicLink()) {
+      agents = "symlink"
+    } else if (!stats.isFile()) {
+      agents = "not-a-file"
+    } else {
+      const result = updateAgents(readFileSync(agentsPath, "utf8"), options.enable)
+      agents = result.status
+      agentsChanged = result.changed
+      agentsText = result.text
+    }
+  }
+
+  if (!dryRun) {
+    if (configChanged) writeFileSync(configPath, nextText)
+    if (agentsChanged && agentsText !== null) writeFileSync(agentsPath, agentsText)
+  }
+
+  return {
+    configPath,
+    discovery,
+    changed: configChanged,
+    agents,
+    dryRun,
+  }
+}
+
+/** Print command usage. */
+function printUsage() {
+  console.log(`Toggle Discovery in an existing CodeOps project.
+
+Usage:
+  node scripts/discovery-toggle.mjs --root <repo> --enable-discovery [--dry-run]
+  node scripts/discovery-toggle.mjs --root <repo> --disable-discovery [--dry-run]
+
+Options:
+  --root <dir>          Repository root (defaults to the current directory)
+  --enable-discovery    Set discovery.enabled to true
+  --disable-discovery   Set discovery.enabled to false
+  --dry-run             Show the result without writing files
+  -h, --help            Show this help
+`)
+}
+
+/** Run the command line. */
+function main() {
+  const args = process.argv.slice(2)
+  if (args.includes("--help") || args.includes("-h")) {
+    printUsage()
+    return
+  }
+  const rootIndex = args.indexOf("--root")
+  const root = rootIndex >= 0 ? args[rootIndex + 1] : process.cwd()
+  if (root === undefined) {
+    throw new DiscoveryToggleError("--root requires a directory.")
+  }
+  const enable = args.includes("--enable-discovery")
+  const disable = args.includes("--disable-discovery")
+  if (enable === disable) {
+    throw new DiscoveryToggleError("Use exactly one of --enable-discovery or --disable-discovery.")
+  }
+  const result = toggleDiscovery({
+    root,
+    enable,
+    dryRun: args.includes("--dry-run"),
+  })
+  const action = enable ? "enabled" : "disabled"
+  console.log(
+    `${result.dryRun ? "[dry-run] " : ""}Discovery ${action} in ${result.configPath} ` +
+      `(chatMaxQuestions: ${result.discovery.chatMaxQuestions ?? "default 3"}).`,
+  )
+  console.log(`AGENTS.md: ${result.agents}.`)
+  if (result.dryRun && result.changed) {
+    console.log("No files were written.")
+  }
+}
+
+const invokedDirectly =
+  process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+
+if (invokedDirectly) {
+  try {
+    main()
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exitCode = 1
+  }
+}

package/skills/analyze-project/SKILL.md

@@ -28,7 +28,7 @@ description: Analyze the current repository and create or refresh concise CodeOp
 
 ## Discovery switch
 
-`analyze-project` accepts `--with-discovery` and `--without-discovery`; passing both flags is a usage error. Both flags validate `codeops/codeops.json` against `schemas/codeops-config.schema.json` before changing anything: an invalid file stops the run with its schema errors and writes nothing (never discard malformed quality, routing, or metrics policy). Refuse to write when `codeops/` or `codeops/codeops.json` is a symlink or not a regular file; never write through a link.
+`analyze-project` accepts `--with-discovery` and `--without-discovery`; passing both flags is a usage error. Existing projects can also use `setup-codeops --enable-discovery` / `--disable-discovery` for the config-only toggle. Both flags validate `codeops/codeops.json` against `schemas/codeops-config.schema.json` before changing anything: an invalid file stops the run with its schema errors and writes nothing (never discard malformed quality, routing, or metrics policy). Refuse to write when `codeops/` or `codeops/codeops.json` is a symlink or not a regular file; never write through a link.
 
 - `--with-discovery`: set `discovery.enabled: true`, keeping every other key. When no file exists, create the minimal AR-35 file with the layout resolved from `_shared/layout-convention.md` (`nested` → `codeops`, `flat` → `.`):
   ```json

package/skills/setup-codeops/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: setup-codeops
 description: >-
-  Sets up or upgrades CodeOps in the current git repo. It scaffolds a fresh nested codeops/ layout, auto-migrates a flat requirements/ + plans/ layout, and detects obsolete traceability.json workflow-state graphs in an existing nested project. Use when the user says "setup-codeops", "/setup-codeops", "set up codeops", "initialize codeops", "upgrade existing codeops", "migrate to the nested layout", or "scaffold the codeops structure". Supports --dry-run and unattended --yes. Every migration previews deterministically, refuses unsafe or ambiguous apply, requires clean Git state for writes, and is idempotent. setup-codeops is the SOLE writer of the layout marker.
+  Sets up or upgrades CodeOps in the current git repo. It scaffolds a fresh nested codeops/ layout, auto-migrates a flat requirements/ + plans/ layout, and detects obsolete traceability.json workflow-state graphs in an existing nested project. Use when the user says "setup-codeops", "/setup-codeops", "set up codeops", "initialize codeops", "upgrade existing codeops", "migrate to the nested layout", or "scaffold the codeops structure". Supports --dry-run, unattended --yes, and --enable-discovery/--disable-discovery for existing projects. Every migration previews deterministically, refuses unsafe or ambiguous apply, requires clean Git state for writes, and is idempotent. setup-codeops is the SOLE writer of the layout marker.
 ---
 
 # CodeOps Layout Setup (`setup-codeops`)
@@ -21,8 +21,9 @@ it is the single source of truth for the layout. Do not re-encode paths here.
 - This skill sets up the *structure*. It never authors requirements, plans, or roadmaps — that is
   `make-requirements` / `make-plan` / `roadmap`, which then resolve paths via the convention doc.
 - A fresh scaffold enables Discovery by default (`discovery.enabled: true`,
-  `chatMaxQuestions: 3`). Existing projects keep their current setting; enable it with
-  `analyze-project --with-discovery` or by adding the setting manually.
+  `chatMaxQuestions: 3`). Existing projects can toggle it with
+  `setup-codeops --enable-discovery` / `--disable-discovery`; `analyze-project --with-discovery`
+  remains available for the same config change with guidance refresh.
 
 ## Dispatch — detect repo state, then branch
 
@@ -59,6 +60,31 @@ fresh scaffold should live in version control) and suggest `git init` first.
 | *(none)* | Interactive: scaffold creates the skeleton; either migration previews then asks for one confirmation before applying. |
 | `--dry-run` | Preview only — compute and show what would happen; change **nothing**. |
 | `--yes` | Apply an unblocked migration without confirmation, then verify it. Safety refusals still apply. |
+| `--enable-discovery` | Enable Discovery in an existing project without re-scaffolding. Preserves every other config key. |
+| `--disable-discovery` | Disable Discovery, keeping `chatMaxQuestions` and every other config key. |
+
+`--enable-discovery` and `--disable-discovery` are mutually exclusive. Validate that before the
+layout branch so a usage error never changes the repository.
+
+## Discovery toggle
+
+After the layout branch (no-op, migration, or fresh scaffold), apply exactly one discovery flag
+when present:
+
+```bash
+node "${CODEOPS_PLUGIN_ROOT}/scripts/discovery-toggle.mjs" --root . --enable-discovery
+node "${CODEOPS_PLUGIN_ROOT}/scripts/discovery-toggle.mjs" --root . --disable-discovery
+```
+
+Add `--dry-run` to preview. The script validates the JSON, refuses symlinked `codeops/` or
+`codeops/codeops.json`, preserves unrelated policy, and adds or removes the managed line
+`- Discovery: enabled — question rounds open in the local Discovery page` when the
+`CODEOPS-PROJECT` block exists. If `AGENTS.md` is absent or has no managed block, the config still
+changes; report that guidance should be refreshed with `analyze-project`.
+
+A fresh scaffold starts enabled. Passing `--disable-discovery` during scaffold turns it off; passing
+`--enable-discovery` is idempotent. Without either flag, an existing project keeps its current
+setting and a fresh scaffold stays enabled.
 
 ## Migration engines (delegation — do not re-implement)
 
@@ -86,6 +112,7 @@ deletion, and idempotency.
 
 - [scaffold.md](scaffold.md) — the minimal fresh-repo skeleton.
 - [migration.md](migration.md) — flat-layout and legacy workflow-state migration UX.
+- `scripts/discovery-toggle.mjs` — deterministic config and managed-line toggle.
 - [_shared/layout-convention.md](../../_shared/layout-convention.md) — the layout/path/ID/marker source of truth.
 
 ## Grounded Options & Recommendations