opencode-goal-mode 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v0.3.2
+
+- Only the `goal` agent is user-selectable. The structural validator now requires
+  every other agent to be `mode: subagent` (no `all`/extra `primary`), so the
+  specialist reviewers can only be invoked by the Goal agent via the task tool,
+  never picked by the user.
+- Friendlier subagent names in the TUI: review-verdict toasts now read
+  "Security Reviewer → PASS" / "API Reviewer → PASS" instead of raw hyphenated ids
+  (`prettyAgentName` drops the `goal-` prefix, de-hyphenates, keeps acronyms).
+- Release pipeline: a single `vX.Y.Z` tag push now publishes to npm AND creates
+  the matching GitHub Release (versions stay in sync). `publish:check` fails the
+  release if the tag does not match `package.json` or the version already exists.
+- README: npm-first install instructions and a documented release flow.
+
 ## v0.3.1
 
 - Sidebar: when a task is running but no goal is set, show a clean grey `No goal`

package/README.md

@@ -90,7 +90,11 @@ second) — negligible for a per-tool-call guard:
 ## What it adds
 
 - A primary `goal` agent that owns implementation but delegates research,
-  discovery, verification planning, and reviews to subagents.
+  discovery, verification planning, and reviews to subagents. **`goal` is the only
+  user-selectable agent** — every specialist (security, diff, verifier, …) is a
+  `mode: subagent` that the Goal agent invokes via the task tool; the user never
+  picks one directly. They surface with friendly names (e.g. "Security Reviewer",
+  "API Reviewer") rather than raw ids.
 - Strict review gates for prompt compliance, diff review, verification, security,
   UX, operations, data, API, performance, tests, docs, quality, and final audit.
 - Slash commands: `/goal`, `/goal-contract`, `/goal-review`,
@@ -111,8 +115,9 @@ second) — negligible for a per-tool-call guard:
     `goal_reviewer_memory`, `goal_status`, `goal_reset`.
   - **Live state injection** into the system prompt so the model always knows
     what the guard requires.
