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 != { }) {
-      source = jsonFormat.generate "config.json" cfg.settings;
+    xdg.configFile = {
+      "opencode/config.json" = mkIf (cfg.settings != { }) {
+        source = jsonFormat.generate "config.json" cfg.settings;
+      };
+      "opencode/AGENTS.md" = mkIf (cfg.rules != "") {
+        text = cfg.rules;
+      };
     };
   };
 }