opencode: add support for global custom instructions via rules option

- Introduce `rules` option to provide global custom instructions for opencode
- Write `rules` content to `~/.config/opencode/AGENTS.md` if non-empty
- Update tests to cover presence and absence of `AGENTS.md` file with rules content

modules/programs/opencode.nix

@@ -41,13 +41,49 @@ in
         See <https://opencode.ai/docs/config/> for the documentation.
       '';
     };
+    rules = lib.mkOption {
+      type = lib.types.lines;
+      description = "You can provide global custom instructions to opencode; this value is written to {file}~/.config/opencode/AGENTS.md";
+      default = "";
+      example = lib.literalExpression ''
+        '''
+          # TypeScript Project Rules
+
+          ## External File Loading
+
+          CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand.
+
+          Instructions:
+
+          - Do NOT preemptively load all references - use lazy loading based on actual need
+          - When loaded, treat content as mandatory instructions that override defaults
+          - Follow references recursively when needed
+
+          ## Development Guidelines
+
+          For TypeScript code style and best practices: @docs/typescript-guidelines.md
+          For React component architecture and hooks patterns: @docs/react-patterns.md
+          For REST API design and error handling: @docs/api-standards.md
+          For testing strategies and coverage requirements: @test/testing-guidelines.md
+
+          ## General Guidelines
+
+          Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md.
+        '''
+      '';
+    };
   };
 
   config = mkIf cfg.enable {
     home.packages = mkIf (cfg.package != null) [ cfg.package ];
 
-    xdg.configFile."opencode/config.json" = mkIf (cfg.settings != { }) {
+    xdg.configFile = {
-      source = jsonFormat.generate "config.json" cfg.settings;
+      "opencode/config.json" = mkIf (cfg.settings != { }) {
+        source = jsonFormat.generate "config.json" cfg.settings;
+      };
+      "opencode/AGENTS.md" = mkIf (cfg.rules != "") {
+        text = cfg.rules;
+      };
     };
   };
 }

tests/modules/programs/opencode/AGENTS.md

@@ -0,0 +1,22 @@
+# TypeScript Project Rules
+
+## External File Loading
+
+CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand.
+
+Instructions:
+
+- Do NOT preemptively load all references - use lazy loading based on actual need
+- When loaded, treat content as mandatory instructions that override defaults
+- Follow references recursively when needed
+
+## Development Guidelines
+
+For TypeScript code style and best practices: @docs/typescript-guidelines.md
+For React component architecture and hooks patterns: @docs/react-patterns.md
+For REST API design and error handling: @docs/api-standards.md
+For testing strategies and coverage requirements: @test/testing-guidelines.md
+
+## General Guidelines
+
+Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md.

tests/modules/programs/opencode/default.nix

@@ -1,3 +1,5 @@
 {
   opencode-settings = ./settings.nix;
+  opencode-rules = ./rules.nix;
+  opencode-empty-rules = ./empty-rules.nix;
 }

tests/modules/programs/opencode/empty-rules.nix

@@ -0,0 +1,9 @@
+{
+  programs.opencode = {
+    enable = true;
+    rules = "";
+  };
+  nmt.script = ''
+    assertPathNotExists home-files/.config/opencode/AGENTS.md
+  '';
+}

tests/modules/programs/opencode/rules.nix

@@ -0,0 +1,34 @@
+{
+  programs.opencode = {
+    enable = true;
+    rules = ''
+      # TypeScript Project Rules
+
+      ## External File Loading
+
+      CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand.
+
+      Instructions:
+
+      - Do NOT preemptively load all references - use lazy loading based on actual need
+      - When loaded, treat content as mandatory instructions that override defaults
+      - Follow references recursively when needed
+
+      ## Development Guidelines
+
+      For TypeScript code style and best practices: @docs/typescript-guidelines.md
+      For React component architecture and hooks patterns: @docs/react-patterns.md
+      For REST API design and error handling: @docs/api-standards.md
+      For testing strategies and coverage requirements: @test/testing-guidelines.md
+
+      ## General Guidelines
+
+      Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md.
+    '';
+  };
+  nmt.script = ''
+    assertFileExists home-files/.config/opencode/AGENTS.md
+    assertFileContent home-files/.config/opencode/AGENTS.md \
+      ${./AGENTS.md}
+  '';
+}