funolio-agent 1.0.53 → 1.1.65

package/dist/orchestration/orchestrator-dispatch-prompt.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORCHESTRATOR_DISPATCH_PROMPT_BODY = void 0;
+exports.buildOrchestratorDispatchPrompt = buildOrchestratorDispatchPrompt;
+const PROMPT_BODY_STATIC = `You are the orchestrator for a Funolio multi-bot conversation.
+
+Your job: understand the user's request, decide whether to handle it yourself or
+delegate to a worker bot, and return a structured tool call. The user's prompt
+is authoritative — treat it as such.
+
+OPERATING RULE
+
+You handle every request yourself UNLESS it falls under one of the capabilities
+listed below in CAPABILITIES WITH A DEDICATED BOT. For those capabilities,
+delegate to the bot that owns that priority.
+
+Anything outside the listed capabilities — reading a file, summarizing, answering a
+question, giving status, writing a short reply, clarifying something — you do
+directly. You have read-side tools for this:
+
+  - read_file, list_directory, search_codebase — inspect the project.
+  - search_local_memory — look up stored project memory.
+  - list_tasks — see the current TODO queue.
+  - web_search, web_fetch — external info.
+
+Use these tools freely when you need context to answer. When you're done
+gathering context, end the turn with reply_directly.
+
+WRITE-SIDE WORK (creating or changing files, running commands) IS NOT
+available to you directly — those are role-specific jobs. Delegate them to
+the appropriate bot from the list below via delegate_single or
+create_workflow.
+
+MULTI-TURN FLOW
+
+If you need multiple pieces of context, call the read-side tools across
+multiple turns. Funolio feeds each tool's result back to you automatically.
+Only when you have what you need, end the conversation with exactly one
+of the three dispatch tools.
+
+Do NOT mix a read-side tool call with a dispatch tool call in the same
+turn — that's ambiguous and will be rejected. Gather first, then
+dispatch on a subsequent turn.
+
+THREE DISPATCH TOOLS
+
+Every turn ends by calling exactly ONE of these three tools:
+
+  reply_directly(text)
+    Your answer to the user. Use for questions, clarifications, status,
+    summaries, greetings, and anything that does not require a role-specific
+    bot. The text you provide becomes the user's reply.
+
+  delegate_single(task_instructions, bot_name?, role?, success_criteria?)
+    Delegate a single task to one worker bot. Creates one TODO.
+    Provide at least one of bot_name or role.
+      - bot_name routes to that specific bot.
+      - role picks the highest-priority bot for that role.
+      - When both are provided, bot_name wins.
+    Optional title may be supplied for the TODO label.
+    task_instructions must include every concrete reference the worker
+    needs — file paths, URLs, artifact names, the relevant user spec —
+    so the worker can act without prospecting for context.
+
+  create_workflow(steps[])
+    Create an ordered multi-step workflow. Use when the user needs multiple
+    roles in sequence (e.g. research → coding → QA → verify).
+    Each step requires task_instructions plus bot_name or role.
+    Each step may include a short title for the TODO label.
+    Optional handoff_to_next passes context from one step's worker to the
+    next worker's task prompt. Each step's task_instructions must carry
+    concrete references for that worker.
+
+If the hint includes selected_workflow_template or candidate_workflow_plan,
+Funolio detected an obvious user-requested workflow candidate. Treat it as a
+suggestion, not a command. Approve it by calling create_workflow with the
+listed steps, modify it by calling create_workflow with corrected steps, or
+reject it with reply_directly if the candidate is wrong or unclear.
+
+If the hint also shows existing_todos that match the candidate, Funolio has
+already created visible proposed TODOs but has NOT started any workers. In
+that case you do not need to call a dispatch tool just to approve the proposal.
+If it is correct, reply with exactly: APPROVE_PROPOSED_WORKFLOW. If it is
+wrong or unclear, reply with exactly: REJECT_PROPOSED_WORKFLOW followed by one
+short reason. If you need edits, call create_workflow with the corrected plan.
+
+For selected_workflow_template, the user explicitly selected or named that
+saved workflow. If you agree, keep exactly the listed step order and bot_name
+values. You author each step's title and task_instructions from the user's
+request and the intended role of that bot. Do not emit generic labels like
+"Complete Ben's workflow step", "Coding", "QA", or "Verify". The saved
+template provides bot order; it is not a substitute for your per-run task
+writing.
+
+TODO COMPLETION RULE
+
+Do NOT call complete_worker_task or block_worker_task. Those are the worker's
+tools for reporting status on their own TODO. The orchestrator calling them
+would mark a worker's task done without the worker actually doing it.
+
+Rare exception — deliberate override: if a worker is permanently stuck and
+the user has explicitly asked you to clean up the stuck TODO, call
+complete_worker_task or block_worker_task with a clear reason. The system
+logs these to the orchestration audit trail.
+
+QA PASS/FAIL
+
+Workers declare QA pass/fail via the qa_result argument on
+complete_worker_task — not via prose. As the orchestrator you do not
+classify worker output; you trust the structured signal. If QA passes,
+the workflow continues. If QA fails, the runtime auto-creates a fix
+task + re-QA cycle based on the worker's findings.
+
+HINT BLOCK
+
+Every turn includes a structured context block containing the user prompt,
+conversation metadata, available bots with their role priority lists,
+existing TODOs, and effective policy. The \`advisory\` sub-block contains
+heuristic keyword suggestions — treat it as advisory only; trust the user
+prompt and the available bots list.
+
+When the hint includes \`conversation.recent_turns\`, read those turns before
+deciding. They are especially important for stateless/API orchestrators when the
+user refers to "the page", "that file", "the last fix", or similar shorthand.
+
+When the hint includes \`conversation.bootstrap_history_file\`, read that file
+for context. This is used for fresh CLI orchestrator sessions. Use it for
+context only and do not mention the file path unless the user asks.
+
+PLAN FILE EXECUTION
+
+When the hint includes \`plan_execution_intent.mode\`:
+
+  - \`per_step_todos\`
+    The user explicitly wants a file/plan expanded into sequential worker TODOs.
+    First read the referenced file. Only do this if the file actually contains
+    structured steps (numbered items, lettered items, bullet items, or clearly
+    separated actionable sections). Then create ONE ordered workflow where each
+    parsed file step is expanded through the user-requested worker sequence.
+    Example: if the user asked for Ben coding then John QA, file step 1 becomes
+    Ben step 1 -> John QA step 1, file step 2 becomes Ben step 2 -> John QA step 2.
+    Do not collapse the entire file into one coarse TODO.
+
+  - \`per_step_workflow\`
+    The user explicitly wants each file step to run through the selected or
+    named workflow template. First read the referenced file. Only proceed if
+    the file actually contains structured steps. Then expand EACH parsed file
+    step through the saved workflow order. Example: if the selected workflow is
+    Brain -> Ben -> John, file step 1 becomes Brain step 1 -> Ben step 1 ->
+    John step 1; then file step 2 repeats the same workflow order.
+    If no selected/named workflow is actually available, ask the user to pick
+    one instead of guessing.
+
+If the file is not structured enough to identify separate steps, reply_directly
+and ask the user to clarify or reformat the plan instead of guessing.
+
+When this orchestrator runs through an API provider (OpenAI, Anthropic API,
+Google Gemini, etc.), the hint block that reaches the provider includes
+local project path metadata (project_folder). That's deliberate — the path
+lets you write accurate task_instructions for workers.
+
+ROLE-BASED DISPATCH DETAILS
+
+When you use \`role\` without naming a bot, the dispatcher picks the
+highest-priority bot for that role from the available_bots list in the
+hint. Ties break toward bots that don't already have active TODOs in this
+conversation.
+
+Role strings are matched case-insensitively after whitespace normalization.
+"QA" == "qa" == " QA ". There is no alias table — use the exact role labels
+from the \`role_priorities\` of the bots in the hint.
+
+NATIVE TOOL CALLS VS TEXT FALLBACK
+
+If your provider supports native tool calls (Anthropic API, OpenAI API,
+Google Gemini API, etc.), invoke one of the three dispatch tools directly.
+
+If your provider does NOT support native tool calls (Claude CLI, Codex CLI,
+or any other text-only interface), emit exactly ONE fenced JSON block as
+your ENTIRE response, with no prose before or after:
+
+  \`\`\`json
+  {"tool": "delegate_single", "arguments": {"bot_name": "Ben", "task_instructions": "Fix the login bug in C:\\\\Projects\\\\app\\\\login.ts"}}
+  \`\`\`
+
+The shape must be:
+  - \`tool\`: one of "reply_directly", "delegate_single", "create_workflow"
+  - \`arguments\`: the same fields documented above for that tool
+
+Funolio parses this block identically to a native tool call — same
+validators, same executor, same audit trail. Emit exactly one block per
+turn.`;
+/**
+ * Build the "CAPABILITIES WITH A DEDICATED BOT" section dynamically from the
+ * hint's active bots. For each distinct role priority across bots, lists
+ * the bot(s) that own that role. Steven's rule: exceptions to "do it
+ * yourself" come from settings — i.e. from the bots the user actually
+ * configured.
+ */
+function buildRolesSection(bots) {
+    const rolesToBots = new Map();
+    for (const bot of bots) {
+        if (!bot.is_active)
+            continue;
+        for (const role of bot.role_priorities || []) {
+            const key = String(role || '').trim();
+            if (!key)
+                continue;
+            const list = rolesToBots.get(key) || [];
+            if (!list.includes(bot.name))
+                list.push(bot.name);
+            rolesToBots.set(key, list);
+        }
+    }
+    if (rolesToBots.size === 0) {
+        return [
+            'CAPABILITIES WITH A DEDICATED BOT',
+            '',
+            '(none configured for this conversation — handle every request yourself via reply_directly, unless the user explicitly names a bot.)',
+        ].join('\n');
+    }
+    const lines = ['CAPABILITIES WITH A DEDICATED BOT', ''];
+    const sorted = Array.from(rolesToBots.entries()).sort(([a], [b]) => a.localeCompare(b));
+    for (const [role, owners] of sorted) {
+        lines.push(`  - ${role} → ${owners.join(', ')}`);
+    }
+    lines.push('');
+    lines.push('These are the ONLY roles for which delegation is preferred. Any');
+    lines.push('request that does not cleanly map to one of the roles above, you');
+    lines.push('handle yourself via reply_directly.');
+    return lines.join('\n');
+}
+/**
+ * Build the full system prompt for an orchestrator turn.
+ *
+ * Output shape:
+ *   [Orchestrator Operating Prompt]
+ *   <static body>
+ *
+ *   <dynamic roles-with-a-dedicated-bot section>
+ *
+ *   [Additional Guidance]   — if provided
+ *   <soul_md or bot-specific text>
+ *
+ *   [Hint Block]
+ *   <JSON-stringified hint>
+ *
+ *   [End of Hint]
+ */
+function buildOrchestratorDispatchPrompt(input) {
+    const rolesSection = buildRolesSection(input.hint.available_bots || []);
+    const parts = [
+        '[Orchestrator Operating Prompt]',
+        PROMPT_BODY_STATIC.trim(),
+        '',
+        rolesSection,
+    ];
+    const guidance = input.additionalGuidance?.trim();
+    if (guidance) {
+        parts.push('', '[Additional Guidance]', guidance);
+    }
+    parts.push('', '[Hint Block]', JSON.stringify(input.hint, null, 2), '[End of Hint]');
+    return parts.join('\n');
+}
+/** Export the static body for tests. */
+exports.ORCHESTRATOR_DISPATCH_PROMPT_BODY = PROMPT_BODY_STATIC;
+//# sourceMappingURL=orchestrator-dispatch-prompt.js.map

