@yeaft/webchat-agent 0.1.62 → 0.1.64

package/claude.js

@@ -1,7 +1,15 @@
 import { query, Stream } from './sdk/index.js';
 import ctx from './context.js';
 import { sendConversationList, sendOutput, sendError, handleAskUserQuestion } from './conversation.js';
-import { buildRolePlaySystemPrompt } from './roleplay.js';
+import {
+  buildRolePlaySystemPrompt,
+  rolePlaySessions,
+  initRolePlayRouteState,
+  detectRoleSignal,
+  processRolePlayRoutes,
+  buildRouteEventMessage,
+  getRolePlayRouteState
+} from './roleplay.js';
 
 /**
  * Start a Claude SDK query for a conversation
@@ -89,6 +97,12 @@ export async function startClaudeQuery(conversationId, workDir, resumeSessionId)
   if (savedRolePlayConfig) {
     options.appendSystemPrompt = buildRolePlaySystemPrompt(savedRolePlayConfig);
     console.log(`[SDK] RolePlay appendSystemPrompt injected (teamType: ${savedRolePlayConfig.teamType})`);
+
+    // Initialize RolePlay route state if session exists
+    const rpSession = rolePlaySessions.get(conversationId);
+    if (rpSession) {
+      initRolePlayRouteState(rpSession, state);
+    }
   }
 
   // Validate session ID is a valid UUID before using it
@@ -414,6 +428,51 @@ async function processClaudeOutput(conversationId, claudeQuery, state) {
           continue;
         }
 
+        // ★ RolePlay ROUTE detection: check accumulated text for ROUTE blocks
+        const rpSession = state.rolePlayConfig ? rolePlaySessions.get(conversationId) : null;
+        let roleplayAutoContinue = false;
+        let roleplayContinueRoles = [];
+
+        if (rpSession && rpSession._routeInitialized && state._roleplayAccumulated) {
+          const { routes, hasHumanRoute, continueRoles } = processRolePlayRoutes(
+            state._roleplayAccumulated, rpSession
+          );
+
+          if (routes.length > 0) {
+            // Send route events to frontend
+            for (const route of routes) {
+              const routeEvent = buildRouteEventMessage(
+                conversationId, rpSession.currentRole || 'unknown', route
+              );
+              ctx.sendToServer(routeEvent);
+            }
+
+            // Send route state update
+            const routeState = getRolePlayRouteState(conversationId);
+            if (routeState) {
+              ctx.sendToServer({
+                type: 'roleplay_status',
+                conversationId,
+                ...routeState
+              });
+            }
+
+            if (hasHumanRoute) {
+              // Stop auto-continue, wait for user input
+              ctx.sendToServer({
+                type: 'roleplay_waiting_human',
+                conversationId,
+                fromRole: rpSession.currentRole,
+                message: rpSession.waitingHumanContext?.message || ''
+              });
+            } else if (continueRoles.length > 0) {
+              // Auto-continue: pick the first route target and send the prompt
+              roleplayAutoContinue = true;
+              roleplayContinueRoles = continueRoles;
+            }
+          }
+        }
+
         // ★ Turn 完成：发送 turn_completed，进程继续运行等待下一条消息
         // stream-json 模式下 Claude 进程是持久运行的，for-await 在 result 后继续等待
         // 不清空 state.query 和 state.inputStream，下次用户消息直接通过同一个 inputStream 发送
@@ -424,6 +483,47 @@ async function processClaudeOutput(conversationId, claudeQuery, state) {
         // ★ await 确保 result 和 turn_completed 消息确实发送成功
         // 不 await 会导致 encrypt 失败时消息静默丢失，前端卡在"思考中"
         await sendOutput(conversationId, message);
+
+        // ★ RolePlay auto-continue: inject next role's prompt into the same conversation
+        if (roleplayAutoContinue && rpSession && state.inputStream) {
+          // Reset accumulated text for next turn
+          state._roleplayAccumulated = '';
+
+          for (const { to, prompt, taskId, taskTitle } of roleplayContinueRoles) {
+            rpSession.currentRole = to;
+            if (rpSession.roleStates[to]) {
+              rpSession.roleStates[to].status = 'active';
+            }
+
+            console.log(`[RolePlay] Auto-continuing to role: ${to}`);
+
+            // Re-activate the turn
+            state.turnActive = true;
+            state.turnResultReceived = false;
+
+            // Send the continuation prompt through the same input stream
+            const userMessage = {
+              type: 'user',
+              message: { role: 'user', content: prompt }
+            };
+            sendOutput(conversationId, userMessage);
+            state.inputStream.enqueue(userMessage);
+
+            // RolePlay uses a single conversation — only one target can be active
+            // at a time. Additional route targets are ignored.
+            break;
+          }
+
+          // Send status update (don't send turn_completed yet since we're continuing)
+          sendConversationList();
+          continue;
+        }
+
+        // Reset accumulated text
+        if (state._roleplayAccumulated !== undefined) {
+          state._roleplayAccumulated = '';
+        }
+
         await ctx.sendToServer({
           type: 'turn_completed',
           conversationId,
@@ -434,9 +534,61 @@ async function processClaudeOutput(conversationId, claudeQuery, state) {
         continue;
       }
 
+      // ★ RolePlay: accumulate assistant text and detect ROLE signals
+      if (state.rolePlayConfig && message.type === 'assistant' && message.message?.content) {
+        const content = message.message.content;
+        let textChunk = '';
+        if (typeof content === 'string') {
+          textChunk = content;
+        } else if (Array.isArray(content)) {
+          textChunk = content.filter(b => b.type === 'text').map(b => b.text).join('');
+        }
+        if (textChunk) {
+          if (state._roleplayAccumulated === undefined) {
+            state._roleplayAccumulated = '';
+          }
+          state._roleplayAccumulated += textChunk;
+
+          // Detect ROLE signal for current role tracking
+          const rpSession = rolePlaySessions.get(conversationId);
+          if (rpSession && rpSession._routeInitialized) {
+            const detectedRole = detectRoleSignal(textChunk);
+            if (detectedRole) {
+              const prevRole = rpSession.currentRole;
+              rpSession.currentRole = detectedRole;
+              if (rpSession.roleStates[detectedRole]) {
+                rpSession.roleStates[detectedRole].status = 'active';
+              }
+              if (prevRole && prevRole !== detectedRole && rpSession.roleStates[prevRole]) {
+                rpSession.roleStates[prevRole].status = 'idle';
+              }
+              console.log(`[RolePlay] Role switched: ${prevRole || 'none'} -> ${detectedRole}`);
+            }
+          }
+        }
+      }
+
       // 检测后台任务
       detectAndTrackBackgroundTask(conversationId, state, message);
 
+      // ★ RolePlay: attach role metadata to messages sent to frontend
+      if (state.rolePlayConfig) {
+        const rpSession = rolePlaySessions.get(conversationId);
+        if (rpSession && rpSession._routeInitialized) {
+          // Attach current role info to the message as metadata
+          const enrichedMessage = {
+            ...message,
+            _roleplay: {
+              role: rpSession.currentRole,
+              features: rpSession.features ? Array.from(rpSession.features.values()) : [],
+              round: rpSession.round
+            }
+          };
+          sendOutput(conversationId, enrichedMessage);
+          continue;
+        }
+      }
+
       sendOutput(conversationId, message);
     }
   } catch (error) {

package/connection/message-router.js

@@ -12,7 +12,7 @@ import {
   createConversation, resumeConversation, deleteConversation,
   handleRefreshConversation, handleCancelExecution,
   handleUserInput, handleUpdateConversationSettings, handleAskUserAnswer,
-  sendConversationList
+  sendConversationList, handleCheckCrewContext
 } from '../conversation.js';
 import {
   createCrewSession, handleCrewHumanInput, handleCrewControl,
@@ -66,6 +66,10 @@ export async function handleMessage(msg) {
       await createConversation(msg);
       break;
 
+    case 'check_crew_context':
+      handleCheckCrewContext(msg);
+      break;
+
     case 'resume_conversation':
       await resumeConversation(msg);
       break;

package/conversation.js

@@ -2,7 +2,7 @@ import ctx from './context.js';
 import { loadSessionHistory } from './history.js';
 import { startClaudeQuery } from './claude.js';
 import { crewSessions, loadCrewIndex } from './crew.js';
-import { rolePlaySessions, saveRolePlayIndex, removeRolePlaySession, loadRolePlayIndex, validateRolePlayConfig } from './roleplay.js';
+import { rolePlaySessions, saveRolePlayIndex, removeRolePlaySession, loadRolePlayIndex, validateRolePlayConfig, initRolePlayRouteState, loadCrewContext } from './roleplay.js';
 
 // Restore persisted roleplay sessions on module load (agent startup)
 loadRolePlayIndex();
@@ -54,7 +54,17 @@ export async function sendConversationList() {
     // roleplay conversations are stored in ctx.conversations but also tracked in rolePlaySessions
     if (rolePlaySessions.has(id)) {
       entry.type = 'rolePlay';
-      entry.rolePlayRoles = rolePlaySessions.get(id).roles;
+      const rpSession = rolePlaySessions.get(id);
+      entry.rolePlayRoles = rpSession.roles;
+      // Include route state if initialized
+      if (rpSession._routeInitialized) {
+        entry.rolePlayState = {
+          currentRole: rpSession.currentRole,
+          round: rpSession.round,
+          features: rpSession.features ? Array.from(rpSession.features.values()) : [],
+          waitingHuman: rpSession.waitingHuman || false
+        };
+      }
     }
     list.push(entry);
   }
@@ -130,6 +140,15 @@ export async function createConversation(msg) {
     rolePlayConfig = result.config;
   }
 
+  // Load .crew context if rolePlay and projectDir contains .crew directory
+  if (rolePlayConfig) {
+    const crewContext = loadCrewContext(effectiveWorkDir);
+    if (crewContext) {
+      rolePlayConfig.crewContext = crewContext;
+      console.log(`  RolePlay: loaded .crew context (${crewContext.roles.length} roles, ${crewContext.features.length} features)`);
+    }
+  }
+
   console.log(`Creating conversation: ${conversationId} in ${effectiveWorkDir} (lazy start)`);
   if (username) console.log(`  User: ${username} (${userId})`);
   if (rolePlayConfig) console.log(`  RolePlay: teamType=${rolePlayConfig.teamType}, roles=${rolePlayConfig.roles?.length}`);
@@ -161,7 +180,7 @@ export async function createConversation(msg) {
 
   // Register in rolePlaySessions for type inference in sendConversationList
   if (rolePlayConfig) {
-    rolePlaySessions.set(conversationId, {
+    const rpSession = {
       roles: rolePlayConfig.roles,
       teamType: rolePlayConfig.teamType,
       language: rolePlayConfig.language,
@@ -169,7 +188,10 @@ export async function createConversation(msg) {
       createdAt: Date.now(),
       userId,
       username,
-    });
+    };
+    rolePlaySessions.set(conversationId, rpSession);
+    // Initialize route state eagerly so it's ready when Claude starts
+    initRolePlayRouteState(rpSession, ctx.conversations.get(conversationId));
     saveRolePlayIndex();
   }
 
@@ -467,9 +489,29 @@ export async function handleUserInput(msg) {
 
   // 发送用户消息到输入流
   // Claude stream-json 模式支持在回复过程中接收新消息（写入 stdin）
+  let effectivePrompt = prompt;
+
+  // ★ RolePlay: if session was waiting for human input, clear the flag and
+  // wrap the user message with context about which role was asking
+  const rpSession = rolePlaySessions.get(conversationId);
+  if (rpSession && rpSession.waitingHuman && rpSession.waitingHumanContext) {
+    const { fromRole, message: requestMessage } = rpSession.waitingHumanContext;
+    const fromRoleConfig = rpSession.roles.find?.(r => r.name === fromRole) ||
+                           (Array.isArray(rpSession.roles) ? rpSession.roles.find(r => r.name === fromRole) : null);
+    const fromLabel = fromRoleConfig
+      ? (fromRoleConfig.icon ? `${fromRoleConfig.icon} ${fromRoleConfig.displayName}` : fromRoleConfig.displayName)
+      : fromRole;
+
+    effectivePrompt = `人工回复（回应 ${fromLabel} 的请求: "${requestMessage}"）:\n\n${prompt}`;
+
+    rpSession.waitingHuman = false;
+    rpSession.waitingHumanContext = null;
+    console.log(`[RolePlay] Human responded, resuming from ${fromRole}'s request`);
+  }
+
   const userMessage = {
     type: 'user',
-    message: { role: 'user', content: prompt }
+    message: { role: 'user', content: effectivePrompt }
   };
 
   console.log(`[${conversationId}] Sending: ${prompt.substring(0, 100)}...`);
@@ -556,3 +598,38 @@ export function handleAskUserAnswer(msg) {
     console.log(`[AskUser] No pending question for requestId: ${msg.requestId}`);
   }
 }
+
+/**
+ * Handle check_crew_context request — check if a directory has .crew context
+ * and return role/context info for RolePlay auto-import.
+ */
+export function handleCheckCrewContext(msg) {
+  const { projectDir, requestId } = msg;
+  if (!projectDir) {
+    ctx.sendToServer({ type: 'crew_context_result', requestId, found: false });
+    return;
+  }
+  const crewContext = loadCrewContext(projectDir);
+  if (!crewContext) {
+    ctx.sendToServer({ type: 'crew_context_result', requestId, found: false });
+    return;
+  }
+  // Return a safe subset for the frontend (no full claudeMd content, just metadata)
+  ctx.sendToServer({
+    type: 'crew_context_result',
+    requestId,
+    found: true,
+    roles: crewContext.roles.map(r => ({
+      name: r.name,
+      displayName: r.displayName,
+      icon: r.icon,
+      description: r.description,
+      roleType: r.roleType,
+      isDecisionMaker: r.isDecisionMaker,
+      hasClaudeMd: !!(r.claudeMd && r.claudeMd.length > 0),
+    })),
+    teamType: crewContext.teamType,
+    language: crewContext.language,
+    featureCount: crewContext.features.length,
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.62",
+  "version": "0.1.64",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/roleplay.js

@@ -1,13 +1,16 @@
 /**
  * Role Play — lightweight multi-role collaboration within a single conversation.
  *
- * Manages rolePlaySessions (in-memory + persisted to disk) and builds the
- * appendSystemPrompt that instructs Claude to role-play multiple characters.
+ * Manages rolePlaySessions (in-memory + persisted to disk), builds the
+ * appendSystemPrompt that instructs Claude to role-play multiple characters,
+ * and handles ROUTE protocol for Crew-style role switching within a single
+ * Claude conversation.
  */
 
 import { join } from 'path';
 import { homedir } from 'os';
-import { readFileSync, writeFileSync, existsSync, renameSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, renameSync, readdirSync } from 'fs';
+import { parseRoutes } from './crew/routing.js';
 
 const ROLEPLAY_INDEX_PATH = join(homedir(), '.claude', 'roleplay-sessions.json');
 // ★ backward compat: old filename before rename
@@ -23,7 +26,9 @@ export const rolePlaySessions = new Map();
 export function saveRolePlayIndex() {
   const data = [];
   for (const [id, session] of rolePlaySessions) {
-    data.push({ id, ...session });
+    // Only persist core fields, skip runtime route state
+    const { _routeInitialized, currentRole, features, round, roleStates, waitingHuman, waitingHumanContext, ...core } = session;
+    data.push({ id, ...core });
   }
   try {
     writeFileSync(ROLEPLAY_INDEX_PATH, JSON.stringify(data, null, 2));
@@ -65,6 +70,147 @@ export function removeRolePlaySession(conversationId) {
   saveRolePlayIndex();
 }
 
+// ---------------------------------------------------------------------------
+// .crew context import
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a file if it exists, otherwise return null.
+ * @param {string} filePath
+ * @returns {string|null}
+ */
+function readFileOrNull(filePath) {
+  try {
+    if (!existsSync(filePath)) return null;
+    return readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load .crew context from a project directory.
+ * Returns null if .crew/ doesn't exist.
+ *
+ * @param {string} projectDir - absolute path to project root
+ * @returns {{ sharedClaudeMd: string, roles: Array, kanban: string, features: Array, teamType: string, language: string } | null}
+ */
+export function loadCrewContext(projectDir) {
+  const crewDir = join(projectDir, '.crew');
+  if (!existsSync(crewDir)) return null;
+
+  // 1. Shared CLAUDE.md
+  const sharedClaudeMd = readFileOrNull(join(crewDir, 'CLAUDE.md')) || '';
+
+  // 2. session.json → roles, teamType, language, features
+  let sessionRoles = [];
+  let teamType = 'dev';
+  let language = 'zh-CN';
+  let sessionFeatures = [];
+  const sessionPath = join(crewDir, 'session.json');
+  const sessionJson = readFileOrNull(sessionPath);
+  if (sessionJson) {
+    try {
+      const session = JSON.parse(sessionJson);
+      if (Array.isArray(session.roles)) {
+        sessionRoles = session.roles;
+      }
+      if (session.teamType) teamType = session.teamType;
+      if (session.language) language = session.language;
+      if (Array.isArray(session.features)) {
+        sessionFeatures = session.features;
+      }
+    } catch {
+      // Invalid JSON — ignore
+    }
+  }
+
+  // 3. Per-role CLAUDE.md from .crew/roles/*/CLAUDE.md
+  const roleClaudes = {};
+  const rolesDir = join(crewDir, 'roles');
+  if (existsSync(rolesDir)) {
+    try {
+      const roleDirs = readdirSync(rolesDir, { withFileTypes: true })
+        .filter(d => d.isDirectory())
+        .map(d => d.name);
+      for (const dirName of roleDirs) {
+        const md = readFileOrNull(join(rolesDir, dirName, 'CLAUDE.md'));
+        if (md) roleClaudes[dirName] = md;
+      }
+    } catch {
+      // Permission error or similar — ignore
+    }
+  }
+
+  // 4. Merge roles: deduplicate by roleType, attach claudeMd
+  const roles = deduplicateRoles(sessionRoles, roleClaudes);
+
+  // 5. Kanban
+  const kanban = readFileOrNull(join(crewDir, 'context', 'kanban.md')) || '';
+
+  // 6. Feature files from context/features/*.md
+  const features = [];
+  const featuresDir = join(crewDir, 'context', 'features');
+  if (existsSync(featuresDir)) {
+    try {
+      const files = readdirSync(featuresDir)
+        .filter(f => f.endsWith('.md') && f !== 'index.md')
+        .sort();
+      for (const f of files) {
+        const content = readFileOrNull(join(featuresDir, f));
+        if (content) {
+          features.push({ name: f.replace('.md', ''), content });
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  return { sharedClaudeMd, roles, kanban, features, teamType, language, sessionFeatures };
+}
+
+/**
+ * Deduplicate Crew roles by roleType.
+ * Crew may have dev-1, dev-2, dev-3 — collapse to a single "dev" for RolePlay.
+ * Attaches per-role CLAUDE.md content.
+ */
+function deduplicateRoles(sessionRoles, roleClaudes) {
+  const byType = new Map(); // roleType -> first role seen
+  const merged = [];
+
+  for (const r of sessionRoles) {
+    const type = r.roleType || r.name;
+    const claudeMd = roleClaudes[r.name] || '';
+
+    if (byType.has(type)) {
+      // Already have this roleType — skip duplicate instance
+      continue;
+    }
+
+    byType.set(type, true);
+
+    // Use roleType as the RolePlay name (e.g. "developer" instead of "dev-1")
+    // But keep "pm" and "designer" as-is since they're typically single-instance
+    const name = type;
+    // Strip instance suffix from displayName (e.g. "开发者-托瓦兹-1" → "开发者-托瓦兹")
+    let displayName = r.displayName || name;
+    displayName = displayName.replace(/-\d+$/, '');
+
+    merged.push({
+      name,
+      displayName,
+      icon: r.icon || '',
+      description: r.description || '',
+      claudeMd: claudeMd.substring(0, MAX_CLAUDE_MD_LEN),
+      roleType: type,
+      isDecisionMaker: !!r.isDecisionMaker,
+    });
+  }
+
+  return merged;
+}
+
 // ---------------------------------------------------------------------------
 // Input validation
 // ---------------------------------------------------------------------------
@@ -160,11 +306,11 @@ export function validateRolePlayConfig(config) {
  * Build the appendSystemPrompt that tells Claude about the role play roles
  * and how to switch between them.
  *
- * @param {{ roles: Array, teamType: string, language: string }} config
+ * @param {{ roles: Array, teamType: string, language: string, crewContext?: object }} config
  * @returns {string}
  */
 export function buildRolePlaySystemPrompt(config) {
-  const { roles, teamType, language } = config;
+  const { roles, teamType, language, crewContext } = config;
   const isZh = language === 'zh-CN';
 
   // Build role list
@@ -181,6 +327,14 @@ export function buildRolePlaySystemPrompt(config) {
     ? buildZhPrompt(roleList, workflow)
     : buildEnPrompt(roleList, workflow);
 
+  // Append .crew context if available
+  if (crewContext) {
+    const contextBlock = buildCrewContextBlock(crewContext, isZh);
+    if (contextBlock) {
+      return (prompt + '\n\n' + contextBlock).trim();
+    }
+  }
+
   return prompt.trim();
 }
 
@@ -196,17 +350,37 @@ ${roleList}
 
 ## 角色切换规则
 
-切换角色时，输出以下信号（必须独占一行，前后不能有其他内容）：
+### 方式一：ROUTE 协议（推荐）
+
+当一个角色完成工作需要交给另一个角色时，使用 ROUTE 块：
+
+\`\`\`
+---ROUTE---
+to: {目标角色name}
+summary: {交接内容摘要}
+task: {任务ID，如 task-1}（可选）
+taskTitle: {任务标题}（可选）
+---END_ROUTE---
+\`\`\`
+
+ROUTE 规则：
+- 一次可以输出多个 ROUTE 块（例如同时发给 reviewer 和 tester）
+- \`to\` 必须是有效的角色 name，或 \`human\` 表示需要用户输入
+- \`summary\` 是交给目标角色的具体任务和上下文
+- \`task\` / \`taskTitle\` 用于追踪 feature/任务（PM 分配任务时应填写）
+- ROUTE 块必须在角色输出的末尾
+
+### 方式二：ROLE 信号（简单切换）
 
 ---ROLE: {角色name}---
 
-切换后，你必须完全以该角色的视角和人格思考、说话和行动。不要混用其他角色的口吻。
+直接切换到目标角色继续工作，适用于简单的角色轮转。
 
-**重要**：
+### 通用规则
+
+- 切换后，你必须完全以该角色的视角和人格思考、说话和行动
 - 第一条输出必须先切换到起始角色（通常是 PM）
-- 每次切换时先用 1-2 句话说明为什么要切换（作为上一个角色的收尾）
-- 切换后立即以新角色身份开始工作
-- 信号格式必须严格匹配：三个短横线 + ROLE: + 空格 + 角色name + 三个短横线
+- 每次切换前留下交接信息（完成了什么、对下一角色的要求）
 
 ## 工作流程
 
@@ -243,17 +417,37 @@ ${roleList}
 
 ## Role Switching Rules
 
-When switching roles, output the following signal (must be on its own line, nothing else before or after):
+### Method 1: ROUTE Protocol (Recommended)
+
+When a role finishes work and needs to hand off to another role, use a ROUTE block:
+
+\`\`\`
+---ROUTE---
+to: {target_role_name}
+summary: {handoff content summary}
+task: {task ID, e.g. task-1} (optional)
+taskTitle: {task title} (optional)
+---END_ROUTE---
+\`\`\`
+
+ROUTE rules:
+- You can output multiple ROUTE blocks at once (e.g., send to both reviewer and tester)
+- \`to\` must be a valid role name, or \`human\` to request user input
+- \`summary\` is the specific task and context for the target role
+- \`task\` / \`taskTitle\` are for tracking features/tasks (PM should fill these when assigning)
+- ROUTE blocks must be at the end of the role's output
+
+### Method 2: ROLE Signal (Simple Switch)
 
 ---ROLE: {role_name}---
 
-After switching, you must fully think, speak, and act from that role's perspective and personality. Do not mix tones from other roles.
+Directly switch to the target role to continue working. Suitable for simple role rotation.
 
-**Important**:
+### General Rules
+
+- After switching, you must fully think, speak, and act from that role's perspective
 - Your first output must switch to the starting role (usually PM)
-- Before each switch, briefly explain why you're switching (as closure for the current role)
-- After switching, immediately begin working as the new role
-- Signal format must strictly match: three hyphens + ROLE: + space + role_name + three hyphens
+- Before each switch, leave handoff information (what was done, requirements for next role)
 
 ## Workflow
 
@@ -320,3 +514,205 @@ function buildDevWorkflow(roleNames, isZh) {
 
   return steps.join('\n');
 }
+
+// ---------------------------------------------------------------------------
+// RolePlay ROUTE protocol support
+// ---------------------------------------------------------------------------
+
+// Re-export parseRoutes for use by claude.js and tests
+export { parseRoutes } from './crew/routing.js';
+
+/**
+ * Initialize RolePlay route state on a session.
+ * Called when a roleplay conversation is first created or resumed.
+ *
+ * @param {object} session - rolePlaySessions entry
+ * @param {object} convState - ctx.conversations entry
+ */
+export function initRolePlayRouteState(session, convState) {
+  if (!session._routeInitialized) {
+    session.currentRole = null;
+    session.features = new Map();
+    session.round = 0;
+    session.roleStates = {};
+    session.waitingHuman = false;
+    session.waitingHumanContext = null;
+
+    // Initialize per-role states
+    for (const role of session.roles) {
+      session.roleStates[role.name] = {
+        currentTask: null,
+        status: 'idle'
+      };
+    }
+    session._routeInitialized = true;
+  }
+
+  // Also store accumulated text on convState for ROUTE detection during streaming
+  if (!convState._roleplayAccumulated) {
+    convState._roleplayAccumulated = '';
+  }
+}
+
+/**
+ * Detect a ROLE signal in text: ---ROLE: xxx---
+ * Returns the role name if found at the end of accumulated text, null otherwise.
+ */
+export function detectRoleSignal(text) {
+  const match = text.match(/---ROLE:\s*([a-zA-Z0-9_-]+)\s*---/);
+  return match ? match[1].toLowerCase() : null;
+}
+
+/**
+ * Process ROUTE blocks detected in a completed turn's output.
+ * Called from claude.js when a result message is received.
+ *
+ * Returns { routes, hasHumanRoute, continueRoles } for the caller to act on.
+ *
+ * @param {string} accumulatedText - full text output from the current turn
+ * @param {object} session - rolePlaySessions entry
+ * @returns {{ routes: Array, hasHumanRoute: boolean, continueRoles: Array<{to, prompt}> }}
+ */
+export function processRolePlayRoutes(accumulatedText, session) {
+  const routes = parseRoutes(accumulatedText);
+  if (routes.length === 0) {
+    return { routes: [], hasHumanRoute: false, continueRoles: [] };
+  }
+
+  const roleNames = new Set(session.roles.map(r => r.name));
+  let hasHumanRoute = false;
+  const continueRoles = [];
+
+  for (const route of routes) {
+    const { to, summary, taskId, taskTitle } = route;
+
+    // Track features
+    if (taskId && taskTitle && !session.features.has(taskId)) {
+      session.features.set(taskId, { taskId, taskTitle, createdAt: Date.now() });
+    }
+
+    // Update source role state
+    if (session.currentRole && session.roleStates[session.currentRole]) {
+      session.roleStates[session.currentRole].status = 'idle';
+    }
+
+    if (to === 'human') {
+      hasHumanRoute = true;
+      session.waitingHuman = true;
+      session.waitingHumanContext = {
+        fromRole: session.currentRole,
+        reason: 'requested',
+        message: summary
+      };
+    } else if (roleNames.has(to)) {
+      // Update target role state
+      if (session.roleStates[to]) {
+        session.roleStates[to].status = 'active';
+        if (taskId) {
+          session.roleStates[to].currentTask = { taskId, taskTitle };
+        }
+      }
+
+      // Build prompt for the target role
+      const fromRole = session.currentRole || 'unknown';
+      const fromRoleConfig = session.roles.find(r => r.name === fromRole);
+      const fromLabel = fromRoleConfig
+        ? (fromRoleConfig.icon ? `${fromRoleConfig.icon} ${fromRoleConfig.displayName}` : fromRoleConfig.displayName)
+        : fromRole;
+
+      const targetRoleConfig = session.roles.find(r => r.name === to);
+      const targetClaudeMd = targetRoleConfig?.claudeMd || '';
+
+      let prompt = `来自 ${fromLabel} 的消息:\n${summary}\n\n`;
+      if (targetClaudeMd) {
+        prompt += `---\n<role-context>\n${targetClaudeMd}\n</role-context>\n\n`;
+      }
+      prompt += `你现在是 ${targetRoleConfig?.displayName || to}。请开始你的工作。完成后通过 ROUTE 块传递给下一个角色。`;
+
+      continueRoles.push({ to, prompt, taskId, taskTitle });
+    } else {
+      console.warn(`[RolePlay] Unknown route target: ${to}`);
+    }
+  }
+
+  // Increment round
+  session.round++;
+
+  return { routes, hasHumanRoute, continueRoles };
+}
+
+/**
+ * Build the route event message to send to the frontend via WebSocket.
+ *
+ * @param {string} conversationId
+ * @param {string} fromRole
+ * @param {{ to, summary, taskId, taskTitle }} route
+ * @returns {object} WebSocket message
+ */
+export function buildRouteEventMessage(conversationId, fromRole, route) {
+  return {
+    type: 'roleplay_route',
+    conversationId,
+    from: fromRole,
+    to: route.to,
+    taskId: route.taskId || null,
+    taskTitle: route.taskTitle || null,
+    summary: route.summary || ''
+  };
+}
+
+/**
+ * Get the current RolePlay route state summary for frontend status updates.
+ *
+ * @param {string} conversationId
+ * @returns {object|null} Route state summary or null if not a roleplay session
+ */
+export function getRolePlayRouteState(conversationId) {
+  const session = rolePlaySessions.get(conversationId);
+  if (!session || !session._routeInitialized) return null;
+
+  return {
+    currentRole: session.currentRole,
+    round: session.round,
+    features: session.features ? Array.from(session.features.values()) : [],
+    roleStates: session.roleStates || {},
+    waitingHuman: session.waitingHuman || false,
+    waitingHumanContext: session.waitingHumanContext || null
+  };
+}
+
+// ---------------------------------------------------------------------------
+// .crew context block for system prompt
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the .crew context block to append to the system prompt.
+ * Includes shared instructions, kanban, and feature history.
+ */
+function buildCrewContextBlock(crewContext, isZh) {
+  const sections = [];
+
+  if (crewContext.sharedClaudeMd) {
+    const header = isZh ? '## 项目共享指令（来自 .crew）' : '## Shared Project Instructions (from .crew)';
+    sections.push(`${header}\n\n${crewContext.sharedClaudeMd}`);
+  }
+
+  if (crewContext.kanban) {
+    const header = isZh ? '## 当前任务看板' : '## Current Task Board';
+    sections.push(`${header}\n\n${crewContext.kanban}`);
+  }
+
+  if (crewContext.features && crewContext.features.length > 0) {
+    const header = isZh ? '## 历史工作记录' : '## Work History';
+    // Only include the last few features to avoid blowing up context
+    const recentFeatures = crewContext.features.slice(-5);
+    const featureTexts = recentFeatures.map(f => {
+      // Truncate each feature to keep total size reasonable
+      const content = f.content.length > 2000 ? f.content.substring(0, 2000) + '\n...(truncated)' : f.content;
+      return `### ${f.name}\n${content}`;
+    }).join('\n\n');
+    sections.push(`${header}\n\n${featureTexts}`);
+  }
+
+  return sections.join('\n\n');
+}