Change AGENTS.md to read from project root, not workspace

Design decision: Read AGENTS.md from projectPath (project root) instead of
workspacePath (individual workspace/worktree directories).

Rationale:
- Ensures consistent instructions across all workspaces for a project
- Simplifies mental model: one AGENTS.md per project, not per branch
- Aligns with typical workflow where instructions are project-level context
- Still allows workspace-specific overrides via AGENTS.local.md (gitignored)

Changes:
- buildSystemMessage() now reads AGENTS.md from metadata.projectPath
- Environment context still uses workspacePath (where code executes)
- Updated docs/instruction-files.md to reflect project-level instructions
- Updated all tests to use projectDir instead of workspaceDir
- Renamed test variables for clarity

Breaking change: Branch-specific AGENTS.md files will no longer be read.
Migration: Move workspace-specific instructions to project root AGENTS.md,
or use AGENTS.local.md for personal/workspace-specific overrides.

Author: ammar-agent

docs/instruction-files.md

@@ -5,10 +5,12 @@
 cmux layers instructions from two locations:
 
 1. `~/.cmux/AGENTS.md` (+ optional `AGENTS.local.md`) — global defaults
-2. `<workspace>/AGENTS.md` (+ optional `AGENTS.local.md`) — workspace-specific context
+2. `<project>/AGENTS.md` (+ optional `AGENTS.local.md`) — project-specific context
 
 Priority within each location: `AGENTS.md` → `AGENT.md` → `CLAUDE.md` (first match wins). If the base file is found, cmux also appends `AGENTS.local.md` from the same directory when present.
 
+**Note**: Instructions are read from the project root (where the main repository is located), not from individual workspace directories. This ensures consistent instructions across all workspaces for a project.
+
 ## Mode Prompts
 
 > Use mode-specific sections to optimize context and customize the behavior specific modes.
@@ -19,7 +21,7 @@ cmux reads mode context from sections inside your instruction files. Add a headi
 
 Rules:
 
-- Workspace instructions are checked first, then global instructions
+- Project instructions are checked first, then global instructions
 - The first matching section wins (at most one section is used)
 - The section's content is everything until the next heading of the same or higher level
 - Missing sections are ignored (no error)

src/services/systemMessage.test.ts

