@cristochang/spec-integration 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenCode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @cristochang/spec-integration
+
+> Passive workflow reminders when working with OpenCode specs
+
+## Compatibility Warning
+
+**This plugin is version-locked to opencode.**
+
+It relies on internal Spec capabilities provided at runtime by opencode core.
+Do not expect compatibility across major opencode versions.
+
+Current compatibility: opencode >=0.9.0 <0.10.0
+
+## What it does
+
+- Shows you which spec is currently active for your session
+- Warns you when making file edits while a spec is still in "pending" status
+- Reminds you of the spec's scope and success criteria when making changes
+
+## What it doesn't do
+
+- **Does not block** any operations (passive mode only)
+- **Does not modify** tool arguments or behavior
+- **Does not persist** any data to disk
+- **Does not create** files or directories
+
+## Installation
+
+```bash
+npm install @cristochang/spec-integration
+```
+
+Add to your `.opencode/config.json`:
+
+```json
+{
+  "plugin": [
+    "@cristochang/spec-integration@latest"
+  ]
+}
+```
+
+## Configuration
+
+Add an `experimental.specIntegration` section to your `.opencode/config.json`:
+
+```json
+{
+  "experimental": {
+    "specIntegration": {
+      "enabled": true,
+      "mode": "passive",
+      "warningCooldown": 60000
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable or disable the plugin |
+| `mode` | `"passive"` | `"passive"` | Warning mode (only "passive" is supported) |
+| `warningCooldown` | number | `60000` | Milliseconds between warnings for the same session |
+
+## How it works
+
+The plugin monitors the following tools and shows reminders when an active spec exists:
+
+- `edit` - Editing existing files
+- `write` - Creating new files
+- `multiedit` - Batch edits
+- `patch` - Patch operations
+- `bash` - Shell commands
+
+### Failure Strategy
+
+If the Spec capability is not available (e.g., running on an incompatible opencode version), the plugin **silently disables itself** and will not interfere with your workflow.
+
+## When to use this plugin
+
+**Use it when:**
+- You want to maintain awareness of your active spec while coding
+- You're working in a team that uses specs for task tracking
+- You want gentle reminders about spec boundaries without enforced constraints
+
+**Don't use it when:**
+- You prefer complete autonomy without any workflow suggestions
+- You're doing exploratory coding that doesn't align with spec-based workflows
+- You find the reminders distracting (just set `enabled: false`)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @opencode-ai/spec-integration
+ *
+ * Spec workflow integration plugin for OpenCode
+ *
+ * This plugin provides passive reminders when working with code changes
+ * while a spec is active in your session.
+ *
+ * @packageDocumentation
+ */
+import type { Hooks, PluginInput } from "@opencode-ai/plugin";
+/**
+ * Spec Integration Plugin for OpenCode
+ *
+ * A passive workflow integration that provides context-aware reminders
+ * when working with code changes under active specs.
+ *
+ * This plugin uses the Spec capability provided by opencode core at runtime.
+ * If the Spec capability is not available, the plugin silently disables itself.
+ */
+export declare function SpecIntegrationPlugin(input: PluginInput): Promise<Hooks>;
+export default SpecIntegrationPlugin;

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAY,MAAM,qBAAqB,CAAA;AAyEvE;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,CA6D9E;AAED,eAAe,qBAAqB,CAAA"}

package/dist/index.js

@@ -0,0 +1,106 @@
+// src/index.ts
+var MONITORED_TOOLS = [
+  "edit",
+  "write",
+  "multiedit",
+  "patch",
+  "bash"
+];
+var callWarnings = /* @__PURE__ */ new Map();
+var warningCooldowns = /* @__PURE__ */ new Map();
+var DEFAULT_CONFIG = {
+  enabled: true,
+  mode: "passive",
+  warningCooldown: 6e4
+};
+var pluginConfig = { ...DEFAULT_CONFIG };
+function shouldShowWarning(sessionID) {
+  const lastWarning = warningCooldowns.get(sessionID) ?? 0;
+  const now = Date.now();
+  if (now - lastWarning < pluginConfig.warningCooldown) {
+    return false;
+  }
+  return true;
+}
+function markNeedsWarning(callID, specID, message) {
+  callWarnings.set(callID, { specID, message });
+}
+function getWarning(callID) {
+  const warning = callWarnings.get(callID);
+  callWarnings.delete(callID);
+  return warning;
+}
+function generateWarningMessage(spec, tool) {
+  const objective = spec.objective;
+  const inclusions = spec.scope.inclusions.join(", ");
+  switch (spec.status) {
+    case "pending":
+      return `\u26A0\uFE0F Working on ${tool} while spec is in "pending" status. Spec: "${objective}". Consider approving the spec with spec_approve before making changes. Use spec_get to view full details.`;
+    case "approved":
+      return `\u2139\uFE0F Working on spec: "${objective}". In-scope: ${inclusions}. Use spec_get to review full scope and success criteria.`;
+    case "implemented":
+      return `\u2139\uFE0F Working on ${tool} for a spec already marked as "implemented". Spec: "${objective}". Consider if new changes are still within the original scope.`;
+    case "cancelled":
+      return `\u26A0\uFE0F Working on ${tool} while spec is "cancelled". Spec: "${objective}". Consider creating a new spec for this work.`;
+    default:
+      return `\u2139\uFE0F Active spec: "${objective}"`;
+  }
+}
+async function SpecIntegrationPlugin(input) {
+  const specCap = input.capabilities?.spec;
+  if (!specCap) {
+    pluginConfig.enabled = false;
+  }
+  return {
+    config: async (config) => {
+      const integrationConfig = config.experimental?.specIntegration;
+      if (integrationConfig) {
+        pluginConfig = {
+          enabled: integrationConfig.enabled ?? DEFAULT_CONFIG.enabled,
+          mode: integrationConfig.mode ?? DEFAULT_CONFIG.mode,
+          warningCooldown: integrationConfig.warningCooldown ?? DEFAULT_CONFIG.warningCooldown
+        };
+      } else {
+        pluginConfig = { ...DEFAULT_CONFIG };
+      }
+    },
+    "tool.execute.before": async ({ tool, sessionID, callID }, _output) => {
+      if (!pluginConfig.enabled || !specCap) {
+        return;
+      }
+      const spec = await specCap.getActive(sessionID);
+      if (!spec) {
+        return;
+      }
+      if (tool.startsWith("spec_")) {
+        return;
+      }
+      if (MONITORED_TOOLS.includes(tool)) {
+        if (shouldShowWarning(sessionID)) {
+          const message = generateWarningMessage(spec, tool);
+          markNeedsWarning(callID, spec.id, message);
+          warningCooldowns.set(sessionID, Date.now());
+        }
+      }
+    },
+    "tool.execute.after": async ({ tool, sessionID, callID }, output) => {
+      if (!pluginConfig.enabled) {
+        return;
+      }
+      const warning = getWarning(callID);
+      if (warning) {
+        if (output.metadata) {
+          output.metadata._specWarning = {
+            specID: warning.specID,
+            message: warning.message
+          };
+        }
+      }
+    }
+  };
+}
+var index_default = SpecIntegrationPlugin;
+export {
+  SpecIntegrationPlugin,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@cristochang/spec-integration",
+  "version": "0.1.0",
+  "description": "Spec workflow integration plugin for OpenCode - passive reminders when working with specs",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npm run build:js && npm run build:dts",
+    "build:js": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --external:@opencode-ai/plugin",
+    "build:dts": "tsc --emitDeclarationOnly",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "spec",
+    "workflow",
+    "integration",
+    "passive",
+    "reminder"
+  ],
+  "author": "OpenCode",
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=0.9.0 <0.10.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "workspace:*",
+    "@types/node": "22.13.9",
+    "esbuild": "0.27.2",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}