feat(opencode): configure local instruction filenames

packages/core/src/config.ts

@@ -95,6 +95,9 @@ export class Info extends Schema.Class<Info>("Config.Info")({
   instructions: Schema.String.pipe(Schema.Array, Schema.optional).annotate({
     description: "Additional paths or URLs supplying ambient instructions",
   }),
+  local_instruction_filenames: Schema.String.pipe(Schema.Array, Schema.optional).annotate({
+    description: "Additional filenames to search for when loading directory-specific instructions",
+  }),
   references: ConfigReference.Info.pipe(Schema.optional).annotate({
     description: "Named local directories or Git repositories available as external context",
   }),

packages/core/src/instruction-context.ts

@@ -2,6 +2,7 @@ export * as InstructionContext from "./instruction-context"
 
 import { Array, Effect, Layer, Schema } from "effect"
 import { isAbsolute, join, relative, sep } from "path"
+import { Config } from "./config"
 import { FSUtil } from "./fs-util"
 import { Flag } from "./flag/flag"
 import { Global } from "./global"
@@ -21,6 +22,7 @@ const key = SystemContext.Key.make("core/instructions")
 export const layer = Layer.effectDiscard(
   Effect.gen(function* () {
     const fs = yield* FSUtil.Service
+    const config = yield* Config.Service
     const global = yield* Global.Service
     const location = yield* Location.Service
     const registry = yield* SystemContextRegistry.Service
@@ -42,11 +44,17 @@ export const layer = Layer.effectDiscard(
       const fromProject = relative(stop, start)
       const insideProject =
         fromProject === "" || (fromProject !== ".." && !fromProject.startsWith(`..${sep}`) && !isAbsolute(fromProject))
+      const targets = Array.dedupe([
+        "AGENTS.md",
+        ...(yield* config.entries()).flatMap((entry) =>
+          entry.type === "document" ? (entry.info.local_instruction_filenames ?? []) : [],
+        ),
+      ])
       const discovered = new Set(
         (Flag.OPENCODE_DISABLE_PROJECT_CONFIG || !insideProject
           ? []
           : yield* fs.up({
-              targets: ["AGENTS.md"],
+              targets,
               start,
               stop,
             })

packages/core/src/system-context/builtins.ts

@@ -1,6 +1,7 @@
 export * as SystemContextBuiltIns from "./builtins"
 
 import { DateTime, Effect, Layer, Schema } from "effect"
+import { Config } from "../config"
 import { Location } from "../location"
 import { SystemContext } from "./index"
 import { InstructionContext } from "../instruction-context"
@@ -42,6 +43,7 @@ const builtIns = Layer.effectDiscard(
 
 export const layer = Layer.mergeAll(builtIns, InstructionContext.layer).pipe(
   Layer.provideMerge(SystemContextRegistry.layer),
+  Layer.provide(Config.locationLayer),
 )
 
 export const locationLayer = layer

packages/core/src/v1/config/config.ts

@@ -121,6 +121,9 @@ export const Info = Schema.Struct({
   instructions: Schema.optional(Schema.mutable(Schema.Array(Schema.String))).annotate({
     description: "Additional instruction files or patterns to include",
   }),
+  local_instruction_filenames: Schema.optional(Schema.mutable(Schema.Array(Schema.String))).annotate({
+    description: "Additional filenames to search for when loading directory-specific instructions",
+  }),
   layout: Schema.optional(ConfigLayoutV1.Layout).annotate({ description: "@deprecated Always uses stretch layout." }),
   permission: Schema.optional(ConfigPermissionV1.Info),
   tools: Schema.optional(Schema.Record(Schema.String, Schema.Boolean)),

packages/core/src/v1/config/migrate.ts

@@ -63,6 +63,7 @@ export function migrate(info: typeof ConfigV1.Info.Type) {
     skills: info.skills && [...(info.skills.paths ?? []), ...(info.skills.urls ?? [])],
     commands: info.command,
     instructions: info.instructions,
+    local_instruction_filenames: info.local_instruction_filenames,
     references: info.references ?? info.reference,
     plugins: info.plugin?.map((plugin) =>
       typeof plugin === "string" ? plugin : { package: plugin[0], options: plugin[1] },

packages/core/test/config/config.test.ts

@@ -144,6 +144,14 @@ describe("Config", () => {
     }),
   )
 
+  it.effect("migrates v1 local instruction filenames", () =>
+    Effect.sync(() => {
+      expect(
+        ConfigMigrateV1.migrate({ local_instruction_filenames: ["REVIEW.md"] }).local_instruction_filenames,
+      ).toEqual(["REVIEW.md"])
+    }),
+  )
+
   it.live("returns an empty configuration when directory files do not exist", () =>
     Effect.acquireRelease(
       Effect.promise(() => tmpdir()),
@@ -325,6 +333,7 @@ describe("Config", () => {
                 },
                 skills: ["./skills", "~/shared-skills", "https://example.com/.well-known/skills/"],
                 instructions: ["CONTRIBUTING.md", ".cursor/rules/*.md", "https://example.com/shared-rules.md"],
+                local_instruction_filenames: ["REVIEW.md", "SECURITY.md"],
                 references: {
                   local: { path: "../library" },
                   sdk: { repository: "github.com/example/sdk", branch: "main" },
@@ -418,6 +427,7 @@ describe("Config", () => {
               ".cursor/rules/*.md",
               "https://example.com/shared-rules.md",
             ])
+            expect(documents[0]?.info.local_instruction_filenames).toEqual(["REVIEW.md", "SECURITY.md"])
             expect(documents[0]?.info.references).toEqual({
               local: { path: "../library" },
               sdk: { repository: "github.com/example/sdk", branch: "main" },

packages/core/test/instruction-context.test.ts

@@ -2,6 +2,7 @@ import { describe, expect } from "bun:test"
 import { Effect, Layer } from "effect"
 import fs from "fs/promises"
 import path from "path"
+import { Config } from "@opencode-ai/core/config"
 import { FSUtil } from "@opencode-ai/core/fs-util"
 import { Global } from "@opencode-ai/core/global"
 import { InstructionContext } from "@opencode-ai/core/instruction-context"
@@ -14,6 +15,11 @@ import { tmpdir } from "./fixture/tmpdir"
 import { testEffect } from "./lib/effect"
 
 const it = testEffect(Layer.empty)
+const instructionLayer = (entries: Config.Entry[] = []) =>
+  InstructionContext.layer.pipe(
+    Layer.provideMerge(SystemContextRegistry.layer),
+    Layer.provide(Layer.mock(Config.Service, { entries: () => Effect.succeed(entries) })),
+  )
 
 describe("InstructionContext", () => {
   it.live("loads global and upward project AGENTS.md files as one aggregate context", () =>
@@ -41,7 +47,7 @@ describe("InstructionContext", () => {
 
           const load = SystemContextRegistry.Service.pipe(
             Effect.flatMap((service) => service.load()),
-            Effect.provide(InstructionContext.layer.pipe(Layer.provideMerge(SystemContextRegistry.layer))),
+            Effect.provide(instructionLayer()),
             Effect.provide(FSUtil.defaultLayer),
             Effect.provide(Global.layerWith({ config: global })),
             Effect.provide(
@@ -96,6 +102,65 @@ describe("InstructionContext", () => {
     ),
   )
 
+  it.live("loads configured instruction filenames from every config scope", () =>
+    Effect.acquireRelease(
+      Effect.promise(() => tmpdir()),
+      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
+    ).pipe(
+      Effect.flatMap((tmp) =>
+        Effect.gen(function* () {
+          const directory = path.join(tmp.path, "project", "packages", "core")
+          const agents = path.join(directory, "AGENTS.md")
+          const review = path.join(directory, "REVIEW.md")
+          const security = path.join(directory, "SECURITY.md")
+          yield* Effect.promise(async () => {
+            await fs.mkdir(directory, { recursive: true })
+            await fs.writeFile(agents, "agents")
+            await fs.writeFile(review, "review")
+            await fs.writeFile(security, "security")
+          })
+
+          const context = yield* SystemContextRegistry.Service.pipe(
+            Effect.flatMap((service) => service.load()),
+            Effect.provide(
+              instructionLayer([
+                new Config.Document({
+                  type: "document",
+                  info: new Config.Info({ local_instruction_filenames: ["REVIEW.md"] }),
+                }),
+                new Config.Document({
+                  type: "document",
+                  info: new Config.Info({ local_instruction_filenames: ["SECURITY.md", "REVIEW.md"] }),
+                }),
+              ]),
+            ),
+            Effect.provide(FSUtil.defaultLayer),
+            Effect.provide(Global.layerWith({ config: path.join(tmp.path, "global") })),
+            Effect.provide(
+              Layer.succeed(
+                Location.Service,
+                Location.Service.of(
+                  location(
+                    { directory: AbsolutePath.make(directory) },
+                    { projectDirectory: AbsolutePath.make(path.join(tmp.path, "project")) },
+                  ),
+                ),
+              ),
+            ),
+          )
+
+          expect((yield* SystemContext.initialize(context)).baseline).toBe(
+            [
+              `Instructions from: ${agents}\nagents`,
+              `Instructions from: ${review}\nreview`,
+              `Instructions from: ${security}\nsecurity`,
+            ].join("\n\n"),
+          )
+        }),
+      ),
+    ),
+  )
+
   it.live("keeps an empty AGENTS.md as available context", () =>
     Effect.acquireRelease(
       Effect.promise(() => tmpdir()),
@@ -107,7 +172,7 @@ describe("InstructionContext", () => {
           yield* Effect.promise(() => fs.writeFile(file, ""))
           const context = yield* SystemContextRegistry.Service.pipe(
             Effect.flatMap((service) => service.load()),
-            Effect.provide(InstructionContext.layer.pipe(Layer.provideMerge(SystemContextRegistry.layer))),
+            Effect.provide(instructionLayer()),
             Effect.provide(FSUtil.defaultLayer),
             Effect.provide(Global.layerWith({ config: path.join(tmp.path, "global") })),
             Effect.provide(
@@ -136,7 +201,7 @@ describe("InstructionContext", () => {
       ).pipe(Layer.provide(FSUtil.defaultLayer))
       const context = yield* SystemContextRegistry.Service.pipe(
         Effect.flatMap((service) => service.load()),
-        Effect.provide(InstructionContext.layer.pipe(Layer.provideMerge(SystemContextRegistry.layer))),
+        Effect.provide(instructionLayer()),
         Effect.provide(failingFS),
         Effect.provide(Global.layerWith({ config: "/global" })),
         Effect.provide(
@@ -172,7 +237,7 @@ describe("InstructionContext", () => {
       ).pipe(Layer.provide(FSUtil.defaultLayer))
       const context = yield* SystemContextRegistry.Service.pipe(
         Effect.flatMap((service) => service.load()),
-        Effect.provide(InstructionContext.layer.pipe(Layer.provideMerge(SystemContextRegistry.layer))),
+        Effect.provide(instructionLayer()),
         Effect.provide(racingFS),
         Effect.provide(Global.layerWith({ config: "/global" })),
         Effect.provide(
@@ -212,7 +277,7 @@ describe("InstructionContext", () => {
 
       yield* SystemContextRegistry.Service.pipe(
         Effect.flatMap((service) => service.load()),
-        Effect.provide(InstructionContext.layer.pipe(Layer.provideMerge(SystemContextRegistry.layer))),
+        Effect.provide(instructionLayer()),
         Effect.provide(observingFS),
         Effect.provide(Global.layerWith({ config: "/global" })),
         Effect.provide(
@@ -241,7 +306,7 @@ describe("InstructionContext", () => {
 
       yield* SystemContextRegistry.Service.pipe(
         Effect.flatMap((service) => service.load()),
-        Effect.provide(InstructionContext.layer.pipe(Layer.provideMerge(SystemContextRegistry.layer))),
+        Effect.provide(instructionLayer()),
         Effect.provide(
           Layer.effect(
             FSUtil.Service,
@@ -271,7 +336,7 @@ describe("InstructionContext", () => {
       let scanned = false
       yield* SystemContextRegistry.Service.pipe(
         Effect.flatMap((service) => service.load()),
-        Effect.provide(InstructionContext.layer.pipe(Layer.provideMerge(SystemContextRegistry.layer))),
+        Effect.provide(instructionLayer()),
         Effect.provide(
           Layer.effect(
             FSUtil.Service,

packages/opencode/src/config/config.ts

@@ -47,6 +47,11 @@ function mergeConfigConcatArrays(target: Info, source: Info): Info {
   if (target.instructions && source.instructions) {
     merged.instructions = Array.from(new Set([...target.instructions, ...source.instructions]))
   }
+  if (target.local_instruction_filenames && source.local_instruction_filenames) {
+    merged.local_instruction_filenames = Array.from(
+      new Set([...target.local_instruction_filenames, ...source.local_instruction_filenames]),
+    )
+  }
   return merged
 }