@dlacaille/opencode-copilot-instructions 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 ekroon (https://github.com/ekroon)
+Copyright (c) 2026 Dominic Lacaille
+
+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,58 @@
+# @dlacaille/opencode-copilot-instructions
+
+An [OpenCode](https://opencode.ai) V2 plugin that loads GitHub Copilot custom instruction files into OpenCode's context.
+
+## Installation
+
+Add the plugin to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["@dlacaille/opencode-copilot-instructions"]
+}
+```
+
+OpenCode installs the package from npm on startup.
+
+## Usage
+
+### Repository-wide instructions
+
+Create `.github/copilot-instructions.md`. Its content is added to every model request, including compaction.
+
+### Path-specific instructions
+
+Create `.github/instructions/*.instructions.md` files with an `applyTo` field:
+
+```markdown
+---
+applyTo: "**/*.ts,**/*.tsx"
+---
+
+Always use explicit return types.
+```
+
+When the `read`, `edit`, or `write` tools touch a matching file, the instructions are appended to the tool result. Each file is added once per session, and again after the session is compacted.
+
+`applyTo` accepts a comma-separated string or a YAML list of [picomatch](https://github.com/micromatch/picomatch) globs, relative to the project directory.
+
+Instructions are loaded when the plugin starts. Restart OpenCode after changing them.
+
+## Development
+
+```sh
+npm install --legacy-peer-deps
+npm test
+npm run typecheck
+```
+
+To try a local checkout, point `plugins` at its path, for example `"plugins": ["~/projects/opencode-copilot-instructions"]`.
+
+## Credits
+
+Based on [ekroon/opencode-copilot-instructions](https://github.com/ekroon/opencode-copilot-instructions) by [@ekroon](https://github.com/ekroon), ported to the OpenCode V2 plugin API.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index"

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@dlacaille/opencode-copilot-instructions",
+  "version": "0.1.0",
+  "description": "OpenCode plugin that loads GitHub Copilot custom instruction files",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "copilot",
+    "instructions"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "front-matter": "^4.0.2",
+    "picomatch": "^4.0.3"
+  },
+  "peerDependencies": {
+    "@opencode/plugin": ">=2.0.0"
+  },
+  "devDependencies": {
+    "@opencode/plugin": "^2.0.15",
+    "@types/node": "^22.0.0",
+    "@types/picomatch": "^4.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/frontmatter.ts

@@ -0,0 +1,38 @@
+import * as frontMatterModule from "front-matter"
+
+const fm = (frontMatterModule as any).default ?? frontMatterModule
+
+export interface Frontmatter {
+  applyTo?: string | string[]
+}
+
+export interface ParsedFrontmatter {
+  frontmatter: Frontmatter
+  body: string
+}
+
+export function parseFrontmatter(content: string): ParsedFrontmatter {
+  const normalized = content.replace(/\r\n/g, "\n")
+
+  if (!fm.test(normalized)) {
+    return { frontmatter: {}, body: content }
+  }
+
+  try {
+    const parsed = fm(normalized)
+    const attrs = parsed.attributes as Record<string, unknown>
+    const result: Frontmatter = {}
+
+    if (attrs.applyTo !== undefined) {
+      if (typeof attrs.applyTo === "string") {
+        result.applyTo = attrs.applyTo
+      } else if (Array.isArray(attrs.applyTo)) {
+        result.applyTo = attrs.applyTo.filter((item): item is string => typeof item === "string")
+      }
+    }
+
+    return { frontmatter: result, body: parsed.body }
+  } catch {
+    return { frontmatter: {}, body: content }
+  }
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+import * as path from "node:path"
+import { Plugin } from "@opencode/plugin"
+import { loadRepoInstructions, loadPathInstructions } from "./loader"
+import { SessionState } from "./session-state"
+
+const FILE_TOOLS = new Set(["read", "edit", "write"])
+
+function getRelativePath(directory: string, filePath: string): string {
+  const normalizedDir = directory.endsWith("/") ? directory.slice(0, -1) : directory
+  if (!path.isAbsolute(filePath)) return filePath
+  return path.relative(normalizedDir, filePath)
+}
+
+export default Plugin.define({
+  id: "copilot-instructions",
+  async setup(ctx) {
+    const directory = ctx.location.directory
+    const repoInstructions = loadRepoInstructions(directory)
+    const pathInstructions = loadPathInstructions(directory)
+
+    if (repoInstructions) {
+      console.log("[copilot-instructions] Loaded repo instructions from .github/copilot-instructions.md")
+    }
+    for (const instruction of pathInstructions) {
+      console.log(`[copilot-instructions] Loaded path instructions from ${path.basename(instruction.file)}`)
+    }
+    if (!repoInstructions && pathInstructions.length === 0) {
+      console.log("[copilot-instructions] No Copilot instructions found")
+    }
+
+    const state = new SessionState()
+
+    const injectRepoInstructions = (event: { system: Array<{ type: string; text: string }> }) => {
+      if (!repoInstructions) return
+      event.system.push({
+        type: "text",
+        text: `<copilot-instruction:copilot-instructions.md>\n${repoInstructions.trimEnd()}\n</copilot-instruction:copilot-instructions.md>`,
+      })
+    }
+
+    // Inject repo-wide instructions into every model call so they survive compaction.
+    await ctx.session.hook("context", injectRepoInstructions)
+    await ctx.session.hook("compaction", injectRepoInstructions)
+
+    await ctx.tool.hook("execute.before", (event) => {
+      if (!FILE_TOOLS.has(event.tool)) return
+
+      const input = event.input as { path?: unknown }
+      const filePath = input?.path
+      if (!filePath || typeof filePath !== "string") return
+
+      const relativePath = getRelativePath(directory, filePath)
+      const matching = pathInstructions.filter((instruction) => {
+        if (state.isFileInjected(event.sessionID, instruction.file)) return false
+        return instruction.matcher(relativePath)
+      })
+      if (matching.length === 0) return
+
+      for (const instruction of matching) state.markFileInjected(event.sessionID, instruction.file)
+
+      const text = matching
+        .map((instruction) => {
+          const filename = path.basename(instruction.file)
+          const patterns = instruction.applyTo.join(", ")
+          return `<copilot-instruction:${filename}>\n## Path-Specific Instructions (applies to: ${patterns})\n\n${instruction.content.trimEnd()}\n</copilot-instruction:${filename}>`
+        })
+        .join("\n\n")
+
+      state.setPending(event.id, text)
+    })
+
+    await ctx.tool.hook("execute.after", (event) => {
+      const text = state.consumePending(event.id)
+      if (!text) return
+      if (event.status !== "completed") return
+
+      const existing = typeof event.result.content === "string" ? event.result.content : ""
+      event.result = {
+        ...event.result,
+        content: existing ? `${existing}\n\n${text}` : text,
+      }
+    })
+
+    const controller = new AbortController()
+    void (async () => {
+      for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+        if (event.type === "session.compaction.ended") {
+          state.clearSession(event.data.sessionID)
+        }
+      }
+    })()
+
+    return () => controller.abort()
+  },
+})

package/src/loader.ts

@@ -0,0 +1,57 @@
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { parseFrontmatter } from "./frontmatter"
+import { createMatcher, normalizePatterns, type Matcher } from "./matcher"
+
+export interface PathInstruction {
+  file: string
+  applyTo: string[]
+  content: string
+  matcher: Matcher
+}
+
+/** Load repo-wide instructions from .github/copilot-instructions.md */
+export function loadRepoInstructions(directory: string): string | null {
+  const filePath = path.join(directory, ".github", "copilot-instructions.md")
+  try {
+    return fs.readFileSync(filePath, "utf-8")
+  } catch {
+    return null
+  }
+}
+
+/** Load path-specific instructions from .github/instructions/*.instructions.md */
+export function loadPathInstructions(directory: string): PathInstruction[] {
+  const instructionsDir = path.join(directory, ".github", "instructions")
+  let files: string[]
+  try {
+    files = fs.readdirSync(instructionsDir)
+  } catch {
+    return []
+  }
+
+  const result: PathInstruction[] = []
+  for (const filename of files) {
+    if (!filename.endsWith(".instructions.md")) continue
+
+    const filePath = path.join(instructionsDir, filename)
+    let content: string
+    try {
+      content = fs.readFileSync(filePath, "utf-8")
+    } catch {
+      continue
+    }
+
+    const parsed = parseFrontmatter(content)
+    const patterns = normalizePatterns(parsed.frontmatter.applyTo)
+    if (patterns.length === 0) continue
+
+    result.push({
+      file: filePath,
+      applyTo: patterns,
+      content: parsed.body,
+      matcher: createMatcher(patterns),
+    })
+  }
+  return result
+}

package/src/matcher.ts

@@ -0,0 +1,18 @@
+import picomatch from "picomatch"
+
+export type Matcher = (path: string) => boolean
+
+export function createMatcher(patterns: string[]): Matcher {
+  if (patterns.length === 0) return () => false
+  const isMatch = picomatch(patterns)
+  return (path) => isMatch(path)
+}
+
+export function normalizePatterns(applyTo: string | string[] | undefined): string[] {
+  if (applyTo === undefined) return []
+  if (Array.isArray(applyTo)) return applyTo
+  return applyTo
+    .split(",")
+    .map((pattern) => pattern.trim())
+    .filter((pattern) => pattern.length > 0)
+}

package/src/session-state.ts

@@ -0,0 +1,37 @@
+/**
+ * Encapsulates session-related state for the Copilot Instructions plugin.
+ *
+ * Tracks which path-specific instructions have been injected per session, and
+ * pending instructions keyed by tool call ID.
+ */
+export class SessionState {
+  private injectedPerSession = new Map<string, Set<string>>()
+  private pendingInstructions = new Map<string, string>()
+
+  isFileInjected(sessionId: string, file: string): boolean {
+    return this.injectedPerSession.get(sessionId)?.has(file) ?? false
+  }
+
+  markFileInjected(sessionId: string, file: string): void {
+    let files = this.injectedPerSession.get(sessionId)
+    if (!files) {
+      files = new Set()
+      this.injectedPerSession.set(sessionId, files)
+    }
+    files.add(file)
+  }
+
+  clearSession(sessionId: string): void {
+    this.injectedPerSession.delete(sessionId)
+  }
+
+  setPending(callId: string, text: string): void {
+    this.pendingInstructions.set(callId, text)
+  }
+
+  consumePending(callId: string): string | undefined {
+    const text = this.pendingInstructions.get(callId)
+    this.pendingInstructions.delete(callId)
+    return text
+  }
+}