Function buildPlanInstructions

src/node/services/streamContextBuilder.ts:103–222

(
  opts: BuildPlanInstructionsOptions
)

 *    used a plan-like agent
 */
export async function buildPlanInstructions(
  opts: BuildPlanInstructionsOptions
): Promise<PlanInstructionsResult> {
  const {
    runtime,
    metadata,
    workspaceId,
    effectiveMode,
    effectiveAgentId,
    agentIsPlanLike,
    agentDiscoveryRuntime,
    agentDiscoveryPath,
    additionalSystemInstructions,
    shouldDisableTaskToolsForDepth,
    taskDepth,
    taskSettings,
    requestPayloadMessages,
  } = opts;

  const workspaceLog = log.withFields({ workspaceId, workspaceName: metadata.name });

  // Construct plan mode instruction if in plan mode
  // This is done backend-side because we have access to the plan file path
  let effectiveAdditionalInstructions = additionalSystemInstructions;
  const muxHome = runtime.getMuxHome();
  const planFilePath = getPlanFilePath(metadata.name, metadata.projectName, muxHome);

  // Read plan file (handles legacy migration transparently)
  const planResult = await readPlanFile(runtime, metadata.name, metadata.projectName, workspaceId);

  const chatHasStartHerePlanSummary = hasStartHerePlanSummary(requestPayloadMessages);

  if (effectiveMode === "plan") {
    const planModeInstruction = getPlanModeInstruction(planFilePath, planResult.exists);
    effectiveAdditionalInstructions = additionalSystemInstructions
      ? `${planModeInstruction}\n\n${additionalSystemInstructions}`
      : planModeInstruction;
  } else if (planResult.exists && planResult.content.trim()) {
    // Users often use "Replace all chat history" after plan mode. In exec (or other non-plan)
    // modes, the model can lose the plan file location because plan path injection only
    // happens in plan mode.
    //
    // Exception: the ProposePlanToolCall "Start Here" flow already stores the full plan
    // (and plan path) directly in chat history. In that case, prompting the model to
    // re-open the plan file is redundant and often results in an extra "read …KB" step.
    if (!chatHasStartHerePlanSummary) {
      const planFileHint = getPlanFileHint(planFilePath, planResult.exists);
      if (planFileHint) {
        effectiveAdditionalInstructions = effectiveAdditionalInstructions
          ? `${planFileHint}\n\n${effectiveAdditionalInstructions}`
          : planFileHint;
      }
    } else {
      workspaceLog.debug(
        "Skipping plan file hint: Start Here already includes the plan in chat history."
      );
    }
  }