From d9414b99d120d215d748922315ed5ac5119c046f Mon Sep 17 00:00:00 2001
From: Marius Wichtner <marius@kilocode.ai>
Date: Tue, 27 Jan 2026 12:08:11 +0100
Subject: [PATCH] Improve AGENTS.md

---
 .opencode/agent/kilocode-markers.md | 34 -------------------
 .opencode/opencode.jsonc            |  1 -
 AGENTS.md                           | 52 +++++++++++++++++++++++++++++
 3 files changed, 52 insertions(+), 35 deletions(-)
 delete mode 100644 .opencode/agent/kilocode-markers.md

diff --git a/.opencode/agent/kilocode-markers.md b/.opencode/agent/kilocode-markers.md
deleted file mode 100644
index 4b861bdad09..00000000000
--- a/.opencode/agent/kilocode-markers.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# Kilocode Change Markers
-
-To minimize merge conflicts when syncing with upstream, mark Kilo Code-specific changes in shared code with `kilocode_change` comments.
-
-**Single line:**
-
-```typescript
-const value = 42 // kilocode_change
-```
-
-**Multi-line:**
-
-```typescript
-// kilocode_change start
-const foo = 1
-const bar = 2
-// kilocode_change end
-```
-
-**New files:**
-
-```typescript
-// kilocode_change - new file
-```
-
-## When markers are NOT needed
-
-Code in these paths is Kilo Code-specific and does NOT need `kilocode_change` markers:
-
-- `packages/opencode/src/kilocode/` - All files in this directory
-- `packages/opencode/test/kilocode/` - All test files for kilocode
-- Any other path containing `kilocode` in filename or directory name
-
-These paths are entirely Kilo Code additions and won't conflict with upstream.
diff --git a/.opencode/opencode.jsonc b/.opencode/opencode.jsonc
index 9f5b7c5fdf7..c3f0b7070d1 100644
--- a/.opencode/opencode.jsonc
+++ b/.opencode/opencode.jsonc
@@ -4,7 +4,6 @@
   // "enterprise": {
   //   "url": "https://enterprise.dev.opencode.ai",
   // },
-  "instructions": [".opencode/agent/kilocode-markers.md"],
   "provider": {
     "opencode": {
       "options": {},
diff --git a/AGENTS.md b/AGENTS.md
index d621b18146c..469c12198f5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -86,3 +86,55 @@ Tests MUST test actual implementation, do not duplicate logic into a test.
 ## Fork Merge Process
 
 Kilo CLI is a fork of [opencode](https://github.com/anomalyco/opencode).
+
+### Minimizing Merge Conflicts
+
+We regularly merge upstream changes from opencode. To minimize merge conflicts and keep the sync process smooth:
+
+1. **Prefer `kilocode` directories** - Place Kilo-specific code in dedicated directories whenever possible:
+   - `packages/opencode/src/kilocode/` - Kilo-specific source code
+   - `packages/opencode/test/kilocode/` - Kilo-specific tests
+   - `packages/kilo-gateway/` - The Kilo Gateway package
+
+2. **Minimize changes to shared files** - When you must modify files that exist in upstream opencode, keep changes as small and isolated as possible.
+
+3. **Use `kilocode_change` markers** - When modifying shared code, mark your changes with `kilocode_change` comments so they can be easily identified during merges.
+
+4. **Avoid restructuring upstream code** - Don't refactor or reorganize code that comes from opencode unless absolutely necessary.
+
+The goal is to keep our diff from upstream as small as possible, making regular merges straightforward and reducing the risk of conflicts.
+
+### Kilocode Change Markers
+
+To minimize merge conflicts when syncing with upstream, mark Kilo Code-specific changes in shared code with `kilocode_change` comments.
+
+**Single line:**
+
+```typescript
+const value = 42 // kilocode_change
+```
+
+**Multi-line:**
+
+```typescript
+// kilocode_change start
+const foo = 1
+const bar = 2
+// kilocode_change end
+```
+
+**New files:**
+
+```typescript
+// kilocode_change - new file
+```
+
+#### When markers are NOT needed
+
+Code in these paths is Kilo Code-specific and does NOT need `kilocode_change` markers:
+
+- `packages/opencode/src/kilocode/` - All files in this directory
+- `packages/opencode/test/kilocode/` - All test files for kilocode
+- Any other path containing `kilocode` in filename or directory name
+
+These paths are entirely Kilo Code additions and won't conflict with upstream.