feat: add symlink support for AGENTS.md file loading

- Add safeReadFileFollowingSymlinks function to handle symlink resolution
- Update loadAgentRulesFile to use the new symlink-aware function
- Add comprehensive tests for both symlink and regular file scenarios
- Ensures AGENTS.md can be a symlink pointing to actual rules file

Author: roomote

src/core/prompts/sections/__tests__/custom-instructions.spec.ts

@@ -54,12 +54,14 @@ const readFileMock = vi.fn()
 const statMock = vi.fn()
 const readdirMock = vi.fn()
 const readlinkMock = vi.fn()
+const lstatMock = vi.fn()
 
 // Replace fs functions with our mocks
 fs.readFile = readFileMock as any
 fs.stat = statMock as any
 fs.readdir = readdirMock as any
 fs.readlink = readlinkMock as any
+fs.lstat = lstatMock as any
 
 // Mock process.cwd
 const originalCwd = process.cwd
@@ -509,6 +511,17 @@ describe("addCustomInstructions", () => {
 		// Simulate no .roo/rules-test-mode directory
 		statMock.mockRejectedValueOnce({ code: "ENOENT" })
 
+		// Mock lstat to indicate AGENTS.md is NOT a symlink
+		lstatMock.mockImplementation((filePath: PathLike) => {
+			const pathStr = filePath.toString()
+			if (pathStr.endsWith("AGENTS.md")) {
+				return Promise.resolve({
+					isSymbolicLink: vi.fn().mockReturnValue(false),
+				})
+			}
+			return Promise.reject({ code: "ENOENT" })
+		})
+
 		readFileMock.mockImplementation((filePath: PathLike) => {
 			const pathStr = filePath.toString()
 			if (pathStr.endsWith("AGENTS.md")) {
@@ -558,6 +571,17 @@ describe("addCustomInstructions", () => {
 		// Simulate no .roo/rules-test-mode directory
 		statMock.mockRejectedValueOnce({ code: "ENOENT" })
 
+		// Mock lstat to indicate AGENTS.md is NOT a symlink
+		lstatMock.mockImplementation((filePath: PathLike) => {
+			const pathStr = filePath.toString()
+			if (pathStr.endsWith("AGENTS.md")) {
+				return Promise.resolve({
+					isSymbolicLink: vi.fn().mockReturnValue(false),
+				})
+			}
+			return Promise.reject({ code: "ENOENT" })
+		})
+
 		readFileMock.mockImplementation((filePath: PathLike) => {
 			const pathStr = filePath.toString()
 			if (pathStr.endsWith("AGENTS.md")) {
@@ -602,6 +626,17 @@ describe("addCustomInstructions", () => {
 		// Simulate no .roo/rules-test-mode directory
 		statMock.mockRejectedValueOnce({ code: "ENOENT" })
 
+		// Mock lstat to indicate AGENTS.md is NOT a symlink
+		lstatMock.mockImplementation((filePath: PathLike) => {
+			const pathStr = filePath.toString()
+			if (pathStr.endsWith("AGENTS.md")) {
+				return Promise.resolve({
+					isSymbolicLink: vi.fn().mockReturnValue(false),
+				})
+			}
+			return Promise.reject({ code: "ENOENT" })
+		})
+
 		readFileMock.mockImplementation((filePath: PathLike) => {
 			const pathStr = filePath.toString()
 			if (pathStr.endsWith("AGENTS.md")) {
@@ -628,6 +663,106 @@ describe("addCustomInstructions", () => {
 		expect(result).toContain("Roo rules content")
 	})
 
+	it("should follow symlinks when loading AGENTS.md", async () => {
+		// Simulate no .roo/rules-test-mode directory
+		statMock.mockRejectedValueOnce({ code: "ENOENT" })
+
+		// Mock lstat to indicate AGENTS.md is a symlink
+		lstatMock.mockImplementation((filePath: PathLike) => {
+			const pathStr = filePath.toString()
+			if (pathStr.endsWith("AGENTS.md")) {
+				return Promise.resolve({
+					isSymbolicLink: vi.fn().mockReturnValue(true),
+				})
+			}
+			return Promise.reject({ code: "ENOENT" })
+		})
+
+		// Mock readlink to return the symlink target
+		readlinkMock.mockImplementation((filePath: PathLike) => {
+			const pathStr = filePath.toString()
+			if (pathStr.endsWith("AGENTS.md")) {
+				return Promise.resolve("../actual-agents-file.md")
+			}
+			return Promise.reject({ code: "ENOENT" })
+		})
+
+		// Mock readFile to return content from the resolved path
+		readFileMock.mockImplementation((filePath: PathLike) => {
+			const pathStr = filePath.toString()
+			const normalizedPath = pathStr.replace(/\\/g, "/")
+			if (normalizedPath.endsWith("actual-agents-file.md")) {
+				return Promise.resolve("Agent rules from symlinked file")
+			}
+			return Promise.reject({ code: "ENOENT" })
+		})
+
+		const result = await addCustomInstructions(
+			"mode instructions",
+			"global instructions",
+			"/fake/path",
+			"test-mode",
+			{ settings: { maxConcurrentFileReads: 5, todoListEnabled: true, useAgentRules: true } },
+		)
+
+		expect(result).toContain("# Agent Rules Standard (AGENTS.md):")
+		expect(result).toContain("Agent rules from symlinked file")
+
+		// Verify lstat was called to check if it's a symlink
+		expect(lstatMock).toHaveBeenCalledWith(expect.stringContaining("AGENTS.md"))
+
+		// Verify readlink was called to resolve the symlink
+		expect(readlinkMock).toHaveBeenCalledWith(expect.stringContaining("AGENTS.md"))
+
+		// Verify the resolved path was read
+		expect(readFileMock).toHaveBeenCalledWith(expect.stringContaining("actual-agents-file.md"), "utf-8")
+	})
+
+	it("should handle AGENTS.md as a regular file when not a symlink", async () => {
+		// Simulate no .roo/rules-test-mode directory
+		statMock.mockRejectedValueOnce({ code: "ENOENT" })
+
+		// Mock lstat to indicate AGENTS.md is NOT a symlink
+		lstatMock.mockImplementation((filePath: PathLike) => {
+			const pathStr = filePath.toString()
+			if (pathStr.endsWith("AGENTS.md")) {
+				return Promise.resolve({
+					isSymbolicLink: vi.fn().mockReturnValue(false),
+				})
+			}
+			return Promise.reject({ code: "ENOENT" })
+		})
+
+		// Mock readFile to return content directly from AGENTS.md
+		readFileMock.mockImplementation((filePath: PathLike) => {
+			const pathStr = filePath.toString()
+			if (pathStr.endsWith("AGENTS.md")) {
+				return Promise.resolve("Agent rules from regular file")
+			}
+			return Promise.reject({ code: "ENOENT" })
+		})
+
+		const result = await addCustomInstructions(
+			"mode instructions",
+			"global instructions",
+			"/fake/path",
+			"test-mode",
+			{ settings: { maxConcurrentFileReads: 5, todoListEnabled: true, useAgentRules: true } },
+		)
+
+		expect(result).toContain("# Agent Rules Standard (AGENTS.md):")
+		expect(result).toContain("Agent rules from regular file")
+
+		// Verify lstat was called
+		expect(lstatMock).toHaveBeenCalledWith(expect.stringContaining("AGENTS.md"))
+
+		// Verify readlink was NOT called since it's not a symlink
+		expect(readlinkMock).not.toHaveBeenCalledWith(expect.stringContaining("AGENTS.md"))
+
+		// Verify the file was read directly
+		expect(readFileMock).toHaveBeenCalledWith(expect.stringContaining("AGENTS.md"), "utf-8")
+	})
+
 	it("should return empty string when no instructions provided", async () => {
 		// Simulate no .roo/rules directory
 		statMock.mockRejectedValueOnce({ code: "ENOENT" })

src/core/prompts/sections/custom-instructions.ts

@@ -26,6 +26,34 @@ async function safeReadFile(filePath: string): Promise<string> {
 	}
 }
 
+/**
+ * Safely read a file and follow symlinks if necessary
+ */
+async function safeReadFileFollowingSymlinks(filePath: string): Promise<string> {
+	try {
+		// Check if the path is a symlink
+		const stats = await fs.lstat(filePath)
+		if (stats.isSymbolicLink()) {
+			// Resolve the symlink to get the actual file path
+			const linkTarget = await fs.readlink(filePath)
+			const resolvedPath = path.resolve(path.dirname(filePath), linkTarget)
+			// Read from the resolved path
+			const content = await fs.readFile(resolvedPath, "utf-8")
+			return content.trim()
+		} else {
+			// Not a symlink, read normally
+			const content = await fs.readFile(filePath, "utf-8")
+			return content.trim()
+		}
+	} catch (err) {
+		const errorCode = (err as NodeJS.ErrnoException).code
+		if (!errorCode || !["ENOENT", "EISDIR"].includes(errorCode)) {
+			throw err
+		}
+		return ""
+	}
+}
+
 /**
  * Check if a directory exists
  */
@@ -222,7 +250,7 @@ export async function loadRuleFiles(cwd: string): Promise<string> {
 async function loadAgentRulesFile(cwd: string): Promise<string> {
 	try {
 		const agentsPath = path.join(cwd, "AGENTS.md")
-		const content = await safeReadFile(agentsPath)
+		const content = await safeReadFileFollowingSymlinks(agentsPath)
 		if (content) {
 			return `# Agent Rules Standard (AGENTS.md):\n${content}`
 		}