opencode-goal-mode 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## v0.3.3
+
+- Release notes: the GitHub Release body is now generated from the matching
+  `CHANGELOG.md` section (`scripts/release-notes.mjs`), so releases always ship
+  real notes instead of an empty auto-summary.
+- Richer repository: README badges (npm version/downloads, CI, release, license,
+  node), a quick-links bar, and a terminal-style sidebar demo
+  (`docs/sidebar-demo.svg`); a descriptive repo summary and topics; and
+  community health files (CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, issue and PR
+  templates).
+- Stronger npm discoverability: expanded `keywords` (opencode-plugin,
+  opencode-tui-plugin, guardrails, review-gates, completion-enforcement, …).
+
+## 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

@@ -1,10 +1,25 @@
 # OpenCode Goal Mode
 
+[![npm version](https://img.shields.io/npm/v/opencode-goal-mode?color=2da44e&label=npm)](https://www.npmjs.com/package/opencode-goal-mode)
+[![npm downloads](https://img.shields.io/npm/dm/opencode-goal-mode?color=2da44e)](https://www.npmjs.com/package/opencode-goal-mode)
+[![CI](https://github.com/devinoldenburg/opencode-goal-mode/actions/workflows/ci.yml/badge.svg)](https://github.com/devinoldenburg/opencode-goal-mode/actions/workflows/ci.yml)
+[![Release](https://github.com/devinoldenburg/opencode-goal-mode/actions/workflows/publish.yml/badge.svg)](https://github.com/devinoldenburg/opencode-goal-mode/actions/workflows/publish.yml)
+[![license](https://img.shields.io/npm/l/opencode-goal-mode?color=2da44e)](LICENSE)
+[![node](https://img.shields.io/node/v/opencode-goal-mode?color=2da44e)](package.json)
+
 Strict Goal Mode for OpenCode: a primary `goal` agent, a matrix of specialized
 review subagents, slash commands, and a `goal-guard` plugin that enforces review
 discipline, blocks destructive shell commands, and preserves goal state across
 compaction **and** restarts.
 
+```bash
+npm install -g opencode-goal-mode && opencode-goal-mode-install --global
+```
+
+![OpenCode Goal Mode sidebar banner](docs/sidebar-demo.svg)
+
+**[Install](#install) · [Why it's different](#why-its-different) · [Benchmarks](#benchmarks-honest-edition) · [TUI integration](#tui-integration) · [Configuration](#configuration) · [Releasing](#releasing) · [Architecture](ARCHITECTURE.md)**
+
 See [ARCHITECTURE.md](ARCHITECTURE.md) for the design and [research/](research/)
 for the platform reference, comparison, and threat model.
 
@@ -90,7 +105,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 +130,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 +160,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 +286,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/docs/sidebar-demo.svg

@@ -0,0 +1,54 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="760" height="280" viewBox="0 0 760 280" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" role="img" aria-label="OpenCode Goal Mode sidebar banner: the active goal in yellow with a gate-status line, and a grey No goal state.">
+  <defs>
+    <style>
+      .win { fill: #0d1117; stroke: #30363d; stroke-width: 1; }
+      .bar { fill: #161b22; }
+      .dot { stroke-width: 0; }
+      .title { fill: #8b949e; font-size: 12px; }
+      .label { fill: #8b949e; font-size: 12px; }
+      .goal { fill: #FFD700; font-size: 13px; }
+      .goalb { fill: #FFD700; font-size: 13px; font-weight: 700; }
+      .status { fill: #FFD700; font-size: 12px; }
+      .muted { fill: #808080; font-size: 13px; }
+      .chat { fill: #c9d1d9; font-size: 12px; }
+      .dim { fill: #6e7681; font-size: 12px; }
+      .ok { fill: #2da44e; font-size: 12px; }
+      .div { stroke: #30363d; stroke-width: 1; }
+    </style>
+  </defs>
+
+  <!-- window -->
+  <rect class="win" x="1" y="1" width="758" height="278" rx="8"/>
+  <rect class="bar" x="1" y="1" width="758" height="30" rx="8"/>
+  <rect class="bar" x="1" y="20" width="758" height="11"/>
+  <circle class="dot" cx="20" cy="16" r="5" fill="#ff5f56"/>
+  <circle class="dot" cx="38" cy="16" r="5" fill="#ffbd2e"/>
+  <circle class="dot" cx="56" cy="16" r="5" fill="#27c93f"/>
+  <text class="title" x="86" y="20">opencode — goal mode</text>
+
+  <!-- vertical divider between chat and sidebar -->
+  <line class="div" x1="470" y1="31" x2="470" y2="279"/>
+
+  <!-- chat pane (left) -->
+  <text class="dim" x="20" y="58">▌ goal</text>
+  <text class="chat" x="20" y="82">▸ Goal Contract recorded (4 acceptance criteria)</text>
+  <text class="chat" x="20" y="104">▸ implementing… running verification</text>
+  <text class="ok"   x="20" y="126">✓ Security Reviewer → PASS</text>
+  <text class="ok"   x="20" y="148">✓ Verifier → PASS</text>
+  <text class="dim"  x="20" y="170">▸ Diff Reviewer running…</text>
+
+  <!-- sidebar pane (right) -->
+  <text class="label" x="490" y="58">SESSION</text>
+  <line class="div" x1="490" y1="68" x2="740" y2="68"/>
+
+  <!-- goal banner (active) -->
+  <text x="490" y="98"><tspan class="goal">◆ </tspan><tspan class="goalb">GOAL</tspan><tspan class="goal">  Ship the OAuth</tspan></text>
+  <text class="goal"   x="490" y="116">refactor</text>
+  <text class="status" x="490" y="138">3/5 gates · dirty</text>
+
+  <line class="div" x1="490" y1="170" x2="740" y2="170"/>
+
+  <!-- no-goal state -->
+  <text class="label" x="490" y="196">when no goal is set</text>
+  <text class="muted" x="490" y="222">No goal</text>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-mode",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Strict Goal Mode agents, commands, and guard plugin for OpenCode.",
   "type": "module",
   "engines": {
@@ -48,9 +48,24 @@
   },
   "keywords": [
     "opencode",
+    "opencode-plugin",
+    "opencode-tui-plugin",
     "goal-mode",
     "agents",
-    "review",
+    "ai-agents",
+    "agentic",
+    "subagents",
+    "code-review",
+    "review-gates",
+    "guardrails",
+    "completion-enforcement",
+    "shell-guard",
+    "destructive-command",
+    "tui",
+    "llm",
+    "claude",
+    "coding-agent",
+    "developer-tools",
     "plugin"
   ],
   "repository": {

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();