@@ -8,15 +8,18 @@ import type { Mock } from "bun:test";
 
 describe("buildSystemMessage", () => {
   let tempDir: string;
+  let projectDir: string;
   let workspaceDir: string;
   let globalDir: string;
   let mockHomedir: Mock<typeof os.homedir>;
 
   beforeEach(async () => {
     // Create temp directory for test
     tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "systemMessage-test-"));
+    projectDir = path.join(tempDir, "project");
     workspaceDir = path.join(tempDir, "workspace");
     globalDir = path.join(tempDir, ".cmux");
+    await fs.mkdir(projectDir, { recursive: true });
     await fs.mkdir(workspaceDir, { recursive: true });
     await fs.mkdir(globalDir, { recursive: true });
 
@@ -33,9 +36,9 @@ describe("buildSystemMessage", () => {
   });
 
   test("includes mode-specific section when mode is provided", async () => {
-    // Write instruction file with mode section
+    // Write instruction file with mode section to projectDir
     await fs.writeFile(
-      path.join(workspaceDir, "AGENTS.md"),
+      path.join(projectDir, "AGENTS.md"),
       `# General Instructions
 Always be helpful.
 
@@ -49,7 +52,7 @@ Use diagrams where appropriate.
       id: "test-workspace",
       name: "test-workspace",
       projectName: "test-project",
-      projectPath: tempDir,
+      projectPath: projectDir,
     };
 
     const systemMessage = await buildSystemMessage(metadata, workspaceDir, "plan");
@@ -65,9 +68,9 @@ Use diagrams where appropriate.
   });
 
   test("excludes mode-specific section when mode is not provided", async () => {
-    // Write instruction file with mode section
+    // Write instruction file with mode section to projectDir
     await fs.writeFile(
-      path.join(workspaceDir, "AGENTS.md"),
+      path.join(projectDir, "AGENTS.md"),
       `# General Instructions
 Always be helpful.
 
@@ -80,7 +83,7 @@ Focus on planning and design.
       id: "test-workspace",
       name: "test-workspace",
       projectName: "test-project",
-      projectPath: tempDir,
+      projectPath: projectDir,
     };
 
     const systemMessage = await buildSystemMessage(metadata, workspaceDir);
@@ -94,7 +97,7 @@ Focus on planning and design.
     expect(systemMessage).toContain("Focus on planning and design");
   });
 
-  test("prefers workspace mode section over global mode section", async () => {
+  test("prefers project mode section over global mode section", async () => {
     // Write global instruction file with mode section
     await fs.writeFile(
       path.join(globalDir, "AGENTS.md"),
@@ -105,33 +108,33 @@ Global plan instructions.
 `
     );
 
-    // Write workspace instruction file with mode section
+    // Write project instruction file with mode section
     await fs.writeFile(
-      path.join(workspaceDir, "AGENTS.md"),
-      `# Workspace Instructions
+      path.join(projectDir, "AGENTS.md"),
+      `# Project Instructions
 
 ## Mode: Plan
-Workspace plan instructions (should win).
+Project plan instructions (should win).
 `
     );
 
     const metadata: WorkspaceMetadata = {
       id: "test-workspace",
       name: "test-workspace",
       projectName: "test-project",
-      projectPath: tempDir,
+      projectPath: projectDir,
     };
 
     const systemMessage = await buildSystemMessage(metadata, workspaceDir, "plan");
 
-    // Should include workspace mode section in the <plan> tag (workspace wins)
-    expect(systemMessage).toMatch(/<plan>\s*Workspace plan instructions \(should win\)\./s);
+    // Should include project mode section in the <plan> tag (project wins)
+    expect(systemMessage).toMatch(/<plan>\s*Project plan instructions \(should win\)\./s);
     // Global instructions are still present in <custom-instructions> section (that's correct)
-    // But the mode-specific <plan> section should only have workspace content
+    // But the mode-specific <plan> section should only have project content
     expect(systemMessage).not.toMatch(/<plan>[^<]*Global plan instructions/s);
   });
 
-  test("falls back to global mode section when workspace has none", async () => {
+  test("falls back to global mode section when project has none", async () => {
     // Write global instruction file with mode section
     await fs.writeFile(
       path.join(globalDir, "AGENTS.md"),
@@ -142,19 +145,19 @@ Global plan instructions.
 `
     );
 
-    // Write workspace instruction file WITHOUT mode section
+    // Write project instruction file WITHOUT mode section
     await fs.writeFile(
-      path.join(workspaceDir, "AGENTS.md"),
-      `# Workspace Instructions
-Just general workspace stuff.
+      path.join(projectDir, "AGENTS.md"),
+      `# Project Instructions
+Just general project stuff.
 `
     );
 
     const metadata: WorkspaceMetadata = {
       id: "test-workspace",
       name: "test-workspace",
       projectName: "test-project",
-      projectPath: tempDir,
+      projectPath: projectDir,
     };
 
     const systemMessage = await buildSystemMessage(metadata, workspaceDir, "plan");
@@ -165,7 +168,7 @@ Just general workspace stuff.
 
   test("handles mode with special characters by sanitizing tag name", async () => {
     await fs.writeFile(
-      path.join(workspaceDir, "AGENTS.md"),
+      path.join(projectDir, "AGENTS.md"),
       `## Mode: My-Special_Mode!
 Special mode instructions.
 `
@@ -175,7 +178,7 @@ Special mode instructions.
       id: "test-workspace",
       name: "test-workspace",
       projectName: "test-project",
-      projectPath: tempDir,
+      projectPath: projectDir,
     };
 
     const systemMessage = await buildSystemMessage(metadata, workspaceDir, "My-Special_Mode!");

src/services/systemMessage.ts

@@ -55,10 +55,10 @@ function getSystemDirectory(): string {
  *
  * Instruction sources are layered in this order:
  * 1. Global instructions: ~/.cmux/AGENTS.md (+ AGENTS.local.md)
- * 2. Workspace instructions: <workspace>/AGENTS.md (+ AGENTS.local.md)
+ * 2. Project instructions: <projectPath>/AGENTS.md (+ AGENTS.local.md)
  * 3. Mode-specific context (if mode provided): Extract a section titled "Mode: <mode>"
  *    (case-insensitive) from the instruction file. We search at most one section in
- *    precedence order: workspace instructions first, then global instructions.
+ *    precedence order: project instructions first, then global instructions.
  *
  * Each instruction file location is searched for in priority order:
  * - AGENTS.md
@@ -68,8 +68,8 @@ function getSystemDirectory(): string {
  * If a base instruction file is found, its corresponding .local.md variant is also
  * checked and appended when building the instruction set (useful for personal preferences not committed to git).
  *
- * @param metadata - Workspace metadata
- * @param workspacePath - Absolute path to the workspace worktree directory
+ * @param metadata - Workspace metadata (contains projectPath for reading AGENTS.md)
+ * @param workspacePath - Absolute path to the workspace directory (for environment context)
  * @param mode - Optional mode name (e.g., "plan", "exec") - looks for {MODE}.md files if provided
  * @param additionalSystemInstructions - Optional additional system instructions to append at the end
  * @returns System message string with all instruction sources combined
@@ -90,21 +90,22 @@ export async function buildSystemMessage(
   }
 
   const systemDir = getSystemDirectory();
-  const workspaceDir = workspacePath;
+  const projectDir = metadata.projectPath;
 
-  // Gather instruction sets from both global and workspace directories
-  // Global instructions apply first, then workspace-specific ones
-  const instructionDirectories = [systemDir, workspaceDir];
+  // Gather instruction sets from both global and project directories
+  // Global instructions apply first, then project-specific ones
+  // Note: We read from projectPath (the main repo) not workspacePath (the worktree)
+  const instructionDirectories = [systemDir, projectDir];
   const instructionSegments = await gatherInstructionSets(instructionDirectories);
   const customInstructions = instructionSegments.join("\n\n");
 
-  // Look for a "Mode: <mode>" section inside instruction sets, preferring workspace over global
+  // Look for a "Mode: <mode>" section inside instruction sets, preferring project over global
   // This behavior is documented in docs/instruction-files.md - keep both in sync when changing.
   let modeContent: string | null = null;
   if (mode) {
-    const workspaceInstructions = await readInstructionSet(workspaceDir);
-    if (workspaceInstructions) {
-      modeContent = extractModeSection(workspaceInstructions, mode);
+    const projectInstructions = await readInstructionSet(projectDir);
+    if (projectInstructions) {
+      modeContent = extractModeSection(projectInstructions, mode);
     }
     if (!modeContent) {
       const globalInstructions = await readInstructionSet(systemDir);
@@ -115,7 +116,8 @@ export async function buildSystemMessage(
   }
 
   // Build the final system message
-  const environmentContext = buildEnvironmentContext(workspaceDir);
+  // Use workspacePath for environment context (where code actually executes)
+  const environmentContext = buildEnvironmentContext(workspacePath);
   const trimmedPrelude = PRELUDE.trim();
   let systemMessage = `${trimmedPrelude}\n\n${environmentContext}`;