package/dist/orchestration/orchestrator-dispatch-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-dispatch-prompt.js","sourceRoot":"","sources":["../../src/orchestration/orchestrator-dispatch-prompt.ts"],"names":[],"mappings":"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"}

package/dist/orchestration/orchestrator-operating-prompt.d.ts

@@ -8,7 +8,9 @@ export interface OrchestratorFrontDoorDecision {
     delegate_request?: string;
     workflow_request?: string;
     clarification_questions?: string[];
+    narration?: string;
 }
+export declare const ORCHESTRATOR_DECISION_SENTINEL = "===DECISION===";
 export interface SpecialistInfo {
     name: string;
     roleLabel: string;
@@ -35,6 +37,7 @@ export declare function buildOrchestratorOperatingPrompt(input: {
     primaryRole?: string | null;
     specialists?: SpecialistInfo[];
     workflowNames?: string[];
+    localPromptContract?: 'legacy' | 'api_or_fresh_cli' | 'cli_recurring';
     entryMode?: 'normal' | 'orchestration_bias';
     signalSummary?: FrontDoorSignalSummary;
     systemSuggestion?: FrontDoorSystemSuggestion | null;
@@ -43,7 +46,19 @@ export declare function buildOrchestratorOperatingPrompt(input: {
     effectivePolicy?: string | null;
     recentSummary?: string | null;
     lastFiveTurns?: string | null;
+    bootstrapHistoryFilePath?: string | null;
     decisionOnly?: boolean;
+    defaultBotName?: string | null;
 }): string;
+/**
+ * Splits the LLM raw output at the ===DECISION=== sentinel.
+ * Returns { narration, decisionText } where narration may be empty if the
+ * LLM did not follow the format. The decisionText is the portion after
+ * the sentinel (or the entire raw if no sentinel was found, for backward compat).
+ */
+export declare function splitOrchestratorNarrationAndDecision(raw: string): {
+    narration: string;
+    decisionText: string;
+};
 export declare function parseOrchestratorFrontDoorDecision(raw: string): OrchestratorFrontDoorDecision | null;
 //# sourceMappingURL=orchestrator-operating-prompt.d.ts.map

package/dist/orchestration/orchestrator-operating-prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator-operating-prompt.d.ts","sourceRoot":"","sources":["../../src/orchestration/orchestrator-operating-prompt.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,yBAAyB,GACjC,SAAS,GACT,cAAc,GACd,UAAU,GACV,UAAU,GACV,SAAS,CAAC;AAEd,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,yBAAyB,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,UAAU,GAAG,MAAM,CAAC;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;CAC7D;AAED,wBAAgB,gCAAgC,CAAC,KAAK,EAAE;IACtD,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,QAAQ,GAAG,oBAAoB,CAAC;IAC5C,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,gBAAgB,CAAC,EAAE,yBAAyB,GAAG,IAAI,CAAC;IACpD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,MAAM,CAuLT;AAED,wBAAgB,kCAAkC,CAAC,GAAG,EAAE,MAAM,GAAG,6BAA6B,GAAG,IAAI,CAgDpG"}
+{"version":3,"file":"orchestrator-operating-prompt.d.ts","sourceRoot":"","sources":["../../src/orchestration/orchestrator-operating-prompt.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,yBAAyB,GACjC,SAAS,GACT,cAAc,GACd,UAAU,GACV,UAAU,GACV,SAAS,CAAC;AAEd,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,yBAAyB,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,UAAU,GAAG,MAAM,CAAC;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,8BAA8B,mBAAmB,CAAC;AAE/D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;CAC7D;AAED,wBAAgB,gCAAgC,CAAC,KAAK,EAAE;IACtD,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,mBAAmB,CAAC,EAAE,QAAQ,GAAG,kBAAkB,GAAG,eAAe,CAAC;IACtE,SAAS,CAAC,EAAE,QAAQ,GAAG,oBAAoB,CAAC;IAC5C,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,gBAAgB,CAAC,EAAE,yBAAyB,GAAG,IAAI,CAAC;IACpD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,wBAAwB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,GAAG,MAAM,CAgWT;AAED;;;;;GAKG;AACH,wBAAgB,qCAAqC,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAS9G;AAED,wBAAgB,kCAAkC,CAAC,GAAG,EAAE,MAAM,GAAG,6BAA6B,GAAG,IAAI,CA+CpG"}

package/dist/orchestration/orchestrator-operating-prompt.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORCHESTRATOR_DECISION_SENTINEL = void 0;
 exports.buildOrchestratorOperatingPrompt = buildOrchestratorOperatingPrompt;
+exports.splitOrchestratorNarrationAndDecision = splitOrchestratorNarrationAndDecision;
 exports.parseOrchestratorFrontDoorDecision = parseOrchestratorFrontDoorDecision;
+exports.ORCHESTRATOR_DECISION_SENTINEL = '===DECISION===';
 function buildOrchestratorOperatingPrompt(input) {
     const primaryRole = input.primaryRole?.trim() || 'generalist';
     const specialists = input.specialists || [];
@@ -22,6 +25,7 @@ function buildOrchestratorOperatingPrompt(input) {
     const workflowLines = workflowNames.length > 0
         ? workflowNames.map((w) => `- "${w}"`).join('\n')
         : '(none)';
+    const localPromptContract = input.localPromptContract || 'legacy';
     const decisionOnly = input.decisionOnly !== false;
     const entryMode = input.entryMode || 'normal';
     const projectName = input.projectName?.trim() || '(none)';
@@ -29,6 +33,8 @@ function buildOrchestratorOperatingPrompt(input) {
     const effectivePolicy = input.effectivePolicy?.trim() || 'No confirmed special policy is set.';
     const recentSummary = input.recentSummary?.trim() || '(none)';
     const lastFiveTurns = input.lastFiveTurns?.trim() || '(no recent turns)';
+    const bootstrapHistoryFilePath = input.bootstrapHistoryFilePath?.trim() || null;
+    const defaultBotName = input.defaultBotName?.trim() || '(none)';
     const signalLines = input.signalSummary
         ? [
             input.signalSummary.matchedBots?.length ? `- Matched bot names: ${input.signalSummary.matchedBots.join(', ')}` : null,
@@ -60,6 +66,128 @@ ${signalLines || '- No additional signal details recorded.'}`
 Pay attention to the ENTIRE user prompt before deciding. The most important routing signal may appear anywhere in the prompt, including near the end.
 Default to handling the request yourself unless the code front door gives a strong delegation or workflow suggestion or the user clearly directs work to an available worker.
 ${signalLines || ''}`.trim();
+    if (localPromptContract !== 'legacy') {
+        return `You are acting as Orchestrator and ${primaryRole} in this request.
+
+By default, you do the work yourself.
+
+Only split the work when:
+- part of the request clearly belongs to another listed bot or role
+- the user explicitly asks for a named workflow that is listed here
+- the request clearly requires multiple bots doing different tasks
+
+Workflow and TODOs are not the same.
+Use a saved workflow template when the user names one that is listed here.
+Use TODOs when the work needs to be split across multiple bots or roles.
+
+If you keep the work, do the work now in this same response.
+If you split the work, create the needed TODOs and stop after clearly setting up the next step.
+
+If the user mentions another bot only as context, history, or authorship, keep the work and handle it yourself.
+Handle these kinds of direct orchestration work yourself by default:
+- answer user questions
+- inspect the project or codebase and explain findings
+- read files
+- write or update plain-text notes, plans, fix lists, and summaries
+- create, edit, reorder, or explain TODOs
+- break work into sequential steps
+- summarize progress and status
+- ask clarifying questions
+- do lightweight project research and comparison
+- keep work that does not clearly belong to a listed worker role
+
+If you cannot complete kept work directly, use the default bot instead of forcing a worker workflow.
+
+Available Bots and Roles
+${specialistLines}
+
+Default Bot
+- ${defaultBotName}
+
+Named Workflows
+${workflowLines}
+If the user names a saved workflow listed here, execute that template sequentially.
+If no matching saved workflow is listed, do not treat the word "workflow" as a template error. Use normal language context.
+
+Project
+- Name: ${projectName}
+- Folder: ${projectFolder}
+${localPromptContract === 'api_or_fresh_cli'
+            ? bootstrapHistoryFilePath
+                ? `
+
+Bootstrap History File
+Please read the history file at: ${bootstrapHistoryFilePath}
+Use it for context only. Do not mention the file or path unless the user asks.`
+                : `
+
+Recent Summary
+${recentSummary}
+
+Last 5 Turns
+${lastFiveTurns}`
+            : ''}
+
+${decisionOnly
+            ? `OUTPUT FORMAT (TWO PARTS — narration THEN decision JSON)
+
+PART 1: NARRATION
+Write exactly ONE short, friendly, natural sentence telling the user what you're about to do.
+- Be conversational and warm, like a helpful colleague casually narrating their plan to a teammate.
+- Vary the wording every time. Never sound scripted or robotic.
+- If you're routing to specific bots, mention them by name in a natural way.
+- Do NOT say "I am reviewing your request" or any similar boilerplate.
+- Do NOT use exclamation points unless the moment really calls for it.
+- Do NOT add any preamble, headers, or labels — just the sentence itself.
+
+PART 2: DECISION
+After the narration, on a new line, write exactly the marker ${exports.ORCHESTRATOR_DECISION_SENTINEL}
+Then on the next line, write exactly one JSON object describing your decision.
+Do not wrap JSON in markdown fences.
+Do not add commentary before or after the JSON.
+
+EXAMPLE:
+${(() => {
+                const researchBot = specialists.find((s) => /research|brainstorm|plan/i.test(s.roleLabel));
+                const codingBot = specialists.find((s) => /cod|build|develop|engineer/i.test(s.roleLabel));
+                const qaBot = specialists.find((s) => /qa|review/i.test(s.roleLabel));
+                const rName = researchBot?.name || 'the researcher';
+                const cName = codingBot?.name || 'the coder';
+                const qName = qaBot?.name || 'the reviewer';
+                return `Got it — I'll have ${rName} sketch a plan first, then ${cName} can build it and ${qName} will give it a once-over.
+${exports.ORCHESTRATOR_DECISION_SENTINEL}
+${JSON.stringify({
+                    mode: 'workflow',
+                    reason: 'Multi-step build',
+                    workflow_request: `${rName} plan, ${cName} code, ${qName} QA`,
+                }, null, 2)}`;
+            })()}
+
+THE JSON SCHEMA:`
+            : `OUTPUT FORMAT (TWO PARTS — narration THEN decision/answer)
+
+PART 1: NARRATION
+If you are splitting the work, write exactly ONE short, friendly sentence first telling the user what you're about to do.
+Be natural and warm. Vary the wording. No robotic boilerplate.
+If you are keeping the work and answering directly, skip narration and just return your answer.
+
+PART 2: DECISION OR DIRECT ANSWER
+- If you keep the work: return the user-facing answer directly with no JSON, no sentinel.
+- If you split the work: after narration, on a new line write ${exports.ORCHESTRATOR_DECISION_SENTINEL}, then write exactly one JSON object.
+- Do not wrap JSON in markdown fences.
+
+THE JSON SCHEMA:`}
+${JSON.stringify({
+            mode: decisionOnly ? 'respond | execute_self | delegate | workflow | clarify' : 'respond | delegate | workflow | clarify',
+            reason: 'short explanation',
+            response: 'only for respond',
+            delegate_target: 'bot name or NONE',
+            delegate_role: 'coding | qa | research | none',
+            delegate_request: 'self-contained task',
+            workflow_request: 'short objective',
+            clarification_questions: [],
+        }, null, 2)}`;
+    }
     return `You are ${input.orchestratorName}.
 
 ${decisionOnly
@@ -88,24 +216,31 @@ DELEGATION POSTURE
 - If the system suggests a TODO or workflow for work that cannot be clearly delegated to an available worker other than yourself, do not create a TODO or workflow. Handle the request yourself instead.
 - You may delegate without a system suggestion only when the user clearly directs work to an available worker, role, or specialist other than yourself.
 - If you disagree with the system suggestion, explain why in the "reason" field.
+- If no listed worker role clearly matches the task, keep the work yourself.
+- If you cannot complete kept work directly, use the default bot instead of forcing a worker workflow.
 
 ---
 
 Available Workers
 ${specialistLines}
 
+Default Bot
+- ${defaultBotName}
+
 AVAILABLE WORKER BOUNDARY
 - Delegable work is defined by the available bots, their roles, and their stated responsibilities in this project.
 - A bot name, model name, or prior worker reference is not by itself a delegation request.
 - If the user mentions a worker only as context, history, or authorship, keep the request and handle it yourself.
 - Delegate when the request clearly directs work to an available worker or clearly requires work owned by that worker's role.
+- Handle these kinds of work yourself by default: answering user questions, inspecting the project or codebase and explaining findings, reading files, writing or updating plain-text notes/plans/fix lists/summaries, creating/editing/reordering TODOs, breaking work into sequential steps, summarizing progress/status, asking clarifying questions, and lightweight project research/comparison.
 
 ---
 
 Available Workflows
 ${workflowLines}
 - Use workflow when the system suggests workflow and that suggestion is correct, or when the user clearly requests multi-worker or staged work.
-- If no workflows are listed, named workflow mode is not available.
+- If the user names a saved workflow listed here, execute that template sequentially.
+- If no matching saved workflow is listed, do not treat the word "workflow" as a template error. Use normal language context.
 - Delegate ONE clear task only.
 
 - delegate_request MUST be fully self-contained:
@@ -118,8 +253,8 @@ ${workflowLines}
 - The receiving bot has NO prior context
 - Do NOT reference prior conversation ("as discussed", "above", etc.)
 
-- Only use workflow when it is explicitly requested and a system-defined workflow is available.
-- Do NOT create your own workflows.
+- Treat the listed worker roles and responsibilities as the explicit delegation scope for worker bots.
+- Work outside those listed worker scopes should stay with you unless you intentionally fall back to the default bot.
 
 ---
 
@@ -149,15 +284,45 @@ DECISION ORDER
 ---
 
 ${decisionOnly
-        ? `OUTPUT JSON ONLY
-Return exactly one JSON object.
-Do not wrap it in markdown fences.
-Do not add commentary before or after the JSON.`
-        : `OUTPUT RULES
-- If you keep the work, return the user-facing answer directly and do NOT return JSON.
-- If you delegate, use workflow, or need clarification, return exactly one JSON object.
+        ? `OUTPUT FORMAT (TWO PARTS — narration THEN decision JSON)
+
+PART 1: NARRATION
+Write exactly ONE short, friendly, natural sentence telling the user what you're about to do.
+- Be conversational and warm, like a helpful colleague casually narrating their plan to a teammate.
+- Vary the wording every time. Never sound scripted or robotic.
+- If you're routing to specific bots, mention them by name in a natural way.
+- Do NOT say "I am reviewing your request" or any similar boilerplate.
+- Do NOT use exclamation points unless the moment really calls for it.
+- Do NOT add any preamble, headers, or labels — just the sentence itself.
+
+PART 2: DECISION
+After the narration, on a new line, write exactly the marker ${exports.ORCHESTRATOR_DECISION_SENTINEL}
+Then on the next line, write exactly one JSON object describing your decision.
+Do not wrap JSON in markdown fences.
+
+EXAMPLE:
+Got it — I'll have Brain sketch a plan first, then Ben can build it and John will give it a once-over.
+${exports.ORCHESTRATOR_DECISION_SENTINEL}
+${JSON.stringify({
+            mode: 'workflow',
+            reason: 'Multi-step build',
+            workflow_request: 'Brain plan, Ben code, John QA',
+        }, null, 2)}
+
+THE JSON SCHEMA:`
+        : `OUTPUT FORMAT (TWO PARTS — narration THEN decision/answer)
+
+PART 1: NARRATION
+If you are splitting the work, write exactly ONE short, friendly sentence first telling the user what you're about to do.
+Be natural and warm. Vary the wording. No robotic boilerplate.
+If you are keeping the work and answering directly, skip narration and just return your answer.
+
+PART 2: DECISION OR DIRECT ANSWER
+- If you keep the work: return the user-facing answer directly with no JSON, no sentinel.
+- If you split the work: after narration, on a new line write ${exports.ORCHESTRATOR_DECISION_SENTINEL}, then write exactly one JSON object.
 - Do not wrap JSON in markdown fences.
-- Do not add commentary before or after the JSON.`}
+
+THE JSON SCHEMA:`}
 ${JSON.stringify({
         mode: decisionOnly ? 'respond | execute_self | delegate | workflow | clarify' : 'respond | delegate | workflow | clarify',
         reason: 'short explanation',
@@ -183,13 +348,37 @@ RECENT SUMMARY
 ${recentSummary}
 
 LAST 5 TURNS
-${lastFiveTurns}`;
+${lastFiveTurns}${bootstrapHistoryFilePath
+        ? `
+
+BOOTSTRAP HISTORY FILE
+Please read the history file at: ${bootstrapHistoryFilePath}
+Use it for context only. Do not mention the file or path unless the user asks.`
+        : ''}`;
+}
+/**
+ * Splits the LLM raw output at the ===DECISION=== sentinel.
+ * Returns { narration, decisionText } where narration may be empty if the
+ * LLM did not follow the format. The decisionText is the portion after
+ * the sentinel (or the entire raw if no sentinel was found, for backward compat).
+ */
+function splitOrchestratorNarrationAndDecision(raw) {
+    const text = String(raw || '');
+    const sentinelIdx = text.indexOf(exports.ORCHESTRATOR_DECISION_SENTINEL);
+    if (sentinelIdx < 0) {
+        return { narration: '', decisionText: text };
+    }
+    const narration = text.slice(0, sentinelIdx).trim();
+    const decisionText = text.slice(sentinelIdx + exports.ORCHESTRATOR_DECISION_SENTINEL.length).trim();
+    return { narration, decisionText };
 }
 function parseOrchestratorFrontDoorDecision(raw) {
     const trimmed = String(raw || '').trim();
     if (!trimmed)
         return null;
-    const unfenced = trimmed
+    const { narration, decisionText } = splitOrchestratorNarrationAndDecision(trimmed);
+    const sourceForJson = decisionText || trimmed;
+    const unfenced = sourceForJson
         .replace(/^```json\s*/i, '')
         .replace(/^```\s*/i, '')
         .replace(/\s*```$/i, '')
@@ -211,13 +400,9 @@ function parseOrchestratorFrontDoorDecision(raw) {
         else {
             normalizedMode = 'execute_self';
         }
-        // Safety net: if respond mode contains ANY orchestration language, auto-correct to execute_self
-        if (normalizedMode === 'respond' && typeof parsed.response === 'string') {
-            const resp = parsed.response.toLowerCase();
-            if (/which (worker|bot|agent|specialist)|ready to coordinate|get the right bots|before i start|need a few details|i need to know|which .* should handle|let me (coordinate|orchestrate|route|assign)/i.test(resp)) {
-                normalizedMode = 'execute_self';
-            }
-        }
+        // Prefer top-level narration field on the JSON object if present, otherwise the pre-sentinel text.
+        const narrationFromJson = typeof parsed.narration === 'string' ? parsed.narration.trim() : '';
+        const finalNarration = narrationFromJson || narration || '';
         return {
             mode: normalizedMode,
             reason: String(parsed.reason || '').trim(),
@@ -229,6 +414,7 @@ function parseOrchestratorFrontDoorDecision(raw) {
             clarification_questions: Array.isArray(parsed.clarification_questions)
                 ? parsed.clarification_questions.map((item) => String(item || '').trim()).filter(Boolean)
                 : undefined,
+            narration: finalNarration || undefined,
         };
     }
     catch {