chore: release v0.3.1

OpenCode's argument token is $ARGUMENTS, not $ARGUMENTS$. With the
extra dollar sign, OpenCode did not substitute the token, so the LLM
ended up writing the literal $ARGUMENTS$ line into the memory file
when no arguments were passed.

CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.3.1
+
+- Fix the OpenCode `$ARGUMENTS` token in the `plugin-compaction-init` template so it is properly substituted instead of being written into the memory file.
+
+## 0.3.0
+
+- Auto-register a `/plugin-compaction-init` slash command that scaffolds the compaction memory file with `## Keep` and `## Discard` sections of classification rules. User-supplied arguments are appended to extend the defaults.
+
+## 0.2.4
+
+- Normalize npm package repository metadata.
+
+## 0.2.3
+
+- Always ask the model to report whether custom compaction instructions were applied.
+
+## 0.2.2
+
+- Add explicit markers for applied and skipped custom compaction instructions.
+
+## 0.2.1
+
+- Add the server entrypoint expected by OpenCode's npm plugin loader.
+
 ## 0.1.2
 
 - Skip compaction prompt changes when no prompt or memory file is provided.

README.md

@@ -1,16 +1,22 @@
 # opencode-plugin-compaction-prompt
 
-Customize OpenCode's compaction prompt to guide which context carries forward, which details are omitted, and what the next session should retain.
+**Compact fearlessly with priority-aware compaction.**
+
+When you work across multiple features, OpenCode's default compaction doesn't know how to distinguish active work from older discussions, so it gives them equal priority. This can make important current details easy to lose.
+
+Customize OpenCode's compaction prompt for priority-aware compaction, deciding which messages are prioritized or discarded in the next session. Specify which discussions to discard and which decisions, files, and snippets to prioritize in the summary.
 
 [GitHub](https://github.com/bendtherules/opencode-plugin-compaction-prompt) · [npm](https://www.npmjs.com/package/opencode-plugin-compaction-prompt)
 
 ## Install
 
 ```bash
-opencode plugin opencode-plugin-compaction-prompt
+opencode plugin -g opencode-plugin-compaction-prompt
 ```
 
-Or add it to `opencode.json` manually:
+This installs the plugin in your global OpenCode configuration. To install it for one project only, omit `-g`.
+
+You can also add it manually to your global `opencode.jsonc`:
 
 ```json
 {
@@ -21,7 +27,7 @@ Or add it to `opencode.json` manually:
       {
         "memoryFile": ".opencode/compaction.md",
         "mode": "append",
-        "completionMarker": "Custom compaction request honored."
+        "completionMarker": "opencode-plugin-compaction-prompt: Custom compaction done."
       }
     ]
   ]
@@ -30,17 +36,24 @@ Or add it to `opencode.json` manually:
 
 Create `.opencode/compaction.md` in the project when you have project-specific context to preserve. The file is optional.
 
+### /plugin-compaction-init <instructions>
+
+- Writes the memory file at the configured `memoryFile` path with a top instruction line and `## Keep` and `## Discard` sections containing classification rules for which messages to preserve or drop.
+- **Recommended**: pass user instructions to extend the default rules with concrete topics — specific areas of discussion you want kept or dropped.
+
 ## Options
 
-| Option             | Default                              | Description                                                                                                |
+| Option             | Default                                                      | Description                                                                                                |
-| ------------------ | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| ------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
-| `memoryFile`       | `.opencode/compaction.md`            | File resolved relative to the active worktree.                                                             |
+| `memoryFile`       | `.opencode/compaction.md`                                    | File resolved relative to the active worktree.                                                             |
-| `mode`             | `append`                             | Append instructions to OpenCode's default prompt, or use `replace` to provide a complete prompt.           |
+| `mode`             | `append`                                                     | Append instructions to OpenCode's default prompt, or use `replace` to provide a complete prompt.           |
-| `prompt`           | "" (empty)                           | Additional instructions used together with `memoryFile`; both are included in the compaction instructions. |
+| `prompt`           | "" (empty)                                                   | Additional instructions used together with `memoryFile`; both are included in the compaction instructions. |
-| `completionMarker` | `Custom compaction request honored.` | Exact text the model is asked to append at the end of the summary.                                         |
+| `completionMarker` | `opencode-plugin-compaction-prompt: Custom compaction done.` | Exact text the model is asked to append at the end of the summary.                                         |
 
 Append mode is the recommended default because it preserves OpenCode's built-in compaction behavior. Replace mode is available when the complete prompt needs to be controlled by this plugin.
 
+When neither a prompt nor a memory file is available, the plugin asks the model to echo `opencode-plugin-compaction-prompt: No custom compaction applied.` instead.
+
 ## Development
 
 ```bash
@@ -55,7 +68,11 @@ The npm package exposes the compiled entrypoint at `dist/index.js` and TypeScrip
 
 ## Publishing
 
-Before publishing a release:
+### Update the changelog
+
+Add the changes for the new version to `CHANGELOG.md`.
+
+### Verify the release
 
 ```bash
 bun run format:check
@@ -63,14 +80,19 @@ bun test
 bun run typecheck
 bun run build
 bun run pack:check
+```
+
+### Publish the release
+
+```bash
+npm version minor -m "chore: release v%s"
+git push origin main --follow-tags
 VERSION="$(node -p "require('./package.json').version")"
-git tag "v$VERSION"
-git push origin "v$VERSION"
 gh release create "v$VERSION" --generate-notes
 npm publish
 ```
 
-Update the version in `package.json`, changelog, and the tag before each release. `npm publish` rebuilds `dist/` automatically.
+Use `npm version patch` or `npm version major` when appropriate. `npm publish` rebuilds `dist/` automatically.
 
 ## Compatibility
 

examples/opencode.json

@@ -7,7 +7,7 @@
         "memoryFile": ".opencode/compaction.md",
         "mode": "append",
         "prompt": "<Example prompt for compaction>",
-        "completionMarker": "Custom compaction request honored."
+        "completionMarker": "opencode-plugin-compaction-prompt: Custom compaction done."
       }
     ]
   ]

package.json

@@ -1,11 +1,13 @@
 {
   "name": "opencode-plugin-compaction-prompt",
-  "version": "0.1.2",
+  "version": "0.3.1",
   "description": "Customize OpenCode's compaction prompt to preserve important context and omit unnecessary details.",
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "repository": {
     "type": "git",
-    "url": "https://github.com/bendtherules/opencode-plugin-compaction-prompt.git"
+    "url": "git+https://github.com/bendtherules/opencode-plugin-compaction-prompt.git"
   },
   "homepage": "https://github.com/bendtherules/opencode-plugin-compaction-prompt#readme",
   "bugs": {
@@ -15,6 +17,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
   "files": [

src/index.ts

@@ -13,7 +13,42 @@ export type CompactionOptions = PluginOptions & {
 
 const defaultMemoryFile = ".opencode/compaction.md";
 const defaultPrompt = "";
-const defaultCompletionMarker = "Custom compaction request honored.";
+const defaultCompletionMarker =
+  "opencode-plugin-compaction-prompt: Custom compaction done.";
+const skippedCompactionMarker =
+  "opencode-plugin-compaction-prompt: No custom compaction applied.";
+const initCommandName = "plugin-compaction-init";
+
+/**
+ * Builds the prompt the auto-registered `/plugin-compaction-init` slash
+ * command sends to the model. `$ARGUMENTS` is left unsubstituted so
+ * OpenCode substitutes it at invocation time.
+ *
+ * @param memoryFile Literal path to the memory file, inserted verbatim.
+ * @returns The full command-body template.
+ */
+export function buildInitCommandTemplate(memoryFile: string): string {
+  return `You are creating the file \`${memoryFile}\` (relative to the current project root). It is a meta-classification of which messages to preserve and which to discard during session compaction, not a summary of details.
+
+Follow this format:
+
+\`\`\`
+Keep all details related to the keep topics below, and discard everything related to the discard topics below.
+
+## Keep
+
+## Discard
+\`\`\`
+
+\`## Keep\` contains one bullet per active in-progress topic. Each bullet is a **classification rule** describing how to recognize messages that discuss that topic, including its requirements, design decisions, dependency information, and ongoing discussions needed to continue the work.
+
+\`## Discard\` contains one bullet per older or already-finished topic. Each bullet is a **classification rule** describing how to recognize messages to drop — features/tasks already shipped, abandoned, or otherwise not relevant to the next session, including any debug loops or repeated fix attempts that have already concluded. Add a final catch-all bullet:
+
+- Any other older discussions not mentioned above.
+
+$ARGUMENTS
+`;
+}
 
 function asString(value: unknown): string | undefined {
   if (typeof value !== "string") {
@@ -28,11 +63,7 @@ function buildInstructions(
   prompt: string,
   completionMarker: string,
   memory: string,
-): string | undefined {
+): string {
-  if (!prompt && !memory) {
-    return undefined;
-  }
-
   const sections = [
     "## User Compaction Instructions",
     `These instructions take precedence over previous instructions if there is conflict. At the very end of the summary, echo exactly: **${completionMarker}**`,
@@ -107,16 +138,32 @@ export const CompactionPromptPlugin: Plugin = async (
   };
 
   return {
+    config: async (cfg): Promise<void> => {
+      if (cfg.command?.[initCommandName]) {
+        await context.client.app.log({
+          body: {
+            level: "warn",
+            message: `Skipping registration of "${initCommandName}": already defined in config.`,
+            service: "opencode-plugin-compaction-prompt",
+          },
+        });
+        return;
+      }
+
+      cfg.command ??= {};
+      cfg.command[initCommandName] = {
+        description: `Create ${memoryFile} [compaction file]`,
+        template: buildInitCommandTemplate(memoryFile),
+      };
+    },
     "experimental.session.compacting": async (
       _input,
       output,
     ): Promise<void> => {
       const memory = await readMemory(memoryPath, logError);
-      const instructions = buildInstructions(prompt, completionMarker, memory);
+      const marker =
-
+        prompt || memory ? completionMarker : skippedCompactionMarker;
-      if (!instructions) {
+      const instructions = buildInstructions(prompt, marker, memory);
-        return;
-      }
 
       if (mode === "replace") {
         output.prompt = instructions;

test/index.test.ts

@@ -2,7 +2,10 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { CompactionPromptPlugin } from "../src/index.js";
+import {
+  buildInitCommandTemplate,
+  CompactionPromptPlugin,
+} from "../src/index.js";
 
 const temporaryDirectories: string[] = [];
 
@@ -55,7 +58,9 @@ describe("CompactionPromptPlugin", () => {
     );
 
     expect(output.context[0]).toContain("Keep the active hypothesis.");
-    expect(output.context[0]).toContain("Custom compaction request honored.");
+    expect(output.context[0]).toContain(
+      "opencode-plugin-compaction-prompt: Custom compaction done.",
+    );
   });
 
   test("combines custom instructions with a configured memory file", async () => {
@@ -114,10 +119,12 @@ describe("CompactionPromptPlugin", () => {
     );
 
     expect(context.logs).toHaveLength(0);
-    expect(output.context).toHaveLength(0);
+    expect(output.context[0]).toContain(
+      "echo exactly: **opencode-plugin-compaction-prompt: No custom compaction applied.**",
+    );
   });
 
-  test("does not modify compaction when no instructions are provided", async () => {
+  test("adds a skipped marker when no instructions are provided", async () => {
     const context = await createContext();
     const hooks = await CompactionPromptPlugin(context as never);
     const output: { context: string[]; prompt?: string } = {
@@ -129,7 +136,10 @@ describe("CompactionPromptPlugin", () => {
       output,
     );
 
-    expect(output.context).toEqual(["Existing context"]);
+    expect(output.context[0]).toBe("Existing context");
+    expect(output.context[1]).toContain(
+      "echo exactly: **opencode-plugin-compaction-prompt: No custom compaction applied.**",
+    );
     expect(output.prompt).toBeUndefined();
   });
 
@@ -147,6 +157,110 @@ describe("CompactionPromptPlugin", () => {
     );
 
     expect(context.logs).toHaveLength(1);
-    expect(output.context).toHaveLength(0);
+    expect(output.context[0]).toContain(
+      "echo exactly: **opencode-plugin-compaction-prompt: No custom compaction applied.**",
+    );
+  });
+});
+
+describe("buildInitCommandTemplate", () => {
+  test("substitutes the configured memory file path verbatim", () => {
+    const template = buildInitCommandTemplate("docs/agent-memory.md");
+
+    expect(template).toContain("`docs/agent-memory.md`");
+    expect(template).not.toContain(".opencode/compaction.md");
+  });
+
+  test("contains the file skeleton and both section headings", () => {
+    const template = buildInitCommandTemplate(".opencode/compaction.md");
+
+    expect(template).toContain("```\nKeep all details related to");
+    expect(template).toContain("## Keep\n");
+    expect(template).toContain("## Discard\n");
+  });
+
+  test("leaves $ARGUMENTS unsubstituted for OpenCode to fill in", () => {
+    const template = buildInitCommandTemplate(".opencode/compaction.md");
+
+    expect(template.trimEnd().endsWith("$ARGUMENTS")).toBe(true);
+  });
+});
+
+describe("CompactionPromptPlugin config hook", () => {
+  test("registers the plugin-compaction-init command by default", async () => {
+    const context = await createContext();
+    const hooks = await CompactionPromptPlugin(context as never);
+    const cfg: {
+      command?: Record<string, { description: string; template: string }>;
+    } = {};
+
+    await hooks.config?.(cfg as never);
+
+    expect(cfg.command?.["plugin-compaction-init"]).toBeDefined();
+    expect(
+      cfg.command?.["plugin-compaction-init"].description.length,
+    ).toBeGreaterThan(0);
+    expect(cfg.command?.["plugin-compaction-init"].template).toContain(
+      ".opencode/compaction.md",
+    );
+    expect(cfg.command?.["plugin-compaction-init"].template).toContain(
+      "## Keep",
+    );
+    expect(cfg.command?.["plugin-compaction-init"].template).toContain(
+      "## Discard",
+    );
+    expect(cfg.command?.["plugin-compaction-init"].template).toContain(
+      "$ARGUMENTS",
+    );
+    expect(context.logs).toHaveLength(0);
+  });
+
+  test("uses the configured memoryFile in the registered template", async () => {
+    const context = await createContext();
+    const hooks = await CompactionPromptPlugin(context as never, {
+      memoryFile: "notes/agent.md",
+    });
+    const cfg: {
+      command?: Record<string, { description: string; template: string }>;
+    } = {};
+
+    await hooks.config?.(cfg as never);
+
+    expect(cfg.command?.["plugin-compaction-init"].template).toContain(
+      "`notes/agent.md`",
+    );
+    expect(cfg.command?.["plugin-compaction-init"].template).not.toContain(
+      ".opencode/compaction.md",
+    );
+  });
+
+  test("skips registration and logs a warning when the command is already defined", async () => {
+    const context = await createContext();
+    const hooks = await CompactionPromptPlugin(context as never);
+    const userTemplate = "user-provided template body";
+    const cfg: {
+      command?: Record<string, { description: string; template: string }>;
+    } = {
+      command: {
+        "plugin-compaction-init": {
+          description: "user description",
+          template: userTemplate,
+        },
+      },
+    };
+
+    await hooks.config?.(cfg as never);
+
+    expect(cfg.command?.["plugin-compaction-init"].template).toBe(userTemplate);
+    expect(context.logs).toHaveLength(1);
+    expect(context.logs[0]).toMatchObject({
+      body: {
+        level: "warn",
+        service: "opencode-plugin-compaction-prompt",
+      },
+    });
+    expect(
+      (context.logs[0] as { body?: { message?: string } }).body?.message,
+    ).toContain("plugin-compaction-init");
   });
 });