Clarify AGENTS.md layering: workspace replaces project, not layers

Make it clear that workspace and project instructions are mutually exclusive:
- Global instructions are always layered
- Workspace instructions REPLACE project instructions (not layered)
- Project instructions are only used as fallback when workspace doesn't exist

Changes:
- Simplified logic to only read project if workspace doesn't exist
- Updated comments to emphasize replacement vs layering
- Updated documentation to make behavior crystal clear
- Mode extraction only checks workspace OR project, not both

Author: ammar-agent

docs/instruction-files.md

@@ -2,15 +2,16 @@
 
 ## Overview
 
-cmux layers instructions from multiple locations:
+cmux layers instructions from two sources:
 
-1. `~/.cmux/AGENTS.md` (+ optional `AGENTS.local.md`) — global defaults
-2. `<workspace>/AGENTS.md` (+ optional `AGENTS.local.md`) — workspace-specific context (if exists)
-3. `<project>/AGENTS.md` (+ optional `AGENTS.local.md`) — project fallback
+1. **Global**: `~/.cmux/AGENTS.md` (+ optional `AGENTS.local.md`) — always included
+2. **Context**: Either workspace OR project AGENTS.md (not both):
+   - **Workspace**: `<workspace>/AGENTS.md` (+ optional `AGENTS.local.md`) — if exists
+   - **Project**: `<project>/AGENTS.md` (+ optional `AGENTS.local.md`) — fallback if workspace doesn't exist
 
 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.
 
-**Fallback behavior**: If a workspace doesn't have its own AGENTS.md, the project root's AGENTS.md is used as a fallback. This is particularly useful for SSH workspaces where files may not be fully cloned yet.
+**Fallback behavior**: Workspace instructions **replace** project instructions (not layered). If a workspace doesn't have AGENTS.md, the project root's AGENTS.md is used. This is particularly useful for SSH workspaces where files may not be fully cloned yet.
 
 ## Mode Prompts
 
@@ -22,7 +23,7 @@ cmux reads mode context from sections inside your instruction files. Add a headi
 
 Rules:
 
-- Workspace instructions are checked first, then project, then global instructions
+- Context instructions (workspace or project fallback) 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.ts

@@ -96,13 +96,13 @@ async function readInstructionSetFromRuntime(
 /**
  * Builds a system message for the AI model by combining multiple instruction sources.
  *
- * Instruction sources are layered in this order:
- * 1. Global instructions: ~/.cmux/AGENTS.md (+ AGENTS.local.md)
- * 2. Workspace instructions: <workspacePath>/AGENTS.md (+ AGENTS.local.md) - if exists
- * 3. Project instructions: <projectPath>/AGENTS.md (+ AGENTS.local.md) - fallback if workspace doesn't have one
- * 4. 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 project, then global instructions.
+ * Instruction sources are layered as follows:
+ * 1. Global instructions: ~/.cmux/AGENTS.md (+ AGENTS.local.md) - always included
+ * 2. Context instructions: EITHER workspace OR project AGENTS.md (not both)
+ *    - Workspace: <workspacePath>/AGENTS.md (+ AGENTS.local.md) - if exists (read via runtime)
+ *    - Project: <projectPath>/AGENTS.md (+ AGENTS.local.md) - fallback if workspace doesn't exist
+ * 3. Mode-specific context (if mode provided): Extract a section titled "Mode: <mode>"
+ *    (case-insensitive) from the instruction file. Priority: context instructions, then global.
  *
  * Each instruction file location is searched for in priority order:
  * - AGENTS.md
@@ -138,43 +138,34 @@ export async function buildSystemMessage(
   const systemDir = getSystemDirectory();
   const projectDir = metadata.projectPath;
 
-  // Read workspace instructions using runtime (may be remote for SSH)
-  // Try to read AGENTS.md from workspace directory first
+  // Layer 1: Global instructions (always included)
+  const globalInstructions = await readInstructionSet(systemDir);
+
+  // Layer 2: Workspace OR Project instructions (not both)
+  // Try workspace first (via runtime, may be remote for SSH)
+  // Fall back to project if workspace doesn't have AGENTS.md
   const workspaceInstructions = await readInstructionSetFromRuntime(runtime, workspacePath);
+  const projectInstructions = workspaceInstructions ? null : await readInstructionSet(projectDir);
 
-  // Gather instruction sets from global and project directories (always local)
-  // Note: We gather from both systemDir and projectDir, but workspace is handled separately
-  const localInstructionDirs = [systemDir, projectDir];
-  const localInstructionSegments = await gatherInstructionSets(localInstructionDirs);
-
-  // Combine all instruction sources
-  // Priority: global, workspace (if found), project (as fallback)
-  const allSegments = [...localInstructionSegments];
-  if (workspaceInstructions) {
-    // Insert workspace instructions after global (index 0) but before project
-    allSegments.splice(1, 0, workspaceInstructions);
-  }
-  const customInstructions = allSegments.join("\n\n");
+  // Combine instruction sources
+  // Result: global + (workspace OR project)
+  const instructionSegments = [globalInstructions, workspaceInstructions || projectInstructions].filter(
+    Boolean
+  );
+  const customInstructions = instructionSegments.join("\n\n");
 
   // Look for a "Mode: <mode>" section inside instruction sets
-  // Priority: workspace instructions, then project, then global
+  // Priority: workspace (or project fallback), then global
+  // We only check the workspace OR project instructions, not both
   // This behavior is documented in docs/instruction-files.md - keep both in sync when changing.
   let modeContent: string | null = null;
   if (mode) {
-    if (workspaceInstructions) {
-      modeContent = extractModeSection(workspaceInstructions, mode);
-    }
-    if (!modeContent) {
-      const projectInstructions = await readInstructionSet(projectDir);
-      if (projectInstructions) {
-        modeContent = extractModeSection(projectInstructions, mode);
-      }
+    const contextInstructions = workspaceInstructions || projectInstructions;
+    if (contextInstructions) {
+      modeContent = extractModeSection(contextInstructions, mode);
     }
-    if (!modeContent) {
-      const globalInstructions = await readInstructionSet(systemDir);
-      if (globalInstructions) {
-        modeContent = extractModeSection(globalInstructions, mode);
-      }
+    if (!modeContent && globalInstructions) {
+      modeContent = extractModeSection(globalInstructions, mode);
     }
   }