-  - **TUI toasts**: a toast on each review verdict (PASS/FAIL) and a single
-    "completion unlocked" toast the moment the last required gate clears.
+  - **TUI toasts**: a toast on each review verdict (PASS/FAIL), with the
+    reviewer's friendly name, and a single "completion unlocked" toast the moment
+    the last required gate clears.
 - An **experimental** companion TUI plugin (`plugins/goal-sidebar.js`) that shows
   the active goal as a shining-yellow banner in the sidebar with a compact gate
   status line. See [TUI integration](#tui-integration).
@@ -140,27 +145,40 @@ enforcement and writes its state to disk, and an experimental TUI plugin
   (`toastOnReview`), and blocked destructive commands / premature completions
   toast as before (`toastOnBlock`).
 
-## Install globally
+## Install
+
+### From npm (recommended)
 
 ```bash
-npm ci
-npm run validate
-npm run install:global
+npm install -g opencode-goal-mode
+opencode-goal-mode-install --global    # installs into ~/.config/opencode
 ```
 
-Restart OpenCode after installation. OpenCode loads agents, commands, and
-plugins at startup.
+Then restart OpenCode (it loads agents, commands, and plugins at startup). In the
+agent picker you will see **only the `goal` agent** — the specialist reviewers are
+subagents the Goal agent drives for you; they are never selectable by the user.
 
-## Install into one project
+Install into a single project instead of globally:
 
 ```bash
+npm install -D opencode-goal-mode
+npx opencode-goal-mode-install         # writes to ./.opencode
+```
+
+Upgrade later by re-running the same install command after `npm install -g
+opencode-goal-mode@latest`; the installer replaces only the files it owns and
+leaves your local edits alone (see [Installer options](#installer-options)).
+
+### From source
+
+```bash
+git clone https://github.com/devinoldenburg/opencode-goal-mode
+cd opencode-goal-mode
 npm ci
 npm run validate
-npm run install:local
+npm run install:global                 # or: npm run install:local
 ```
 
-This writes to `./.opencode` in the current project.
-
 ## Installer options
 
 ```bash
@@ -253,32 +271,34 @@ keeps read-only inspection from dirtying the session, preserves goal state durin
 compaction and across restarts, and blocks premature `Goal Completed` responses
 when review gates are missing or stale.
 
-## npm publishing
+## Releasing
 
-Install from npm after the first publish:
+Releases are fully automated and **version-synced**: one pushed tag publishes to
+npm *and* creates the matching GitHub Release. The pipeline lives in
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml) (Node 24).
 
 ```bash
-npm install -g opencode-goal-mode
-opencode-goal-mode-install --global
+npm version patch        # bumps package.json + package-lock.json and creates the vX.Y.Z tag
+git push --follow-tags   # pushes main + the tag → the Release workflow runs
 ```
 
-Publishing is handled by `.github/workflows/publish.yml`, which runs on Node 24
-and publishes with the `NPM_TOKEN` repository secret. The workflow validates the
-package, checks the tag matches `package.json`, verifies the version is not
-already on npm, then publishes. Manual workflow dispatch defaults to
-`npm publish --dry-run`.
+On a `vX.Y.Z` tag push the workflow:
 
-Release flow for a new version:
+1. installs and runs the full CI gate (`npm run ci` — tests, audit, structural
+   validation, `npm pack --dry-run`);
+2. runs `npm run publish:check`, which **fails if the tag does not match
+   `package.json`** or if that version already exists on npm;
+3. publishes with `npm publish --access public` using the `NPM_TOKEN` repository
+   secret;
+4. creates the GitHub Release for the tag with auto-generated notes.
 
-```bash
-npm version patch
-git push --follow-tags
-```
+So the git tag, the `package.json` version, the npm version, and the GitHub
+Release version are always identical. A manual `workflow_dispatch` is available
+and defaults to a safe `npm publish --dry-run`.
 
-For a version that is already bumped and reviewed, commit the current tree, tag
-the reviewed version (for example `v0.2.4`), push the branch and tag, then create
-the GitHub Release. Ensure `NPM_TOKEN` has npm publish rights before publishing
-the release.
+**One-time setup:** add a publish-scoped npm token as the `NPM_TOKEN` repository
+secret (`gh secret set NPM_TOKEN`). Treat that token as sensitive — never commit
+it.
 
 ## Goal Completion Contract
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-mode",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Strict Goal Mode agents, commands, and guard plugin for OpenCode.",
   "type": "module",
   "engines": {

package/plugins/goal-guard/agents.js

@@ -130,3 +130,23 @@ export const CONTEXTUAL_GATES = Object.freeze({
 
 /** The reviewer that, when it returns a verdict, closes one review cycle. */
 export const CYCLE_CLOSING_AGENT = "goal-final-auditor";
+
+/** Acronyms that should stay upper-case in display names. */
+const ACRONYMS = new Set(["api", "ux", "ui", "sql", "ops", "qa"]);
+
+/**
+ * Human-friendly display name for an agent id: drops the `goal-` namespace
+ * prefix, turns hyphens into spaces, Title-Cases words, and keeps known acronyms
+ * upper-case. e.g. "goal-security-reviewer" → "Security Reviewer",
+ * "goal-api-reviewer" → "API Reviewer", "goal-final-auditor" → "Final Auditor".
+ */
+export function prettyAgentName(id) {
+  const raw = String(id || "").trim();
+  if (!raw) return "";
+  return raw
+    .replace(/^goal-/, "")
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((w) => (ACRONYMS.has(w.toLowerCase()) ? w.toUpperCase() : w.charAt(0).toUpperCase() + w.slice(1)))
+    .join(" ");
+}

package/plugins/goal-guard.js

@@ -23,7 +23,7 @@ import { createStore, createState } from "./goal-guard/state.js";
 import { createPersistence } from "./goal-guard/persistence.js";
 import { createLogger } from "./goal-guard/logger.js";
 import { analyzeCommand, looksLikeDestructiveBash, looksLikeMutatingBash, isVerification } from "./goal-guard/shell.js";
-import { isPrimaryAgent, isReviewAgent, CYCLE_CLOSING_AGENT } from "./goal-guard/agents.js";
+import { isPrimaryAgent, isReviewAgent, CYCLE_CLOSING_AGENT, prettyAgentName } from "./goal-guard/agents.js";
 import { textOf, parseVerdict, recordVerdict } from "./goal-guard/verdicts.js";
 import { completionAllowed, missingGates, refreshStickyGates } from "./goal-guard/gates.js";
 import { evaluateCompletionClaim } from "./goal-guard/completion.js";
@@ -210,9 +210,9 @@ export function createGuard(input = {}, options = {}, overrides = {}) {
         // Surface review progress in the TUI: a toast per recorded verdict, and a
         // single celebratory toast the moment the last required gate clears.
         if (recordedAgent && recordedVerdict && config.toastOnReview) {
-          logger.toast(`Goal Guard: ${recordedAgent} → ${recordedVerdict}`, recordedVerdict === "PASS" ? "success" : "warning");
+          logger.toast(`${prettyAgentName(recordedAgent)} → ${recordedVerdict}`, recordedVerdict === "PASS" ? "success" : "warning");
           if (!wasAllowed && completionAllowed(state, config)) {
-            logger.toast("Goal Guard: all required gates passed — completion unlocked", "success");
+            logger.toast("All required gates passed — completion unlocked", "success");
           }
         }
         persist();